Skip to content

RBAC Matrix

Role hierarchy (tenant-scoped): owner > admin > manager > employee > viewer

Platform Admin is a completely separate access system based on platformAdmin / hipaaAdmin boolean fields on the Better Auth user record (Postgres) and is not part of this matrix. See Platform Admin section below.


Incident Management

Action Viewer Employee Manager Admin Owner
Report incident Yes Yes Yes Yes Yes
View public incidents Yes Yes Yes Yes Yes
View private incidents — — Yes Yes Yes
Add comment Yes Yes Yes Yes Yes
Change status ³ — Yes Yes Yes Yes
Assign incident — Yes Yes Yes Yes
Resolve incident — Yes Yes Yes Yes
Close incident — Yes Yes Yes Yes

Private incidents are flagged at creation. Only Manager and above can see them.

³ Viewer incident updates: Viewers hold the UPDATE_INCIDENT server permission but with an important restriction: they may only update incidents they reported themselves. Status transitions (change status, assign, resolve, close) remain restricted to Employee and above. The UPDATE_INCIDENT permission for Viewers is intentional and enforced at the action layer.


Policy Management

Action Viewer Employee Manager Admin Owner
View published policies (Company Documents) Yes Yes Yes Yes Yes
Access Policy Management (/policies) — — Yes Yes Yes
Create policy (blank or from template) — — Yes Yes Yes
Edit draft policy content — — Yes Yes Yes
Submit policy for approval — — Yes Yes Yes
View approval thread — — Yes Yes Yes
Comment on approval thread — — Yes Yes Yes
Approve / reject policy — — — ¹ Yes ¹ Yes ¹
Request changes (revert approved → draft) — — — Yes Yes
Publish policy — — — Yes Yes
Acknowledge policy (mark as read) — Yes Yes Yes Yes
Accept template update — — Yes Yes Yes
Dismiss template update — — Yes Yes Yes
View template update diff — — Yes Yes Yes
Use Smart Template Discovery — — Yes Yes Yes

