Permissions Phase A Built

Permissions governs who can do what, and on which merchant's data. It defines roles, grants permissions to those roles, scopes access per organization/merchant, and automatically filters every list and detail query to the requesting user's reach. Every other module relies on it for authorization.

1. Identity

Property	Value
Module ID	CORE-02
Tier	Core
Status	Built
Phase	P1 (fixed roles + filtering), P2 (custom roles + granular grants)
Priority	HIGH
Primary users	Super Admin · Admin · Operator · Owner · Cashier · Employee

2. Purpose & Scope

Included	Excluded
Eight fixed system roles + role hierarchy	Wildcard permissions (e.g. sales.*)
Custom role creation with priority and scope	Permission categories / UI grouping
Permission catalog (create, update, delete)	Time- or shift-based permissions
Grant / revoke permissions to roles	Permission audit log
Grant / revoke roles to users	Role templates / pre-configured bundles
Effective-permission query (direct + inherited)	Per-merchant active-role switching
Per-merchant & per-organization scoping
Automatic role-based data filtering
Privilege-escalation guard

3. Capabilities

Capability	What the user can do	Status
Fixed system roles	Eight immutable roles seeded at startup, each with a numeric priority	Built
Role-based data filtering	Every list/count/detail query is auto-filtered to the user's scope	Built
System-role bypass	Super Admin, Admin, Operator see all data, skipping scope filtering	Built
Per-merchant scoping	Grants apply within the merchant chosen by the active-merchant header	Built
HQ-owner expansion	An Owner at a head-quarter merchant reaches every sibling merchant of that organizer	Built
Custom roles	Create roles with an i18n name, priority, and optional org/merchant scope	Built
Permission catalog	Create, update, and delete permission definitions	Built
Grant / revoke to roles	Add or remove permissions on a role (idempotent)	Built
Grant / revoke roles to users	Assign or remove roles from users	Built
Effective permissions	View a user's combined direct + role-inherited permissions	Built
Privilege-escalation guard	Block managing any role at or above the actor's own priority	Built

4. Module Dependencies

Depends on	Why
User Management	Users are the subjects that receive roles and permissions
Commerce	Organizations and merchants are the scopes roles attach to
All feature modules	Every module's data is filtered and authorized through Permissions

5. Backend Packages

Implementation detail lives in the developer docs — this section only maps the module to the services that power it.

Package	Role	Developer docs
@nx/identity	Roles, permissions, policy-definition grants, sign-in token	identity
@nx/core	Casbin model + per-merchant policy adapter + enforcer wiring	Casbin Authorization

6. Key User Flows

7. Roles & Permissions

Live develop snapshot. For the full per-permission breakdown see the Permission Matrix.

Role	Identifier	Priority	Enforcement	Reach
Super Admin	999_super-admin	999	Always-allow bypass	Everything
Admin	900_admin	900	Always-allow bypass	Everything
Operator	600_operator	600	Always-allow bypass	Everything
Owner	500_organizer-owner	500	Per-merchant domain	Own organizer + its merchants
Cashier	110_cashier	110	Per-merchant domain	Assigned merchant (mirrors Employee)
Employee	100_employee	100	Per-merchant domain	Assigned merchant
Customer	010_customer	10	None (customer-facing)	No backend permissions
Guest	001_guest	1	Global (*)	Onboarding-only (pre-merchant)

Owner vs Employee: both receive a lenient full-CRUD grant on most modules and differ only in inventory (Employee is read-only on master data) and ledger (Owner-only). Cashier mirrors Employee exactly.

8. Status & Roadmap

Phase	Capabilities
P1	Eight fixed roles · priority hierarchy · system-role bypass · automatic data filtering · role context in sign-in token
P2	Custom roles · permission catalog · grant/revoke to roles & users · effective-permission query · privilege-escalation guard · per-merchant scoping
P3 (planned)	Wildcard permissions · permission categories · role templates · time-based permissions · permission audit log

9. Related Pages

• URD
• Test Cases
• PRDs
• Permission Matrix — full per-role permission reference
• User Management
• identity — RBAC & Policy Definitions
• identity — Casbin Authorization