Admin: Prove the complete role and target permission matrix in integration tests

[gekichumai-admin]

Phase / step: Phase 5 — Hardening and rollout / Step 1
Parent: #301
Depends on: #325, #331, #332

Context and goal

Authorization regressions are the highest-risk failure mode in the administrator API. Add a table-driven, database-backed integration suite that proves every actor/target/action combination through the real HTTP, session, router, guard, and transaction layers rather than testing only isolated policy helpers.

Scope and implementation notes

• Define a human-readable permission matrix for unauthenticated callers, ordinary users, administrators, and allowlisted super administrators across administrator reads, ordinary-user moderation, administrator moderation, administrator grant/revoke, and attempts to affect super administrators.
• Cover target classes independently: ordinary user, database administrator, effective super administrator, missing user, and a target whose role changes between list/read and mutation.
• Exercise representative real endpoints for read access, role grant/revoke, ban/unban, and another moderation mutation. Assert both HTTP status and stable typed error code for every denied case.
• Prove that administrators can read administrator data and moderate ordinary users but cannot moderate administrators, grant/revoke administrators, or affect super administrators.
• Prove that super administrators can moderate ordinary users and database administrators and can grant/revoke administrators, while still being unable to target any effective super administrator.
• Include recent-primary-authentication cases for each destructive action: missing proof, expired proof, proof bound to another session, and valid proof within the ten-minute window.
• Include role/session transition cases: a pre-promotion session cannot access admin routes, a fresh post-promotion session can, and every session is invalid after ban or demotion.
• Include active temporary, expired temporary, and permanent ban cases across sign-in and authenticated writes. Preserve public anonymous reads in the same suite.
• Include the administrator Access-assertion boundary for every capability category: a valid application session without valid Access proof is denied before feature authorization, while a valid assertion never upgrades an ordinary user.
• Prove that an account's email-verification flag does not alter the role matrix or eligibility for promotion.
• Add a route-inventory assertion requiring every /api/admin procedure to declare a capability category and appear in the matrix. A newly added procedure without a declared expectation must fail CI.
• Use deterministic test-only immutable IDs for the super-administrator configuration. Do not mock the effective-role resolver or weaken the database safety checks used by the existing integration suite.
• Keep test failures diagnostic by printing actor class, target class, capability, expected result, and actual typed result without emitting cookies, credentials, or configured production values.

Acceptance criteria

• The committed matrix covers every combination of actor class, target class, and supported administrator capability.
• Tests call the real HTTP API with real Better Auth sessions and PostgreSQL data rather than bypassing middleware.
• Every expected denial asserts the correct typed 401 or 403 response and leaves database state unchanged.
• Administrator and super-administrator positive capabilities are proven without granting either class excess authority.
• No user, administrator, or super administrator can affect an effective super administrator through the application.
• Missing, expired, cross-session, and valid recent-authentication proofs are covered.
• Promotion, demotion, ban, unban, temporary expiry, and multi-session revocation semantics are covered.
• Verified and unverified accounts receive identical authorization outcomes when role and session state are otherwise equal.
• Test-signed Access assertions prove the outer-proof/application-RBAC combination without calling or weakening the external provider.
• CI fails when an administrator procedure is absent from the capability inventory/matrix.
• The complete integration suite passes repeatedly without order dependence or leaked database state.

Out of scope

• Browser-level end-to-end tests.
• Cloudflare Access policy testing.
• Performance/load testing of administrator endpoints.
• Testing features that are explicitly deferred from admin v1.