feat(token)!: namespace server-attested private claims under JWT_PRIVATE_CLAIM_PREFIX

[appleboy]

Summary

Introduces JWT_PRIVATE_CLAIM_PREFIX (default "extra") — a configurable namespace AuthGate prepends (with an _ separator AuthGate adds itself) to every server-attested private JWT claim. With the default, JWTs now carry extra_domain / extra_project / extra_service_account instead of bare domain / project / service_account. A deployment using JWT_PRIVATE_CLAIM_PREFIX=acme would emit acme_*. The bare logical names are gone — this is a hard cutover, called out below as a breaking change.

The new claim list lives in an unexported registry inside internal/token exposed via token.PrivateClaimRegistry() (returns a defensive copy). Future additions are a one-line append rather than scattered edits across emission, reserved-keys, and tests.

⚠️ BREAKING CHANGE

Server-attested private claims are no longer emitted under their bare names. Downstream services that read claims["domain"] / claims["project"] / claims["service_account"] directly must update at the same time as the AuthGate upgrade:

// before
domain := claims["domain"].(string)

// after (default prefix)
domain := claims["extra_domain"].(string)

// after (operator-chosen prefix, e.g. JWT_PRIVATE_CLAIM_PREFIX=acme)
domain := claims["acme_domain"].(string)

Token cache flush required. Tokens minted before the upgrade may sit in the cache with bare-name claims. Flush the token cache (Redis FLUSH or restart with empty memory cache) on upgrade, or wait for tokens to expire naturally. There is no automatic cache-key namespace bump.

AI Authorship

• AI was used. Details:
  • Tool / model: Claude Opus 4.7 (1M context) via Claude Code, executing plan.md
  • AI-authored files: every file in this PR
  • Human line-by-line reviewed: TODO — author should mark which files they walked through line-by-line. Recommend prioritizing internal/config/config.go (validation), internal/token/reserved.go (reserved-set logic), internal/services/token.go (buildClientClaims / buildServerClaims / composeIssuanceClaims), and internal/services/token_extra_claims_parser.go.

Change classification

• Core code (broad impact — needs line-by-line review)

This change alters the wire format of every issued JWT in every grant flow (authorization_code, device_code, client_credentials, refresh_token). Failure or regression spreads to every downstream consumer of AuthGate tokens. Reviewers should treat the issuance and reserved-key paths as security-critical.

Plan reference

Implementation followed plan.md on the branch. Goal: introduce a configurable prefix so downstream services can syntactically distinguish AuthGate-private claims from OIDC public claims, removing the per-deployment lookup table. Hard cutover by design.

Verification

• Unit tests
• Integration tests (services-level with sqlite store)
• At least 3 e2e tests (1 happy path + 2 errors)
• Stress / soak test: N/A — no new long-running paths
• Manual verification suggested for reviewer:
  1. Boot with default config → issue any token → confirm JWT carries extra_domain / extra_project / extra_service_account (when configured) and bare names are absent.
  2. Set JWT_PRIVATE_CLAIM_PREFIX=acme, restart → issue token → confirm acme_* keys, extra_* and bare names absent.
  3. POST to /oauth/token with extra_claims={"extra_domain":"evil"} → expect 400 invalid_request.
  4. curl /.well-known/openid-configuration → confirm claims_supported does not list extra_domain (or any <prefix>_* private claim).
  5. Set invalid prefixes (extra_, 1bad, 16-char) → expect startup failure with a clear message.

Test coverage added in internal/services/token_private_claim_prefix_test.go:

