Roles & Permissions

Comprehensive access control matrix, role boundaries, and governance invariants in Flockbase.

Flockbase implements strict role-based access control (RBAC) enforced at both the API route guard layer and inside database transactions. Every action is verified against the actor's role and organizational scope.

The 5-Tier Role Hierarchy

┌─────────────────────────────────────────────────────────────┐
│                        SUPER_ADMIN                          │
│          Full organizational and executive control          │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────┐
│                           ADMIN                             │
│     Operational management of all units, members & logs     │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────┐
│                        UNIT_LEADER                          │
│      Heads a specific department; oversees worker roster     │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────┐
│                    ASSISTANT_UNIT_LEADER                    │
│     Assists leader; manages unit attendance & excuses       │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────┐
│                           WORKER                            │
│     Departmental volunteer; submits attendance & excuses    │
└─────────────────────────────────────────────────────────────┘

Permission Matrix

Capability	SUPER_ADMIN	ADMIN	UNIT_LEADER	ASSISTANT	WORKER
Create & Deactivate Admins	✅	❌	❌	❌	❌
Promote Admin to Super Admin	✅ (Max 5)	❌	❌	❌	❌
View Audit Logs	✅	✅	❌	❌	❌
Create & Delete Units	✅	✅	❌	❌	❌
Assign Unit Leaders	✅	✅	❌	❌	❌
Invite Workers (Unit Scope)	✅	✅	✅ (Own Unit)	✅ (Own Unit)	❌
Regenerate Unit Invite Links	✅	✅	✅ (Own Unit)	✅ (Own Unit)	❌
Schedule Services	✅	✅	❌	❌	❌
Generate QR Check-in Codes	✅	✅	✅	✅	❌
Mark Manual Attendance	✅	✅	✅ (Own Unit)	✅ (Own Unit)	❌
Review & Approve Excuses	✅	✅	✅ (Own Unit)	✅ (Own Unit)	❌
Submit Personal Absence Excuse	✅	✅	✅	✅	✅
Self Check-in via QR / Link	✅	✅	✅	✅	✅

Governance Rules & Invariants

Flockbase enforces several non-negotiable security invariants in code:

1. The Super Admin Cap (`MAX_SUPER_ADMINS = 5`)

To maintain executive accountability and prevent credential proliferation, the system prohibits promoting more than 5 active Super Admins. Any API call attempting to promote a sixth super admin will fail with:

{
  "statusCode": 400,
  "code": "SUPER_ADMIN_LIMIT_REACHED",
  "message": "Cannot promote: maximum limit of 5 super admins reached."
}

2. Strict Unit-Scope Isolation

Unit Leaders and Assistant Unit Leaders are scoped strictly to their assigned unitId:

A Unit Leader cannot view or modify workers belonging to another unit.
A Unit Leader cannot approve excuses for members outside their unit.
Attempts to access out-of-scope records result in 403 Forbidden or USER_OUT_OF_SCOPE.

3. Role Protection Invariants

Departmental leaders cannot deactivate or modify an account that holds ADMIN or SUPER_ADMIN status.
Standard workers cannot promote themselves or alter unit assignments.
A user assigned as a Unit Leader cannot be reassigned to a different unit without first unlinking their leadership status, protecting Unit.leaderId consistency.

4. Account Status Transitions

Every account is in one of three states:

ACTIVE: Normal access permitted.
INACTIVE: Soft-deactivated; credentials cannot log in; unit associations preserved.
BLOCKED: Account suspended by governance with a mandatory reason. All active refresh tokens and session tokens are revoked immediately upon suspension.