refactor(access): readability + maintainability sweep + introduce mockery

[jmgilman]

Summary

First slice of a multi-session refactor sweep across the codebase, targeting readability, maintainability, and architectural purity (hexagonal, strong typing, strong contractual boundaries). Scope is the two packages under access/: access/jwt/ and access/middleware/. Explicitly non-functional — no schema, port, or behavioural changes.

Highlights

access/jwt/

• Rename IssuedToken.Plaintext → IssuedToken.JWT (cascaded through consumers in exchange/, http/compose/, testkit/, authz/role/). Plaintext falsely implied "unencrypted body" in a crypto package; the field carries the signed compact JWS serialization.
• Rename the matching VerifyToken parameter to jwt and document it as accepting a compact JWS.
• Add godocs to every private helper across keys.go, issuer.go, verifier.go.
• New validation.go absorbs the cross-file validateRequiredString so Issuer and Verifier share the helper from a neutral location.
• Annotate validateProtectedHeaders as the JWS security gate, with one comment per check naming the attack class it defends against (multi-signature, token-type confusion, ambiguous kid, alg substitution, unrecognised crit per RFC 7515 §4.1.11).
• Split the 600+ line monolithic jwt_test.go into issuer_test.go, verifier_test.go, and helpers_test.go. No tests added, removed, or reorganised.

access/middleware/

• Compile-time assertion: var _ authkit.PrincipalAuthenticator = (*Authenticator)(nil). Makes the port relationship explicit.
• Godocs on bearerToken and unauthenticated; inline comments on the security-relevant branches (existence-leak defence, defensive principal.ID check, RFC 7235 case-insensitive bearer scheme).
• Test refactor: replace memory.Store with the generated authkitmocks.PrincipalFinder. Add three previously-missing rejection cases (cancelled context, nil request, internal finder error) plus a regression test for the principal.ID == "" defence.

Mockery introduction (first time in this repo)

• Add github.com/vektra/mockery/v3 v3.7.0 as a go.mod tool dependency so go tool mockery works with no system install.
• .mockery.yaml configures generation; today it only covers authkit.PrincipalFinder. Future passes append interfaces as their consumer tests get refactored.
• Generated mock lands at mocks/authkit/principal_finder.go in package authkitmocks.
• New generate Moon task wraps the invocation; CI drift-detection is a follow-up once more mocks land.

Deliberately NOT changed

• No new port interfaces. *jwt.Verifier is the single concrete adapter; access/middleware is its single consumer. Adding an interface today would be a "might-be-useful-later" abstraction explicitly forbidden by the refactor brief.
• validateProtectedHeaders is not split. Inline comments are the right tool for explaining each security check; splitting would scatter the gate.
• unauthenticated helpers stay duplicated across jwt and middleware. Two three-line copies; a shared package would add API surface for trivial savings.
• apikey.IssuedToken.Plaintext stays. That's proof/apikey/'s pass, not this one.

Test plan

• moon run root:check --summary minimal — format, lint, build, unit tests, integration tests with Testcontainers. All green.
• go test ./access/... — all 28 sub-tests pass (jwt + middleware).
• go vet ./... clean across the module.
• go doc -all github.com/meigma/authkit/access/jwt diff against master: only IssuedToken.Plaintext removed and IssuedToken.JWT added.
• go doc -all github.com/meigma/authkit/access/middleware diff against master: empty (the interface assertion is package-private from the doc perspective).
• Reviewer functional check: testkit pastebin login flow if anything looks suspicious in the rename cascade.

🤖 Generated with Claude Code