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 BuildRepoProviderID(owner, repo string) string
- func DefaultFunctionSourceDir() string
- type Config
- type DeployMode
- type FunctionConfig
- type FunctionInfo
- type GCFClient
- type LiveGCFClient
- func (c *LiveGCFClient) AccessSecretVersion(ctx context.Context, projectID, secretID string) ([]byte, error)
- 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) SetProjectIAMBinding(ctx context.Context, projectID, member, role 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) UpdateFunctionEnvVars(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 MintDiscovery
- type OIDCProviderConfig
- type Provisioner
- func (p *Provisioner) CopyAgentPEM(ctx context.Context, srcOrg, dstOrg, role string) error
- func (p *Provisioner) DiscoverMint(ctx context.Context) (*MintDiscovery, error)
- func (p *Provisioner) EnsureOrgInMint(ctx context.Context, expectedURL string, org string, ...) error
- func (p *Provisioner) GetExistingRoleAppIDs(ctx context.Context) (map[string]string, error)
- func (p *Provisioner) GetFunctionURL(ctx context.Context) (string, error)
- 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) ProvisionWIF(ctx context.Context) (wifProvider string, err error)
- func (p *Provisioner) RegisterPerRepoWIF(ctx context.Context, repo 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 ErrFunctionNotFound = errors.New("mint function not found")
ErrFunctionNotFound is returned when the mint function does not exist.
var ErrSecretNotFound = errors.New("secret not found")
ErrSecretNotFound is returned when a Secret Manager secret does not exist.
Functions ¶
func BuildRepoProviderID ¶
BuildRepoProviderID generates a GCP WIF provider ID scoped to a single repo. GCP requires 4-32 chars, [a-z][a-z0-9-]*, no trailing hyphen.
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
Repo string // per-repo mode: "owner/repo"; empty = per-org
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 for PEM storage, org registration,
// per-repo WIF, and PEM auto-copy.
MintURL string
// DeployMode controls function deployment: auto (default) or skip.
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; skips deploy if unchanged. DeployAuto DeployMode = iota // DeploySkip never redeploys; reuses the existing function URL. DeploySkip )
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
AccessSecretVersion(ctx context.Context, projectID, secretID string) ([]byte, error)
// IAM bindings
SetSecretIAMBinding(ctx context.Context, resource, member, role string) error
SetProjectIAMBinding(ctx context.Context, projectID, 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)
UpdateFunctionEnvVars(ctx context.Context, projectID, region, functionName string, envVars map[string]string) (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) AccessSecretVersion ¶
func (c *LiveGCFClient) AccessSecretVersion(ctx context.Context, projectID, secretID string) ([]byte, error)
AccessSecretVersion reads the latest version of a Secret Manager secret.
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) SetProjectIAMBinding ¶
func (c *LiveGCFClient) SetProjectIAMBinding(ctx context.Context, projectID, member, role string) error
SetProjectIAMBinding sets an IAM binding on a GCP project. Uses read-modify-write with retry on 409 Conflict (etag mismatch).
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) UpdateFunctionEnvVars ¶
func (c *LiveGCFClient) UpdateFunctionEnvVars(ctx context.Context, projectID, region, functionName string, envVars map[string]string) (string, error)
UpdateFunctionEnvVars updates only the environment variables of a Cloud Function v2, leaving build config and other service config untouched.
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 MintDiscovery ¶
MintDiscovery holds the results of a single GetFunction call, providing both the URL and existing role-to-app-ID mappings.
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) CopyAgentPEM ¶
func (p *Provisioner) CopyAgentPEM(ctx context.Context, srcOrg, dstOrg, role string) error
CopyAgentPEM copies a PEM secret from one org to another. Used when the same public GitHub App is installed in multiple orgs — the PEM is the same (tied to the app), just needs a secret under the target org's naming convention.
func (*Provisioner) DiscoverMint ¶
func (p *Provisioner) DiscoverMint(ctx context.Context) (*MintDiscovery, error)
DiscoverMint fetches the mint function once and returns its URL and ROLE_APP_IDS in a single API call. Returns ErrFunctionNotFound (wrapped) if the function does not exist.
func (*Provisioner) EnsureOrgInMint ¶
func (p *Provisioner) EnsureOrgInMint(ctx context.Context, expectedURL string, org string, roleAppIDs map[string]string) error
EnsureOrgInMint validates that a mint function exists at expectedURL and that the given org is registered in ALLOWED_ORGS and ROLE_APP_IDS. If the org is missing, it updates the function's env vars to include it.
WARNING: read-modify-write without locking — concurrent calls from parallel per-repo installs sharing the same mint can race, causing one update to overwrite the other. Run installs sequentially when sharing a mint, or accept that a lost update will be corrected on the next run.
func (*Provisioner) GetExistingRoleAppIDs ¶
GetExistingRoleAppIDs reads ROLE_APP_IDS from the deployed mint function. Returns (nil, nil) if the function doesn't exist or has no ROLE_APP_IDS.
func (*Provisioner) GetFunctionURL ¶
func (p *Provisioner) GetFunctionURL(ctx context.Context) (string, error)
GetFunctionURL returns the URL of the deployed mint function.
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
- Grant Vertex AI access to each org's WIF principalSet (direct WIF)
- 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) ProvisionWIF ¶
func (p *Provisioner) ProvisionWIF(ctx context.Context) (wifProvider string, err error)
ProvisionWIF creates the WIF infrastructure (service account, pool, provider, principal binding) needed for GitHub Actions to authenticate via OIDC. All operations are idempotent. Returns the full WIF provider resource path and service account email.
func (*Provisioner) RegisterPerRepoWIF ¶
func (p *Provisioner) RegisterPerRepoWIF(ctx context.Context, repo string) error
RegisterPerRepoWIF adds a repo to the mint's PER_REPO_WIF_REPOS env var so the mint routes OIDC tokens from that repo to a dedicated WIF provider instead of the org-level default. Idempotent — skips repos already listed. Not safe for concurrent calls — run per-repo installs sequentially when sharing a mint.
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.