Authorization

Role-based access control (RBAC) system for the Club Wilo platform.

RBAC Overview

The platform uses a permission-based authorization model where:

• Users are assigned a role
• Roles contain a set of permissions
• Permissions follow the entity:action pattern (e.g., users:read, roles:write)
• Access to API endpoints and frontend routes is controlled by checking permissions

Wildcard Permission

The special wildcard permission * grants unrestricted access to all resources. Only the SuperAdmin role uses this — instead of listing every individual permission, the backend returns ["*"] and both backend and frontend recognize it as full access.

This simplifies permission checks and ensures SuperAdmin always has access to new permissions without requiring updates.

Built-in Roles

Role	Permissions	Description
SuperAdmin	* (wildcard)	Full platform access
Employee	profile:read, profile:write	Basic employee access
User	profile:read, profile:write	End customer access

Administrators can create additional roles with custom permission sets through the admin panel.

Permission Catalog

Permission	Description
users:read	View user list and details
users:write	Create and update users
users:delete	Soft-delete users
roles:read	View roles and their permissions
roles:write	Create roles and modify permissions
roles:delete	Delete roles
permissions:read	View available permissions
profile:read	View own profile
profile:write	Update own profile
audit:read	View audit logs
members:read	View member list and details
members:write	Create and update members
members:delete	Delete members
settings:write	Modify platform settings
blacklist:write	Blacklist users

How Authorization Works

Backend Flow

1. User authenticates and receives a JWT containing sub (user ID) and role claims
2. API endpoints declare required permissions via .RequireAuthorization("permission-name")
3. PermissionAuthorizationHandler extracts the user ID and role from the JWT
4. PermissionService resolves the user's permissions (with FusionCache for performance)
5. If the user has the wildcard * or the specific required permission, access is granted

Frontend Flow

1. After login, the auth store fetches the user profile including their permissions array
2. hasPermission(p) checks if the user has * or the specific permission
3. hasAnyPermission(...perms) checks if the user has * or any of the listed permissions
4. The permissionGuard router guard checks that the user has all permissions declared in the route's meta.permissions array (AND logic)
5. Routes without meta.permissions are accessible to any authenticated user

Route Protection

Routes declare required permissions in their meta configuration:

{
    path: '/admin/users',
    meta: {
        requiresAuth: true,
        permissions: ['users:read', 'roles:read'] // ALL required (AND logic)
    }
}

The guard uses AND logic — the user must have every listed permission to access the route. A user with the wildcard * permission automatically satisfies all checks.