@guisao-llc/gambit-rbac 0.1.0

package/dist/authorize.d.ts

@@ -0,0 +1,62 @@
+import { Request, RequestHandler } from "express";
+import { HttpError } from "@guisao-llc/gambit-auth";
+import { CachedRole } from "./permission-cache";
+/**
+ * The authorization middleware pair.
+ *
+ * Knows nothing about tenants, features, or any permission catalog. Everything
+ * app-specific arrives through config: how a token is verified, and an optional
+ * entitlement check that runs only after the permission check has passed.
+ *
+ * The two guards it returns differ in ways that are easy to collapse by
+ * accident. They are kept as distinct match policies over a shared preamble —
+ * see each one.
+ */
+/** The minimum a decoded token must carry. Apps extend this with their own. */
+export interface AuthClaims {
+    roles?: string;
+}
+export interface EntitlementContext<TClaims> {
+    /** The permission(s) the route is gated on. */
+    required: string[];
+    /**
+     * The permission(s) that actually DECIDED access — what an entitlement check
+     * should price. For `authorize` this is the REQUIREMENT, not whatever the
+     * role happened to hold: a `:read` granted by group access still gates on the
+     * requirement's entitlement.
+     */
+    matched: string[];
+    roleName: string;
+    role: CachedRole | undefined;
+    claims: TClaims;
+}
+/** Return an HttpError to deny, or null to allow. */
+export type EntitlementCheck<TClaims> = (ctx: EntitlementContext<TClaims>) => Promise<HttpError | null> | HttpError | null;
+export interface AuthorizeConfig<TClaims extends AuthClaims> {
+    /** Verify the raw Authorization header and resolve the claims. Throws to reject. */
+    verifyToken: (authorization: string) => Promise<TClaims>;
+    /** Optional second layer, run only after the permission check passes. */
+    checkEntitlement?: EntitlementCheck<TClaims>;
+    /**
+     * Accept any permission in the same group for a `:read` requirement.
+     *
+     * Off by default, because it WIDENS access and a shared package must not
+     * widen access silently. Turn it on in an app whose UI no longer grants
+     * `<group>:read` keys directly — there, holding `invoices:write` is the only
+     * way anyone ends up able to read invoices at all.
+     */
+    readImpliesGroupAccess?: boolean;
+}
+/**
+ * Build the `authorize` / `authorizeAny` pair for one app.
+ *
+ * Returns middleware factories with the signatures route files already use, so
+ * adopting this changes no route.
+ */
+export declare function createAuthorize<TClaims extends AuthClaims>(config: AuthorizeConfig<TClaims>): {
+    authorize: (permission: string) => RequestHandler;
+    authorizeAny: (permissions: string[]) => RequestHandler;
+};
+/** `Request` re-exported so consumers can type their own entitlement checks. */
+export type { Request };
+//# sourceMappingURL=authorize.d.ts.map

package/dist/authorize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAkD,MAAM,oBAAoB,CAAC;AAEhG;;;;;;;;;;GAUG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB,CAAC,OAAO;IACzC,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,CAAC,OAAO,IAAI,CACtC,GAAG,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAC7B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;AAElD,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,UAAU;IACzD,oFAAoF;IACpF,WAAW,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAcD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,UAAU,EACxD,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC;4BA+DD,MAAM,KAAG,cAAc;gCAkBnB,MAAM,EAAE,KAAG,cAAc;EAQ7D;AAED,gFAAgF;AAChF,YAAY,EAAE,OAAO,EAAE,CAAC"}

