authorization

Authorization

Role-based access control implemented in plain code on top of AdonisJS Bouncer — no external RBAC library. Four moving parts:

1. PERMISSIONS — a const catalog of every capability the app understands.
2. ROLES — a const catalog of role slugs, each with a weight used to pick a display role.
3. WithRoles — a mixin composed into User that grants assignRole / hasRole / hasPermission / syncRoles.
4. BasePolicy subclasses — enforce hasPermission(...) at the controller.

On the frontend a typed GlobalPermissions object flows through Inertia's shared props and is consumed via useCan(). Adding a permission is a two-line change (PERMISSIONS const + wherever it's gated); adding a role is a config + seed touch.

Rules

• Single source of truth for capabilities in a PERMISSIONS const object under the users module. Naming: <mod>.<action> (users.create, tokens.view_list). Adding a permission = adding one entry + referencing it wherever it's gated. A new module's capabilities go in this same const — the <mod>.<action> naming already namespaces them; don't fork a second PERMISSIONS. One central catalog; the policies that consume it stay in each module.
• Role slugs live in a ROLES const with a matching ROLE_WEIGHTS map. The weights drive mainRole() for display ordering. Adding a role = new entry + a seed that grants its permissions.
• Roles store their own permissions on the Role model as a JSON column (role.permissions: Permission[]). Seed with Role.updateOrCreate({ name }, { permissions: [...] }).
• WithRoles mixin composes into User next to withAuthFinder. It exposes:
  • Mutations: assignRole(role), assignRoles(roles), syncRoles(roles), revokeRole(role), revokeRoles(roles).
  • Checks: hasRole(name), hasPermission(permission).
  • Reads: getRoleNames(), getPermissions(), preloadedRoles (sync read of .load('roles')).
• Policies subclass BasePolicy and live at app/<mod>/policies/<entity>_policy.ts. One method per gated action. Signature: currentUser first, resource second when applicable. Return boolean | AuthorizerResponse.
• Gate at the controller before validating: await bouncer.with(EntityPolicy).authorize('methodName', resource?). On deny it throws → 403 (JSON) or 302 back (HTML/Inertia). Every mutation route (POST/PUT/PATCH/DELETE) must be gated by a Bouncer policy — no exceptions.
• Frontend shared prop: an Inertia middleware computes a small can: GlobalPermissions object (manageUsers, manageTokens, …) and shares it on every request. Read with useCan(). Extending the object = adding a boolean field to global_permissions.ts computed from user.hasPermission(PERMISSIONS.x); useCan types update automatically.
• Escalation guards are defense-in-depth on top of validators:
  • requireManageRoles(executor) — throws if the executor lacks users.manage_roles.
  • requireManageRolesIfEscalating(executor, desiredRoles) — enforces the check even when a validator accepted a non-default role. Call at create / invite paths.
  • AdminLockoutException — prevents a user from removing their own admin role. Raised inside SyncUserRoles when target and executor are the same and admin is being dropped.