Custom RBAC

Define custom roles within your Organization to grant members granular permissions beyond their base role. Custom roles are fully additive — they can only add permissions, never restrict them — ensuring consistent security boundaries while giving Malet Owners precise control over who can do what.

How It Works

Every Organization member already has a base role (OWNER, ADMIN, MEMBER, VIEWER) and optionally a Vertical role (GUIDE, KITCHEN, PHOTOGRAPHER, etc.). Custom roles add a third layer:

┌──────────────────────────────────────────────────────────────────────┐
│                     Permission Resolution                            │
│                                                                      │
│  Layer 1: BASE_ROLE_PERMISSIONS[MEMBER]                              │
│     → VIEW_ANALYTICS                                                 │
│                                                                      │
│  Layer 2: VERTICAL_ROLE_PERMISSIONS[KITCHEN]                         │
│     → VIEW_ORDERS, CREATE_ORDERS, UPDATE_ORDER_STATUS, ACCESS_KDS    │
│                                                                      │
│  Layer 3: CustomRole.permissions                                     │
│     → MANAGE_PRODUCTS, MANAGE_ORDERS                                 │
│                                                                      │
│  ═══════════════════════════════════════════                          │
│  Result: { VIEW_ANALYTICS, VIEW_ORDERS, CREATE_ORDERS,               │
│            UPDATE_ORDER_STATUS, ACCESS_KDS, MANAGE_PRODUCTS,          │
│            MANAGE_ORDERS } (deduplicated)                             │
└──────────────────────────────────────────────────────────────────────┘

Key design principle: Custom role permissions are additive-only. A MEMBER with a custom role always retains their base MEMBER permissions. The custom role can grant additional permissions but cannot revoke existing ones. This prevents a misconfigured custom role from accidentally locking someone out.

Entity Schema

CustomRole

Indexes:

• { organizationId: 1 } — Fast org-level lookups
• { organizationId: 1, slug: 1 } — Unique slug per Organization

Constraints:

• Maximum 50 custom roles per Organization — prevents abuse and keeps permission resolution performant
• Slug must match ^[a-z0-9-]+$ (lowercase alphanumeric + hyphens)
• At most one isDefault: true role per Organization — creating a new default automatically clears the previous one

Membership Extension

The Membership entity gains a new field:

When querying a member's permissions via GraphQL, the resolved field automatically includes custom role permissions:

query {
	myMemberships {
		organizationId
		role # Base role (MEMBER, ADMIN, etc.)
		verticalRole # Optional vertical role (KITCHEN, GUIDE, etc.)
		customRoleId # Optional custom role ID
		permissions # Computed: Base + Vertical + Custom (deduplicated)
	}
}

GraphQL Mutations

All mutations require the MANAGE_ROLES permission — only Organization OWNER and ADMIN roles have this by default.

Create Custom Role

mutation CreateCustomRole($input: CreateCustomRoleInput!) {
	createCustomRole(input: $input) {
		id
		organizationId
		name
		slug
		description
		permissions
		isDefault
		createdBy
		createdAt
	}
}

Variables:

{
	"input": {
		"orgId": "org-abc123",
		"name": "Inventory Manager",
		"slug": "inventory-manager",
		"description": "Can manage products and view analytics",
		"permissions": ["MANAGE_PRODUCTS", "VIEW_ANALYTICS"],
		"isDefault": false
	}
}

slug is optional — if omitted, it's auto-generated from the name (e.g. "Inventory Manager" → inventory-manager). Must be unique within the Organization.

Update Custom Role

Partial updates are supported — only include the fields you want to change.

mutation UpdateCustomRole($input: UpdateCustomRoleInput!) {
	updateCustomRole(input: $input) {
		id
		name
		description
		permissions
		isDefault
	}
}

Variables:

{
	"input": {
		"orgId": "org-abc123",
		"roleId": "role-xyz789",
		"name": "Senior Inventory Manager",
		"permissions": ["MANAGE_PRODUCTS", "MANAGE_ORDERS", "VIEW_ANALYTICS"]
	}
}

If updating permissions, at least one permission must remain. Empty permission arrays are rejected.

Delete Custom Role

Deletes the custom role and cascade-clears the customRoleId from all memberships that reference it. Members lose the custom role's extra permissions immediately but retain their base and vertical permissions.

