Admin that earns trust. Not a CRUD table with a sidebar.
Role-based access control with permission guards, immutable audit log, safe impersonation with reason + TTL + audit chain, and user management. Built for production from day one.
See What You Get →$ asa install admin-basicAuto-installs dependencies: db-basic (auto), auth-basic (auto)
What You Get
Fully functional slices — not TODO skeletons.
dashboard
Admin overview — user counts, subscription stats, recent activity. Permission-gated server-side.
users
User list with search, pagination, and profile details. Requires admin.users.list permission.
roles
Assign and remove roles. 3 built-in roles (owner, admin, support) with canonical permissions.
impersonation
Safe impersonation — start/stop with mandatory reason, TTL expiry, HttpOnly cookie, and full audit chain.
audit-log
Filterable, paginated, immutable audit log viewer. Every admin action is tracked with actor, subject, and reason.
Generated File Map
Every file is real, functional code you own.
Security Guarantees
Built-in protection — not an afterthought.
Permission-based guards (not role strings)
Guards check requirePermission('admin.users.list'), not role === 'admin'. Permissions are decoupled from roles — safe to extend.
Immutable audit log
Append-only table with DELETE/UPDATE blocked by RLS policy. No admin can erase their own audit trail.
Safe impersonation (hybrid b+c model)
Admin session stays admin. Impersonation is server-side context only. No fake user JWT. Short-lived HttpOnly cookie with TTL.
Mandatory reason for impersonation
Every impersonation requires a reason (min 3 characters). Stored in audit log. Support and compliance traceability.
JWT claims via Custom Access Token Hook
User roles and permissions are embedded in JWT via Supabase Custom Access Token Hook. No extra DB query on every request.
Server-side permission enforcement
Every admin handler calls requirePermission() server-side. Lint rule SEC-003 blocks admin routes without server-side guards.
What This Prevents in Production
Real problems this module eliminates before they cost you customers.
Support team can't debug safely
Without safe impersonation, support staff share passwords or ask users for screenshots. Slow, insecure, and frustrating for customers.
No audit trail for admin actions
An admin deletes a user or changes a role — and there's no record of who did it or why. Compliance fails, trust erodes.
Role checks scattered as string comparisons
AI tools generate role === 'admin' everywhere. One typo or rename breaks access control across the entire app.
Admin can erase their own tracks
Mutable audit logs let bad actors cover incidents. Immutable, append-only logs are the minimum for customer trust.
No permission granularity
Either you're admin with full access, or you're not. No way to give support staff read-only user access without exposing billing controls.
Extension Points
Your code. Your rules. Extend when ready.
- →Add custom roles by extending the roles migration and permissions.ts
- →Add per-resource permissions by extending the permission constants
- →Add impersonation banner UI by reading getActiveImpersonation() in layout
- →Add audit log export (CSV/JSON) by extending the audit-log handler
- →Add IP/geolocation tracking by extending logAuditEvent() metadata
- →Add team/organization scoping by extending user_roles with org_id
Protected by 22 Lint Rules
Every module is enforced by ASA CLI's tiered lint engine. 8 blockers catch critical security issues. 8 warnings flag architectural risks. 6 info rules guide best practices.
Run asa lint anytime. Runs in CI too.
Admin control surface that customers trust.
Install admin-basic and ship RBAC, audit log, and impersonation today.
New app? Start with Build Right. Existing app? Start with a Quick Scan before stabilization.
View All Foundation Modules →