package/dist/authorize.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthorize = createAuthorize;
+const gambit_auth_1 = require("@guisao-llc/gambit-auth");
+const permission_cache_1 = require("./permission-cache");
+/** Any permission in the same group satisfies a `:read` requirement. */
+function hasGroupAccess(roleName, permission) {
+    if ((0, permission_cache_1.hasPermission)(roleName, permission))
+        return true;
+    const group = permission.split(":")[0];
+    const cached = (0, permission_cache_1.getCachedRole)(roleName);
+    if (!cached)
+        return false;
+    for (const p of cached.permissions) {
+        if (p.startsWith(`${group}:`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Build the `authorize` / `authorizeAny` pair for one app.
+ *
+ * Returns middleware factories with the signatures route files already use, so
+ * adopting this changes no route.
+ */
+function createAuthorize(config) {
+    const { verifyToken, checkEntitlement, readImpliesGroupAccess = false } = config;
+    /**
+     * Everything the two guards share: header presence, verification, claims,
+     * the role check, the entitlement hand-off, and the error mapping. `match` is
+     * the only part that varies — it returns the permissions that decided access,
+     * or null to deny.
+     */
+    const guard = (required, match) => {
+        return async (req, _res, next) => {
+            const { authorization } = req.headers;
+            if (!authorization) {
+                return next(new gambit_auth_1.HttpError("Not authorized", 401));
+            }
+            try {
+                const claims = await verifyToken(authorization);
+                // The host app types `Request.user` through its own augmentation, which
+                // this package cannot see. Writing the key without declaring its type
+                // is deliberate — see gambit-auth's createAuthenticate.
+                req.user = claims;
+                const roleName = claims.roles;
+                if (!roleName) {
+                    return next(new gambit_auth_1.HttpError("No role assigned to this user", 403));
+                }
+                const matched = match(roleName);
+                if (!matched) {
+                    return next(new gambit_auth_1.HttpError("You do not have permission to perform this action", 403));
+                }
+                if (checkEntitlement) {
+                    const denial = await checkEntitlement({
+                        required,
+                        matched,
+                        roleName,
+                        role: (0, permission_cache_1.getCachedRole)(roleName),
+                        claims,
+                    });
+                    if (denial)
+                        return next(denial);
+                }
+                next();
+            }
+            catch {
+                return next(new gambit_auth_1.HttpError("Unauthorized", 401));
+            }
+        };
+    };
+    /**
+     * Requires the exact permission — unless `readImpliesGroupAccess` is on and
+     * the requirement ends in `:read`, in which case any permission in the same
+     * group satisfies it. Non-read requirements are always strict.
+     */
+    const authorize = (permission) => guard([permission], (roleName) => {
+        const granted = readImpliesGroupAccess && permission.endsWith(":read")
+            ? hasGroupAccess(roleName, permission)
+            : (0, permission_cache_1.hasPermission)(roleName, permission);
+        return granted ? [permission] : null;
+    });
+    /**
+     * Requires ANY ONE of the listed permissions.
+     *
+     * Two deliberate differences from `authorize`, kept explicit rather than
+     * unified because collapsing them would silently change who gets through:
+     * the match is STRICT — no group-prefix fallback, ever — and the entitlement
+     * check is priced on every listed permission the role actually holds, rather
+     * than on a single requirement.
+     */
+    const authorizeAny = (permissions) => guard(permissions, (roleName) => {
+        if (!(0, permission_cache_1.hasAnyPermission)(roleName, permissions))
+            return null;
+        const role = (0, permission_cache_1.getCachedRole)(roleName);
+        return permissions.filter((p) => role?.permissions.has(p));
+    });
+    return { authorize, authorizeAny };
+}
+//# sourceMappingURL=authorize.js.map

package/dist/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":";;AA2EA,0CA0FC;AApKD,yDAAoD;AACpD,yDAAgG;AAuDhG,wEAAwE;AACxE,SAAS,cAAc,CAAC,QAAgB,EAAE,UAAkB;IAC1D,IAAI,IAAA,gCAAa,EAAC,QAAQ,EAAE,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAA,gCAAa,EAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAC7B,MAAgC;IAEhC,MAAM,EAAE,WAAW,EAAE,gBAAgB,EAAE,sBAAsB,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;IAEjF;;;;;OAKG;IACH,MAAM,KAAK,GAAG,CACZ,QAAkB,EAClB,KAA4C,EAC5B,EAAE;QAClB,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC/B,MAAM,EAAE,aAAa,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC;YAEtC,IAAI,CAAC,aAAa,EAAE,CAAC;gBACnB,OAAO,IAAI,CAAC,IAAI,uBAAS,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC;YACpD,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,aAAa,CAAC,CAAC;gBAChD,wEAAwE;gBACxE,sEAAsE;gBACtE,wDAAwD;gBACvD,GAA0C,CAAC,IAAI,GAAG,MAAM,CAAC;gBAC1D,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC;gBAE9B,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,OAAO,IAAI,CAAC,IAAI,uBAAS,CAAC,+BAA+B,EAAE,GAAG,CAAC,CAAC,CAAC;gBACnE,CAAC;gBAED,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAChC,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,IAAI,CACT,IAAI,uBAAS,CAAC,mDAAmD,EAAE,GAAG,CAAC,CACxE,CAAC;gBACJ,CAAC;gBAED,IAAI,gBAAgB,EAAE,CAAC;oBACrB,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;wBACpC,QAAQ;wBACR,OAAO;wBACP,QAAQ;wBACR,IAAI,EAAE,IAAA,gCAAa,EAAC,QAAQ,CAAC;wBAC7B,MAAM;qBACP,CAAC,CAAC;oBACH,IAAI,MAAM;wBAAE,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;gBAClC,CAAC;gBAED,IAAI,EAAE,CAAC;YACT,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC,IAAI,uBAAS,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC;YAClD,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,CAAC;IAEF;;;;OAIG;IACH,MAAM,SAAS,GAAG,CAAC,UAAkB,EAAkB,EAAE,CACvD,KAAK,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE;QAC/B,MAAM,OAAO,GACX,sBAAsB,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC;YACpD,CAAC,CAAC,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC;YACtC,CAAC,CAAC,IAAA,gCAAa,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC1C,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC,CAAC,CAAC;IAEL;;;;;;;;OAQG;IACH,MAAM,YAAY,GAAG,CAAC,WAAqB,EAAkB,EAAE,CAC7D,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,EAAE;QAC9B,IAAI,CAAC,IAAA,mCAAgB,EAAC,QAAQ,EAAE,WAAW,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1D,MAAM,IAAI,GAAG,IAAA,gCAAa,EAAC,QAAQ,CAAC,CAAC;QACrC,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEL,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AACrC,CAAC"}

package/dist/cascades.d.ts

@@ -0,0 +1,52 @@
+import { SequentialCascade } from "@guisao-llc/gambit-cascade";
+/**
+ * Deleting a role, and deleting a permission.
+ *
+ * Both exist because roles and permissions are referenced BY STRING, not by
+ * id: a role is identified downstream by its `name`, and a permission by its
+ * `key`, which roles store in a plain array. Mongo will not clean either up,
+ * so removing one means purging strings out of documents that point at it.
+ *
+ * Both cascades therefore run keyed on a STRING rather than an ObjectId, which
+ * is why the runner is generic over its arguments at all.
+ */
+/** The narrowest slice of a mongoose model these cascades need. */
+export interface RoleCollection {
+    deleteOne(filter: Record<string, unknown>): Promise<unknown>;
+    updateMany(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<unknown>;
+}
+export interface PermissionCollection {
+    deleteOne(filter: Record<string, unknown>): Promise<unknown>;
+}
+export interface RoleDeletionConfig {
+    /** The app's role model. */
+    roleModel: RoleCollection;
+    /**
+     * Remove `roleName` from every account that currently holds it.
+     *
+     * INJECTED, and this is the seam that made the whole RBAC vertical portable.
+     * Clearing a deleted role off the accounts holding it is genuinely RBAC's
+     * business — but the ACCOUNT MODEL is not. One app's carries a school id and
+     * an account kind; another's carries something else entirely. So the cascade
+     * asks for one capability and the app supplies it.
+     *
+     * Accounts left with no role fall back to "no permissions", which is the
+     * safer default: a stale role string would otherwise reach the resolver,
+     * which cannot resolve it and cannot report that it failed to.
+     */
+    clearRoleFromAccounts: (roleName: string) => Promise<void>;
+}
+/**
+ * Clear the role off its accounts, THEN delete it.
+ *
+ * The ordering is load-bearing. Both steps resolve the role by NAME, so
+ * deleting the document first destroys the only handle the account step has —
+ * leaving every holder pointing at a role that no longer exists.
+ */
+export declare function buildRoleDeletion(config: RoleDeletionConfig): SequentialCascade<[string]>;
+export interface PermissionDeletionConfig {
+    roleModel: RoleCollection;
+    permissionModel: PermissionCollection;
+}
+export declare function buildPermissionDeletion(config: PermissionDeletionConfig): SequentialCascade<[string]>;
+//# sourceMappingURL=cascades.d.ts.map

package/dist/cascades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascades.d.ts","sourceRoot":"","sources":["../src/cascades.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEjF;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,UAAU,CACR,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,qBAAqB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAiBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,CAKzF;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,cAAc,CAAC;IAC1B,eAAe,EAAE,oBAAoB,CAAC;CACvC;AA2BD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,wBAAwB,GAC/B,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,CAK7B"}

package/dist/cascades.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRoleDeletion = buildRoleDeletion;
+exports.buildPermissionDeletion = buildPermissionDeletion;
+const gambit_cascade_1 = require("@guisao-llc/gambit-cascade");
+class ClearRoleFromAccounts {
+    constructor(clear) {
+        this.clear = clear;
+    }
+    async execute(roleName) {
+        await this.clear(roleName);
+    }
+}
+/** Runs LAST, so the name is still resolvable for every leaf before it. */
+class DeleteRoleRecord {
+    constructor(roleModel) {
+        this.roleModel = roleModel;
+    }
+    async execute(roleName) {
+        await this.roleModel.deleteOne({ name: roleName });
+    }
+}
+/**
+ * Clear the role off its accounts, THEN delete it.
+ *
+ * The ordering is load-bearing. Both steps resolve the role by NAME, so
+ * deleting the document first destroys the only handle the account step has —
+ * leaving every holder pointing at a role that no longer exists.
+ */
+function buildRoleDeletion(config) {
+    return new gambit_cascade_1.SequentialCascade([
+        new ClearRoleFromAccounts(config.clearRoleFromAccounts),
+        new DeleteRoleRecord(config.roleModel),
+    ]);
+}
+/**
+ * Pull the key out of every role that holds it.
+ *
+ * A boot-time catalog sync typically prunes unknown keys too, but only on the
+ * NEXT boot. This is the runtime mirror, so an authorization decision made a
+ * second after the delete does not consult a key that is gone.
+ */
+class PurgeKeyFromRolePermissions {
+    constructor(roleModel) {
+        this.roleModel = roleModel;
+    }
+    async execute(permissionKey) {
+        await this.roleModel.updateMany({ permissions: permissionKey }, { $pull: { permissions: permissionKey } });
+    }
+}
+/** Runs LAST, for the same reason DeleteRoleRecord does. */
+class DeletePermissionRecord {
+    constructor(permissionModel) {
+        this.permissionModel = permissionModel;
+    }
+    async execute(permissionKey) {
+        await this.permissionModel.deleteOne({ key: permissionKey });
+    }
+}
+function buildPermissionDeletion(config) {
+    return new gambit_cascade_1.SequentialCascade([
+        new PurgeKeyFromRolePermissions(config.roleModel),
+        new DeletePermissionRecord(config.permissionModel),
+    ]);
+}
+//# sourceMappingURL=cascades.js.map

package/dist/cascades.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascades.js","sourceRoot":"","sources":["../src/cascades.ts"],"names":[],"mappings":";;AAoEA,8CAKC;AAgCD,0DAOC;AAhHD,+DAAiF;AA8CjF,MAAM,qBAAqB;IACzB,YAA6B,KAAkD;QAAlD,UAAK,GAAL,KAAK,CAA6C;IAAG,CAAC;IACnF,KAAK,CAAC,OAAO,CAAC,QAAgB;QAC5B,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,gBAAgB;IACpB,YAA6B,SAAyB;QAAzB,cAAS,GAAT,SAAS,CAAgB;IAAG,CAAC;IAC1D,KAAK,CAAC,OAAO,CAAC,QAAgB;QAC5B,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;CACF;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,MAA0B;IAC1D,OAAO,IAAI,kCAAiB,CAAW;QACrC,IAAI,qBAAqB,CAAC,MAAM,CAAC,qBAAqB,CAAC;QACvD,IAAI,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC;KACvC,CAAC,CAAC;AACL,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,2BAA2B;IAC/B,YAA6B,SAAyB;QAAzB,cAAS,GAAT,SAAS,CAAgB;IAAG,CAAC;IAC1D,KAAK,CAAC,OAAO,CAAC,aAAqB;QACjC,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAC7B,EAAE,WAAW,EAAE,aAAa,EAAE,EAC9B,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,aAAa,EAAE,EAAE,CAC1C,CAAC;IACJ,CAAC;CACF;AAED,4DAA4D;AAC5D,MAAM,sBAAsB;IAC1B,YAA6B,eAAqC;QAArC,oBAAe,GAAf,eAAe,CAAsB;IAAG,CAAC;IACtE,KAAK,CAAC,OAAO,CAAC,aAAqB;QACjC,MAAM,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC;IAC/D,CAAC;CACF;AAED,SAAgB,uBAAuB,CACrC,MAAgC;IAEhC,OAAO,IAAI,kCAAiB,CAAW;QACrC,IAAI,2BAA2B,CAAC,MAAM,CAAC,SAAS,CAAC;QACjD,IAAI,sBAAsB,CAAC,MAAM,CAAC,eAAe,CAAC;KACnD,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { RequestHandler } from "express";
+import { CachedRole } from "./permission-cache";
+/**
+ * @guisao-llc/gambit-rbac
+ *
+ * Roles, permissions, and the middleware that enforces them.
+ *
+ * The whole vertical is portable because every place it would otherwise reach
+ * for something app-shaped, it takes that thing as configuration instead: the
+ * cache is given a loader rather than a model, the cascades are given models
+ * rather than importing them, and the role schema is a fragment so the app owns
+ * its tenant field. What is left names no application.
+ */
+export { configurePermissionCache, getPermissions, hasPermission, hasAnyPermission, listRoleNamesWithPermission, getCachedRole, refreshCache, _seedCacheForTesting, _resetForTesting, } from "./permission-cache";
+export type { CachedRole, LoadedRole, PermissionCacheConfig } from "./permission-cache";
+export { createAuthorize } from "./authorize";
+export type { AuthClaims, AuthorizeConfig, EntitlementCheck, EntitlementContext, } from "./authorize";
+export { roleFields, permissionFields, PERMISSION_ACTIONS } from "./schema";
+export type { RoleFieldsConfig, PermissionFieldsConfig, PermissionAction, } from "./schema";
+export { buildRoleDeletion, buildPermissionDeletion } from "./cascades";
+export type { RoleDeletionConfig, PermissionDeletionConfig, RoleCollection, PermissionCollection, } from "./cascades";
+/** Does this role hold the permission? Undefined role answers false. */
+export declare function can(roleName: string | undefined, permission: string): boolean;
+/** Does this role hold at least one of these? Undefined role answers false. */
+export declare function canAny(roleName: string | undefined, permissions: string[]): boolean;
+export interface PlatformAdminConfig {
+    /**
+     * Decide whether a role is a platform administrator.
+     *
+     * Required, with no default, on purpose. This gate sits ABOVE every tenant —
+     * it guards settings that affect all of them at once — so a package must not
+     * guess at what qualifies. An app that gets this wrong grants the keys to
+     * everything, and a silent default is exactly how that happens.
+     */
+    isPlatformAdmin: (role: CachedRole | undefined) => boolean;
+    /** Where the role name lives on the request. Defaults to `req.user.roles`. */
+    getRoleName?: (req: unknown) => string | undefined;
+}
+/**
+ * "Is the caller a platform-level administrator?"
+ *
+ * Mount AFTER authentication — this never verifies a token itself, which keeps
+ * exactly one place doing that.
+ */
+export declare function createRequirePlatformAdmin(config: PlatformAdminConfig): RequestHandler;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAkD,MAAM,oBAAoB,CAAC;AAEhG;;;;;;;;;;GAUG;AAEH,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,2BAA2B,EAC3B,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAExF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EACV,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC5E,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAIpB,wEAAwE;AACxE,wBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAG7E;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAGnF;AAID,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,eAAe,EAAE,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,KAAK,OAAO,CAAC;IAC3D,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CACpD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,mBAAmB,GAAG,cAAc,CAgBtF"}

package/dist/index.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPermissionDeletion = exports.buildRoleDeletion = exports.PERMISSION_ACTIONS = exports.permissionFields = exports.roleFields = exports.createAuthorize = exports._resetForTesting = exports._seedCacheForTesting = exports.refreshCache = exports.getCachedRole = exports.listRoleNamesWithPermission = exports.hasAnyPermission = exports.hasPermission = exports.getPermissions = exports.configurePermissionCache = void 0;
+exports.can = can;
+exports.canAny = canAny;
+exports.createRequirePlatformAdmin = createRequirePlatformAdmin;
+const gambit_auth_1 = require("@guisao-llc/gambit-auth");
+const permission_cache_1 = require("./permission-cache");
+/**
+ * @guisao-llc/gambit-rbac
+ *
+ * Roles, permissions, and the middleware that enforces them.
+ *
+ * The whole vertical is portable because every place it would otherwise reach
+ * for something app-shaped, it takes that thing as configuration instead: the
+ * cache is given a loader rather than a model, the cascades are given models
+ * rather than importing them, and the role schema is a fragment so the app owns
+ * its tenant field. What is left names no application.
+ */
+var permission_cache_2 = require("./permission-cache");
+Object.defineProperty(exports, "configurePermissionCache", { enumerable: true, get: function () { return permission_cache_2.configurePermissionCache; } });
+Object.defineProperty(exports, "getPermissions", { enumerable: true, get: function () { return permission_cache_2.getPermissions; } });
+Object.defineProperty(exports, "hasPermission", { enumerable: true, get: function () { return permission_cache_2.hasPermission; } });
+Object.defineProperty(exports, "hasAnyPermission", { enumerable: true, get: function () { return permission_cache_2.hasAnyPermission; } });
+Object.defineProperty(exports, "listRoleNamesWithPermission", { enumerable: true, get: function () { return permission_cache_2.listRoleNamesWithPermission; } });
+Object.defineProperty(exports, "getCachedRole", { enumerable: true, get: function () { return permission_cache_2.getCachedRole; } });
+Object.defineProperty(exports, "refreshCache", { enumerable: true, get: function () { return permission_cache_2.refreshCache; } });
+Object.defineProperty(exports, "_seedCacheForTesting", { enumerable: true, get: function () { return permission_cache_2._seedCacheForTesting; } });
+Object.defineProperty(exports, "_resetForTesting", { enumerable: true, get: function () { return permission_cache_2._resetForTesting; } });
+var authorize_1 = require("./authorize");
+Object.defineProperty(exports, "createAuthorize", { enumerable: true, get: function () { return authorize_1.createAuthorize; } });
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "roleFields", { enumerable: true, get: function () { return schema_1.roleFields; } });
+Object.defineProperty(exports, "permissionFields", { enumerable: true, get: function () { return schema_1.permissionFields; } });
+Object.defineProperty(exports, "PERMISSION_ACTIONS", { enumerable: true, get: function () { return schema_1.PERMISSION_ACTIONS; } });
+var cascades_1 = require("./cascades");
+Object.defineProperty(exports, "buildRoleDeletion", { enumerable: true, get: function () { return cascades_1.buildRoleDeletion; } });
+Object.defineProperty(exports, "buildPermissionDeletion", { enumerable: true, get: function () { return cascades_1.buildPermissionDeletion; } });
+// ── Direct questions, for code that is not middleware ────────────────────────
+/** Does this role hold the permission? Undefined role answers false. */
+function can(roleName, permission) {
+    if (!roleName)
+        return false;
+    return (0, permission_cache_1.hasPermission)(roleName, permission);
+}
+/** Does this role hold at least one of these? Undefined role answers false. */
+function canAny(roleName, permissions) {
+    if (!roleName)
+        return false;
+    return (0, permission_cache_1.hasAnyPermission)(roleName, permissions);
+}
+/**
+ * "Is the caller a platform-level administrator?"
+ *
+ * Mount AFTER authentication — this never verifies a token itself, which keeps
+ * exactly one place doing that.
+ */
+function createRequirePlatformAdmin(config) {
+    const { isPlatformAdmin, getRoleName = (req) => req.user?.roles, } = config;
+    return (req, _res, next) => {
+        const roleName = getRoleName(req);
+        if (!roleName || !isPlatformAdmin((0, permission_cache_1.getCachedRole)(roleName))) {
+            return next(new gambit_auth_1.HttpError("Only a platform administrator can change this setting", 403));
+        }
+        return next();
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAuDA,kBAGC;AAGD,wBAGC;AAwBD,gEAgBC;AAvGD,yDAAoD;AACpD,yDAAgG;AAEhG;;;;;;;;;;GAUG;AAEH,uDAU4B;AAT1B,4HAAA,wBAAwB,OAAA;AACxB,kHAAA,cAAc,OAAA;AACd,iHAAA,aAAa,OAAA;AACb,oHAAA,gBAAgB,OAAA;AAChB,+HAAA,2BAA2B,OAAA;AAC3B,iHAAA,aAAa,OAAA;AACb,gHAAA,YAAY,OAAA;AACZ,wHAAA,oBAAoB,OAAA;AACpB,oHAAA,gBAAgB,OAAA;AAIlB,yCAA8C;AAArC,4GAAA,eAAe,OAAA;AAQxB,mCAA4E;AAAnE,oGAAA,UAAU,OAAA;AAAE,0GAAA,gBAAgB,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAOzD,uCAAwE;AAA/D,6GAAA,iBAAiB,OAAA;AAAE,mHAAA,uBAAuB,OAAA;AAQnD,gFAAgF;AAEhF,wEAAwE;AACxE,SAAgB,GAAG,CAAC,QAA4B,EAAE,UAAkB;IAClE,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,IAAA,gCAAa,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED,+EAA+E;AAC/E,SAAgB,MAAM,CAAC,QAA4B,EAAE,WAAqB;IACxE,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,IAAA,mCAAgB,EAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AACjD,CAAC;AAkBD;;;;;GAKG;AACH,SAAgB,0BAA0B,CAAC,MAA2B;IACpE,MAAM,EACJ,eAAe,EACf,WAAW,GAAG,CAAC,GAAG,EAAE,EAAE,CACnB,GAAqC,CAAC,IAAI,EAAE,KAAK,GACrD,GAAG,MAAM,CAAC;IAEX,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,QAAQ,IAAI,CAAC,eAAe,CAAC,IAAA,gCAAa,EAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YAC3D,OAAO,IAAI,CACT,IAAI,uBAAS,CAAC,uDAAuD,EAAE,GAAG,CAAC,CAC5E,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/permission-cache.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Role → permission cache.
+ *
+ * Every authorization decision reads from here, so it is a synchronous
+ * in-memory map rather than a query. It knows nothing about tenants: this
+ * answers "what may this ROLE do", which is the same question in any app.
+ *
+ * ── Why the loader is injected, and the cache is not ─────────────────────────
+ *
+ * The cache itself is module-level state, deliberately. Every consumer imports
+ * `hasPermission` directly and expects the same cache; handing out instances
+ * would mean threading one through every call site for no benefit, since a
+ * process has exactly one set of roles.
+ *
+ * But WHERE roles come from is the app's business — its model, its tenant
+ * scoping, its connection. So `refreshCache` does not import a model; it calls
+ * the loader the app registered. Same rule as everywhere else here: a shared
+ * module must not PICK the thing it depends on, it must be GIVEN it.
+ */
+export interface CachedRole {
+    permissions: Set<string>;
+    bypassFeatureChecks: boolean;
+}
+/** The shape `loadRoles` must return. Anything else about a role is the app's. */
+export interface LoadedRole {
+    name: string;
+    permissions: string[];
+    bypassFeatureChecks?: boolean;
+}
+export interface PermissionCacheConfig {
+    /** Read every role. Called by `refreshCache` on boot and after role writes. */
+    loadRoles: () => Promise<LoadedRole[]>;
+    /** Where to report a refresh. Defaults to no output — a library should be quiet. */
+    onRefresh?: (roleCount: number) => void;
+}
+/** Register how roles are loaded. Call once, during app startup. */
+export declare function configurePermissionCache(config: PermissionCacheConfig): void;
+/** Every permission held by a role. Empty set when the role is unknown. */
+export declare function getPermissions(roleName: string): Set<string>;
+/** Does the role hold this exact permission? */
+export declare function hasPermission(roleName: string, permission: string): boolean;
+/** Does the role hold at least one of these? */
+export declare function hasAnyPermission(roleName: string, permissions: string[]): boolean;
+/**
+ * Which roles hold this permission.
+ *
+ * Lenient about junk input — empty or whitespace returns `[]` rather than
+ * throwing — to match `hasPermission`, which answers `false` for an unknown
+ * role instead of failing. Never mutates the cache.
+ */
+export declare function listRoleNamesWithPermission(permission: string): string[];
+/** The whole cached entry, including `bypassFeatureChecks`. */
+export declare function getCachedRole(roleName: string): CachedRole | undefined;
+/**
+ * Rebuild from the loader. Call on boot and after any role write.
+ *
+ * Throws on failure rather than swallowing: a silent refresh failure leaves
+ * the cache stale after a write, so the app keeps enforcing permissions that
+ * were just changed — and nothing anywhere says so.
+ */
+export declare function refreshCache(): Promise<void>;
+/**
+ * Seed the cache directly. TESTS ONLY — never call this in production code.
+ *
+ * Clears before seeding, which matters more than it looks: a test that seeds
+ * the role under test and expects a previously-seeded admin to survive gets
+ * neither. Seed every role a single assertion needs in ONE call.
+ */
+export declare function _seedCacheForTesting(entries: Record<string, string[] | {
+    permissions: string[];
+    bypassFeatureChecks: boolean;
+}>): void;
+/** Drop the loader and the contents. Tests that call `refreshCache` need this. */
+export declare function _resetForTesting(): void;
+//# sourceMappingURL=permission-cache.d.ts.map

package/dist/permission-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-cache.d.ts","sourceRoot":"","sources":["../src/permission-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,SAAS,EAAE,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACvC,oFAAoF;IACpF,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAKD,oEAAoE;AACpE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAE5E;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAE5D;AAED,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAIjF;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAOxE;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEtE;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAiBlD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,CACb,MAAM,EACN,MAAM,EAAE,GAAG;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,mBAAmB,EAAE,OAAO,CAAA;CAAE,CACnE,GACA,IAAI,CAaN;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}

package/dist/permission-cache.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Role → permission cache.
+ *
+ * Every authorization decision reads from here, so it is a synchronous
+ * in-memory map rather than a query. It knows nothing about tenants: this
+ * answers "what may this ROLE do", which is the same question in any app.
+ *
+ * ── Why the loader is injected, and the cache is not ─────────────────────────
+ *
+ * The cache itself is module-level state, deliberately. Every consumer imports
+ * `hasPermission` directly and expects the same cache; handing out instances
+ * would mean threading one through every call site for no benefit, since a
+ * process has exactly one set of roles.
+ *
+ * But WHERE roles come from is the app's business — its model, its tenant
+ * scoping, its connection. So `refreshCache` does not import a model; it calls
+ * the loader the app registered. Same rule as everywhere else here: a shared
+ * module must not PICK the thing it depends on, it must be GIVEN it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configurePermissionCache = configurePermissionCache;
+exports.getPermissions = getPermissions;
+exports.hasPermission = hasPermission;
+exports.hasAnyPermission = hasAnyPermission;
+exports.listRoleNamesWithPermission = listRoleNamesWithPermission;
+exports.getCachedRole = getCachedRole;
+exports.refreshCache = refreshCache;
+exports._seedCacheForTesting = _seedCacheForTesting;
+exports._resetForTesting = _resetForTesting;
+const _cache = new Map();
+let _config;
+/** Register how roles are loaded. Call once, during app startup. */
+function configurePermissionCache(config) {
+    _config = config;
+}
+/** Every permission held by a role. Empty set when the role is unknown. */
+function getPermissions(roleName) {
+    return _cache.get(roleName)?.permissions ?? new Set();
+}
+/** Does the role hold this exact permission? */
+function hasPermission(roleName, permission) {
+    return _cache.get(roleName)?.permissions.has(permission) ?? false;
+}
+/** Does the role hold at least one of these? */
+function hasAnyPermission(roleName, permissions) {
+    const entry = _cache.get(roleName);
+    if (!entry)
+        return false;
+    return permissions.some((p) => entry.permissions.has(p));
+}
+/**
+ * Which roles hold this permission.
+ *
+ * Lenient about junk input — empty or whitespace returns `[]` rather than
+ * throwing — to match `hasPermission`, which answers `false` for an unknown
+ * role instead of failing. Never mutates the cache.
+ */
+function listRoleNamesWithPermission(permission) {
+    if (typeof permission !== "string" || permission.trim() === "")
+        return [];
+    const names = [];
+    for (const [roleName, entry] of _cache.entries()) {
+        if (entry.permissions.has(permission))
+            names.push(roleName);
+    }
+    return names;
+}
+/** The whole cached entry, including `bypassFeatureChecks`. */
+function getCachedRole(roleName) {
+    return _cache.get(roleName);
+}
+/**
+ * Rebuild from the loader. Call on boot and after any role write.
+ *
+ * Throws on failure rather than swallowing: a silent refresh failure leaves
+ * the cache stale after a write, so the app keeps enforcing permissions that
+ * were just changed — and nothing anywhere says so.
+ */
+async function refreshCache() {
+    if (!_config) {
+        throw new Error("gambit-rbac: refreshCache() before configurePermissionCache(). " +
+            "Register a loadRoles during startup.");
+    }
+    const roles = await _config.loadRoles();
+    _cache.clear();
+    for (const role of roles) {
+        _cache.set(role.name, {
+            permissions: new Set(role.permissions),
+            bypassFeatureChecks: role.bypassFeatureChecks ?? false,
+        });
+    }
+    _config.onRefresh?.(roles.length);
+}
+/**
+ * Seed the cache directly. TESTS ONLY — never call this in production code.
+ *
+ * Clears before seeding, which matters more than it looks: a test that seeds
+ * the role under test and expects a previously-seeded admin to survive gets
+ * neither. Seed every role a single assertion needs in ONE call.
+ */
+function _seedCacheForTesting(entries) {
+    _cache.clear();
+    for (const [role, value] of Object.entries(entries)) {
+        _cache.set(role, Array.isArray(value)
+            ? { permissions: new Set(value), bypassFeatureChecks: false }
+            : {
+                permissions: new Set(value.permissions),
+                bypassFeatureChecks: value.bypassFeatureChecks,
+            });
+    }
+}
+/** Drop the loader and the contents. Tests that call `refreshCache` need this. */
+function _resetForTesting() {
+    _cache.clear();
+    _config = undefined;
+}
+//# sourceMappingURL=permission-cache.js.map

package/dist/permission-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-cache.js","sourceRoot":"","sources":["../src/permission-cache.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,66 @@
+import { SchemaDefinitionProperty } from "mongoose";
+/**
+ * The two records RBAC keeps: a role, and a permission.
+ *
+ * Schema FRAGMENTS rather than models, for the reason the account and person
+ * fragments are: a role belongs to a TENANT, and the tenant is the one thing
+ * this package cannot know. One app scopes roles by school, another by
+ * practice. A model defined here would have to pick, and picking means every
+ * other app carries a field named after somebody else's domain.
+ *
+ * The app builds the model:
+ *
+ *   const roleSchema = new Schema(
+ *     roleFields({ tenant: { field: "schoolId", ref: "Schools" } }),
+ *     { timestamps: true },
+ *   );
+ *   roleSchema.index({ name: 1, schoolId: 1 }, { unique: true, sparse: true });
+ *   export const Roles = mongoose.model("Roles", roleSchema);
+ *
+ * and hands it to whatever here needs one.
+ */
+export interface RoleFieldsConfig {
+    /**
+     * Scope roles to an organization. Omit for an app whose roles are global.
+     *
+     * Optional rather than required because a single-tenant app has no such
+     * concept, and forcing one on it would mean a field nothing ever sets.
+     */
+    tenant?: {
+        field: string;
+        ref?: string;
+    };
+}
+/**
+ * Build the role fields for spreading into an app's schema.
+ *
+ * `permissions` holds permission KEY STRINGS, not references. That is
+ * deliberate and it propagates: because a role is identified downstream by its
+ * name and its permissions by their keys, deleting either one has to purge
+ * strings out of arrays rather than rely on referential integrity. The cascades
+ * in this package exist for exactly that reason.
+ */
+export declare function roleFields(config?: RoleFieldsConfig): Record<string, SchemaDefinitionProperty>;
+/**
+ * The actions a permission can express.
+ *
+ * `add` is in this list because a catalog that uses it and a schema that
+ * forbids it is a lie waiting to be found. In the app this was extracted from,
+ * fourteen permissions declared `action: "add"` against an enum of
+ * `["read", "write", "delete"]` — and nothing failed, because the sync path
+ * used `bulkWrite`, which does not run validators by default. The enum was
+ * simply not enforced. Any validated write would have rejected those fourteen.
+ */
+export declare const PERMISSION_ACTIONS: readonly ["read", "add", "write", "delete"];
+export type PermissionAction = (typeof PERMISSION_ACTIONS)[number];
+export interface PermissionFieldsConfig {
+    /** Override the permitted actions if an app needs a different vocabulary. */
+    actions?: readonly string[];
+}
+/**
+ * Build the permission fields. No tenant: a permission is a definition, not a
+ * grant. Which ROLE holds it is the tenant-scoped part, and that lives on the
+ * role.
+ */
+export declare function permissionFields(config?: PermissionFieldsConfig): Record<string, SchemaDefinitionProperty>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,GAAE,gBAAqB,GAC5B,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CA8B1C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,6CAA8C,CAAC;AAC9E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,GAAE,sBAA2B,GAClC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAS1C"}

package/dist/schema.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISSION_ACTIONS = void 0;
+exports.roleFields = roleFields;
+exports.permissionFields = permissionFields;
+const mongoose_1 = require("mongoose");
+/**
+ * Build the role fields for spreading into an app's schema.
+ *
+ * `permissions` holds permission KEY STRINGS, not references. That is
+ * deliberate and it propagates: because a role is identified downstream by its
+ * name and its permissions by their keys, deleting either one has to purge
+ * strings out of arrays rather than rely on referential integrity. The cascades
+ * in this package exist for exactly that reason.
+ */
+function roleFields(config = {}) {
+    const { tenant } = config;
+    const fields = {
+        name: { type: String, required: true },
+        /** Permission keys, e.g. "invoices:read". Strings, not refs — see above. */
+        permissions: { type: [String], default: [] },
+        /** A role every tenant sees, rather than one belonging to a single tenant. */
+        isGlobal: { type: Boolean, default: false },
+        /**
+         * Skip the host app's entitlement check entirely.
+         *
+         * Only meaningful in an app that HAS entitlements (see `createAuthorize`'s
+         * `checkEntitlement`). Keep it off the API surface: a role that can grant
+         * itself this can grant itself everything the entitlement layer was
+         * protecting.
+         */
+        bypassFeatureChecks: { type: Boolean, default: false },
+        /** Whether the role can be handed out through the app's UI. */
+        assignable: { type: Boolean, default: true },
+    };
+    if (tenant) {
+        fields[tenant.field] = {
+            type: mongoose_1.Schema.Types.ObjectId,
+            ...(tenant.ref ? { ref: tenant.ref } : {}),
+        };
+    }
+    return fields;
+}
+/**
+ * The actions a permission can express.
+ *
+ * `add` is in this list because a catalog that uses it and a schema that
+ * forbids it is a lie waiting to be found. In the app this was extracted from,
+ * fourteen permissions declared `action: "add"` against an enum of
+ * `["read", "write", "delete"]` — and nothing failed, because the sync path
+ * used `bulkWrite`, which does not run validators by default. The enum was
+ * simply not enforced. Any validated write would have rejected those fourteen.
+ */
+exports.PERMISSION_ACTIONS = ["read", "add", "write", "delete"];
+/**
+ * Build the permission fields. No tenant: a permission is a definition, not a
+ * grant. Which ROLE holds it is the tenant-scoped part, and that lives on the
+ * role.
+ */
+function permissionFields(config = {}) {
+    const { actions = exports.PERMISSION_ACTIONS } = config;
+    return {
+        key: { type: String, required: true, unique: true },
+        label: { type: String, required: true },
+        group: { type: String, required: true },
+        action: { type: String, enum: [...actions], required: true },
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":";;;AA6CA,gCAgCC;AAyBD,4CAWC;AAjHD,uCAA4D;AAoC5D;;;;;;;;GAQG;AACH,SAAgB,UAAU,CACxB,SAA2B,EAAE;IAE7B,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAE1B,MAAM,MAAM,GAA6C;QACvD,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;QACtC,4EAA4E;QAC5E,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;QAC5C,8EAA8E;QAC9E,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE;QAC3C;;;;;;;WAOG;QACH,mBAAmB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE;QACtD,+DAA+D;QAC/D,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE;KAC7C,CAAC;IAEF,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG;YACrB,IAAI,EAAE,iBAAM,CAAC,KAAK,CAAC,QAAQ;YAC3B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3C,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACU,QAAA,kBAAkB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAQ9E;;;;GAIG;AACH,SAAgB,gBAAgB,CAC9B,SAAiC,EAAE;IAEnC,MAAM,EAAE,OAAO,GAAG,0BAAkB,EAAE,GAAG,MAAM,CAAC;IAEhD,OAAO;QACL,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QACnD,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;QACvC,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;QACvC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;KAC7D,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@guisao-llc/gambit-rbac",
+  "version": "0.1.0",
+  "description": "Roles, permissions, a permission cache, and the express middleware that enforces them.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Guisao-LLC/Gambit.git",
+    "directory": "packages/gambit-rbac"
+  },
+  "homepage": "https://github.com/Guisao-LLC/Gambit/tree/main/packages/gambit-rbac",
+  "keywords": ["rbac", "permissions", "authorization", "express", "middleware"],
+  "engines": { "node": ">=20 <23" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm run build && npm test && node ../../scripts/prepublish-check.mjs"
+  },
+  "dependencies": {
+    "@guisao-llc/gambit-auth": "^0.1.0",
+    "@guisao-llc/gambit-cascade": "^0.1.0"
+  },
+  "peerDependencies": {
+    "express": "^4.21.0",
+    "mongoose": ">=8"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21"
+  },
+  "publishConfig": { "access": "public" }
+}