Role-based access control

Model

Users receive zero or more roles through UserRole. Roles receive zero or more typed permissions through RolePermission. Effective permissions are the union of active grants. Permission keys follow <area>.<action>, such as roles.manage.

The reusable list and helpers live in @submicron/auth. The database remains authoritative for grants. UI visibility may improve clarity but never replaces server-side authorization.

Seeded roles

• Founder/Admin: every seeded permission.
• General Manager: broad cross-functional access except role and settings management.
• Operations/CRM Officer: CRM management plus operational read/document access.
• Engineer: audit contribution plus quote, approval, and document visibility.
• Finance/Admin: quote and approval management plus administrative visibility.
• Store Manager: limited customer, quote, approval, and document access.
• Field Staff: field-oriented audit contribution and read access.
• Viewer: non-administrative view permissions only.

These are initial assumptions, not a final segregation-of-duties policy. Named business owners must approve them before production use.

Enforcement pattern

1. Validate a Better Auth session.
2. Reject inactive or missing users.
3. Load roles and permissions from PostgreSQL.
4. Validate the exact permission near the protected query or mutation.
5. Record consequential actions in ActivityLog.

Resource ownership, row-level scope, temporary delegation, and approval thresholds are deferred until actual workflows are designed.