Spice OAuth2 Client Starter

Unified documentation: spiceframework.dev/integrations/oauth2-client.

starter-oauth2client provides a bounded OAuth 2.0 client-credentials integration for Spice services. It returns an ordinary *http.Client; there is no global client, discovery service, reflection, or network activity during construction.

Install

go get github.com/spice-framework/starter-oauth2client@latest

The module uses Go 1.26.5. Its machine-readable Spice core boundaries are in spice-compatibility.json.

Use

options := oauth2client.Options{
    ClientID:     config.ClientID,
    ClientSecret: config.ClientSecret,
    TokenURL:     config.TokenURL,
    Scopes:       []string{"inventory.read"},
}

tokenClient := &http.Client{
    Timeout:   5 * time.Second,
    Transport: tracedTokenTransport,
}
resourceClient := &http.Client{
    Timeout:   10 * time.Second,
    Transport: tracedResourceTransport,
}

client, err := oauth2client.NewClient(
    applicationContext,
    options,
    tokenClient,
    resourceClient,
)

Both HTTP clients must have positive timeouts. Spice clones them, so later mutations to the inputs do not silently alter the constructed client. The token transport is used only for credential acquisition; the resource transport is used only for application requests and remains the observability seam.

Security and failure behavior

• Token and resource URLs must use HTTPS. HTTP resource requests fail before a token is acquired.
• Token redirects are never followed. Resource redirects fail closed by default; a caller-supplied CheckRedirect policy is preserved.
• The token response is bounded to 64 KiB by default and at most 1 MiB.
• Only valid Bearer tokens are accepted.
• TokenError preserves context.Canceled and context.DeadlineExceeded classification without retaining upstream bodies, URLs, tokens, or credentials.
• The application-lifetime context controls token acquisition. Each resource request retains its own context and cancellation.
• Token caching and concurrent refresh coordination are provided by the pinned golang.org/x/oauth2 implementation.

Construction does not read environment variables or files. Load secrets through the application's explicit configuration system and avoid logging Options.

Provider-specific parameters

EndpointParameters supports bounded values such as audience. Standard OAuth2 fields (client_id, client_secret, grant_type, and scope) cannot be overridden. AuthStyleHeader is the default; select AuthStyleParameters only for providers that explicitly require credentials in the form body.

Verification

make check
make compatibility
make lint
make release-rehearsal
make security
make verify
make verify-release

The final gate checks formatting, modules and vendor reproducibility, vet, allowlisted linting, NilAway, gosec, govulncheck, shuffled/race tests, coverage, minimum/current Spice compatibility, and offline vendor execution. Local TLS fixtures prove token and resource behavior without external services.

Release rehearsal validates the exact spice-dev renderer and spice-library-release-verify verifier authorized by go.mod, then renders the same inert plan twice entirely from vendor with network and workspace resolution disabled. It requires byte-identical outputs, canonical checksums, central-renderer SPDX provenance, and no rehearsal signatures on Windows and Linux.

See docs/dependency-review.md for the dependency decision and docs/support.md for the support policy.

Releases

Each version tag is an ordinary Go module release. The repository also builds an exact-commit source archive, committed-graph SPDX 2.3 SBOM, SHA-256 checksums, and an Ed25519 signature/public key without an external release build system. Production mode requires a clean checkout, exact tag, and protected signing key; an explicit unsigned rehearsal is available for local proof. See docs/releasing.md for the artifact and trust contract. The protected central workflow is the sole release authority. It validates the candidate without credentials, renders and signs with immutable trusted code, authenticates the result with an independent verifier, and publishes only after separate protected approvals.

License

Apache License 2.0.