go-authcrunch: Skill for Codex

Refresh Token Implementation

The implementation is opt-in under authn.PortalConfig.RefreshTokens. The reusable token/session engine lives at pkg/authn/token_refresh, with Go package identifier tokenrefresh. Use that import path and qualifier in consumers. Read configuration and client contract when exposing settings, integrating clients, or changing public behavior. Read the managed storage contract when selecting a borrowed refresh backend, assembling a root or standalone portal, or changing generation activation and readiness. Use refresh-token-identity to change login proof, MFA completion, sandbox redemption, credential-version revalidation, and captured upstream provider evidence. Use refresh-token-transports to change refresh/logout HTTP routes, cookies, native transport, browser coordination, continuation, and fresh login. These are distinct boundaries; a change may require more than one owner.

Directive support here is the public parser package and its portal integration. The block example in the client contract describes an embedding parser's input; it does not establish implemented Caddyfile support. Keep the parser and its unit/E2E coverage in this module. Never modify sibling directories for consumer integration; those repositories are updated separately.

Ownership

• pkg/authn/token_refresh_config.go: serializable config, defaults, canonical HTTPS origin/mount validation, cookie naming, durations, and capacity bounds. The public type is authn.TokenRefreshConfig. An empty CookieName inherits the portal cookie factory; validation must leave it empty. An enabled explicit override feeds cookie_config.refresh_token_cookie_name before the factory's defaults and collision checks. The factory owns the effective runtime name.
• pkg/authn/token_refresh/parser: public NewTokenRefreshConfigFromDirectives([]string) (*authn.TokenRefreshConfig, error), using cfgutil.DecodeArgs for encoded statements from token refresh blocks. Directive keys use separate words; states use enabled/disabled keywords. Construction opts in, rejects duplicate/unknown/malformed directives, and delegates normalization to authn.TokenRefreshConfig.Validate. This package owns the parser implementation and its external-package unit tests; the portal model remains in pkg/authn. Additional authn.TokenRefreshConfig settings need corresponding grammar in this constructor and consumer coverage through PortalConfig.RefreshTokens.
• pkg/authn/portal.go: configured-realm capability checks, selected-store preflight, pending publication, failed-construction cleanup, and Portal.Close().
• pkg/authn/token_refresh_managed.go, persistent_state.go: persistent namespace/generation initialization, managed activation and publication.
• pkg/authn/token_refresh/managed.go: typed descriptors, immutable prepared bindings, managed metadata/readiness and borrowed generation views.
• pkg/authn/token_issuer.go: shared access/refresh issuance. HTTP and JSON sandbox login must call the same issuer; grantAccess only delivers signed output.
• pkg/authn/token_refresh_runtime.go: portal adapters, current transformations, challenge checks, and KMS signing.
• pkg/authn/token_refresh_provider.go: completed OAuth callback issuance, bounded provider snapshots, trust bindings, and provider-specific renewal.
• pkg/authn/token_refresh/{token,store,memory,manager}.go: opaque encoding, store contract, bounded in-memory families, and staged issuance/rotation.
• pkg/kms/crypto_keystore.go: legacy access signing-key lifetime selection.
• pkg/authn/access_signing.go: selected external signing, exact staged-claim verification and effective lifetime. Read the selected signing contract for the borrowed root/standalone boundary, strict profile and issuer equality.