Effective permissions

Externa authorizes with session auth (Fortify), Spatie roles/permissions, and a custom effective permission layer that unions direct roles with roles inherited from user groups. Super-admins bypass ability checks via Gate::before.

Session authentication (Fortify)

User model traits include Spatie HasRoles, Fortify TwoFactorAuthenticatable + PasskeyAuthenticatable (PasskeyUser), and soft deletes. Passkeys guide: Passkeys.

Spatie Permission

• Package: spatie/laravel-permission
• Config: config/permission.php
• Canonical permission names live in App\Enums\PermissionEnum
• Sync command: php artisan permissions:sync (SyncPermissionsCommand)
  • Upserts DB permissions from the enum
  • Regenerates resources/js/enums/permission-enum.ts
• Seeders: PermissionSeeder runs sync; RoleSeeder creates built-in roles and syncPermissions

Admin FormRequests typically call AuthorizesWithPermission::authorizePermission(), which delegates to EffectivePermissionResolver::hasPermission().

PermissionEnum

All values (kebab-case strings):

Source: app/Enums/PermissionEnum.php. Helper: PermissionEnum::values().

RoleEnum

Built-in roles (app/Enums/RoleEnum.php), seeded in RoleSeeder:

Reader show set: every permission whose name starts with can-show- (dashboard, users, groups, roles, permissions, files, collections, activity logs, api keys, jobs, …). Reader does not get can-use-ai, can-manage-project-settings, or mutating file/collection permissions.

The public role cannot be assigned to users/groups, renamed, or deleted. Configure its Collection access matrix for anonymous API traffic.

EffectivePermissionResolver

Class: App\Services\Authorization\EffectivePermissionResolver (singleton in AppServiceProvider).

API

Resolution algorithm

1. Role names / ids = unique union of:
   • Direct: $user->roles
   • Via groups: roles attached to each of the user’s groups
2. If super-admin ∈ role names → permissions = full PermissionEnum::values()
3. Else permissions = unique union of:
   • Spatie $user->getAllPermissions() (direct + via assigned roles)
   • Permissions from roles attached through the user’s groups (group → role → permission)
4. Results are cached for the request keyed by user id

hasPermission returns true immediately for super-admins; otherwise checks membership in permissionsFor.

HomePath (post-login redirect) also uses EffectivePermissionResolver::hasPermission, so group-inherited can-show-* permissions affect where users land after login.

Gate::before

Configured in AppServiceProvider::configureAuthorization():

Gate::before(function (?User $user): ?bool {
    if ($user === null) {
        return null;
    }

    if (app(EffectivePermissionResolver::class)->isSuperAdmin($user)) {
        return true;
    }

    return null;
});

Super-admins therefore pass any Gate / authorize() ability check, including abilities that are not registered. Covered by tests/Feature/Authorization/SuperAdminGateTest.php.

Middleware

Aliases in bootstrap/app.php:

These are custom aliases (not Spatie’s default role / permission middleware package aliases).

Where they are applied

Admin (routes/admin.php): individual resources use ->middleware('permission:…') with the matching PermissionEnum value. All /files/* routes sit inside Route::middleware('can.manage.files').

AI (routes/ai.php): authenticated AI group uses auth + verified + permission:can-use-ai (some import status routes add further checks). Per-tool Spatie checks via ChecksAiPermissions; item tools also apply CollectionPermissionEnforcer (field ACL / item_filter).

Collections (routes/collections.php): auth + verified plus Spatie permission: per action (same pattern as admin). See Collections API.

Frontend: useCan and auth.permissions

Shared by HandleInertiaRequests:

'auth' => [
    'user' => $user,
    'permissions' => $user ? $permissionResolver->permissionsFor($user) : [],
    'roleNames' => $user ? $permissionResolver->roleNamesFor($user) : [],
    'isSuperAdmin' => $user ? $permissionResolver->isSuperAdmin($user) : false,
],

Hook: resources/js/hooks/use-can.ts

const { can, auth } = useCan()
if (can(PermissionEnum.CanEditCollections)) {
  // show edit UI
}

Helper userHasPermission (resources/js/lib/permissions.ts):

1. No user → false
2. auth.isSuperAdmin → true
3. Else auth.permissions.includes(permission)

Used by sidebar nav filtering, collections destructive actions, AI FAB visibility, admin screens, and similar UI gates.

Enforcement matrix

Related pages

• Public CMS API — headless /api/v1, public role, API keys
• Roles & permissions — product feature guide
• Architecture — shared props and middleware stack
• AI assistant model — tool-level permission gates
• Admin & files API — route-level permission strings