Documentation
¶
Overview ¶
Package gcf implements the dispatch.Dispatcher interface using a GCP Cloud Function as the token mint. The mint validates GitHub OIDC tokens via Workload Identity Federation and issues scoped installation tokens for each agent role.
Index ¶
- Variables
- func DefaultFunctionSourceDir() string
- type Config
- type DeployMode
- type FunctionConfig
- type FunctionInfo
- type GCFClient
- type LiveGCFClient
- func (c *LiveGCFClient) AddSecretVersion(ctx context.Context, projectID, secretID string, data []byte) error
- func (c *LiveGCFClient) CreateFunction(ctx context.Context, projectID, region, functionName string, ...) (string, error)
- func (c *LiveGCFClient) CreateSecret(ctx context.Context, projectID, secretID string) error
- func (c *LiveGCFClient) CreateServiceAccount(ctx context.Context, projectID, saName, displayName string) error
- func (c *LiveGCFClient) CreateWIFPool(ctx context.Context, projectNumber, poolID, displayName string) error
- func (c *LiveGCFClient) CreateWIFProvider(ctx context.Context, projectNumber, poolID, providerID string, ...) error
- func (c *LiveGCFClient) GetFunction(ctx context.Context, projectID, region, functionName string) (*FunctionInfo, error)
- func (c *LiveGCFClient) GetProjectNumber(ctx context.Context, projectID string) (string, error)
- func (c *LiveGCFClient) GetSecret(ctx context.Context, projectID, secretID string) error
- func (c *LiveGCFClient) GetWIFProvider(ctx context.Context, projectNumber, poolID, providerID string) (*WIFProviderInfo, error)
- func (c *LiveGCFClient) SetCloudRunInvoker(ctx context.Context, projectID, region, serviceName string) error
- func (c *LiveGCFClient) SetSecretIAMBinding(ctx context.Context, resource, member, role string) error
- func (c *LiveGCFClient) UpdateFunction(ctx context.Context, projectID, region, functionName string, ...) (string, error)
- func (c *LiveGCFClient) UpdateWIFProvider(ctx context.Context, projectNumber, poolID, providerID string, ...) error
- func (c *LiveGCFClient) UploadFunctionSource(ctx context.Context, projectID, region string, sourceZip []byte) (json.RawMessage, error)
- func (c *LiveGCFClient) WaitForOperation(ctx context.Context, operationName string) error
- type OIDCProviderConfig
- type Provisioner
- func (p *Provisioner) Name() string
- func (p *Provisioner) OrgSecretNames() []string
- func (p *Provisioner) OrgVariableNames() []string
- func (p *Provisioner) Provision(ctx context.Context) (map[string]string, error)
- func (p *Provisioner) SecretExists(ctx context.Context, org, role string) (bool, error)
- func (p *Provisioner) StoreAgentPEM(ctx context.Context, org, role string, pemData []byte) error
- type WIFProviderInfo
Constants ¶
This section is empty.
Variables ¶
var ErrSecretNotFound = errors.New("secret not found")
ErrSecretNotFound is returned when a Secret Manager secret does not exist.
Functions ¶
func DefaultFunctionSourceDir ¶
func DefaultFunctionSourceDir() string
DefaultFunctionSourceDir returns the default path to the Cloud Function source directory. This assumes the CLI is run from the repository root.
Types ¶
type Config ¶
type Config struct {
ProjectID string
Region string // default: "us-central1"
WIFPoolName string // default: "fullsend-pool"
WIFProvider string // default: "github-oidc"
GitHubOrgs []string
FunctionSourceDir string // path to Cloud Function source directory
// AgentPEMs maps role → PEM private key data for all agent Apps.
AgentPEMs map[string][]byte
// AgentAppIDs maps role → GitHub App ID for all agent Apps.
AgentAppIDs map[string]string
// MintURL, if set, skips infrastructure deployment and uses the
// existing mint at this URL. Only PEMs are stored.
MintURL string
// DeployMode controls function deployment: auto (default), skip, or force.
DeployMode DeployMode
}
Config holds the inputs for GCF mint provisioning.
type DeployMode ¶
type DeployMode int
DeployMode controls Cloud Function deployment behavior.
const ( // DeployAuto compares source hash and env vars; skips deploy if unchanged. DeployAuto DeployMode = iota // DeploySkip never redeploys; reuses the existing function URL. DeploySkip // DeployForce always redeploys regardless of changes. DeployForce )
type FunctionConfig ¶
type FunctionConfig struct {
ServiceAccount string
EnvVars map[string]string
StorageSource json.RawMessage // structured object from generateUploadUrl response
EntryPoint string
Runtime string
}
FunctionConfig holds parameters for creating a Cloud Function.
type FunctionInfo ¶
type FunctionInfo struct {
Name string
State string
URI string
Region string
EnvVars map[string]string
}
FunctionInfo holds metadata about a deployed Cloud Function.
type GCFClient ¶
type GCFClient interface {
// Service account operations
CreateServiceAccount(ctx context.Context, projectID, saName, displayName string) error
// WIF operations
CreateWIFPool(ctx context.Context, projectNumber, poolID, displayName string) error
CreateWIFProvider(ctx context.Context, projectNumber, poolID, providerID string, cfg OIDCProviderConfig) error
GetWIFProvider(ctx context.Context, projectNumber, poolID, providerID string) (*WIFProviderInfo, error)
UpdateWIFProvider(ctx context.Context, projectNumber, poolID, providerID string, cfg OIDCProviderConfig) error
// Secret Manager
GetSecret(ctx context.Context, projectID, secretID string) error
CreateSecret(ctx context.Context, projectID, secretID string) error
AddSecretVersion(ctx context.Context, projectID, secretID string, data []byte) error
// IAM binding (Secret Manager resources)
SetSecretIAMBinding(ctx context.Context, resource, member, role string) error
// Cloud Run IAM (for function invoker policy)
SetCloudRunInvoker(ctx context.Context, projectID, region, serviceName string) error
// Cloud Functions v2
GetFunction(ctx context.Context, projectID, region, functionName string) (*FunctionInfo, error)
UploadFunctionSource(ctx context.Context, projectID, region string, sourceZip []byte) (storageSource json.RawMessage, err error)
CreateFunction(ctx context.Context, projectID, region, functionName string, cfg FunctionConfig) (string, error)
UpdateFunction(ctx context.Context, projectID, region, functionName string, cfg FunctionConfig) (string, error)
WaitForOperation(ctx context.Context, operationName string) error
// Project number lookup
GetProjectNumber(ctx context.Context, projectID string) (string, error)
}
GCFClient abstracts GCP API operations needed by the provisioner.
type LiveGCFClient ¶
LiveGCFClient implements GCFClient using GCP REST APIs. It embeds *gcp.Client for shared ADC auth.
func NewLiveGCFClient ¶
func NewLiveGCFClient() *LiveGCFClient
NewLiveGCFClient creates a new LiveGCFClient.
func (*LiveGCFClient) AddSecretVersion ¶
func (c *LiveGCFClient) AddSecretVersion(ctx context.Context, projectID, secretID string, data []byte) error
AddSecretVersion adds a new version with the given data to an existing secret.
func (*LiveGCFClient) CreateFunction ¶
func (c *LiveGCFClient) CreateFunction(ctx context.Context, projectID, region, functionName string, cfg FunctionConfig) (string, error)
CreateFunction creates a Cloud Function v2.
func (*LiveGCFClient) CreateSecret ¶
func (c *LiveGCFClient) CreateSecret(ctx context.Context, projectID, secretID string) error
CreateSecret creates a Secret Manager secret.
func (*LiveGCFClient) CreateServiceAccount ¶
func (c *LiveGCFClient) CreateServiceAccount(ctx context.Context, projectID, saName, displayName string) error
CreateServiceAccount creates a new service account.
func (*LiveGCFClient) CreateWIFPool ¶
func (c *LiveGCFClient) CreateWIFPool(ctx context.Context, projectNumber, poolID, displayName string) error
CreateWIFPool creates a new WIF pool.
func (*LiveGCFClient) CreateWIFProvider ¶
func (c *LiveGCFClient) CreateWIFProvider(ctx context.Context, projectNumber, poolID, providerID string, cfg OIDCProviderConfig) error
CreateWIFProvider creates a WIF OIDC provider.
func (*LiveGCFClient) GetFunction ¶
func (c *LiveGCFClient) GetFunction(ctx context.Context, projectID, region, functionName string) (*FunctionInfo, error)
GetFunction checks if a Cloud Function exists and returns its info.
func (*LiveGCFClient) GetProjectNumber ¶
GetProjectNumber looks up the project number for a project ID.
func (*LiveGCFClient) GetSecret ¶
func (c *LiveGCFClient) GetSecret(ctx context.Context, projectID, secretID string) error
GetSecret checks that a Secret Manager secret exists.
func (*LiveGCFClient) GetWIFProvider ¶
func (c *LiveGCFClient) GetWIFProvider(ctx context.Context, projectNumber, poolID, providerID string) (*WIFProviderInfo, error)
GetWIFProvider reads an existing WIF OIDC provider's configuration.
func (*LiveGCFClient) SetCloudRunInvoker ¶
func (c *LiveGCFClient) SetCloudRunInvoker(ctx context.Context, projectID, region, serviceName string) error
SetCloudRunInvoker ensures allUsers has roles/run.invoker on the Cloud Run service backing a Cloud Function. Uses read-modify-write with retry on 409 (etag conflict) to preserve existing bindings. The function's own OIDC validation is the security boundary.
func (*LiveGCFClient) SetSecretIAMBinding ¶
func (c *LiveGCFClient) SetSecretIAMBinding(ctx context.Context, resource, member, role string) error
SetSecretIAMBinding sets an IAM binding on a Secret Manager resource. Uses read-modify-write with retry on 409 Conflict (etag mismatch).
func (*LiveGCFClient) UpdateFunction ¶
func (c *LiveGCFClient) UpdateFunction(ctx context.Context, projectID, region, functionName string, cfg FunctionConfig) (string, error)
UpdateFunction updates an existing Cloud Function v2 using the PATCH API. It returns a long-running operation name that can be polled with WaitForOperation.
func (*LiveGCFClient) UpdateWIFProvider ¶
func (c *LiveGCFClient) UpdateWIFProvider(ctx context.Context, projectNumber, poolID, providerID string, cfg OIDCProviderConfig) error
UpdateWIFProvider patches an existing WIF OIDC provider's attribute condition and allowed audiences.
func (*LiveGCFClient) UploadFunctionSource ¶
func (c *LiveGCFClient) UploadFunctionSource(ctx context.Context, projectID, region string, sourceZip []byte) (json.RawMessage, error)
UploadFunctionSource generates a signed upload URL and uploads the source zip. Returns the storage source URI for use in CreateFunction.
func (*LiveGCFClient) WaitForOperation ¶
func (c *LiveGCFClient) WaitForOperation(ctx context.Context, operationName string) error
WaitForOperation polls a long-running operation until it completes or the context is canceled. Polls every 5 seconds for up to 10 minutes.
type OIDCProviderConfig ¶
type OIDCProviderConfig struct {
IssuerURI string
AttributeCondition string
AllowedAudiences []string
}
OIDCProviderConfig holds configuration for a WIF OIDC provider.
type Provisioner ¶
type Provisioner struct {
// contains filtered or unexported fields
}
Provisioner creates GCP infrastructure for OIDC-based token minting.
func NewProvisioner ¶
func NewProvisioner(cfg Config, gcpAPI GCFClient) *Provisioner
NewProvisioner creates a new Provisioner with defaults applied.
func (*Provisioner) Name ¶
func (p *Provisioner) Name() string
Name returns the dispatcher identifier.
func (*Provisioner) OrgSecretNames ¶
func (p *Provisioner) OrgSecretNames() []string
OrgSecretNames returns nil — the mint uses Secret Manager, not org secrets.
func (*Provisioner) OrgVariableNames ¶
func (p *Provisioner) OrgVariableNames() []string
OrgVariableNames returns the org variables this dispatcher manages.
func (*Provisioner) Provision ¶
Provision creates the GCP infrastructure for the token mint.
When MintURL is empty, deploys the full mint infrastructure:
- Look up project number
- Create/verify service account
- Create/verify WIF pool + provider
- Store all agent PEMs in Secret Manager
- Grant SA access to all role secrets
- Deploy Cloud Function
- Return FULLSEND_MINT_URL
When MintURL is set, reuses an existing mint:
- Store all agent PEMs in Secret Manager
- Return the provided MintURL
func (*Provisioner) SecretExists ¶
SecretExists checks whether the Secret Manager secret for the given org and role exists.
func (*Provisioner) StoreAgentPEM ¶
StoreAgentPEM persists a single org/role's PEM in Secret Manager. Called during App setup so each PEM is stored immediately after creation.
type WIFProviderInfo ¶
WIFProviderInfo holds metadata about a WIF OIDC provider.