Permission & ACL Model

This document defines the permission and access control model for the Plings admin system.

Overview

The Plings admin system uses a three-tier permission model with role-based access control (RBAC) and ability-based permissions.

Admin Access Levels

1. System Owner (/super)

  • Highest Level: Complete system access
  • Routes: All /super/*, /admin/*, /dev/* routes
  • Capabilities:
    • Emergency system controls
    • Security incident response
    • HSM management
    • Master key operations
    • Cross-organization operations
  • Security: Multi-factor authentication required

2. Plings Admin (/admin)

  • Business Operations: Cross-organization management
  • Routes: All /admin/* routes only
  • Capabilities:
    • User management across organizations
    • Billing and invoicing
    • Content moderation
    • Class management
    • Audit log access
  • Security: Standard authentication with session limits

3. Plings Developer (/dev)

  • Technical Operations: Development and debugging
  • Routes: All /dev/* routes only
  • Capabilities:
    • API testing and debugging
    • Performance monitoring
    • System diagnostics
    • Log viewing
    • Feature flags
  • Security: Standard authentication with debug access

Permission Checking

Frontend Route Protection

// AdminRoute - checks for admin permissions
const hasAdminAccess = permissions.isPlingsAdmin || permissions.isSystemOwner;

// DevRoute - checks for developer permissions
const hasDevAccess = permissions.isPlingsDeveloper || permissions.isSystemOwner;

// SuperAdminRoute - checks for system owner only
const hasSuperAdminAccess = permissions.isSystemOwner;

Ability-Based Permissions

Each admin function requires specific abilities:

Function Required Ability
Class Management ADMIN_CLASS_MANAGEMENT
User Administration ADMIN_USER_MANAGEMENT
Billing Operations ADMIN_BILLING_MANAGEMENT
Organization Control ADMIN_ORG_MANAGEMENT
Audit Log Access ADMIN_AUDIT_ACCESS
API Testing DEV_API_TESTING
Debug Panel DEV_DEBUG_PANEL
Performance Monitor DEV_PERFORMANCE_MONITOR

Security Features

Session Management

  • Admin Sessions: 30-minute timeout
  • Super Admin Sessions: 30-minute timeout with warnings
  • Developer Sessions: Standard timeout

Audit Logging

  • All administrative actions are logged
  • Includes user identity, timestamp, and action details
  • Immutable audit trail for compliance

Access Restrictions

  • IP-based restrictions: Configurable for admin access
  • Time-based limits: Session expiration warnings
  • Multi-factor authentication: Required for super admin access

Implementation Notes

Backend Integration

  • Permission checks enforced at GraphQL resolver level
  • Row-level security (RLS) policies in database
  • JWT token-based authentication with ability claims

Frontend Components

  • useUserPermissions hook provides permission state
  • Route protection components prevent unauthorized access
  • Conditional UI rendering based on abilities

For detailed role definitions and permissions matrix, see Frontend Views & Permissions.