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 [email protected]

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, {
  actorId: 'quick-start',
  requestId: 'req-quick-start',
});
await scoped.roles.create({ id: 'order-reader', label: 'Order reader' });
await scoped.roles.allow('order-reader', {
  action: 'invoke',
  resource: 'api: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', 'api:GET:/api/orders')); // true
console.log(await subject.cannot('invoke', 'api: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.

pc.scope(scope, defaults) binds trusted management context once. With actorId/requestId defaults present, ordinary writes reuse the same audit context and derive their own idempotency keys; hand-written idempotencyKey values are only for advanced gateway or queue integrations.

Included capabilities

• scoped roles, direct user-role bindings, single-parent inheritance, allow/deny rules, and effective permission reads
• high-level menu config, page/action/API ownership, previewed role-menu grants, view trees, action maps, view state, and response field projection
• 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 a first role check, plus the next menu/API/response-field path
• 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.