Authentication & RBAC
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication and Role-Based Access Control (RBAC) system in DRX CRM is designed to provide granular security, multi-tenant isolation, and strict accountability for sensitive business operations. The system manages user identities through a tiered role hierarchy, ensuring that financial and inventory actions are performed only by authorized personnel.
At its core, the system utilizes a combination of database-level Row Level Security (RLS) and application-level middleware to enforce permissions. Roles range from local Staff/Cashiers to global Super Admins, with a centralized permissions mapping that dictates access to specific modules such as sales, inventory, and reporting.
Sources: README.md:14-15, testsprite_tests/standard_prd.json:10-15
RBAC Architecture
The RBAC implementation follows a structured schema where permissions are grouped into categories and assigned to specific roles. This mapping is enforced via database functions and RLS policies to prevent unauthorized data access or modification.
Core RBAC Components
The system relies on several key database tables to manage the relationship between users, roles, and permissions:
app_permissions: Stores the unique slugs/codes for every possible action (e.g.,sales.create,inventory.manage).role_permissions: A mapping table that defines which roles have access to which permission codes.user_roles: Associates a specific user with a role within a specific business (tenant).admin_users: A global table for high-level system administrators who bypass standard tenant restrictions.
Sources: supabase/migrations/20251220000000_rbac_schema.sql:11-25, db/migrations/20251208000001_rbac_implementation.sql:4-22
Permission Flow Diagram
The following diagram illustrates how a user request is validated against the permission schema before data is returned.
Role Hierarchy & Permissions
DRX CRM implements a strict hierarchy where higher-level roles inherit or expand upon the capabilities of lower-level roles.
Role Definitions
| Role | Description | Key Permissions |
|---|---|---|
| Cashier | Front-line staff processing sales. | sales.create, catalog.view, customers.view |
| Supervisor | Shift leads with override authority. | sales.void, sales.discount, customers.manage |
| Manager | Operational leads managing the business. | inventory.manage, staff.manage, settings.manage |
| Owner | Business owner with full tenant access. | All Manager permissions + billing/privacy controls |
| Super Admin | Global system administrator. | system.manage, audit.view, bypasses all RLS |
Sources: db/migrations/20251208000001_rbac_implementation.sql:35-43, supabase/migrations/20251220000000_rbac_schema.sql:30-50, app/(app)/settings/team/page.tsx:156-180
Hierarchy Enforcement
The system enforces a "strict role hierarchy" in user management. For instance, Managers are restricted from assigning or modifying "Owner" roles, and system APIs validate the requester's rank before allowing role updates.
Sources: testsprite_tests/standard_prd.json:28-29, app/(app)/settings/team/page.tsx:143-150
Implementation Details
Database-Level Authorization
Authorization is primarily handled via the check_permission PL/pgSQL function. This function is called within Row Level Security (RLS) policies to ensure that even direct database queries are constrained by the RBAC rules.
-- Example of RLS using permission check
CREATE POLICY "Managers can update inventory" ON inventory
FOR UPDATE USING (
check_permission(auth.uid(), business_id, 'inventory.manage')
);
Sources: db/migrations/20251208000001_rbac_implementation.sql:102-120, supabase/migrations/20251220000000_rbac_schema.sql:155-165
Team Management UI
The Team Management interface (/settings/team) provides an administrative view for users with the users.manage permission. It allows for role reassignment and displays the current staff roster within the active business context.
- Permission Gate: The UI checks for
users.managebefore rendering management controls. - Role Updates: Uses the
user_rolestable to perform updates, excluding the "Owner" role which is typically immutable via the standard UI. - Visual Indicators: Uses badges to identify current roles (e.g., Cashier, Manager).
Sources: app/(app)/settings/team/page.tsx:94-110, app/(app)/settings/team/page.tsx:118-135
Audit and Compliance
Every sensitive action triggered by the RBAC system—such as role modifications, price overrides, or inventory adjustments—is logged in an immutable audit trail.
- Audit Logging: Captures
business_id, user context, action type, and timestamps. - RTBF (Right to be Forgotten): The system supports a deletion API that masks Personally Identifiable Information (PII) and removes tenant roles while maintaining financial integrity.
- Tenant Isolation: RLS policies ensure that users from Business A cannot view or modify data belonging to Business B, even if they have the same role title.
Sources: testsprite_tests/standard_prd.json:24-34, CHANGELOG.md:105-108
Summary
The Authentication & RBAC system in DRX CRM provides a robust framework for multi-tenant security. By combining PostgreSQL Enums, central permission mappings, and RLS policies, the system ensures that business data is protected by a hierarchy of roles. This architecture supports the project's core goals of financial correctness, auditability, and operational speed.
Sources: README.md:14-15, testsprite_tests/standard_prd.json:6-10