Mintcore Architecture

This guide describes the shipped wiring of internal/mintcore/ — the shared token-minting library used by three deploy targets. It covers platform accessors, load-site construction, WASM constraints, and the patterns that keep the Cloudflare Worker binary within size limits.

Deploy targets

Mintcore is shared by three deploy targets. Each target has its own load site (entrypoint) that constructs the verifier and PEM accessor and passes them into NewHandler.

Target	Load site	Verifier	PEM accessor
GCF (Cloud Function)	internal/mint	NewSTSVerifier	NewGCPSecretPEMAccessor
Cloudflare Worker	cmd/mint-wasm (mintcoreInitMint)	NewJWKSVerifier	NewHostPEMAccessor
Standalone	cmd/mint	NewJWKSVerifier	NewFilesystemPEMAccessor

A fourth consumer, devmint (used in e2e tests), also constructs NewJWKSVerifier and passes its own PEM accessor via the same NewHandler interface.

Layering

internal/mintcore/        shared library — all mint logic
  mintconsts/             compile-time constants (OIDCAudience)
internal/mint/            GCF load site (has its own go.mod)
cmd/mint/                 standalone HTTP server load site (has its own go.mod)
cmd/mint-wasm/            WASM entrypoint for CF Worker (imports mintcore)
internal/dispatch/cf/
  workersrc/              CF Worker TypeScript adapter (I/O only)
internal/dispatch/gcf/
  mintsrc/                embedded copies for GCF deployment (.embed files)

internal/mintcore/ contains all token-minting logic: request parsing, OIDC verification, claims validation, authorization (org, workflow-ref, repos scope), GitHub App token creation, bot-role lookup (POST /v1/bot-role), and status endpoints. It compiles to both native (!js) and WASM (js) targets. It is a nested module with a local-only replace; packages reachable from pkg/behaviourtest must not import it (including mintconsts). See Go Code.

Entrypoints (internal/mint, cmd/mint, cmd/mint-wasm) are thin. They construct the appropriate OIDCVerifier + PEMAccessor for their platform, call NewHandler(pemAccessor, verifier), and serve HTTP. No mint logic lives in entrypoints.

The CF Worker TypeScript adapter (workersrc/src/index.ts) handles I/O only — Worker secrets, host fetch, Fetch Request/Response mapping. It calls mintcoreInitMint and mintcoreHandleFetch registered on globalThis by the Go WASM bridge in cmd/mint-wasm.

Platform accessors

Two package-internal accessor functions abstract platform I/O inside mintcore:

mintEnv(key string) string

Reads environment/configuration values.

Build tag	Implementation	File
!js (native)	os.Getenv(key)	env.go
js (WASM)	JS callback registered via RegisterEnv	env_js.go

NewHandler reads all configuration variables (ROLE_APP_IDS, ALLOWED_WORKFLOW_FILES, PER_REPO_WIF_REPOS, WORKFLOW_HOST_REPOS, CUSTOM_ROLE_PERMISSIONS, ALLOWED_ROLES) via mintEnv at construction time.

mintHTTP(req *http.Request) (*http.Response, error)

Executes outbound HTTP requests (GitHub API calls).

Build tag	Implementation	File
!js (native)	Cached *http.Client with 30s timeout	http_client.go
js (WASM)	JS fetch callback registered via RegisterHTTP	http_client_js.go

mintHTTP(req) is called at request time inside handler and verifier files (github.go, jwks_verifier.go, sts_verifier.go, gcp_pem.go, tracing.go). It is never called during construction.

Registration on WASM

