Skip to content
Projects

phellipeandrade/rbac has 286 GitHub stars and 22 forks. GitHot measured -1 stars in 24 hours. Last checked 2026-11-19 11:57 UTC. Last push 2026-11-14.

How these counts are measured

Measured star growth

in 24h
-1
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Hierarchical Role-Based Access Control for Node.js

Security

README.md

Original

RBAC

RBAC logo — blue shield and padlock with RBAC wordmark

Hierarchical role-based access control for Node.js and TypeScript.

npm version CI license

RBAC makes authorization decisions from roles, permission names, inheritance, and optional conditions. Define policies in code or load role definitions through a database adapter, then check operations with an asynchronous, deny-by-default API.

  • Hierarchical roles: inherited grants are additive, including conditional grants.
  • Precise matching: exact operations, globs (* and **), and regular expressions.
  • Conditional access: synchronous/async predicates, promises, and explicit callback adapters.
  • Runtime updates: add or merge roles without recreating the authorization instance.
  • Optional integrations: MongoDB, MySQL, PostgreSQL, Express, NestJS, and Fastify.
  • Package interoperability: CommonJS and ESM entry points with TypeScript declarations; matching caches are bounded.

Requirements: Node.js 22.12.0+. The current major version is 4.x; review the migration guide when upgrading.

Documentation

Full documentation · Interactive playground · Generated API reference · Português (Brasil)

The documentation includes complete guides to roles and inheritance, conditions, patterns, runtime updates, database adapters, framework integrations, security, examples, and migration. API reference pages are generated from the public TypeScript entry points.

See the runnable examples in examples/ and version history in CHANGELOG.md.

Brand assets

The full RBAC logo and shield and padlock icon are transparent, fully vector SVGs with no external font dependencies. The brand colors are blue #2563EB and navy #0F172A.

Install

npm install @rbac/core

Quick start

import { createRBAC } from '@rbac/core';

const auth = createRBAC({ roles: {
  viewer: { can: ['posts:read'] },
  editor: { inherits: ['viewer'], can: ['posts:create', 'posts:update'] },
  admin: { inherits: ['editor'], can: ['posts:delete'] }
}, enableLogger: false });

async function main() {
  console.log(await auth.can('editor', 'posts:read'));   // true: inherited
  console.log(await auth.can('viewer', 'posts:delete')); // false
  console.log(await auth.can('unknown', 'posts:read'));  // false
}

void main();

createRBAC({ roles, ...options }) returns an instance with three methods:

Method Description
can(role, operation, params?) Resolves to Promise<boolean>; unmatched operations and unknown roles are denied.
addRole(name, definition) Adds or replaces one role, immediately rebuilding the permission hierarchy.
updateRoles(roles) Merges definitions into existing roles and invalidates matching caches.

The can parameter operation accepts a string or RegExp. Roles require a can array of operation strings or {name, when} grants; inherits is an optional array of role names.

Conditions and asynchronous authorization

import { createRBAC } from '@rbac/core';

type Context = { userId: string; ownerId: string };

const auth = createRBAC<Context>({ roles: {
  author: {
    can: [{
      name: 'article:edit',
      when: async ({ userId, ownerId }: Context) => userId === ownerId
    }]
  }
} });

console.log(await auth.can('author', 'article:edit', {
  userId: '42',
  ownerId: '42'
})); // true

Conditions may return a boolean or a promise. For existing Node-style callback predicates, use callbackWhen() from @rbac/core/helpers. Authorization errors and rejected conditions fail closed. Validate ownership and role information on the server: values supplied by a client are not trustworthy evidence.

Multiple conditional grants for an operation use OR semantics; each condition stays independently evaluable. Conditional results are evaluated for each call, including after role updates.

Patterns

import { createRBAC } from '@rbac/core';

const auth = createRBAC({ roles: {
  operator: { can: ['orders:*', 'files/**', '/^reports:(read|export)$/'] }
} });

