@sarfarajey/rbac-merge

Tiny RBAC primitive shaped after the Salesforce Profile + Permission Set model:

• A profile baseline — a static per-role table of granted capabilities, defined in code and shipped with the application.
• Permission set overrides — per-user, additive grants typically loaded from a database.
• Effective permissions = union of the two. Overrides can only add; never remove.

Generic over role and feature names. Zero dependencies.

Install

npm install @sarfarajey/rbac-merge

Define your roles and features in code

import type { RoleBaseline } from '@sarfarajey/rbac-merge';

type Role    = 'guest' | 'user' | 'admin';
type Feature = 'posts' | 'admin' | 'profile';

const baseline: RoleBaseline<Role, Feature> = {
    guest: {
        posts:   ['view'],
    },
    user: {
        posts:   ['view', 'create'],
        profile: ['view_own', 'edit_own'],
    },
    admin: {
        posts:   ['view', 'create', 'delete'],
        profile: ['view_own', 'edit_own', 'view_others'],
        admin:   ['view_dashboard', 'manage_users'],
    },
};

Check a capability

import { hasPermission } from '@sarfarajey/rbac-merge';

hasPermission<Role, Feature>('user', 'posts', 'create', { baseline });
// → true

hasPermission<Role, Feature>('user', 'posts', 'delete', { baseline });
// → false

hasPermission<Role, Feature>(null, 'posts', 'view', {
    baseline,
    defaultRole: 'guest',
});
// → true

Per-user overrides

A specific user may have extra grants stored in the database — pass them in:

const userOverrides = {
    posts: ['delete'],          // grant delete on posts
    admin: ['view_dashboard'],  // unlock the admin dashboard
};

hasPermission<Role, Feature>('user', 'posts', 'delete', {
    baseline,
    overrides: userOverrides,
});
// → true (granted via override)

Overrides add only — they cannot remove capabilities the baseline grants.

Resolved map

import { getPermissions } from '@sarfarajey/rbac-merge';

getPermissions<Role, Feature>('user', { baseline, overrides: userOverrides });
// {
//   posts:   ['view', 'create', 'delete'],
//   profile: ['view_own', 'edit_own'],
//   admin:   ['view_dashboard'],
// }

Plain merge

If you already have the role's baseline in hand and just want the merge:

import { mergePermissions } from '@sarfarajey/rbac-merge';

mergePermissions(baseline.user, userOverrides);

Security invariants worth knowing

1. Unknown role → denied. If you call hasPermission('developer', ...) and 'developer' is not in your baseline, it is denied. It does not silently fall back to defaultRole. Only null / undefined use defaultRole. This matters when role strings come from untrusted sources (cookies, JWT claims): an attacker writing a bogus role name can never inherit guest's permissions.

2. Adding a capability to the baseline takes effect immediately. No need to migrate per-user override records when you add posts.archive to the admin baseline — every admin gets it on the next deploy.

3. Overrides cannot revoke. If you need to revoke a baseline capability, change the baseline. The data model is intentionally additive to avoid the "forgot to update the override" failure mode.

License

MIT