Test	Covers
TestPrivateClaimPrefix_DefaultPrefix_HappyPath	client_credentials with default prefix; bare names absent
TestPrivateClaimPrefix_CustomPrefix	acme prefix; extra_* and bare names absent
TestPrivateClaimPrefix_CallerCannotImpersonatePrefixedClaim	Two-layer defense: parser rejection + service-layer override
TestPrivateClaimPrefix_CallerCannotInjectBareLegacyName	Bare domain/project/service_account blocked at parser AND stripped at sign time
TestPrivateClaimPrefix_CallerCannotInjectDefaultPrefixOnCustomDeployment	On prefix=acme, smuggled extra_* blocked at parser AND stripped at sign time
TestPrivateClaimPrefix_RefreshContinuity	Refresh re-emits prefixed claims correctly
TestPrivateClaimPrefix_RegistryTableDriven	EmittedName composes consistently for every entry returned by PrivateClaimRegistry()
TestJWTPrivateClaimPrefix_StartupValidation	Empty / digit-prefix / hyphen / trailing-_ / oversized prefix
TestDetectPrefixCollision_Synthetic (config package)	Collision-rejection branch via pure helper + synthetic logical name

Existing tests (token_domain_test.go, token_extra_claims_test.go, local_test.go, reserved_test.go, oidc_test.go) were updated to use the prefixed names from config rather than the deleted constants.

make generate && make fmt && make lint && make test are all green.

Verifiability check

• Inputs and outputs documented (env var, JWT key shape) in .env.example, docs/CONFIGURATION.md, docs/JWT_VERIFICATION.md, CLAUDE.md
• Reviewer can judge correctness from tests + helper signatures (EmittedName, BuildReservedClaimKeys, composeIssuanceClaims)
• Failures surface at startup (Config.Validate()) with a clear message naming the bad prefix and the conflicting key

Security check

• No secrets in code
• All external inputs validated. The parser's reserved set now includes (1) the static RFC/OIDC/AuthGate-internal keys, (2) <prefix>_<logical> for every registry entry, (3) the bare logical names (domain / project / service_account) so callers cannot smuggle the legacy pre-prefix keys past it, and (4) the default-prefixed forms (extra_*) — reserved even on custom-prefix deployments so an un-migrated downstream consumer hardcoded to the default cannot be tricked.
• Defense-in-depth at sign time. generateJWT strips the OIDC ID-token-only keys (nbf / azp / amr / acr / auth_time / nonce / at_hash), the bare logical names, and (on custom-prefix deployments) the default-prefixed forms — so a future regression that bypasses the parser still cannot land any of these in the signed JWT.
• Server-attested <prefix>_domain still wins on collision: applyServerClaims writes it last, overriding caller- or client-supplied values.
• OIDC discovery claims_supported excludes bare AND prefixed AuthGate-private claim names under default and custom prefixes (oidc_test.go exercises all three configurations).
• JWT_DOMAIN semantics unchanged (server-attested, validated at startup, re-resolved on refresh).

Defense-in-depth coverage:

• TestPrivateClaimPrefix_CallerCannotImpersonatePrefixedClaim — parser rejection + service-layer override for the configured prefix's composed key.
• TestPrivateClaimPrefix_CallerCannotInjectBareLegacyName — bare names blocked at both layers.
• TestPrivateClaimPrefix_CallerCannotInjectDefaultPrefixOnCustomDeployment — extra_* blocked at both layers when configured prefix is non-default.

Risk & rollback

Risk

• Silent breakage of downstream JWT consumers that hardcoded claims["domain"]. Mitigation: prominent migration note in .env.example / docs/CONFIGURATION.md / docs/JWT_VERIFICATION.md / CLAUDE.md and this PR description; downstream integration smoke tests should run before merge.
• Stale token cache after upgrade. Mitigation: documented operational requirement to flush the token cache on deploy. No code-level cache-key namespace bump in this PR (could be added later as a follow-up if operators want zero-touch cutover).
• Misconfigured prefix at startup. Mitigation: Config.Validate() fails fast with a clear message naming the bad value or the colliding composed key.

Rollback

Revert the PR. Tokens minted under the new code carry only prefixed claims; downstream services that already migrated will need a coordinated revert. Treat this as a one-way door once consumers adopt — the practical rollback window is short.

Reviewer guide

Read carefully (line-by-line):

