refactor(authz): readability + maintainability sweep

[jmgilman]

Summary

Second slice of the multi-session refactor sweep. PR #61 brought access/ up to the bar; this PR applies the same 10 criteria to authz/role/ and authz/casbin/. Same non-goals: bugs, correctness, performance.

Highlights

authz/role/

• Compile-time assertion: var _ authkit.Authorizer = (*Authorizer)(nil).
• Tightened Authorizer godoc into a contract statement; documented the deniedReason constant.
• Inline comment on the post-resolver ctx.Err() re-check explaining the cancellation-mid-resolution rationale.
• Replaced the hand-rolled fakeActionResolver with the generated authkitmocks.PrincipalActionResolver. Each table case now configures its mock expectations explicitly. The TestAuthorizerAllowsHTTPMiddlewareThroughAccessJWT end-to-end test still uses memory.Store — the right shape for an integration test (matches access pass's TestVerifiedTokenUsesStorageBackedAuthorization).

authz/casbin/

• Compile-time port assertion (same shape as role).
• Reason-string cleanup: "casbin policy denied" → "policy denied". The adapter's implementation name does not belong in the API response; grep confirms no consumer asserts on the literal.
• Godocs on every private symbol (deniedReason, resourceObject, options, defaultOptions); expanded WithRequestBuilder godoc to call out the nil-leaves-default behaviour.
• Tightened Can godoc.
• Inline annotations on the security-relevant branches: fail-closed input validation in DefaultRequestBuilder, the post-projection ctx.Err() re-check, and the type-only-resource form in resourceObject.
• Test file split: 433-line authorizer_test.go → authorizer_test.go (Can + NewAuthorizer cases), request_builder_test.go (DefaultRequestBuilder cases), helpers_test.go (test fixtures + real Casbin enforcer helper). Mechanical lift; every test function preserved verbatim.

Mockery

• Appended authkit.PrincipalActionResolver to .mockery.yaml. The pattern is now: one entry per root-package port that consumer tests need to mock. Adapter-local ports (e.g. casbin.Enforcer) stay hand-rolled.
• Generated mocks/authkit/principal_action_resolver.go.

Deliberately NOT changed

• No new ports in either package. casbin.Enforcer and casbin.RequestBuilder already serve as extension points; promoting them to a ports.go file would mirror nothing else in the codebase.
• No mock for casbin.Enforcer. Adapter-local port for a third-party library; the hand-rolled testEnforcer is small and clear.
• No merge of casbin/options.go into authorizer.go. Five other packages in the repo use a dedicated options.go (proof/oidc/, proof/apikey/, proof/passkey/session/, http/auth/, this one). Consistency wins.
• No deduplication of TestDefaultRequestBuilderValidatesRequiredInputs vs TestAuthorizerCanReturnsDefaultProjectionErrors. They cover the same input rules at different layers; the second test also asserts the enforcer is never called — defense in depth for a security-critical path.
• No rename of role.deniedReason ("action not granted"). Already neutral and accurate.

Test plan

• moon run root:check --summary minimal — format, lint, build, unit, Testcontainers integration. All green.
• go test -v ./authz/... — all sub-tests pass (role + casbin), same case count as pre-split for casbin.
• go tool mockery is idempotent; second run produces no diff.
• Public-surface diff: only godoc text changes for role.Authorizer.Can and casbin.Authorizer.Can, plus one observable string change (Decision.Reason from "casbin policy denied" → "policy denied").

🤖 Generated with Claude Code