permission-core

Documentation | Quick Start | Examples | Changelog

permission-core is a tenant-aware authorization core for Node.js. It persists RBAC state through the host's MonSQLize 3.1 instance and uses one action + resource model for routes, menus, backend APIs, database rows, and fields.

Install

npm install permission-core monsqlize@3.1.0

The root and permission-core/match entries support Node.js >=18.0.0. The optional permission-core/plugins/vext entry inherits Vext 0.3.26's stricter Node.js >=20.19.0 requirement.

import MonSQLize from 'monsqlize';
import { PermissionCore } from 'permission-core';

const msq = new MonSQLize({
  type: 'mongodb',
  databaseName: 'app',
  config: { uri: 'mongodb://127.0.0.1:27017' },
});
await msq.connect();

const pc = new PermissionCore({ monsqlize: msq });
await pc.init();

const scope = { tenantId: 'acme' };
const scoped = pc.scope(scope);
await scoped.roles.create({ id: 'order-reader', label: 'Order reader' });
await scoped.roles.allow('order-reader', {
  action: 'invoke',
  resource: 'GET:/api/orders',
});
await scoped.userRoles.assign('u-1', 'order-reader');

const subject = pc.forSubject({ userId: 'u-1', scope });
console.log(await subject.can('invoke', 'GET:/api/orders')); // true
console.log(await subject.cannot('invoke', 'DELETE:/api/orders')); // true

await pc.close();
await msq.close();

cannot(...) is the logical negation of can(...); the DELETE result is true because no allow rule exists, not because a blocked permission was assigned.

Included capabilities

• scoped roles, direct user-role bindings, single-parent inheritance, allow/deny rules, and effective permission reads
• menu/page/button management, API bindings, previewed role-menu grants, visible trees, button maps, and route state
• authorized Mongo collections that compose business filters, exact tenant fields, row conditions, field permissions, and bounded writes
• optimistic revisions, idempotency, audit evidence, health reporting, and optional MonSQLize-backed semantic caching
• optional native Vext integration from permission-core/plugins/vext for hosts on Node.js >=20.19.0

Ownership boundary

The application owns authentication, trusted subject construction, the MonSQLize connection, business data, HTTP serialization, and operational policy. permission-core owns authorization state and decisions. It does not implement login, expose a generic database adapter layer, or close the host database connection.

Runnable examples

npm run example:basic
npm run example:multi-tenant
npm run example:data-guard
npm run example:menu-admin
npm run example:vext

Run all five with npm run example:all. Each emits stable JSON and uses an in-memory Mongo replica set only as a repository fixture; production applications pass their existing connected MonSQLize 3.1 instance.

Documentation map

• Quick Start: installation through role reads, menu/API grants, row and field filtering, and owner-order shutdown
• Permission lifecycle: transaction, revision, audit, cache, and fail-closed behavior
• API reference: exact public managers, responses, errors, and limits
• Troubleshooting: recovery by error code and details discriminator

Repository validation and release commands are documented separately in CONTRIBUTING.md. Security reports follow SECURITY.md.