mutation DeleteCustomRole($orgId: ID!, $roleId: ID!) {
	deleteCustomRole(orgId: $orgId, roleId: $roleId) {
		id
		name
	}
}

Assign Custom Role to Member

Assigns a custom role to an Organization member. The member must already exist in the Organization, and the custom role must belong to the same Organization.

mutation AssignCustomRole($input: AssignCustomRoleInput!) {
	assignCustomRole(input: $input) {
		userId
		customRoleId
	}
}

Variables:

{
	"input": {
		"orgId": "org-abc123",
		"userId": "user-staff-001",
		"roleId": "role-xyz789"
	}
}

Each member can have at most one custom role at a time. Assigning a new role replaces the previous one.

Remove Custom Role from Member

Clears the customRoleId from a member's record. The member reverts to their base + vertical permissions only.

mutation {
	removeCustomRoleFromMember(orgId: "org-abc123", userId: "user-staff-001") {
		userId
		customRoleId
	}
}

GraphQL Queries

List Organization Custom Roles

Returns all custom roles for an Organization, sorted alphabetically by name.

query OrganizationCustomRoles($orgId: ID!) {
	organizationCustomRoles(orgId: $orgId) {
		id
		name
		slug
		description
		permissions
		isDefault
		createdBy
		createdAt
	}
}

Get Single Custom Role

query CustomRole($roleId: ID!) {
	customRole(roleId: $roleId) {
		id
		name
		slug
		description
		permissions
		isDefault
		createdBy
		createdAt
		updatedAt
	}
}

Returns null if the role does not exist (no error thrown).

Permission Resolution Flow

When the PermissionsGuard evaluates access for a @RequirePermission-decorated resolver, it performs the following:

1. Extract userId from x-user-id header
2. Extract orgId from x-org-id header (or mutation input)
3. Look up Membership (userId + orgId)
4. If membership.customRoleId exists:
   a. Look up CustomRole by id
   b. Extract CustomRole.permissions
5. Compute effective permissions:
   BASE_ROLE_PERMISSIONS[membership.role]
   ∪ VERTICAL_ROLE_PERMISSIONS[membership.verticalRole]
   ∪ CustomRole.permissions
   → Set (deduplicated)
6. Check: required permission ∈ effective set
7. Attach permissions + membership to GraphQL context

The same resolution logic runs in MembershipResolver.permissions() when you query a member's permissions via GraphQL — ensuring consistency between authorization and display.

Available Permissions

Custom roles can grant any combination of the platform's Permission enum values:

Security note: While a custom role can include administrative permissions like MANAGE_ROLES or DELETE_ORG, this is intentional — it allows Organization Owners to precisely delegate authority. The additive-only design ensures a custom role never restricts existing access.

Audit Events

All custom role lifecycle changes are logged via the Organization Audit Trail — see Edit History Audit Trail for the broader field-level change tracking system.

Permission Matrix

Cascade Behavior

Deleting a Custom Role

When a custom role is deleted:

1. The CustomRole document is removed from the database
2. All memberships referencing that customRoleId are updated: customRoleId is set to null
3. Affected members immediately lose the extra permissions — they revert to Base + Vertical only
4. An audit event is recorded with the count of affected memberships

Deleting an Organization Member

When a member is removed from an Organization, their Membership record (including any customRoleId) is deleted. No cleanup of the CustomRole is needed — the role continues to exist for other members.

Module Structure

apps/organizations/src/custom-role/
├── custom-role.entity.ts          # CustomRole entity (Typegoose + GraphQL)
├── custom-role.service.ts         # CRUD + assign/remove + audit logging
├── custom-role.resolver.ts        # GraphQL mutations + queries
├── custom-role.service.spec.ts    # 28 unit tests
├── custom-role.resolver.spec.ts   # 10 unit tests
└── dto/
    ├── create-custom-role.input.ts   # CreateCustomRoleInput
    ├── update-custom-role.input.ts   # UpdateCustomRoleInput
    └── assign-custom-role.input.ts   # AssignCustomRoleInput

Error Handling

Example: Setting Up a Restaurant Org

Here's a practical workflow for a Malet Owner running a restaurant vertical:

# 1. Create a "Shift Manager" custom role
mutation {
	createCustomRole(
		input: {
			orgId: "org-restaurant-01"
			name: "Shift Manager"
			description: "Can manage orders and view kitchen display"
			permissions: [MANAGE_ORDERS, VIEW_ORDERS, ACCESS_KDS]
		}
	) {
		id
		slug # → "shift-manager"
	}
}

# 2. Create a "Content Specialist" custom role
mutation {
	createCustomRole(
		input: {
			orgId: "org-restaurant-01"
			name: "Content Specialist"
			description: "Can update menu items and blog posts"
			permissions: [MANAGE_PRODUCTS, EDIT_BLOGS]
			isDefault: false
		}
	) {
		id
		slug # → "content-specialist"
	}
}

# 3. Assign "Shift Manager" to a MEMBER
mutation {
	assignCustomRole(
		input: { orgId: "org-restaurant-01", userId: "user-maria", roleId: "<shift-manager-id>" }
	) {
		userId
		customRoleId
	}
}

# 4. Query Maria's effective permissions
# (As Maria)
query {
	myMemberships {
		role # "MEMBER"
		customRoleId # "<shift-manager-id>"
		permissions # ["VIEW_ANALYTICS", "MANAGE_ORDERS", "VIEW_ORDERS", "ACCESS_KDS"]
	}
}

Maria now has her base MEMBER permissions (VIEW_ANALYTICS) plus the Shift Manager permissions (MANAGE_ORDERS, VIEW_ORDERS, ACCESS_KDS) — without needing to be promoted to ADMIN.

Testing

Running Tests

# Unit tests only
npx jest --testPathPattern="custom-role" --no-coverage

# E2E tests only
npx jest --config apps/organizations/test/jest-e2e.json --testPathPattern=custom-roles --forceExit

# Full organizations suite (148 unit + 56 E2E)
npx jest --testPathPattern="organizations" --no-coverage

Note: E2E tests use in-memory MongoDB and mock the ALERTS_SERVICE TCP client since the Alerts service isn't running during test execution.

Frontend Implementation

The Custom RBAC UI lives in the Organization management dashboard at /orgs/[slug]/manage#roles. It replaces the previous placeholder with a fully functional role editor and inline assignment system.

Components

Permission Matrix

The PERMISSION_CATEGORIES constant organizes 35 platform permissions into 8 visual groups. Each group renders as a collapsible section with:

• A category-level checkbox to toggle all permissions in the group
• Individual permission checkboxes in a responsive grid
• A selected count indicator

Role Assignment

Roles are assigned inline from the Members tab — each member row has a "Custom Role" <select> dropdown that appears when custom roles exist. The dropdown calls assignCustomRole / removeCustomRoleFromMember mutations directly, triggering a full org reload to reflect the change.

Design Decisions

Frontend Testing

# Unit tests — permission matrix structure validation
npx vitest run --environment node tests/custom-rbac.test.ts

# E2E tests — role list rendering, create flow
pnpm test -- tests/custom-rbac.spec.ts

Related

• Organizations & Permissions — Base roles (OWNER/ADMIN/MEMBER/VIEWER), vertical roles, and the PermissionsGuard that Custom RBAC extends
• Teams & Sub-Groups — Group members into named teams with maletIds scoping — Custom RBAC permissions layer on top of team membership
• Corporate Identity (SAML & SCIM) — Enterprise provisioning that creates members who can then be assigned custom roles
• Organization & Malet Management — Frontend management UI for Organizations, Malets, domains, and billing
• Edit History Audit Trail — Cross-entity field-level audit trail that tracks changes across the platform
• SIEM Event Streaming — Stream audit events (including custom role lifecycle) to external SIEM platforms via HMAC-signed webhooks
• Tag Registry — MANAGE_TAGS permission can be delegated via custom roles for tag administration
• Subscription & Billing — Subscription tiers restrict the maximum number of custom roles per organization and limit total members.
• Revenue Sharing & Payouts — VIEW_PAYOUTS, MANAGE_PAYOUTS, VIEW_REVENUE, and MANAGE_COMMISSIONS permissions can be delegated via custom roles
• Permission Matrix Editor — UI component architecture for the interactive checkbox matrix