RBAC & Policy Definitions v1.0.0

Core Entities

Casbin Authorization Model

The RBAC system uses the scoped-RBAC Casbin model CASBIN_RBAC_DOMAIN_SCOPED_MODEL, shipped by @venizia/ignis core in .../enforcers/models/rbac-domain.model.ts:

ini

[request_definition]
r = sub, dom, obj, act

[policy_definition]
p = sub, dom, obj, act, eft

[role_definition]
g = _, _, _
g2 = _, _
g3 = _, _
g4 = _, _
g5 = _, _

[policy_effect]
e = some(where (p.eft == allow)) && !some(where (p.eft == deny))

[matchers]
m = g(r.sub, p.sub, r.dom) && (p.dom == "SYSTEM_WIDE" || (p.dom == "ANY_MEMBER" && g2(r.sub, r.dom)) || g3(r.dom, p.dom)) && (objectMatch(r.obj, p.obj) || g4(r.obj, p.obj)) && g5(r.act, p.act)

Relation	Casbin	Carries
`g`	role grouping	`assign_role` (User→Role) + `role_inherits` (Role→Role), domain-aware
`g2`	membership	`join_domain` (User→Merchant/Organizer) - the `dom` axis
`g3`	domain nesting	`domain_inherits` (Merchant ⊂ Organizer, Branch ⊂ Company)
`g4`	resource nesting	`resource_inherits` (obj hierarchy, e.g. OrderItem ⊂ Order)
`g5`	action lattice	`action_inherits` (manage ⊃ read/write/execute; write ⊃ create/update/delete)

Token	Meaning
`sub`	Subject - `User_<id>` or `Role_<id>`
`dom`	Request domain - `Merchant_<id>` from `x-merchant-id` (or none)
`obj`	Object - the permission/resource code, e.g. `commerce.product.create`
`act`	Action - `read` / `write` / `execute` / `manage` / `create` / `update` / `delete`
`eft`	Effect - `allow` (default) / `deny`

Effect is default-DENY (allow-and-deny): a request needs a matching allow and no matching deny, so an explicit deny overrides any allow.

A grant's domain scope (the dom on a p line) is one of:

Scope	Matches
`SYSTEM_WIDE`	every domain, bypassing membership
`ANY_MEMBER`	every domain the subject joined via `g2`
`<Type>_<id>`	that domain, plus any `g3`-nested child

Runtime deep-dive. How the ScopedCasbinAdapter loads one principal's edges per request, domain resolution from x-merchant-id, role bypass and Redis enforcer caching are documented in Casbin Authorization.

PolicyDefinition Variants

PolicyDefinition is the single edge table - it replaces UserRole, PermissionMapping, and UserMapping. Each row is one of eight variants; the ScopedCasbinAdapter filters a principal's rows and emits the matching Casbin line.

Variant	Subject → Target	Casbin	Emitted line
`grant`	Role\|User → Permission	`p`	`p, <Role\|User>_<id>, <SYSTEM_WIDE\|ANY_MEMBER\|Type_id>, <objectCode>, <action>, <allow\|deny>`
`assign_role`	User → Role	`g`	`g, User_<id>, Role_<id>, <domain\|>` (null domain ⇒ ``)
`join_domain`	User → Merchant\|Organizer	`g2`	`g2, User_<id>, <Type>_<domainId>`
`role_inherits`	Role → Role (DAG)	`g`	`g, Role_<child>, Role_<parent>, *`
`domain_inherits`	domain nesting	`g3`	`g3, <Type>_<childId>, <Type>_<parentId>`
`resource_inherits`	resource(obj) nesting	`g4`	`g4, <childCode>, <parentCode>`
`action_inherits`	action lattice	`g5`	`g5, <childAction>, <parentAction>`
`merchant_role`	Role available in a Merchant	-	none - `@nx/core` UI metadata; the adapter never reads it

The app-facing names live in @nx/core common/policy-variant.ts (PolicyVariants), wrapping the framework's AuthorizationPolicyVariants.

Fixed System Roles

Eight roles seeded on migration (alwaysRun: true). Cannot be modified or deleted.

Identifier	Name EN	Name VI	Priority	Scope
`999_super-admin`	Super Admin	Siêu Quản Trị Viên	999	System (from IGNIS `AuthorizationRoles`)
`900_admin`	Admin	Quản Trị Viên	900	System (from IGNIS)
`600_operator`	Operator	Vận Hành Viên	600	System
`500_organizer-owner`	Organizer Owner	Chủ Doanh Nghiệp	500	Organization
`110_cashier`	Cashier	Thu Ngân	110	Merchant
`100_employee`	Employee	Nhân Viên	100	Merchant
`010_customer`	Customer	Khách Hàng	10	Customer
`001_guest`	Guest	Khách	1	Global