• internal/config/config.go — validateJWTPrivateClaimPrefix (regex / length / trailing-_ / collision check) and the static reserved-keys list. Note the documented sync requirement with internal/token/reserved.go (the import cycle prevents sharing).
• internal/token/reserved.go — BuildReservedClaimKeys semantics; ValidateExtraClaims now takes a precomputed reserved set rather than reading a package-level map.
• internal/services/token.go — buildClientClaims(client, prefix), buildServerClaims(cfg), composeIssuanceClaims (precedence caller → client → server unchanged).
• internal/services/token_extra_claims_parser.go — NewExtraClaimsParser precomputes the reserved set at construction time using the configured prefix.
• internal/token/types.go — unexported privateClaims registry + PrivateClaimRegistry() accessor (returns a defensive copy) + EmittedName(prefix, logical) helper. Single source of truth for key composition; mutation from other packages is impossible by construction.

Spot-check OK:

• Test files (signatures + the new token_private_claim_prefix_test.go matrix tell the story).
• Doc updates in .env.example, docs/CONFIGURATION.md, docs/JWT_VERIFICATION.md, CLAUDE.md.

Suggested reviewer count: 2+ (core code) — including the token / OAuth module owner.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 73.10924% with 32 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/config/config.go	53.70%	20 Missing and 5 partials ⚠️
internal/token/types.go	33.33%	4 Missing ⚠️
internal/token/reserved.go	88.46%	2 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR introduces a deployment-configurable namespace prefix (JWT_PRIVATE_CLAIM_PREFIX, default "extra") for AuthGate server-attested private JWT claims, moving them from bare keys (domain, project, service_account) to prefixed keys (<prefix>_domain, <prefix>_project, <prefix>_service_account). It also centralizes the private-claim registry to reduce scattered wiring across emission, reserved-key checks, and tests.

Changes:

• Add JWT_PRIVATE_CLAIM_PREFIX config support, defaults, and startup validation (shape/length/trailing _/collision guard).
• Introduce token.PrivateClaims registry and token.EmittedName(prefix, logical) helper; update issuance paths to emit prefixed keys.
• Update extra-claims reserved-key derivation and parser logic to be prefix-aware; refresh/flow tests and docs updated accordingly.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
internal/config/config.go	Adds default/validation for JWT_PRIVATE_CLAIM_PREFIX, including regex/length and collision checks.
internal/config/config_test.go	Ensures base test config includes the new prefix default.
internal/token/types.go	Adds PrivateClaims registry and EmittedName composition helper.
internal/token/reserved.go	Reworks reserved-claim handling to be prefix-derived via BuildReservedClaimKeys and updates ValidateExtraClaims signature.
internal/token/reserved_test.go	Updates reserved-key and ValidateExtraClaims unit tests for prefix behavior.
internal/services/token.go	Emits client/server private claims using the configured prefix during issuance composition.
internal/services/token_test.go	Sets default prefix for tests that construct Config{} ad-hoc.
internal/services/token_extra_claims_parser.go	Precomputes reserved-key set once per parser instance and validates using it.
internal/services/token_extra_claims_parser_test.go	Ensures parser tests use default prefix config.
internal/services/token_extra_claims_test.go	Updates claim-building and server-override tests to expect prefixed keys.
internal/services/token_domain_test.go	Updates domain-claim tests to validate prefixed domain emission/omission.
internal/services/token_private_claim_prefix_test.go	Adds an end-to-end-ish test matrix for default/custom prefix behavior and validation.
internal/token/local_test.go	Updates provider injection tests to use prefixed keys.
internal/handlers/oidc_test.go	Ensures discovery claims_supported doesn’t list private claims (bare or prefixed default).
docs/JWT_VERIFICATION.md	Updates verification/migration guidance to prefixed private-claim keys.
docs/CONFIGURATION.md	Documents new env var, validation rules, and migration notes.
.env.example	Documents new env var, breaking change, and cache-flush guidance.
CLAUDE.md	Updates configuration reference to include the new prefix behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.