console.log(await auth.can('operator', 'orders:approve')); // true
console.log(await auth.can('operator', 'reports:read'));  // true
console.log(await auth.can('operator', 'users:delete'));  // false

Use exact permissions for sensitive operations. Pattern matching guide.

Update roles at runtime

import { createRBAC } from '@rbac/core';

const auth = createRBAC({ roles: { viewer: { can: ['tickets:read'] } } });
auth.addRole('support', { can: ['tickets:read'] });
auth.updateRoles({ support: { can: ['tickets:read', 'tickets:reply'] } });
console.log(await auth.can('support', 'tickets:reply')); // true

Updates merge role definitions, replacing the definition of any role name supplied.

Database adapters and multi-tenancy

Use @rbac/adapters for MongoRoleAdapter, MySQLRoleAdapter, or PostgresRoleAdapter. Install only the database driver your application needs (mongodb, mysql2, or pg). Adapters implement getRoles, addRole, and updateRoles, with optional tenant IDs.

import { createTenantRBAC } from '@rbac/adapters';
import { MongoRoleAdapter } from '@rbac/adapters';

const adapter = new MongoRoleAdapter({
  uri: 'mongodb://localhost:27017',
  dbName: 'app',
  collection: 'rbac_roles'
});

const tenantAuth = await createTenantRBAC(adapter, 'tenant-a');
console.log(await tenantAuth.can('reader', 'documents:read'));

This example assumes a running MongoDB instance and existing tenant role records. createTenantRBAC loads the roles once; reload or update the instance when persistent policies change. See the adapter guide for schema requirements, custom columns, and tenant isolation.

Frameworks, schemas, and configuration

Express, NestJS, and Fastify integrations are available through separate @rbac/express, @rbac/nestjs, and @rbac/fastify packages. Authenticate users before extracting their roles. See middleware integration examples.

Validation schemas are opt-in via @rbac/schemas; importing @rbac/core does not load Zod. The RBACOptions object requires roles and also accepts these optional configuration fields:

Option Description
enableLogger? Enable or disable authorization logging.
logger? Custom (role, operation, result, colorsEnabled?) => void logger.
colors? Force ANSI color on/off; otherwise use the default detection.

Avoid exposing credentials or sensitive request parameters through custom logs. Database connection errors may propagate from adapters; in-memory permission checks deny access when their conditions fail.

Benchmark results (November 2026)

On Node.js 22.14.0 / Windows 11 Pro / Intel i7-9700KF, the v4 comparison suite measured 7,282,499 direct permission checks/s with @rbac/core on the small dataset and 7,086,106 checks/s with 200 resources. The chart compares direct checks on the same host, measured on November 14, 2026.

xychart-beta
    title "Direct authorization - million ops/s (200 resources)"
    x-axis ["@rbac/core", "AccessControl", "rbac", "Easy RBAC", "Fast RBAC"]
    y-axis "Million ops/s" 0 --> 8
    bar [7.09, 0.91, 0.11, 5.75, 2.57]
Library Small direct (ops/s) 200-resource direct (ops/s)
@rbac/core 7,282,499 7,086,106
AccessControl 943,635 908,823
rbac 209,160 111,538
Easy RBAC 6,119,410 5,747,234
Fast RBAC 2,989,702 2,567,862

These results are specific to the measured workloads; other libraries expose different authorization models and APIs. For inherited, glob, conditional and isolated engine measurements, see the complete benchmark report (Português). Raw JSON/CSV/HTML artifacts and reproduction instructions are included in the repository.

npm run build
npm run bench:engine
npm run bench

Development and contributing

npm ci
npm run lint
npm run typecheck
npm test
npm run test:package

Use Node.js 22.14.0 for repository development (see .nvmrc). Read CONTRIBUTING.md for development conventions and documentation authoring.

License

MIT © RBAC contributors.