RBAC

A powerful, fully type-safe Role-Based Access Control (RBAC) plugin for TezX, designed to help you control access to routes, APIs, and resources using simple, template-based permission keys with full IntelliSense support.

Highlights

🎯 Type-safe permission system (T extends string[])
🧠 IntelliSense-based permission enforcement
🔁 Multi-role support (ctx.user.role can be string | string[])
⚙️ Middleware-driven, plug-and-play
❌ Built-in denial handling + custom onDeny() support
🧩 Easy integration with auth middlewares (like authChecker)
🧪 Battle-tested in production apps
🔑 Use role IDs(Dynamically generated, flexible)
🔍 Clean merge of all permissions (No manual logic needed)
🏷️ Static roles still supported (Easy for default usage)

Installation

npm install @tezx/rbac

🧠 How It Works

[Your Middleware]
    ⬇️ sets ctx.user.role
[RBAC Plugin]
    ⬇️ loads permission map
[Route Guard]
    ⬇️ checks permission key
[✓ ALLOW] or [❌ DENY]

Required: `ctx.user.role`

To work correctly, you must set ctx.user.role before using RBAC.

✅ Example:

ctx.user = {
  id: 'user_001',
  role: 'admin',  // ✅ Required
  email: 'rakib@example.com'
};

✅ If roles can be multiple:

ctx.user = {
  role: ['editor', 'viewer']
};

💡 Use authChecker() middleware to assign ctx.user from token/session.

Usage Example


import RBAC from '@tezx/rbac';
type Permissions = ['user:create', 'user:delete', 'order:read', 'property:approve'];

const rbac = new RBAC<Permissions>();

app.use(authChecker()); // ✅ Assigns ctx.user + ctx.user.role

app.use(rbac.plugin({
  loadPermissions: async () => ({
    admin: ['user:create', 'user:delete', 'order:read', 'property:approve'],
    editor: ['order:read'],
    guest: []
  })
}));

app.get('/admin/users', rbac.authorize('user:create'), async (ctx) => {
  return ctx.text('You can create users.');
});

RBAC Lifecycle

Step	Action
1️⃣	`ctx.user.role` assigned by auth middleware
2️⃣	`rbac.plugin()` loads Role→Permission map
3️⃣	`rbac.authorize('permission:key')` checks merged role permissions
4️⃣	If not allowed → return `403` (with `onDeny` if provided)

Replace `role` with Unique Role IDs (Advanced)

RBAC system supports mapping dynamic role identifiers (like database IDs or UUIDs) instead of hardcoded role names.

This is helpful when:

✅ Roles are created dynamically from a dashboard or DB
✅ You want to map user roles like "role_8FaHq1" instead of just "admin"
✅ Permission sets are assigned to these dynamic IDs

🧪 Example

ctx.user = {
  id: 'user_xyz',
  role: 'role_8FaHq1' // ✅ Your actual role ID from database
};

// Load role-permission map based on DB role IDs
loadPermissions: async () => ({
  role_8FaHq1: ['user:create', 'order:read'],
  role_7NbQt55: ['user:delete']
})

✅ Internally, RBAC merges all permissions based on the provided ctx.user.role, whether it's string or string[].

Important

Make sure the role ID you assign in ctx.user.role exactly matches the keys in your permission map.

Bonus: Hybrid Role Support

You can even mix static roles with dynamic IDs if needed:

ctx.user = {
  role: ['admin', 'role_7bXy91']
};

loadPermissions: async () => ({
  admin: ['dashboard:access'],
  role_7bXy91: ['product:create']
});

Plugin API

`rbac.plugin(config)`

Initializes the permission map.

Config options:

Field	Type	Required	Description
`loadPermissions`	`(ctx) => RolePermissionMap`	✅	Role → permission map
`isAuthorized`	`(roles, permissions, ctx)`	❌	Custom check hook
`onDeny`	`(error, ctx)`	❌	Custom deny response

`rbac.authorize('permission:key')`

Middleware to protect routes.

app.post('/orders', rbac.authorize('order:read'), handler);

IntelliSense with Template Types

type Permissions = ['user:create', 'order:read', 'admin:panel'];

const rbac = new RBAC<Permissions>();

✅ Now rbac.authorize(...) will auto-suggest only those permission keys.

Custom Deny Example

rbac.plugin({
  loadPermissions: ...,
  onDeny: (error, ctx) => {
    return ctx.json({
      success: false,
      reason: error.message,
      permission: error.permission
    });
  }
});

Real-World Structure

const permissionMap = {
  admin: ['user:create', 'user:delete'],
  editor: ['order:read'],
  viewer: [],
};

User may have:

ctx.user = {
  id: 'u-001',
  role: ['editor', 'viewer']
};

RBAC will combine permissions from both roles.

Debug Tip

To check permissions being applied at runtime:

console.log(ctx.user.permissions); // all merged permissions

Types Summary

type RolePermissionMap<T extends string[]> = Record<string, T[number][]>;
type DenyError<T extends string[]> = {
  error: string;
  message: string;
  permission: T[number];
};

Exported API

import RBAC, { plugin, authorize } from '@tezx/rbac';

Test Route Example

app.get('/secure', rbac.authorize('admin:panel'), async (ctx) => {
  ctx.body = { status: 'Access granted.' };
});

Best Practices

🔄 Always assign ctx.user.role in authChecker
🧠 Define permissions centrally as union literal type
🔐 Protect all critical routes using rbac.authorize()
🧪 Add logging inside onDeny for better traceability

RBAC

On this page