rbac-fs

Git-friendly, zero-database RBAC — roles and permissions as JSON files, multi-tenant by default, works in Node and the browser, in JS or TS.

npm install rbac-fs gives you role-based access control that stores roles and permissions as human-readable JSON files under a .rbac/ folder — no database to stand up, no opaque policy blob, every role change is a normal, reviewable diff in your PR.

Why rbac-fs

| | rbac-fs | Casbin | AccessControl | CASL | |---|---|---|---|---| | Storage | Git-friendly JSON files | Model + policy files/DB adapters | In-memory / your own storage | In-memory / your own storage | | Multi-tenant | Built in, folder-isolated | Manual (namespacing policies yourself) | Manual | Manual | | Node + browser | One package, both builds | Node-focused | Both, no dedicated browser API | Both | | Framework adapters | 8 built in (NestJS, Express, Fastify, Koa, React, Vue, Angular, Svelte) | None built in | None built in | Some community adapters | | Core dependencies | Zero (Core Engine) | Several | Zero | Zero | | Audit logging | Built in, JSONL + rotation | Not built in | Not built in | Not built in |

Install

npm install rbac-fs

Quick start (JavaScript)

import { RBAC } from 'rbac-fs';

const rbac = new RBAC({ tenantId: 'acme-corp' });
await rbac.createRole('manager', { permissions: [{ resource: 'invoice', actions: ['approve'] }] });

const allowed = await rbac.can({ id: 'u1', role: 'manager' }, 'invoice', 'approve');
console.log(allowed); // true

Quick start (TypeScript)

import { RBAC, type RbacUser } from 'rbac-fs';

const rbac = new RBAC({ tenantId: 'acme-corp' });
await rbac.createRole('manager', { permissions: [{ resource: 'invoice', actions: ['approve'] }] });

const user: RbacUser = { id: 'u1', role: 'manager' };
const allowed: boolean = await rbac.can(user, 'invoice', 'approve');

Both snippets create .rbac/tenants/acme-corp/roles/manager.json on disk the first time they run — that file is the reviewable source of truth from then on; hand-editing it works too (and is picked up automatically, see "Live-reload" below).

Multi-tenant example

const acme = new RBAC({ tenantId: 'acme-corp' });
const globex = new RBAC({ tenantId: 'globex-inc' });

await acme.createRole('manager', { permissions: [{ resource: 'invoice', actions: ['approve'] }] });
await globex.createRole('manager', { permissions: [{ resource: 'ledger', actions: ['approve'] }] });

// Same role name, completely isolated files and permissions per tenant:
// .rbac/tenants/acme-corp/roles/manager.json
// .rbac/tenants/globex-inc/roles/manager.json

// Omit tenantId (or pass null) to use cross-tenant `_shared/` roles instead:
const platform = new RBAC(); // -> .rbac/_shared/roles/*.json

tenantId and role names are sanitized against ^[a-zA-Z0-9_-]+$ before touching the filesystem — path-traversal attempts (../../etc, etc.) are rejected, not silently resolved.

Audit logging + rotation

Every can() call is recorded to logs/<role>.jsonl (JSON Lines — one allow/deny decision per line, so a corrupted line only breaks that one record). Rotation is on by default and configurable:

const rbac = new RBAC({
  tenantId: 'acme-corp',
  rotation: {
    maxSize: '5MB',   // rotate the active log once it reaches this size
    maxAge: '90d',     // delete rotated files older than this
    compress: 'gzip',  // compress rotated files
    maxBackups: 12,    // keep at most this many rotated files per role
  },
});

const entries = await rbac.getAuditLog('manager', { since: '2026-08-01' });

Live-reload

Role files are cached in memory for fast can() checks, and a chokidar-backed watcher invalidates the cache automatically when a role file is hand-edited on disk — no restart needed. Disable caching entirely with new LocalJsonAdapter({ cache: false }) if you're on a filesystem where local file-watching isn't reliable (e.g. some networked/shared volumes).

Dynamic role management

await rbac.createRole('supervisor', { inherits: ['viewer'] });
await rbac.grant('supervisor', { resource: 'invoice', actions: ['view', 'approve'] });
await rbac.revoke('supervisor', { resource: 'invoice', actions: ['approve'] });
await rbac.listRoles();
await rbac.deleteRole('supervisor');

Feature-scoped permissions + composable conditions

A role's permission matrix can have more than one layer: module-level grants, feature-level grants within a module, and a runtime condition scoped to one specific feature.

Module vs. feature — just separate resource ids

resource is a free-form string with no built-in hierarchy — a feature is simply its own resource id, dot-separated by convention. Granting the module does not automatically grant its features (no wildcard rollup):

await rbac.grant('clerk', { resource: 'invoice', actions: ['view'] }); // module-level
await rbac.grant('clerk', { resource: 'invoice.line-items', actions: ['add', 'edit'] }); // feature-level

await rbac.can(clerkUser, 'invoice', 'view'); // true
await rbac.can(clerkUser, 'invoice.line-items', 'add'); // true
await rbac.can(clerkUser, 'invoice', 'add'); // false — module grant doesn't imply the feature

Composable condition — AND/OR/NOT over a fixed, safe operator set

A single when: "a == b" clause can't express "device is mobile and location is in this list" — multiple Condition entries on the same resource+action OR against each other, not AND. The condition tree solves this with and/or/not nodes, nestable to arbitrary depth, over a fixed operator vocabulary — still zero eval()/Function(), just JSON:

await rbac.createRole('mobile-approver', {
  conditions: [
    {
      resource: 'invoice.line-items',
      actions: ['approve'],
      condition: {
        and: [
          { op: 'eq', path: 'device', value: 'mobile' },
          { op: 'in', path: 'location', value: ['US', 'IN', 'EU'] },
        ],
      },
    },
  ],
});

await rbac.can(user, 'invoice.line-items', 'approve', { device: 'mobile', location: 'IN' }); // true
await rbac.can(user, 'invoice.line-items', 'approve', { device: 'desktop', location: 'IN' }); // false

path/valuePath operands resolve the same way when always has: user.<field> reads from the user object passed to can(), any other bare path reads from context (can()'s 4th argument).

Operators:

| Operator | Leaf shape | Meaning | |---|---|---| | eq / neq | { op, path, value } or { op, path, valuePath } | equal / not equal (loose string comparison, same as legacy when) | | gt / gte / lt / lte | { op, path, value: number } or { op, path, valuePath } | numeric comparison | | in / notIn | { op, path, value: [...] } | membership in a literal list | | exists / notExists | { op, path } | is the resolved value defined? | | contains | { op, path, value } | substring match on a string, or membership on an array | | startsWith / endsWith | { op, path, value } | string prefix/suffix match |

when still works, unchanged — a Condition uses exactly one of when (legacy single-clause form) or condition (the tree); both evaluate through the same evaluator, no migration needed for existing role files.

Custom operators — the escape hatch for rules the built-ins can't express

For app-specific logic no fixed operator list can anticipate (geofence radius, business-hours windows, a scoring function), register a named predicate — the engine calls a real function you wrote, never anything parsed out of the JSON role file:

const rbac = new RBAC({
  tenantId: 'acme-corp',
  operators: {
    withinRadius: ({ context, args }) => haversineKm(context.userLocation, context.siteLocation) <= (args?.km as number),
  },
});

await rbac.createRole('field-approver', {
  conditions: [{ resource: 'site-visit', actions: ['approve'], condition: { op: 'custom', name: 'withinRadius', args: { km: 5 } } }],
});

Same option on the browser client: new RBACClient(snapshot, { operators }). Referencing an unregistered custom name throws UnknownConditionOperatorError — deliberately, not a silent deny.

Browser usage

The Node package (rbac-fs) reads/writes .rbac/ on disk and should never ship to a browser bundle. For the browser, fetch an already-resolved permission snapshot from your backend and use the read-only client instead — synchronous, in-memory, zero filesystem access:

import { RBACClient } from 'rbac-fs/client';

const client = new RBACClient(snapshotFromYourApi); // { user?, permissions, conditions? }
client.can('invoice', 'approve'); // synchronous, no await

RBACClient has no close() — unlike the Node RBAC class, it holds no OS resources (no file watchers, no log streams), so there's nothing to release.

Framework adapters

Every adapter is a subpath of the same package — one npm install, pick what you need:

| Import | Framework | What it gives you | |---|---|---| | rbac-fs | — (Node core) | RBAC class, full read/write, the entry point every backend adapter wraps | | rbac-fs/client | — (browser core) | RBACClient, synchronous read-only can() from a snapshot | | rbac-fs/express | Express | rbacMiddleware(rbac, resource, action, options?) | | rbac-fs/nestjs | NestJS | @RequirePermission() decorator + RbacGuard + provideRbac() | | rbac-fs/fastify | Fastify | rbacPlugin — register once, declare config: { rbac: { resource, action } } per route | | rbac-fs/koa | Koa | rbacMiddleware(rbac, resource, action, options?), async/await native | | rbac-fs/react | React | <RbacProvider> + <Can I="approve" a="invoice"> + usePermission() | | rbac-fs/vue | Vue 3 | createRbacPlugin(client) + v-can directive + usePermission() composable | | rbac-fs/angular | Angular | provideRbacClient() + RbacService + *rbacCan structural directive | | rbac-fs/svelte | Svelte | createPermissionStore(client) ($permissions(...)) + createCanAction(client) (use:can) |

Every adapter is a thin translation layer — none of them re-implement permission logic; they all call straight into RBAC.can() / RBACClient.can(), so the same role/permission files drive every framework identically.

See examples/ for a runnable, verified-against-the-real-build code sample for every one of the above — core engine, dynamic roles, conditional grants, multi-tenancy, audit logging, live-reload, and all 8 framework adapters.

Security guardrails (built in, not left to you)

• tenantId/role name sanitization against path traversal, on every call.
• Schema validation on every role write (unknown fields, malformed permissions/conditions all rejected before touching disk).
• Reserved role names (admin, system-admin) blocked from accidental overwrite unless { force: true }.
• Circular inheritance detection on every createRole/grant.
• Condition expressions (legacy when clauses and the composable condition tree — see "Feature-scoped permissions + composable conditions") use a hand-rolled, fixed operator vocabulary — no eval()/Function() — so a hand-edited role file can't become a code-execution vector. custom operators call a function you registered in your own code, never anything parsed out of the file.

Who's allowed to call createRole/grant/etc. in the first place is your app's own business rule — check rbac.can(user, 'role', 'manage') (or whatever permission model fits your app) before exposing role management to end users.

Minimum requirements

Node.js >=20. TypeScript is optional — every subpath ships plain .js (CJS + ESM) with bundled .d.ts types; a .js-only project never needs a TypeScript compiler.

License

MIT