The CF Worker calls RegisterEnv and RegisterHTTP once during mintcoreInitMint — before NewHandler reads configuration. Only cmd/mint-wasm/main.go calls these functions; native entrypoints do not need to (and cannot — the functions are behind //go:build js).

Who may call RegisterEnv / RegisterHTTP

Only the WASM entrypoint (cmd/mint-wasm). These are one-shot registration functions, not something load sites or tests should call. Tests use t.Setenv for environment variables and SetMintHTTPForTest(t, fake) for HTTP overrides.

Load-site construction

Each entrypoint builds the verifier and PEM accessor appropriate for its platform, then passes them into NewHandler:

// cmd/mint (standalone)
verifier, _ := mintcore.NewJWKSVerifier(mintcore.JWKSVerifierConfig{
    IssuerURL: "https://token.actions.githubusercontent.com",
})
pemAccessor, _ := mintcore.NewFilesystemPEMAccessor(os.Getenv("PEM_DIR"))
handler, _ := mintcore.NewHandler(pemAccessor, verifier)

// internal/mint (GCF)
verifier, _ := mintcore.NewSTSVerifier(mintcore.STSVerifierConfig{
    GCPProjectNum:      gcpProjectNum,
    WIFPoolName:        wifPoolName,
    DefaultWIFProvider: defaultWIFProvider,
    PerRepoWIFRepos:    perRepoWIFRepos,
})
pemAccessor := mintcore.NewGCPSecretPEMAccessor(gcpProjectNum)
handler, _ := mintcore.NewHandler(pemAccessor, verifier)

// cmd/mint-wasm (CF Worker)
mintcore.RegisterEnv(getEnvFn)
mintcore.RegisterHTTP(fetchFn)
pemAccessor, _ := mintcore.NewHostPEMAccessor(pemFn)
verifier, _ := mintcore.NewJWKSVerifier(mintcore.JWKSVerifierConfig{
    IssuerURL: "https://token.actions.githubusercontent.com",
})
handler, _ := mintcore.NewHandler(pemAccessor, verifier)

Key properties:

• No getEnv or HTTPDoer parameters on NewHandler. The handler reads config via mintEnv and makes HTTP calls via mintHTTP internally.
• No factories passed into NewHandler. The handler receives constructed interfaces, not factory functions.
• Verifier configs use plain data (strings, maps, booleans). The OIDC audience is the compile-time constant mintconsts.OIDCAudience, applied inside verifier constructors — load sites do not pass it.

WASM-unsafe patterns

These patterns increase the WASM binary size or cause deadlocks in the Worker runtime. Do not use them in internal/mintcore/.

Closures and function values in config structs

// BAD: closure captures http.Client's entire dependency graph
type VerifierConfig struct {
    DoHTTP func(*http.Request) (*http.Response, error)
}

Closure capture pulls the entire dependency graph of the captured variables into the WASM binary. A func(string) string for env lookups or a func(*http.Request) (*http.Response, error) for HTTP inflates the binary even if the function body is trivial, because the compiler must include all transitively reachable types.

mintEnv / mintHTTP inside verifier constructors

// BAD: constructor-time env/HTTP pulls dependencies into the call
// graph at init, and on WASM the JS callbacks may not be registered yet
func NewJWKSVerifier() (*JWKSVerifier, error) {
    issuer := mintEnv("OIDC_ISSUER")  // constructor-time env read
    resp, _ := mintHTTP(req)           // constructor-time HTTP call
    // ...
}

Verifier constructors run during mintcoreInitMint. Using mintHTTP in a constructor tries to make HTTP calls before the event loop is available, risking deadlocks. Using mintEnv in a constructor is less dangerous but couples construction to environment state rather than explicit config.

The shipped pattern: constructors take plain config structs → mintHTTP(req) is called at request time in verifier and handler methods.

WASM-safe patterns

These are the patterns used in shipped code. Follow them when modifying mintcore.

Register* once at bootstrap

On WASM, the CF Worker calls RegisterEnv(fn) and RegisterHTTP(fn) once during mintcoreInitMint, before constructing the handler. Native platforms do not call these — mintEnv delegates to os.Getenv and mintHTTP uses a cached *http.Client automatically via build tags.

Constructors take plain data

Verifier configs contain only strings, maps, and booleans — no function values, no interfaces, no closures:

type JWKSVerifierConfig struct {
    IssuerURL string
}

type STSVerifierConfig struct {
    GCPProjectNum      string
    WIFPoolName        string
    DefaultWIFProvider string
    PerRepoWIFRepos    map[string]bool
    // optional fields...
}

Request-time mintHTTP(req)

HTTP calls happen at request time, not construction time. Files that call mintHTTP include:

• github.go — GitHub App installation token creation
• bot_role.go — GitHub App lookup and installation verification for POST /v1/bot-role
• jwks_verifier.go — JWKS key fetching
• sts_verifier.go — GCP STS token exchange
• gcp_pem.go — GCP Secret Manager access (AccessGCPSecret is the one exception to request-time calls: the native-only GCF load site calls it once in init() to read the collector headers)
• tracing.go — OTLP span export (end of request, bounded timeout)

This is intentional: on WASM, the JS event loop must be free for Promises to settle. Constructor-time HTTP would deadlock.

Handler reads config via mintEnv

NewHandler reads ROLE_APP_IDS, PER_REPO_WIF_REPOS, and other configuration variables once via mintEnv at construction time. This works because RegisterEnv has already been called by the time NewHandler runs — the pattern is: register → construct → serve.

PEM remains injected

PEM access uses the PEMAccessor interface at the NewHandler boundary.

PEM implementation	Platform	Storage
GCPSecretPEMAccessor	GCF	GCP Secret Manager
FilesystemPEMAccessor	Standalone	Local directory (PEM_DIR)
HostPEMAccessor	CF Worker (WASM)	Worker secrets via JS callback

Each load site constructs the appropriate accessor and passes it to NewHandler. Tests can pass any PEMAccessor implementation.

Interfaces vs accessors

Mintcore uses two patterns for dependency injection:

Package-internal accessors (mintEnv, mintHTTP) for production environment lookups and HTTP — these are implementation details of mintcore, not part of its public API. They exist because every file in mintcore needs env/HTTP access, and threading interfaces through every function signature would be impractical. Tests override them with t.Setenv and SetMintHTTPForTest(t, fake).

Interfaces (OIDCVerifier, PEMAccessor) at the NewHandler boundary — these are the public contract between load sites and mintcore. Load sites choose which implementation to construct; mintcore does not know or care which platform it is running on.

type OIDCVerifier interface {
    Verify(ctx context.Context, rawToken string) (*Claims, error)
}

type PEMAccessor interface {
    AccessPEM(ctx context.Context, role string) ([]byte, error)
}

Tracing

tracing.go implements mint request tracing without the OpenTelemetry Go SDK, whose dependency graph would inflate the WASM binary. It provides W3C trace-context extraction, span recording, and OTLP/HTTP JSON export through mintHTTP, so it works unchanged on every target.

• Load-site wiring: load sites build a *Tracer with NewTracer(TracingConfig{...}) (plain data only) and call handler.SetTracer(t) before serving. A load site that routes some requests outside Handler (the standalone fallback proxy) instead wraps its whole handler chain with t.Wrap(next), which starts the server span; Handler reuses it. Code outside mintcore forwards the trace with TraceHeaders(ctx) and records failures with RecordSpanError(ctx, stage, err). NewTracer returns nil when the endpoint is empty, and a nil tracer is a no-op. cmd/mint reads OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT (resolved with ResolveOTLPTracesEndpoint) and collector headers from MINT_OTLP_HEADERS_FILE (parsed with ParseOTLPHeaders). cmd/mint-wasm calls NewStampedTracer with the endpoint and deployment stamped into main.otlpTracesEndpoint / main.traceDeployment via -ldflags (traceLDFlags in internal/dispatch/cf) and the Worker secret named by main.otlpHeadersSecret (default MINT_OTLP_HEADERS; durable deploys stamp a unique per-deploy name), read through the getEnv callback. A bad configuration is logged and leaves tracing off rather than failing mintcoreInitMint. Header values are never stamped. The GCF load site (internal/mint) calls NewStampedTracer from buildTracer with the endpoint and deployment stamped into trace_consts.go (writeTraceConstsGoToZip in internal/dispatch/gcf). When otlpHeadersSecret is stamped, it reads the collector headers once in init() from that Secret Manager secret (fullsend-mint-otlp-headers-<random>, a new ID per deploy so a revision's endpoint and headers can never be mismatched) through AccessGCPSecret, with a 5s timeout. An unreadable secret or a bad configuration is logged and leaves tracing off; it never fails init().
• Adding spans: call startSpan(ctx, name, stage) and use the returned context for downstream calls. Call recordError(err) and then end(). Spans are nil-safe, so call sites need no enabled checks. The stage becomes fullsend.mint.failure_stage on the server span when that span is the first to record an error.
• Never record secrets: do not put tokens, JWTs, PEM bytes, collector headers, or raw upstream response bodies in span attributes. Error text passes through safeErrorMessage, which bounds and redacts it, but do not rely on that redaction as the primary control.
• Fail-open: export has a bounded timeout (TracingConfig.ExportTimeout, default 2s). By default it runs synchronously at the end of ServeHTTP, so serverless runtimes do not drop spans after the response; the net/http server holds the buffered response until it finishes. Long-lived load sites (the standalone mint) set TracingConfig.AsyncExport so export runs in a background goroutine that does not delay the response, and call Tracer.Shutdown(ctx) after the server stops to drain it. Never let an export error affect the response.
• No redirects: export marks its request with withNoRedirect. The native mintHTTP honors it. The js mintHTTP passes it as the fifth noRedirect argument of the host fetch callback, and the Worker adapter then fetches with redirect: "manual".
• Bounded fetch: for noRedirect requests, the js mintHTTP also passes the remaining context deadline as a sixth timeoutMs argument. The Worker adapter aborts the underlying fetch at that deadline (never later than its 20 s host-fetch budget), so a stalled collector cannot keep fetches and payloads alive after the exporter releases its export slot. The adapter discards the collector's response body unread.

Embed sync and make wasm-build

Embedded copies for GCF

Mintcore files are embedded for Cloud Function deployment at internal/dispatch/gcf/mintsrc/mintcore/*.embed. When changing any file in internal/mintcore/, sync it to the corresponding .embed file. The lint-mint-embed-sync pre-commit hook enforces this.

When adding a new file to internal/mintcore/:

1. Create the .embed copy in internal/dispatch/gcf/mintsrc/mintcore/.
2. If the file is included in the GCF bundle (no build tag, or //go:build !js), add it to embeddedMintFiles in internal/dispatch/gcf/provisioner.go and to the go:embed directive.
3. If the file is NOT included in the GCF bundle (Worker-only //go:build js files, or standalone-mint-only files), add it to gcfSkip in TestEmbeddedMintSource_MatchesOriginal in provisioner_test.go.

Current gcfSkip entries: env_js.go, fetch_js.go, http_client_js.go, pem_js.go (all //go:build js), and file_pem.go (standalone-mint-only, //go:build !js).

Build metadata stamping

The mint Cloud Function receives version and commit metadata via deploy-time source stamping, not runtime environment variables. The provisioner writes mintcore/version.go into the function source zip at bundle time (writeVersionGoToZip in internal/dispatch/gcf/provisioner.go) with version and commit values baked in. The same technique stamps GitHub status-auth config into mintcore/status_consts.go, and the tracing endpoint, deployment identity and headers secret ID into the function package's trace_consts.go (internal/mint/trace_consts.go on disk, embedded as mintsrc/trace_consts.go.embed, with tracing disabled). On-disk copies of these generated files are skipped during bundling so stale source cannot overwrite the stamped values. Collector header values are never stamped: they live in Secret Manager.

The Cloudflare Worker follows the same principle: wasmLDFlags in internal/dispatch/cf/provisioner.go stamps mintcore.Version, mintcore.Commit, and status-auth config into the WASM binary via -ldflags at compile time rather than injecting runtime env vars. traceLDFlags adds the tracing endpoint and deployment identity the same way. A traces endpoint always forces a rebuild of a pre-staged mintcore.wasm, because a staged binary does not carry the stamp.

This keeps metadata in lockstep with the deployed code. Follow this pattern for any future build metadata the function needs — never use environment variables for values that must stay in lockstep with the deployed source.

WASM binary size gate

The compiled WASM binary must stay within Cloudflare Workers size limits. Run make wasm-build after any change to internal/mintcore/ or cmd/mint-wasm/ to verify:

Tier	Gzip limit	Makefile behavior
Workers Free	3 MB	Warning
Workers Paid	10 MB	Hard fail

Keep the WASM dependency graph minimal. The Go WASM compiler includes the transitive closure of all referenced packages — small-looking changes can cause large binary size increases. Avoid importing heavy packages (net/http, crypto/x509, cloud SDKs) in files that are WASM-compiled. Use build tags (//go:build js / //go:build !js) to isolate platform-specific implementations.