CASHIER is a merchant-level staff role (same tier as EMPLOYEE). Its priority 110 falls inside the custom-role band (101-499) - that is allowed for fixed roles; the band only constrains user-created CUSTOM roles.

GUEST (001_guest, priority 1) is the unauthenticated tier. Its grants use the SYSTEM_WIDE domain scope (match every domain), so pre-merchant onboarding/reference routes work before any merchant is selected.

Role Hierarchy

Priority 999 ┌─────────────────┐
             │  SUPER_ADMIN    │ ← full system access
             └─────────────────┘
Priority 900 ┌─────────────────┐
             │  ADMIN          │ ← administration
             └─────────────────┘
Priority 600 ┌─────────────────┐
             │  OPERATOR       │ ← system operations
             └─────────────────┘
Priority 500 ┌─────────────────┐
             │  OWNER          │ ← organizer scope
             └─────────────────┘
 101-499     ┌─────────────────┐
             │  CUSTOM ROLES   │ ← user-created
             └─────────────────┘
Priority 110 ┌─────────────────┐
             │  CASHIER        │ ← merchant scope (fixed, within custom band)
             └─────────────────┘
Priority 100 ┌─────────────────┐
             │  EMPLOYEE       │ ← merchant scope
             └─────────────────┘
Priority 10  ┌─────────────────┐
             │  CUSTOMER       │ ← end user
             └─────────────────┘
Priority 1   ┌─────────────────┐
             │  GUEST          │ ← global, unauthenticated
             └─────────────────┘

AppFixedRoles Helper

typescript

AppFixedRoles.isDefaultRole(identifier)     // true if any of the 8 fixed roles
AppFixedRoles.isSystemUser(roles)           // true if SUPER_ADMIN, ADMIN, or OPERATOR
AppFixedRoles.isOrganizerOwner(roles)       // true if OWNER

Identifier format: {priority:3 zero-padded}_{kebab-case-name} - generated by AuthorizationRole.build() with _ delimiter.

Custom Roles

Rule	Value
Priority range	`101` - `499` (`RolePriorities.MIN` / `MAX`)
Type	`CUSTOM`
Identifier	Auto-generated: `{paddedPriority}_{kebabCase(name.en)}`
Uniqueness	Per scope (global for system, per org/merchant for scoped)

Scope Rules by Creator

Creator Role	Allowed Scopes
System users (SUPER_ADMIN, ADMIN, OPERATOR)	Any: system / organizer / merchant
Organizer Owner	Own organizer or own merchants only
Other users (Employee, etc.)	Own merchant only

Ownership is validated against the creator's organizerIds[] and merchantIds[] from the JWT token.

Business Rules

Priority Guards

Cannot create/update/delete roles with equal or higher priority
Cannot grant/revoke roles with equal or higher priority via PolicyDefinition
Prevents privilege escalation

Fixed Role Protection

System roles (AppFixedRoles.DEFAULT_ROLE_IDENTIFIERS) → 403 on update or delete

Deletion Constraints

Entity	Constraint	Error
Role	Cannot delete if users assigned (an `assign_role` row references it)	`409`
Permission	Cannot delete if granted to a role/user (a `grant` row references it)	`409`

Role Deletion Cascade

When a deletable role is removed:

Delete all grant rows: Role → Permission
Delete all merchant_role rows: Role ↔ Merchant availability metadata
Soft-delete the Role entity

Permission Validation

Field	Constraint
`action`	Must be valid `AuthorizationActions`: create, read, update, delete, execute
`scope`	Must be valid `PolicyDomains`: SYSTEM, ORGANIZER, MERCHANT
`subject`	Must be a registered authorize model principal (from IGNIS `MetadataRegistry`)
`code`	Globally unique

API Reference

Roles - `/roles`

Method	Path	Description
`GET`	`/roles`	List (paginated)
`GET`	`/roles/count`	Count
`GET`	`/roles/:id`	Get by ID
`POST`	`/roles`	Create custom role
`PATCH`	`/roles/:id`	Update role
`DELETE`	`/roles/:id`	Soft-delete (with guards)

CreateRoleRequest:

Field	Type	Required
`name`	`{ en, vi }`	Yes
`description`	`{ en, vi }`	No
`priority`	`number` (100-500)	Yes
`status`	`enum`	No
`organizer`	`{ id }`	No (scope)
`merchant`	`{ id }`	No (scope)

