Introduce JWTProfile for declarative JWT validation

[stevenvegt]

Summary

JWT validation was scattered across the codebase with ad-hoc checks after ParseJWT calls. Each JWT type (access token, bearer token, JAR, OpenID4VCI proof, VC, VP) had its own validation pattern — some re-parsed the JWS to read headers, some duplicated iss-to-kid binding, and critically the v1 access token introspection did not call jwt.Validate at all, so tokens without exp/iat were silently accepted with no max-lifetime enforcement. Clock skew tolerance was also inconsistent: the operator-configured auth.clockskew only reached two of the five ParseJWT call sites; the rest defaulted to 0.

This PR introduces a declarative JWTProfile type and threads it through ParseJWT. All caller sites now share one validation shape, one skew policy, and one place to reason about what each JWT type requires.

Changes

Core: crypto/jwt_profile.go + crypto/jwx.go

JWTProfile declares:

• Typ — required typ header value
• RequiredClaims — must be present and non-empty
• MaxValidity — max allowed exp - iat delta (auto-requires exp/iat via jwx's WithMaxDelta)
• ClockSkew — acceptable clock skew; zero falls back to DefaultJWTClockSkew (5s)
• Validators — additional checks (e.g. IssuerKidValidator)

Fluent overrides WithMaxValidity(d) and WithClockSkew(d) let callers override per-call without mutating the shared profile globals.

ParseJWT's signature becomes (tokenString, keyFunc, profile, at *time.Time):

• Typ is checked early, before signature verification.
• MaxValidity and ClockSkew flow into jwx's validation pass.
• Presence + non-empty is checked post-parse; errors mirror the jwx format ("<claim>" not satisfied: ...) for consistency.
• Custom validators run last.
• The variadic jwt.ParseOption is gone; historical verification uses the explicit at *time.Time (only VC/VP signature verification passes non-nil).

Profiles

• v1AccessTokenProfile (auth/services/oauth) — typ: "at+jwt", requires iss/sub/service/exp/iat, iss-to-kid binding, max lifetime tracks configured accessTokenLifeSpan
• v1BearerTokenProfile (auth/services/oauth) — requires iss/sub/exp/iat/aud, max 5s (aud set by claimsFromRequest, required because the builder always sets it)
• jarProfile (auth/api/iam) — requires iss/iat/exp, max 5m; iat/exp are set in Sign() (not Create()) because the jarRequest is persisted between two HTTP requests — setting them at Create would eat into the validity window
• openID4VCIProofProfile (vcr/issuer) — typ: "openid4vci-proof+jwt", requires iat/aud (aud comparison against i.issuerIdentifierURL still runs post-parse)
• vcJWTProfile (vcr/verifier) — iss-to-kid binding for JWT VCs
• vpJWTProfile (vcr/verifier) — requires nbf as issuance anchor

Clock skew unification

• auth.clockskew config now reaches every ParseJWT call site via profile.WithClockSkew(s.clockSkew) (previously only two call sites honored it).
• DefaultJWTClockSkew (5s) applies whenever a profile doesn't set its own — no more silent zero-skew defaults for JAR/VC/VP paths.
• OpenID4VCI proof's hardcoded WithAcceptableSkew(5s) is gone (covered by the default).

VP hardening

The VP builder (vcr/holder/presenter.go) now always sets iat and exp (default 15m when caller doesn't pass Expires). Previously VPs created via /internal/vcr/v2/holder/vp could lack an expiration.

Removed

• Ad-hoc jwt.Validate call and manual iss/sub/service checks in IntrospectAccessToken
• Manual JWT validity too long check in validateAccessTokenRequest
• jws.ParseString re-parse in vcr/issuer/openid.go that existed only to check typ
• Redundant strings.Split(keyID, "#")[0] != issuer check in the VC signature path (covered by IssuerKidValidator)
• Redundant jwt.WithRequiredClaim loop in ParseJWT (presence check is already done post-parse; jwx's WithMaxDelta auto-requires its time claims)

Test plan

• go test ./... passes
• TestService_IntrospectAccessToken covers: missing/wrong typ, VP JWT replayed as access token, missing service/iss/exp/iat, iss/kid DID mismatch, excessive lifetime (both the strict 60s and configurable accessTokenLifeSpan paths), expired token
• New TestParseJWT cases for default clock skew and profile-level override
• JAR Create/Sign/Parse tests verify iat/exp are set at sign time, caller's map is not mutated, and the 5m max is enforced on receive
• Existing test assertions updated to the jwx-style error format ("<claim>" not satisfied: ...)

🤖 Generated with Claude Code

[qltysh]

6 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 8): validate	6

[qltysh]

Coverage Impact

⬇️ Merging this pull request will decrease total coverage on master by 0.04%.

Modified Files with Diff Coverage (7)

Rating	File	% Diff	Uncovered Line #s
	crypto/jwx.go	51.1%	183-184, 187-190...
	vcr/issuer/openid.go	100.0%
	auth/api/iam/jar.go	100.0%
	vcr/holder/presenter.go	100.0%
	vcr/verifier/signature_verifier.go	100.0%
	auth/services/oauth/authz_server.go	100.0%
	crypto/jwt_profile.go	19.0%	56-59, 71-83
	Total	57.9%

🤖 Increase coverage with AI coding...

In the `tighten-jwt-checks` branch, add test coverage for this new code:

- `crypto/jwt_profile.go` -- Lines 56-59 and 71-83
- `crypto/jwx.go` -- Lines 183-184, 187-190, 215-216, 226-227, and 244-261

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.