RBAC Matrix
Role hierarchy (tenant-scoped): owner > admin > manager > employee > viewer
Platform Admin is a completely separate access system based on
platformAdmin/hipaaAdminboolean 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_INCIDENTserver 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. TheUPDATE_INCIDENTpermission 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_ESCALATIONchecks 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, ordeleteJustificationon the asset record.Employee-created assets (customers and suppliers) are placed in
pendingstatus 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 toinactive(sign-in to the tenant is refused), unassigns their devices/vehicles, and releases their open incidents (active/unresolved→assignedwith the team kept, orunassignedwithout 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 iscanChangeDepartmentinsrc/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 fromDEPARTMENTS. 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_requirednotification 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 (
redactEmployeeForinsrc/lib/rbac/employee-visibility.ts) before records leave it:getEmployees,/api/employees,/api/employees/[id]andgetCompanyUsers(#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:
- Login page (
/platform-admin/login) — After sign-in, the server validates the Better Auth session and readsplatformAdmin/hipaaAdminfrom the Postgres user record; signs out and shows an error if neither is set. - 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. - API middleware —
withPlatformAdmin()(Better Auth session +platformAdminfield) andwithHipaaAdminAuth()(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-tokenstays valid until it expires (24 h); delete the admin's rows inhipaa_admin_sessionsto 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) |