Permissions - `/permissions`

Method	Path	Description
`GET`	`/permissions`	List
`GET`	`/permissions/count`	Count
`GET`	`/permissions/:id`	Get by ID
`POST`	`/permissions`	Create
`PATCH`	`/permissions/:id`	Update (`code` is immutable)
`DELETE`	`/permissions/:id`	Soft-delete (with grant check)

CreatePermissionRequest:

Field	Type	Required
`code`	`string`	Yes (globally unique)
`name`	`{ en, vi }`	Yes
`description`	`{ en, vi }`	No
`subject`	`string`	Yes
`action`	`string`	Yes
`scope`	`string`	Yes
`parentId`	`string`	No

Policy Definitions - `/policy-definitions`

Base CRUD (read-only):

Method	Path	Description
`GET`	`/policy-definitions`	List (paginated, filtered)
`GET`	`/policy-definitions/:id`	Get by ID

Role sub-endpoints - /policy-definitions/roles/{roleId}/{type}:

Method	Path	type	Description
`GET`	`.../roles/{id}/permissions`	`permissions`	List role's permissions
`POST`	`.../roles/{id}/permissions`	`permissions`	Grant/revoke permissions
`GET`	`.../roles/{id}/users`	`users`	List role's users
`POST`	`.../roles/{id}/users`	`users`	Assign/remove users

User sub-endpoints - /policy-definitions/users/{userId}/{type}:

Method	Path	type	Description
`GET`	`.../users/{id}/roles`	`roles`	List user's roles
`GET`	`.../users/{id}/permissions`	`permissions`	List user's permissions (query: `mode=direct\|inherit`)
`GET`	`.../users/{id}/organizers`	`organizers`	List user's organizers
`GET`	`.../users/{id}/merchants`	`merchants`	List user's merchants
`POST`	`.../users/{id}/{type}`	any	Grant/revoke targets

Organizer/Merchant sub-endpoints:

Method	Path	Description
`GET`	`.../organizers/{id}`	List organizer's users
`POST`	`.../organizers/{id}`	Assign/remove users
`GET`	`.../commerces/{id}`	List merchant's users
`POST`	`.../commerces/{id}`	Assign/remove users

Request Body for Grant/Revoke

typescript

// For role and user targets
ManageRoleTargetsRequest / ManageUserTargetsRequest {
  action: 'grant' | 'revoke',
  ids: string[],       // min 1
  domain?: string       // optional scope label
}

// For organizer/merchant targets
ManageGroupTargetsRequest {
  action: 'grant' | 'revoke',
  ids: string[]         // min 1
}

Response

typescript

{ granted?: number, revoked?: number, skipped?: number }

Permission Resolution

GET /policy-definitions/users/{id}/permissions?mode=direct → only direct grant rows (User → Permission)
GET /policy-definitions/users/{id}/permissions?mode=inherit → assign_role → grant chain (User → Role → Permission)
Default: inherit

PolicyDefinition Services

Service	Manages
`RolePolicyDefinitionService`	Role↔Permission (`grant`), User↔Role (`assign_role`)
`UserPolicyDefinitionService`	User's roles, permissions, organizers, merchants (read)
`OrganizerPolicyDefinitionService`	User↔Organizer / User↔Merchant (`join_domain`)
`PermissionPolicyDefinitionService`	User↔Permission (`grant`, direct)
`BasePolicyDefinitionService`	Shared privilege escalation validation

JWT Authorization Flow

useRequestContext() Output

typescript

const { currentUser, userId, roles, isAlwaysAllowed } = useRequestContext();

currentUser.priority.highest    // max priority across all roles
currentUser.priority.lowest     // min priority
currentUser.organizers          // [{ id: "org1" }, ...]
currentUser.merchants           // [{ id: "mer1" }, ...]

roles           // string[] of identifiers, e.g. ["999_super-admin"]
isAlwaysAllowed // true if SUPER_ADMIN or ADMIN

Frontend Integration

Decode JWT

typescript

const payload = decodeJwt(token);
const roles = payload.roles;  // Array<{ id, identifier, priority }>
const organizerIds = payload.organizerIds?.split(',').filter(Boolean) ?? [];
const merchantIds = payload.merchantIds?.split(',').filter(Boolean) ?? [];

Check Access

typescript

const isAdmin = roles.some(r => ['999_super-admin', '900_admin'].includes(r.identifier));
const isSystem = roles.some(r => ['999_super-admin', '900_admin', '600_operator'].includes(r.identifier));
const hasOrg = (orgId: string) => organizerIds.includes(orgId);

