RBACBee Lib

A pragmatic TypeScript RBAC toolkit for backend and frontend authorization flows.

Overview

RBACBee Lib separates authorization decisions from transport, persistence and authentication. The core engine is framework-agnostic; adapters connect it to frontend apps, NestJS, PostgreSQL and generated backend templates.

Use it when you need:

• Role-based authorization with permissions, tenant context and resource scope.
• A framework-agnostic frontend client for simple UI permission checks.
• A NestJS guard and decorators that stay independent from your auth strategy.
• PostgreSQL persistence for roles, permissions and assignments.
• A CLI that can generate a full NestJS backend and a React frontend demo.
• Test utilities for fast authorization checks without a database.

Packages

Package	Purpose	NPM
@rbacbee-lib/core	Framework-agnostic RBAC engine, ports, policies and value objects.	npm
@rbacbee-lib/client	Frontend-friendly client for UI permission checks.	npm
@rbacbee-lib/nest	NestJS module, decorators, identity resolvers and global guard.	npm
@rbacbee-lib/postgres	PostgreSQL store and schema migrator for RBAC data.	npm
@rbacbee-lib/cli	Project generator, migration helpers and diagnostics.	npm
@rbacbee-lib/testing	Internal test helpers and in-memory repository.	workspace

Installation

Install only what your app needs:

pnpm add @rbacbee-lib/core
pnpm add @rbacbee-lib/client @rbacbee-lib/core
pnpm add @rbacbee-lib/nest @rbacbee-lib/core
pnpm add @rbacbee-lib/postgres @rbacbee-lib/core pg

Or generate a ready-to-run NestJS backend:

pnpm dlx @rbacbee-lib/cli create my-api --install
cd my-api
cp .env.example .env
pnpm run db:up
pnpm run db:migrate
pnpm run db:seed
pnpm run start:dev

Generate a matching React frontend:

pnpm dlx @rbacbee-lib/cli create my-web --template react-rbac-client --install
cd my-web
cp .env.example .env
pnpm run dev

The frontend template uses Atomic Design, Zustand stores, TanStack Query and @rbacbee-lib/client for UI authorization checks.

Usage

Create an engine with any repository that implements AccessRepository:

import { createRbacEngine, type AccessRepository } from '@rbacbee-lib/core';

const accessRepository: AccessRepository = {
  async getAccessProfile({ userId }) {
    return {
      userId,
      loadedAt: new Date(),
      roles: [{ id: 'admin', name: 'Admin' }],
      permissions: [{ key: 'users:read', sourceRoleId: 'admin' }]
    };
  }
};

const rbac = createRbacEngine({ accessRepository, cacheTtlMs: 30_000 });
const result = await rbac.can({ userId: 'user-1' }, 'users:read');

console.log(result.decision); // allow | deny

Frontend applications can use the client facade:

import { createRbacClient } from '@rbacbee-lib/client/client';
import { createHttpAccessRepository } from '@rbacbee-lib/client/http';

const rbac = createRbacClient({
  principal: { userId: 'user-1', tenantId: 'tenant-1' },
  accessRepository: createHttpAccessRepository({
    endpoint: '/api/rbac/access-profile',
    credentials: 'include'
  })
});

const showEditButton = await rbac.can('posts:update');

Examples

NestJS Guard

import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { RbacGuard, RbacModule, RequirePermission } from '@rbacbee-lib/nest';

@Module({
  imports: [
    RbacModule.forRoot({
      accessRepository,
      identity: { strategy: 'jwt', userIdPath: 'user.sub', tenantIdPath: 'user.tenantId' },
      cacheTtlMs: 30_000
    })
  ],
  providers: [{ provide: APP_GUARD, useExisting: RbacGuard }]
})
export class AppModule {}

class UsersController {
  @RequirePermission('users:read')
  listUsers() {
    return [];
  }
}

PostgreSQL Store

import { createPostgresRbacStore } from '@rbacbee-lib/postgres';

const store = createPostgresRbacStore({ connectionString: process.env.DATABASE_URL });

await store.migrate();
await store.createRole({ id: 'admin', name: 'Admin', permissions: ['users:read'] });
await store.assignRole({ userId: 'user-1', roleId: 'admin', tenantId: 'tenant-1' });

Documentation

• docs/installation.md - setup guide.
• docs/quickstart-nest.md - NestJS quickstart.
• docs/frontend-client.md - framework-agnostic frontend integration.
• docs/postgres.md - PostgreSQL adapter details.
• docs/security.md - security model and defaults.
• examples/ - integration examples.

Contributing

Contributions are welcome. Please keep changes small, typed and tested.

pnpm install
pnpm typecheck
pnpm test
pnpm build

For package changes, update the relevant README and add a changeset when a release is needed.

Author

Created and maintained by Bryan-Herrera-DEV.

License

MIT