Role Hierarchy and Permissions

Purpose and Scope

This document describes how roles are organized hierarchically and how permissions are assigned to roles in the Light framework. It covers the default role hierarchy, permission definition sources (YAML files and database), role inheritance mechanisms, and the special permission markers used for role membership.

For information about how permissions are checked at runtime and enforced on GraphQL fields, see Permission Checking. For details about the User model and role assignments, see User Model and Sessions.

---

Default Role Hierarchy

The Light framework implements a four-tier default role hierarchy that is initialized during application bootstrap. This hierarchy provides a foundation for access control with each level inheriting permissions from the levels above it.

Diagram: Default Four-Tier Role Hierarchy with Permission Inheritance

The hierarchy is established in the loadRbac() method, where each role automatically inherits all permissions from its parent roles. The "Everyone" role is the base level that all authenticated users belong to by default, while "Administrators" sits at the top with wildcard permissions granting full system access.

Sources: src/App.php306-323

---

Role Initialization and Loading

Role and permission data is loaded from three distinct sources during application initialization, with each source serving a different configuration purpose.

Role Hierarchy Initialization Flow

Diagram: Role and Permission Loading Sequence During Application Bootstrap

Sources: src/App.php306-366

---

Permission Definition Sources

YAML Configuration File

The permissions.yml file provides static, version-controlled permission definitions for the default roles. This file is suitable for permissions that are integral to the application and should be consistent across all deployments.

Role	Permissions	Purpose
Administrators	* (wildcard)	Full system access to all operations
Power Users	user.list, user.read, user.add, user.delete, user.update, role.list, user.role.add, user.role.remove, user.changePassword, role.getUser	User and role management capabilities

The wildcard permission * for Administrators grants unrestricted access to all protected operations without requiring explicit permission grants.

Sources: permissions.yml1-15 src/App.php338-343

Database-Stored Permissions

The Permission model stores dynamic permission assignments that can be modified at runtime without code deployment. Each permission record can be assigned to either a role or a specific user.

Diagram: Database Schema for Role and Permission Storage

The Permission table supports two assignment modes:

• Role-based assignment: When permission.role is populated, the permission is granted to all users in that role
• User-specific assignment: When permission.user_id is populated, the permission is granted to a specific user directly

Sources: src/App.php345-355

---

Role Inheritance and Parent-Child Relationships

Database-Driven Role Hierarchy

Beyond the default four-tier hierarchy, custom role hierarchies can be defined through the Role model, which stores parent-child relationships between roles.

Diagram: Extended Role Hierarchy with Custom Roles

The Role model defines relationships where:

• Role.name represents the parent role
• Role.child represents the child role
• A child role inherits all permissions from its parent

This allows creating custom role hierarchies such as organizational structures (e.g., "Developer" → "Team Lead" → "Department Manager") that integrate with the default hierarchy.

Sources: src/App.php325-334

Implementation Details

The role hierarchy loading process:

1. Default hierarchy creation (lines 309-322): Four base roles are created with explicit parent relationships
2. Database role loading (lines 325-334): Custom parent-child relationships from the Role table are loaded
3. Role permission assignment (lines 338-355): Permissions from both YAML and database are applied to roles
4. User role assignment (lines 358-363): Users are assigned to roles via the UserRole table

Sources: src/App.php325-334

---

Special Permission Markers

Role Membership Permissions

The system uses a special permission syntax with the # prefix to represent role membership itself as a permission. This allows checking whether a user belongs to a specific role.

Permission Format	Meaning	Use Case
#administrators	User is a member of Administrators role	Role membership checks
#power users	User is a member of Power Users role	Role-based UI visibility
#everyone	User is authenticated	Basic authentication check
user.list	User can list users	Feature-specific permission

Role membership permissions are automatically created for every role in the system (both default and custom) by converting the role name to lowercase and prefixing with #.

Diagram: Role Membership Permission Generation

This mechanism is applied in three places:

1. Default role creation (lines 309-322)
2. Database role loading (lines 326, 328)
3. User role assignment (line 360)

Sources: src/App.php309-322 src/App.php326 src/App.php360

---

Menu-Based Permissions

The menus.yml file defines navigation menus with associated permissions. These permissions are automatically discovered and included in the system's permission list.

Menu Permission Structure

Menu items can specify:

• Single permission: permission: user.list
• Multiple permissions: permission: [permission.list, permission.add, permission:remove]
• No permission: Menu is accessible to all authenticated users

The getMenusPermission() method recursively extracts all permissions from the menu structure, flattening nested menus and collecting permission strings into a unified list.

Sources: menus.yml1-171 src/App.php368-390

---

Permission Discovery and Aggregation

The system automatically discovers permissions from multiple sources to build a comprehensive permission list. This list is used for permission management interfaces and validation.

Permission Source Matrix

Source	Location	Discovery Method	Purpose
GraphQL Controllers	src/Controller/*.php	Reflection scanning for @Right attributes	API operation permissions
Models	src/Model/*.php	Reflection scanning for @Right attributes	Data access permissions
Database Classes	src/Database/*.php	Reflection scanning for @Right attributes	Database operation permissions
Type Classes	src/Type/*.php	Reflection scanning for @Right attributes	GraphQL type permissions
Custom Controllers	Composer autoload	Namespace scanning for @Right attributes	Extension permissions
Custom Models	Composer autoload	Namespace scanning for @Right attributes	Extension data permissions
Menus	menus.yml + Config	Menu hierarchy traversal	Navigation permissions
RBAC System	Loaded roles	Role permission collection	Role-based permissions

The getPermissions() method aggregates all permissions and performs cleanup:

1. Filters out role membership permissions (starting with #)
2. Removes duplicates
3. Sorts alphabetically

Sources: src/App.php392-472

---

User Role Assignment

Users are assigned to roles through the UserRole model, which creates many-to-many relationships between users and roles. A user can belong to multiple roles simultaneously, inheriting permissions from all assigned roles.

User Role Assignment Flow

Diagram: User with Multiple Role Assignments and Permission Inheritance

During RBAC initialization, the system:

1. Queries all UserRole records (line 358)
2. For each record, ensures the role exists in RBAC (lines 359-360)
3. Assigns the role to the user, granting all role permissions (line 362)

Sources: src/App.php358-363

---

Permission Assignment Methods

The system provides a programmatic method for adding permissions to roles after initialization through the addRolePermissions() method.

This method:

1. Checks if the role exists, creating it if necessary
2. Retrieves the role object from RBAC
3. Adds each permission to the role

This method is used internally when loading permissions from permissions.yml and can be used by extensions to programmatically define custom permissions.

Sources: src/App.php294-304

---

Summary

The role hierarchy and permission system in Light provides a flexible, multi-source authorization framework:

• Four-tier default hierarchy: Everyone → Users → Power Users → Administrators with automatic permission inheritance
• Multiple definition sources: YAML files for version-controlled permissions, database for runtime-configurable permissions
• Parent-child relationships: Extensible role hierarchy through the Role model
• Special permission markers: # prefix denotes role membership as a permission
• Automatic discovery: Permissions are discovered from GraphQL annotations, menus, and RBAC configuration
• Multiple role support: Users can belong to multiple roles, inheriting permissions from all assigned roles

This architecture allows for both declarative permission definitions (YAML, database schema) and dynamic runtime permission management (database records), providing flexibility for different deployment scenarios and administrative needs.