feat: implement fine-grained RBAC service with support for role hierarchy, temporary elevation, and audit logging.

[Dubemtopsite]

Description

Implements comprehensive Role-Based Access Control (RBAC) with a fine-grained permission model. Replaces the previous basic access checks with a structured admin / manager / viewer role hierarchy, each with resource-level permissions across 13 resource types.

Changes

New: backend/services/accessControl.ts

• Role definitions — Three roles (admin, manager, viewer) with explicit permissions per resource. Role hierarchy with strict ordering (admin > manager > viewer) and no duplicate levels.
• Permission check middleware — hasPermission(userId, resource, action) and requirePermission(userId, resource, action) that throws AccessDeniedError on denial.
• Role assignment API — assignRole, revokeRole, getAssignment, getUserRole with automatic audit logging via the existing AuditService. System bootstrap via bootstrap() for initial admin seeding.
• API key scoping — registerApiKeyScope / checkApiKeyPermission / updateApiKeyScope for binding fine-grained permission sets to API keys, with optional resource allow-lists and rate limits.
• Unauthorized access monitoring — Every denied access is recorded as an UnauthorizedAccessEvent. Tracks stats by actor/resource. Dispatches alerts via AlertingService when any actor accumulates 5+ unresolved denials.
• Temporary elevation — Time-limited role elevation via grantTemporaryElevation with configurable TTL. Tracks original vs elevated role for full auditability.
• Escalation prevention — preventEscalation() throws PermissionEscalationError when an actor attempts to assign a role equal to or higher than their own.

Modified: backend/services/index.ts

• Exports AccessControlService, AccessDeniedError, PermissionEscalationError, ROLE_PERMISSIONS, ROLE_HIERARCHY, and all related types.

Modified: src/components/admin/FeatureManagement.tsx

• Added userRole and currentUserId props for RBAC integration.
• Operations (toggle, rollout update) are guarded by requirePermission() — non-admin users see an "Access Denied" alert.
• Switch component is disabled for non-admin users.
• Header shows current role badge with access level indicator.

New: backend/services/__tests__/accessControl.test.ts

• 25 tests covering role hierarchy, assignment, permission checking, temporary elevation, API key scoping, unauthorized access monitoring, escalation prevention, and audit integration.

New: docs/permissions.md

• Full documentation of the RBAC model: role hierarchy, resource list, action types, permission matrix, API reference with examples, and TypeScript types.

Acceptance Criteria

• Role definitions with resource-level permissions
• Permission check middleware for all operations
• Role assignment API with audit
• API key scoping with permission sets
• Unauthorized access monitoring and alerting
• Permission documentation

Technical Scope

• backend/services/ — accessControl.ts with full RBAC implementation
• src/components/admin/FeatureManagement.tsx — RBAC integration with permission-gated controls
• Edge: permission escalation prevention — preventEscalation() with strict canAssignRole() guard
• Edge: role hierarchy complexity — validateRoleHierarchy() ensures no duplicate levels and valid ordering
• Edge: temporary elevation — Time-bounded elevation with automatic expiry and full audit trail

Testing

npx jest --config jest.backend.config.js --testPathPattern "accessControl" --no-coverage
# 25 tests, all passing

Closes #420

[drips-wave]

@Dubemtopsite Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits