refactor(proof/oidc): readability + maintainability sweep

[jmgilman]

Summary

Eighth slice of the multi-session readability sweep (after access/ #61, authz/ #62, exchange/ #63, http/ #64, management/ #65, onboarding/ #66, proof/apikey/ #67). Second of three PRs covering proof/. Same 10-criteria bar.

proof/oidc/ is the JWT trust gate for externally-issued OIDC tokens. The signature work this PR carries is annotating that gate.

Security inline comments on Verifier.VerifyToken

proof/oidc/verifier.go::VerifyToken is analogous to access/jwt/verifier.go (PR #61) but lacked the per-check security annotations. Each branch now carries a comment naming the attack class it defends against:

• Empty-token rejection — signal amplification.
• Unverified-issuer partial parse — lookup-then-verify rationale.
• Trusted-issuer lookup — untrusted-issuer defense.
• Provider-issuer consistency check — config-swap / storage-bug defense.
• Provider revalidation — corrupt trust-store row defense.
• jwt.Parse omnibus — forgery, expiration bypass, time confusion, key-use smuggling.
• Explicit non-empty subject — blank-subject confusion (defense in depth over jwt.Parse's required-claim check).
• Audience match — audience confusion.

Test split

verifier_test.go (616 LOC) split per-domain mirroring the production layout:

• provider_test.go — Provider.Validate tests.
• source_test.go — StaticProviderSource tests.
• verifier_test.go — Verifier.VerifyToken tests only.
• helpers_test.go — fixtures, testIssuer, tokenRequest, failingProviderSource, fixedTime.

Other oidc changes

• Godocs added to every private type, struct, and helper: options, defaultOptions, cachedKeySet, keySetRequest, the source.go clone family, claimPathKey, cloneClaimValue, validateHTTPSURL, signingAlgorithms, unverifiedIssuer, audienceAllowed, forwardClaims, mergedForwardedClaims, tokenClaim, setClaim, keySet, keySetCacheKey, fetchKeySet, constrainKeySet, verificationKey, keyAllowsVerification, unauthenticated.
• Several godocs name the security invariant they preserve (HTTPS-only URLs, symmetric-algorithm refusal, maxJWKSBytes cap, fail-closed empty-key-set, JWK use/key_ops gating).
• Compile-time var _ ProviderSource = (*StaticProviderSource)(nil) assertion added to source.go. Store-side ProviderSource/ProviderTrustStore assertions already live in the store packages' _test.go files.

Explicitly NOT changed

• ProviderSource stays as an interface. The plan considered demoting it to a function type but it has three implementations (StaticProviderSource, store/memory.Store, store/postgres.Store) and is embedded by ProviderTrustStore. The premature-port demotion rule (one method + one implementation) does not apply.
• No file reorganization. Current split (doc.go/options.go/source.go/types.go/verifier.go) is coherent.
• No mockery entries. Package is a leaf consumer; existing hand-rolled failingProviderSource is appropriate.

Commits

1. refactor(proof/oidc): godocs on private types and helpers
2. refactor(proof/oidc): security inline comments on Verifier.VerifyToken
3. test(proof/oidc): split verifier_test.go per domain
4. refactor(proof/oidc): compile-time port assertion for StaticProviderSource

Test plan

• moon run root:check --summary minimal — format, lint, build, unit, Testcontainers integration all green.
• All existing tests pass; no test logic changed in the split.

🤖 Generated with Claude Code