Permission-Aware UI

typescript

const perms = await fetch(`/policy-definitions/users/${userId}/permissions`);
const codes = new Set(perms.map(p => p.code));

const canCreateProduct = codes.has('commerce.product.create');

Seed Data

Fixed Roles (0001)

Identifier	Priority	Type
`999_super-admin`	999	SYSTEM
`900_admin`	900	SYSTEM
`600_operator`	600	SYSTEM
`500_organizer-owner`	500	SYSTEM
`110_cashier`	110	SYSTEM
`100_employee`	100	SYSTEM
`010_customer`	10	SYSTEM
`001_guest`	1	SYSTEM

Default Users (0002)

Username	Password	Role Identifier
`superadmin`	`Superadmin123`	`999_super-admin`
`admin`	`Admin123`	`900_admin`
`owner`	`Owner123`	`500_organizer-owner`
`employee`	`Employee123`	`100_employee`

Cross-Package Permission Seeding

Every service package seeds its own permissions via migration processes (*-seed-permissions, alwaysRun: true) so the catalog stays in sync with code.

Role grants are coarse: seed-role-grants.ts (COARSE_MODULE_GRANTS) gives each fixed role one grant per module it can touch, targeting the module resource node. The action lattice (g5 action_inherits) and resource nesting (g4 resource_inherits) then cover every subject/operation beneath it - e.g. OWNER gets manage, while CASHIER/EMPLOYEE get a narrower action per module. Owner/cashier/employee grants use the ANY_MEMBER domain scope; guest uses SYSTEM_WIDE. Super Admin / Admin / Operator are enforcement-bypassed and need no grants.

Package	Permission Prefix	Example Codes
`@nx/identity`	`identity.*`	`identity.user.create`, `identity.role.update`
`@nx/commerce`	`commerce.*`	`commerce.product.create`, `commerce.merchant.read`
`@nx/sale`	`sale.*`	`sale.order.create`, `sale.check.read`
`@nx/finance`	`finance.*`	`finance.wallet.create`, `finance.transaction.read`
`@nx/inventory`	`inventory.*`	`inventory.stock.update`, `inventory.purchase-order.create`
`@nx/payment`	`payment.*`	`payment.webhook-config.create`
`@nx/pricing`	`pricing.*`	`pricing.fare.create`, `pricing.tax.read`
`@nx/ledger`	`ledger.*`	`ledger.generate`, `ledger.download`
`@nx/signal`	`signal.*`	`signal.client.read`

All permissions are stored in the identity.Permission table and can be granted to roles or users via PolicyDefinition.

Authentication - Sign-in JWT generation
User Management - User creation with role assignment
Customer Management - Customer role
MFA & OTP - OTP-based authentication, rate limiting
Identity Overview - Architecture

Providers

Invoice Types

RBAC & Policy Definitions v1.0.0 ​

Core Entities ​

Casbin Authorization Model ​

PolicyDefinition Variants ​

Fixed System Roles ​

Role Hierarchy ​

AppFixedRoles Helper ​

Custom Roles ​

Scope Rules by Creator ​

Business Rules ​

Priority Guards ​

Fixed Role Protection ​

Deletion Constraints ​

Role Deletion Cascade ​

Permission Validation ​

API Reference ​

Roles - /roles ​

Permissions - /permissions ​

Policy Definitions - /policy-definitions ​

Request Body for Grant/Revoke ​

Response ​

Permission Resolution ​

PolicyDefinition Services ​

JWT Authorization Flow ​

useRequestContext() Output ​

Frontend Integration ​

Decode JWT ​

Check Access ​

Permission-Aware UI ​

Seed Data ​

Fixed Roles (0001) ​

Default Users (0002) ​

Cross-Package Permission Seeding ​

Related Pages ​

RBAC & Policy Definitions v1.0.0

Core Entities

Casbin Authorization Model

PolicyDefinition Variants

Fixed System Roles

Role Hierarchy

AppFixedRoles Helper

Custom Roles

Scope Rules by Creator

Business Rules

Priority Guards

Fixed Role Protection

Deletion Constraints

Role Deletion Cascade

Permission Validation

API Reference

Roles - `/roles`

Permissions - `/permissions`

Policy Definitions - `/policy-definitions`

Request Body for Grant/Revoke

Response

Permission Resolution

PolicyDefinition Services

JWT Authorization Flow

useRequestContext() Output

Frontend Integration

Decode JWT

Check Access

Permission-Aware UI

Seed Data

Fixed Roles (0001)

Default Users (0002)

Cross-Package Permission Seeding

Related Pages