@ibyjs/rbac

Purpose

@ibyjs/rbac is the official reference RBAC implementation of Authorizer. It preserves the Yii-inspired ability to combine unrelated stores for items/hierarchy, membership assignments, and named rules.

Non-goals

It is not a database adapter, global role service, DI container, user-role model, decorator API, or mandatory authorization engine. It owns no persistence and does not assign tenant roles to a global principal.

Public semantics

RbacItem is a named role or permission with an optional application rule name. RbacSubject is exactly a membership subject, optionally tenant-scoped, and RbacAssignment links that subject to an item. RbacItemStore, RbacAssignmentStore, and RbacRuleResolver are independent required collaborators.

RbacAuthorizer rejects construction unless all three collaborators are supplied. It denies missing, suspended, unknown-status, or tenant-mismatched membership; filters assignments to the exact requested subject; sorts traversal for deterministic behavior; follows role children; evaluates named rules; detects hierarchy cycles; and denies when no permission matches. Store/rule failures reject rather than become allow. Allowed and denied results are ordinary explainable authorization decisions. definePermissions is identity-preserving type-safe sugar for an application-owned catalog; it does not register permissions globally.

Examples

import { RbacAuthorizer, definePermissions } from '@ibyjs/rbac'

const permissions = definePermissions({ documents: { read: 'document.read' } })
const authorizer = new RbacAuthorizer({ items, assignments, rules })
const decision = await authorizer.authorize({ context, permission: permissions.documents.read })

Extension and replacement

Implement any store independently—for example, Git-backed RbacItemStore, PostgreSQL RbacAssignmentStore, and TypeScript RbacRuleResolver—then select them in the composition root. Replace the whole engine with another Authorizer without changing use cases. Preserve exact membership and tenant scoping in every assignment backend.

Testing and conformance

@ibyjs/rbac/testing exports deterministic InMemoryRbacItemStore, InMemoryRbacAssignmentStore, and InMemoryRbacRuleResolver with explicit options and recorded rule evaluations. Tests cover direct/inherited grants, misses, false rules, cycles, suspended membership, foreign assignments, tenant mismatches, and collaborator failures. Empty configuration never produces success.

Compatibility

ESM-only. Runtime dependency is limited to @ibyjs/authorization; storage and rule providers remain application-selected. The engine does not import Hono, an ORM, @ibyjs/testing, or an auth provider.

API entry points

• @ibyjs/rbac: RbacItem, RbacSubject, RbacAssignment, RbacItemStore, RbacAssignmentStore, RbacRuleResolver, RbacAuthorizer, definePermissions, and related option/catalog types.
• @ibyjs/rbac/testing: InMemoryRbacItemStore, InMemoryRbacAssignmentStore, InMemoryRbacRuleResolver and their explicit option/recording types.
• Other source and build paths are private.