¹ Self-approval guard: the user who submitted a policy for approval cannot approve or reject their own submission, regardless of role. A second admin or owner must act on it. Exceptions: if no other active admin exists (only owners, or no one else at all), the author may approve with an explicit override and a written reason (OVERRIDE_REASON_MIN, 10+ characters): the audit log records self_review_override with the reason and any other owners are notified (#61, #792). Before #792 a sole admin/owner's self-approval was waived silently; now it needs the override too. A sole admin/owner may still reject (withdraw) their own submission, recorded as self_review_waived (#40). Managers can't approve policies, so they never count as approvers. Inactive or suspended members don't count either (canSignIn()).

Submission notices (#792): on submit, active admins and owners get Policy Awaiting Approval; active managers get Policy Submitted for Approval for awareness only; the submitter gets neither. In-app only, no email. The first approver to act decides (a transaction), and everyone else's notice becomes Policy Approval Complete.

Pending-approval escalation (#61): every admin and owner is notified on submission. After 5 business days still pending, the approvers (except the author) get an in-app reminder; after 10 business days, the owner(s) get an escalation in the app and by email. Business days use the tenant's time zone; the worker job POLICY_APPROVAL_ESCALATION checks each weekday at 9am local time, and each stage fires once per approval round.

Policy lifecycle states

draft → pending_approval → approved → published → expiring → expired
                ↑                ↓
         (request changes) (rejected → draft)
  • draft — editable by its manager/admin/owner creator; not visible to other roles.
  • pending_approval — locked for editing; awaiting admin/owner decision.
  • approved — acknowledged by approver; ready to publish.
  • published — visible to all roles; employees are prompted to acknowledge.
  • expiring — within 30 days of expiry; displayed with a warning badge.
  • expired — past expiry date; renewal required.

Template linkage

When a policy is created from a master template, it stores sourceTemplateId and sourceVersion. If the platform team publishes a new template version, managers and above see a banner offering to Accept (merge updated sections) or Dismiss the update.


Risk Assessment

Action Viewer Employee Manager Admin Owner
Run assessments — — Configurable ² Configurable ² Yes
View published results Yes Yes Yes Yes Yes
Delete an in-progress assessment (#605) — — Own only ² Any Any

² Configurable access: Owner can grant or revoke Manager and Admin access via Module Management → Role Access. Default is on for both.


HIPAA Assessment

Action Viewer Employee Manager Admin Owner
Run HIPAA assessment — Yes Yes Yes Yes

Asset Management

Action Viewer Employee Manager Admin Owner
View assets Yes Yes Yes Yes Yes
Create asset — Yes (pending) Yes Yes Yes
Edit asset — Yes Yes Yes Yes
Delete asset — Yes (pending) Yes Yes Yes
Approve pending assets — — Yes Yes Yes
Assign asset — — Yes Yes Yes
Remove employee from asset (unassign) — — Yes Yes Yes

All create, edit, and delete actions require a justification (minimum 10 characters). This is stored per-action as createJustification, editJustification, or deleteJustification on the asset record.

Employee-created assets (customers and suppliers) are placed in pending status and require manager, admin, or owner approval before becoming active.

Employee deletion requests set status: 'pending_deletion' rather than immediately retiring the asset. A manager, admin, or owner must approve the deletion request before the asset is retired.

Employees can edit existing assets directly (no approval required), but a justification is always recorded.


Assign / unassign applies to devices and vehicles only, and only to active employees (assignAssetToEmployee / unassignAsset, src/lib/actions/asset-assignment.actions.ts, enforced server-side at Manager+).


Employee Management

Action Viewer Employee Manager Admin Owner
Terminate an employee, viewer or manager — — — Yes Yes
Terminate an admin — — — — Yes
Terminate an owner, or yourself — — — — —
Change the department of an employee, viewer or manager — — Yes Yes Yes
Change the department of an admin or owner — — — Yes Yes
Change your own department — — — — —
Edit a terminated employee (reinstate first) — — — — —
Change someone else's role (only an owner can grant owner) — — — Yes Yes
Change your own role — — — — —

Termination (terminateEmployee, src/lib/actions/employees.actions.ts) sets the user to inactive (sign-in to the tenant is refused), unassigns their devices/vehicles, and releases their open incidents (active/unresolved → assigned with the team kept, or unassigned without one), each with a System note "Team member is no longer with the organization." A reason (10+ characters) is required.

Department (#62, setEmployeeDepartment; the rule is canChangeDepartment in src/lib/rbac/department-permissions.ts): a manager, an admin or the owner can change it from the employee detail panel; admins can also set it in the Edit Employee form. Values come from DEPARTMENTS. A terminated employee's record can't be changed. Who changed it, and when, are stored on the user (departmentUpdatedBy, departmentUpdatedAt).


Employee Profile Updates

Action Viewer Employee Manager Admin Owner
Request phone/address update (own record only) — Yes Yes Yes Yes
View approval requests — — Yes Yes Yes
Approve / reject update requests — — Yes Yes Yes
View your own address Yes Yes Yes Yes Yes
View another employee's address — — Yes Yes Yes

Employees may request updates to their own phone number and address only. All three approver roles (Manager, Admin, Owner) receive an approval_required notification simultaneously. Only one approval is needed to process the change, and it must come from someone other than the requester (#724): a manager can request a change to their own record but can't approve or reject it. Once acted upon, all pending approval notifications are removed from every approver's inbox. The requester is notified of the outcome via the in-app notification bell. Requests still waiting are also shown at the top of every approver's bell (Approval requests waiting), managers included (#725).

Addresses (owner, confirmed 2026-11-08): every member sees their own address, so they can check it and request a change. Other people's addresses are for Manager, Admin and Owner only. This is enforced on the server (redactEmployeeFor in src/lib/rbac/employee-visibility.ts) before records leave it: getEmployees, /api/employees, /api/employees/[id] and getCompanyUsers (#725, #833). Any new route or action that returns employee records must apply it too.


Module Management

Action Viewer Employee Manager Admin Owner
Access Module Management — — — — Yes
Enable / disable modules — — — — Yes
Grant/revoke Admin role access — — — — Yes
Grant/revoke Manager role access — — — — Yes

Changes apply to all users of the affected role within the tenant.


Company Settings

Action Viewer Employee Manager Admin Owner
Edit company profile — — — Yes Yes
Publish policy statements — — — Yes Yes
Publish risk assessment — — — Yes Yes
Manage modules — — — — Yes

Platform Admin Portal

The Platform Admin Portal is completely isolated from the tenant RBAC system. A user with the owner role inside any tenant has no access here, and a platform admin has no access to tenant data.

Access is granted by setting platformAdmin: true or hipaaAdmin: true on the Better Auth user record in Postgres, using the pnpm set:admin <email> script (procedure: parking lot › Granting admin access; user guide: PLATFORM_ADMIN.md).

Hub group Better Auth field required Entry point Areas
Policy Admin platformAdmin: true /platform-admin hub Import Catalog (/platform-admin/wizard), Template Rules, Policy Templates
Risk Admin platformAdmin: true /platform-admin hub Risk Questions (/platform-admin/risk-questions: Content Health, Questions, Recommendations, Industry Weights, Seed Control), Question Set Versions (/platform-admin/question-sets)
Tenant Admin platformAdmin: true /platform-admin hub Tenants (/platform-admin/tenants)
Reports platformAdmin / hipaaAdmin /platform-admin hub Risk Content Health (platformAdmin), HIPAA Reports (hipaaAdmin)
HIPAA Admin hipaaAdmin: true /platform-admin hub → /hipaa-admin Dashboard, Companies, Participants

The hub's groups and cards come from ADMIN_AREAS (src/components/admin/admin-areas.ts); each area names the flag (claim) it needs, and a group only appears when the account can use one of its areas.

These are Postgres columns on the Better Auth user table, not Firebase custom claims. A single account can hold both; set:admin sets both at once.

Platform Admin capabilities

Capability Tenant Admin/Owner Platform Admin (platformAdmin) HIPAA Admin (hipaaAdmin)
Manage tenant's own policies Yes — —
Approve / reject tenant policies Yes — —
Author master policy templates (all tenants) — Yes —
Publish template versions + notify tenants — Yes —
Define template recommendation rules — Yes —
Manage HIPAA companies and participants — — Yes
Invite HIPAA participants (confirm-email per row, several at once; invitation email sent) — — Yes
View HIPAA assessment reports — — Yes

HIPAA participants (email-only login at /hipaa/login, not a role above) can only take their own assessment and view or download their own certificates (GET /api/hipaa/certificates, GET /api/hipaa/certificate/{id}). Another participant's certificate returns 403 and is audited.

Enforcement

The field is verified independently at three layers — no single bypass point:

  1. Login page (/platform-admin/login) — After sign-in, the server validates the Better Auth session and reads platformAdmin/hipaaAdmin from the Postgres user record; signs out and shows an error if neither is set.
  2. Layout guard (platform-admin/layout.tsx, hipaa-admin/layout.tsx) — Server-side session check on every navigation; redirects to login if the field is absent.
  3. API middleware — withPlatformAdmin() (Better Auth session + platformAdmin field) and withHipaaAdminAuth() (httpOnly HIPAA session cookie validated via Firestore hash lookup) on every request.

Sign-in and request flow (moved from PLATFORM_ADMIN.md, 2026-10-21):

Better Auth user (email + password)
        │
        ▼
POST /api/auth/sign-in (Better Auth)
        │
        ▼
Session cookie set (httpOnly, Secure, SameSite=Strict)
        │
        ├─ no platformAdmin/hipaaAdmin field  ─→  signOut() + show error
        │
        ├─ hipaaAdmin === true   ─→  POST /api/hipaa/auth/login-admin
        │                              (issues httpOnly HIPAA session cookie)
        │
        └─ any admin field        ─→  redirect to /platform-admin (hub)
                                                │
                                                ▼
                                     hub shows the areas for each field
                                     the account holds (ADMIN_AREAS)
                                                │
                                                ▼
                                     layout.tsx re-checks on every
                                     navigation via auth.api.getSession;
                                     requires platformAdmin OR hipaaAdmin
                                                │
                                                ▼
                                     API routes re-verify via
                                     withPlatformAdmin() on every request

Sign-out: "Sign out" in the sidebar calls the Better Auth sign-out
          endpoint, clears the hipaa-admin-token cookie, and redirects
          to /platform-admin/login
  • No propagation delay: flags are read from Postgres on every request (no session cookie cache), so grants and revokes apply on the next request.
  • HIPAA cookie: an already-issued hipaa-admin-token stays valid until it expires (24 h); delete the admin's rows in hipaa_admin_sessions to cut it off sooner.

Permission keys (appConfig/permissionsMap)

The action tables above describe behaviour. This table shows the permission keys behind it: what the UI checks with usePermission().hasPermission(...), per role.

Source of truth: ROLE_PERMISSIONS in src/lib/rbac/role-permissions.ts. - generatePermissionsMapForSeeding() turns it into the Firestore document appConfig/permissionsMap, field rolePermissions.<role>, written by src/scripts/seed-appconfig.ts. - /api/rbac/permissions serves only the caller's own roles from that document. - The meaning column comes from PERMISSION_LABELS in src/lib/rbac/action-permissions.ts.

Verified 2026-10-22 (#788): the stored document matches the code exactly in both preview (myassetguard) and production (priam-prd). The counts are viewer 8, employee 15, manager 24, admin 38, owner 40.

Permission key Meaning Viewer Employee Manager Admin Owner
user:create Create Users — — — Yes Yes
user:delete Delete Users — — — Yes Yes
user:invite Invite Users — — Yes Yes Yes
user:manage_roles Manage User Roles — — — Yes Yes
user:read View Users Yes Yes Yes Yes Yes
user:update Edit Users — — — Yes Yes
asset:approve Approve Pending Assets — — Yes Yes Yes
asset:create Create Assets — Yes Yes Yes Yes
asset:delete Delete Assets — Yes Yes Yes Yes
asset:export Export Assets — — — Yes Yes
asset:read View Assets Yes Yes Yes Yes Yes
asset:update Edit Assets — Yes Yes Yes Yes
incident:active Activate Incidents — Yes Yes Yes Yes
incident:assign Assign Incidents — Yes Yes Yes Yes
incident:closed Close Incidents — Yes Yes Yes Yes
incident:create Report Incidents Yes Yes Yes Yes Yes
incident:delete Delete Incidents — — — Yes Yes
incident:read View Incidents Yes Yes Yes Yes Yes
incident:resolve Resolve Incidents — Yes Yes Yes Yes
incident:update Edit Incidents Yes Yes Yes Yes Yes
risk:create Start Risk Assessment — — Yes Yes Yes
risk:delete Delete Risk Assessments — — — Yes Yes
risk:generate_runbook Generate Runbooks — — Yes Yes Yes
risk:read View Risk Assessments Yes Yes Yes Yes Yes
risk:update Edit Risk Assessments — — Yes Yes Yes
policy:acknowledge Acknowledge Policies Yes Yes Yes Yes Yes
policy:approve Approve Policies — — — Yes Yes
policy:create Create Policies — — Yes Yes Yes
policy:delete Delete Policies — — — Yes Yes
policy:publish Publish Policies — — — Yes Yes
policy:read View Policies Yes Yes Yes Yes Yes
policy:update Edit Policies — — Yes Yes Yes
report:export Export Reports — — — Yes Yes
report:view View Reports — — Yes Yes Yes
analytics:view View Analytics Dashboard — — Yes Yes Yes
audit:view View Audit Log — — — Yes Yes
settings:billing Manage Billing — — — — Yes
settings:company Manage Company Settings — — — Yes Yes
settings:integrations Manage Integrations — — — Yes Yes
settings:subscription Manage Subscription — — — — Yes

Rules: - Change a role's permissions in the code, then reseed the document in each environment. The UI reads the document, while server actions check role levels. asset-permissions-sync.test.ts proves the two agree for assets. - A stored document that differs from the code is a bug. Compare them before trusting either. - The permissions response is never cached across users. Cache-Control: private, no-store, and the client's 5-minute in-memory cache is keyed to user, organization and roles (#788). Before that fix, a user who signed in after someone else in the same browser saw the previous user's buttons for up to 5 minutes.


Backend Enforcement

All tenant-scoped permissions are enforced server-side. The middleware chain is:

Request → withAuth HOF → permission / role check → handler

Key files:

File Purpose
src/middleware/authMiddleware.ts withAuth HOF (tenant RBAC), withPlatformAdmin HOF, withHipaaAdminAuth HOF
src/lib/rbac/role-permissions.ts Flat permission arrays per role
src/lib/rbac/checkAccess.ts canPerformAction helper (ownership + role checks)
src/lib/modules/default-permissions.ts Per-module, per-role view/create/edit defaults
src/app/api/admin/modules/role-permissions/route.ts Owner-only module access overrides stored in Firestore
src/app/api/admin/publish/assessment/route.ts Admin-only assessment publishing
src/app/api/admin/publish/policy/route.ts Admin-only policy publishing
src/lib/services/policy-service.ts Self-approval guard (submitter ≠ approver)