@dudousxd/nestjs-authz 0.6.7 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @dudousxd/nestjs-authz
 
+## 0.7.0
+
+### Minor Changes
+
+- [#57](https://github.com/DavideCarvalho/nestjs-authz/pull/57) [`6de64a9`](https://github.com/DavideCarvalho/nestjs-authz/commit/6de64a94280187b28f55c4ab5ae5aabb2ef34836) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - External policy engines: a new `DecisionProvider` seam (`DECISION_PROVIDER` token) and a Cerbos adapter at `@dudousxd/nestjs-authz/cerbos`.
+
+  - `DecisionProvider.decide(user, ability, resource)` can **allow, deny or abstain**. It runs right after the `superAdmin` hook and before the permission provider, the policy `before` hook, policies and gates. `authorize()` surfaces denials with reason `decision-provider`. It is also consulted for anonymous callers.
+  - Optional `decideMany` batches `gate.allowsMany` into one engine round-trip. If the batch call fails, each item falls back to its own `decide` call.
+  - Optional `planScope(user, Entity, ability)` feeds `gate.scope()` right after `superAdmin`. Returning `undefined` abstains and falls back to the permission provider or policy scope.
+  - The `superAdmin` hook now receives the resource as a third argument: the checked resource, or the entity class for `gate.scope()`. This is additive.
+  - `@dudousxd/nestjs-authz/cerbos`:
+    - `CerbosDecisionProvider` supports per-user/per-tenant clients, batching with de-duplication and chunking, and fails closed by default.
+    - `cerbosPlanToScope` maps Cerbos `PlanResources` onto the scope AST: and/or, `not` via De Morgan, eq/ne/lt/gt/le/ge/in, and null checks. Anything else is rejected, which fails closed.
+    - Client types are structural, so the package has no runtime dependency on the Cerbos SDKs.
+
+- [#58](https://github.com/DavideCarvalho/nestjs-authz/pull/58) [`8b65088`](https://github.com/DavideCarvalho/nestjs-authz/commit/8b6508804216d46384ec3a734a55b9c0ac1e48b6) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Per-source role assignments (manual vs SSO/SCIM/…).
+
+  Each role assignment now records a `source`, default `'manual'`. Every store adapter gains:
+
+  - `setUserRoles(user, roleNames, { source?, tenantId? })` replaces only that source's assignments, so an SSO sync never removes a role that was granted by hand. It creates missing roles and runs in a transaction.
+  - `assignRole(user, role, { source })` and `removeRole(user, role, { source })`. Without `source`, `removeRole` removes the role from every source.
+  - `getRoleAssignments(user, scope?)` returns `{ role, source, tenantId }[]`.
+  - `getRolesForUser` and the Gate seams still return distinct role names.
+
+  Core's `store-kit` exports `DEFAULT_ROLE_SOURCE` and `RoleAssignment`. The adapters now require `@dudousxd/nestjs-authz >= 0.7.0`.
+
+  **Migration**
+
+  - **TypeORM:** `ensureAuthzSchema` / `autoCreateSchema` adds `source varchar(64) NOT NULL DEFAULT 'manual'` to `authz_user_role`, so existing rows become manual assignments. It never rewrites an existing primary key. Until you widen the key, a role can come from only one source per user, and a second-source insert is silently ignored. Widen it once:
+
+    - PostgreSQL: `ALTER TABLE authz_user_role DROP CONSTRAINT <pk_name>, ADD PRIMARY KEY ("userType","userId","roleId","tenantId","source");`
+    - MySQL (utf8mb4 needs the shorter key columns): `ALTER TABLE authz_user_role MODIFY roleId varchar(64) NOT NULL, MODIFY source varchar(64) NOT NULL DEFAULT 'manual', DROP PRIMARY KEY, ADD PRIMARY KEY (userType, userId, roleId, tenantId, source);`
+    - SQLite: rebuild the table.
+
+    New tables are created with the 5-column key, and `roleId` is now `varchar(64)` so the key fits MySQL's 3072-byte limit.
+
+  - **MikroORM:** the column self-heals the same way. The PK does not. See the adapter README for the SQL.
+  - **Prisma:** opt-in with `roleSources: true` after adding `source String @default("manual")` to `UserRole` and including it in `@@id`. See the adapter README. Without the option the adapter behaves exactly as before.
+  - **Drizzle:** `createAuthzTables()` now includes the column and the widened key, so regenerate with drizzle-kit. `ensureSchema()` adds the column. See the README for the key SQL.
+
 ## 0.6.7
 
 ### Patch Changes

package/dist/cerbos/cerbos-decision.provider.d.ts

@@ -0,0 +1,128 @@
+import type { Type } from '@nestjs/common';
+import type { DecisionProvider, DecisionRequest, DecisionVerdict } from '../decision-provider.js';
+import { type ScopeConstraint } from '../scope.js';
+import type { Resource, User } from '../types.js';
+import { type CerbosFieldMapper, type CerbosPlanLike } from './plan.js';
+/** A Cerbos attribute value (JSON). */
+export type CerbosValue = string | number | boolean | null | CerbosValue[] | {
+    [key: string]: CerbosValue;
+};
+/** The principal sent to Cerbos. */
+export interface CerbosPrincipal {
+    id: string;
+    roles: string[];
+    attr?: Record<string, CerbosValue>;
+    policyVersion?: string;
+    scope?: string;
+}
+/** A resource sent to Cerbos `CheckResources`. */
+export interface CerbosResource {
+    kind: string;
+    id: string;
+    attr?: Record<string, CerbosValue>;
+    policyVersion?: string;
+    scope?: string;
+}
+/** The resource query sent to Cerbos `PlanResources` (a resource without an id). */
+export type CerbosResourceQuery = Omit<CerbosResource, 'id'>;
+/**
+ * The slice of a Cerbos SDK client the adapter uses. `@cerbos/http`'s `HTTP` and `@cerbos/grpc`'s
+ * `GRPC` satisfy it structurally, so this package does not depend on either.
+ */
+export interface CerbosClientLike {
+    checkResources(request: {
+        principal: CerbosPrincipal;
+        resources: Array<{
+            resource: CerbosResource;
+            actions: string[];
+        }>;
+    }): Promise<{
+        isAllowed(check: {
+            resource: {
+                kind: string;
+                id: string;
+                policyVersion?: string;
+                scope?: string;
+            };
+            action: string;
+        }): boolean | undefined;
+    }>;
+    planResources?(request: {
+        principal: CerbosPrincipal;
+        resource: CerbosResourceQuery;
+        action: string;
+    }): Promise<CerbosPlanLike>;
+}
+type Awaitable<T> = T | Promise<T>;
+export interface CerbosDecisionProviderOptions {
+    /**
+     * The Cerbos client, or a per-user resolver (e.g. per-tenant PDPs). Resolving `undefined`
+     * ABSTAINS — the Gate falls back to its own rules (RBAC/policies) for that user.
+     */
+    client: CerbosClientLike | ((user: User) => Awaitable<CerbosClientLike | undefined>);
+    /** Build the Cerbos principal. `undefined` (e.g. anonymous) abstains. */
+    principal: (user: User) => Awaitable<CerbosPrincipal | undefined>;
+    /**
+     * Map a Gate check to a Cerbos resource. `undefined` abstains — use it for abilities/resources
+     * Cerbos does not govern (model-less abilities, other resource types).
+     */
+    resource: (ability: string, resource: Resource | undefined) => CerbosResource | undefined;
+    /** Map an ability to a Cerbos action. Default: the ability name itself. */
+    action?: (ability: string) => string;
+    /**
+     * Query-plan support for `gate.scope(Entity, ability)`. `resource` names the Cerbos resource
+     * kind (and optional attrs/scope) for an entity — `undefined` abstains. `field` maps a resource
+     * attribute (`ownerId`, or `id`) to the column name the ORM adapter resolves (default: same
+     * name; return `undefined` to reject an attribute).
+     */
+    scope?: {
+        resource: (entity: Type<unknown>, ability: string) => CerbosResourceQuery | undefined;
+        field?: CerbosFieldMapper;
+    };
+    /**
+     * What an engine failure (network error, timeout, unsupported query plan) resolves to:
+     * `'deny'` (default — fail CLOSED: an outage must not widen access; scopes become deny-all) or
+     * `'abstain'` (fall back to the Gate's own rules).
+     */
+    onFailure?: 'deny' | 'abstain';
+    /** Observe engine failures (logging/metrics). Never affects the verdict. */
+    onError?: (error: unknown, context: {
+        phase: 'check' | 'plan';
+        ability: string;
+    }) => void;
+    /** Max resources per `CheckResources` call (Cerbos' default server limit is 50). */
+    maxBatchSize?: number;
+}
+/**
+ * A {@link DecisionProvider} backed by a [Cerbos](https://cerbos.dev) policy decision point:
+ * `gate.allows/authorize` → `CheckResources` (batched for `gate.allowsMany`), `gate.scope` →
+ * `PlanResources` mapped onto the scope AST (see {@link cerbosPlanToScope}).
+ *
+ * ```ts
+ * import { DECISION_PROVIDER } from '@dudousxd/nestjs-authz';
+ * import { CerbosDecisionProvider } from '@dudousxd/nestjs-authz/cerbos';
+ * import { HTTP } from '@cerbos/http';
+ *
+ * { provide: DECISION_PROVIDER, useValue: new CerbosDecisionProvider({
+ *     client: new HTTP('http://cerbos:3592'),
+ *     principal: (u: User) => u && { id: u.id, roles: u.roles, attr: { tenantId: u.tenantId } },
+ *     resource: (ability, r) => r instanceof Post
+ *       ? { kind: 'app:post', id: r.id, attr: { ownerId: r.ownerId } } : undefined,
+ *     scope: { resource: (entity) => (entity === Post ? { kind: 'app:post' } : undefined) },
+ * }) }
+ * ```
+ */
+export declare class CerbosDecisionProvider implements DecisionProvider {
+    private readonly options;
+    private readonly failureVerdict;
+    private readonly maxBatchSize;
+    constructor(options: CerbosDecisionProviderOptions);
+    private action;
+    private client;
+    private fail;
+    decide(user: User, ability: string, resource?: Resource): Promise<DecisionVerdict>;
+    decideMany(user: User, requests: DecisionRequest[]): Promise<DecisionVerdict[]>;
+    planScope(user: User, entity: Type<unknown>, ability: string): Promise<ScopeConstraint | undefined>;
+}
+export {};
+//# sourceMappingURL=cerbos-decision.provider.d.ts.map

package/dist/cerbos/cerbos-decision.provider.d.ts.map

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

package/dist/cerbos/cerbos-decision.provider.js

@@ -0,0 +1,134 @@
+import { scopeNone } from '../scope.js';
+import { cerbosPlanToScope } from './plan.js';
+const resourceKey = (r) => JSON.stringify([r.kind, r.id, r.policyVersion ?? null, r.scope ?? null]);
+/**
+ * A {@link DecisionProvider} backed by a [Cerbos](https://cerbos.dev) policy decision point:
+ * `gate.allows/authorize` → `CheckResources` (batched for `gate.allowsMany`), `gate.scope` →
+ * `PlanResources` mapped onto the scope AST (see {@link cerbosPlanToScope}).
+ *
+ * ```ts
+ * import { DECISION_PROVIDER } from '@dudousxd/nestjs-authz';
+ * import { CerbosDecisionProvider } from '@dudousxd/nestjs-authz/cerbos';
+ * import { HTTP } from '@cerbos/http';
+ *
+ * { provide: DECISION_PROVIDER, useValue: new CerbosDecisionProvider({
+ *     client: new HTTP('http://cerbos:3592'),
+ *     principal: (u: User) => u && { id: u.id, roles: u.roles, attr: { tenantId: u.tenantId } },
+ *     resource: (ability, r) => r instanceof Post
+ *       ? { kind: 'app:post', id: r.id, attr: { ownerId: r.ownerId } } : undefined,
+ *     scope: { resource: (entity) => (entity === Post ? { kind: 'app:post' } : undefined) },
+ * }) }
+ * ```
+ */
+export class CerbosDecisionProvider {
+    options;
+    failureVerdict;
+    maxBatchSize;
+    constructor(options) {
+        this.options = options;
+        this.failureVerdict = options.onFailure === 'abstain' ? undefined : false;
+        this.maxBatchSize = Math.max(1, options.maxBatchSize ?? 50);
+    }
+    action(ability) {
+        return this.options.action ? this.options.action(ability) : ability;
+    }
+    async client(user) {
+        const { client } = this.options;
+        return typeof client === 'function' ? client(user) : client;
+    }
+    fail(error, phase, ability) {
+        try {
+            this.options.onError?.(error, { phase, ability });
+        }
+        catch {
+            // An observer must never change the verdict.
+        }
+    }
+    async decide(user, ability, resource) {
+        const [verdict] = await this.decideMany(user, resource === undefined ? [{ ability }] : [{ ability, resource }]);
+        return verdict;
+    }
+    async decideMany(user, requests) {
+        const verdicts = requests.map(() => undefined);
+        const mapped = requests.map((r) => {
+            const resource = this.options.resource(r.ability, r.resource);
+            return resource ? { resource, action: this.action(r.ability) } : undefined;
+        });
+        if (mapped.every((m) => m === undefined))
+            return verdicts;
+        const client = await this.client(user);
+        if (!client)
+            return verdicts;
+        const principal = await this.options.principal(user);
+        if (!principal)
+            return verdicts;
+        // One ResourceCheck per distinct resource, carrying every action asked about it.
+        const checks = new Map();
+        for (const m of mapped) {
+            if (!m)
+                continue;
+            const key = resourceKey(m.resource);
+            const entry = checks.get(key) ?? { resource: m.resource, actions: new Set() };
+            entry.actions.add(m.action);
+            checks.set(key, entry);
+        }
+        const all = [...checks.values()];
+        const answers = new Map();
+        for (let i = 0; i < all.length; i += this.maxBatchSize) {
+            const chunk = all.slice(i, i + this.maxBatchSize);
+            try {
+                const response = await client.checkResources({
+                    principal,
+                    resources: chunk.map((c) => ({ resource: c.resource, actions: [...c.actions] })),
+                });
+                for (const c of chunk) {
+                    for (const action of c.actions) {
+                        answers.set(`${resourceKey(c.resource)}|${action}`, response.isAllowed({ resource: c.resource, action }));
+                    }
+                }
+            }
+            catch (error) {
+                this.fail(error, 'check', requests[0]?.ability ?? '');
+                for (const c of chunk) {
+                    for (const action of c.actions)
+                        answers.set(`${resourceKey(c.resource)}|${action}`, undefined);
+                }
+            }
+        }
+        for (const [index, m] of mapped.entries()) {
+            if (!m)
+                continue;
+            const answer = answers.get(`${resourceKey(m.resource)}|${m.action}`);
+            // No answer for a resource we asked about = engine failure → the failure mode.
+            verdicts[index] = answer === undefined ? this.failureVerdict : answer;
+        }
+        return verdicts;
+    }
+    async planScope(user, entity, ability) {
+        const scope = this.options.scope;
+        if (!scope)
+            return undefined;
+        const resource = scope.resource(entity, ability);
+        if (!resource)
+            return undefined;
+        const client = await this.client(user);
+        if (!client || typeof client.planResources !== 'function')
+            return undefined;
+        const principal = await this.options.principal(user);
+        if (!principal)
+            return undefined;
+        try {
+            const plan = await client.planResources({
+                principal,
+                resource,
+                action: this.action(ability),
+            });
+            return cerbosPlanToScope(plan, scope.field);
+        }
+        catch (error) {
+            this.fail(error, 'plan', ability);
+            return this.failureVerdict === undefined ? undefined : scopeNone;
+        }
+    }
+}
+//# sourceMappingURL=cerbos-decision.provider.js.map

package/dist/cerbos/cerbos-decision.provider.js.map

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

package/dist/cerbos/index.d.ts

@@ -0,0 +1,3 @@
+export { CerbosDecisionProvider, type CerbosClientLike, type CerbosDecisionProviderOptions, type CerbosPrincipal, type CerbosResource, type CerbosResourceQuery, type CerbosValue, } from './cerbos-decision.provider.js';
+export { CerbosPlanUnsupportedError, cerbosPlanToScope, type CerbosFieldMapper, type CerbosPlanLike, type CerbosPlanOperand, } from './plan.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cerbos/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cerbos/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,6BAA6B,EAClC,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC"}

package/dist/cerbos/index.js

@@ -0,0 +1,5 @@
+// `@dudousxd/nestjs-authz/cerbos` — a DecisionProvider backed by a Cerbos PDP. Structural client
+// types only: bring your own `@cerbos/http` / `@cerbos/grpc` client (no runtime dependency here).
+export { CerbosDecisionProvider, } from './cerbos-decision.provider.js';
+export { CerbosPlanUnsupportedError, cerbosPlanToScope, } from './plan.js';
+//# sourceMappingURL=index.js.map

package/dist/cerbos/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cerbos/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,kGAAkG;AAClG,OAAO,EACL,sBAAsB,GAOvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,GAIlB,MAAM,WAAW,CAAC"}

package/dist/cerbos/plan.d.ts

@@ -0,0 +1,41 @@
+import { type ScopeConstraint } from '../scope.js';
+/** A Cerbos query-plan operand (structural mirror of `@cerbos/core`'s `PlanExpressionOperand`). */
+export type CerbosPlanOperand = {
+    operator: string;
+    operands: CerbosPlanOperand[];
+} | {
+    value: unknown;
+} | {
+    name: string;
+};
+/** A Cerbos `PlanResources` response (structural: `kind` + optional `condition`). */
+export interface CerbosPlanLike {
+    kind: string;
+    condition?: CerbosPlanOperand;
+}
+/**
+ * Maps a Cerbos resource attribute (the part after `request.resource.attr.`, or `id` for
+ * `request.resource.id`) to a scope `field` (a column the ORM adapter resolves). Return
+ * `undefined` to reject the attribute — the plan is then unsupported (fail closed).
+ */
+export type CerbosFieldMapper = (attribute: string) => string | undefined;
+/** Thrown when a Cerbos query plan uses something the scope AST cannot express. */
+export declare class CerbosPlanUnsupportedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Translate a Cerbos `PlanResources` result into the ORM-neutral {@link ScopeConstraint} that
+ * `gate.scope()` returns (and every ORM adapter compiles to a WHERE):
+ *
+ * - `KIND_ALWAYS_ALLOWED` → `allow-all`, `KIND_ALWAYS_DENIED` → `deny-all`;
+ * - `KIND_CONDITIONAL` → the condition tree: `and`/`or` → groups, `not` pushed down to the leaves
+ *   (De Morgan; `eq`↔`ne`, `lt`↔`gte`, `in`↔`nin`, …), comparisons `eq ne lt gt le ge in` against
+ *   a resource attribute → leaf conditions (`eq null` → `isNull`). Operands may appear in either
+ *   order (`value < attr` is flipped).
+ *
+ * Anything else — arithmetic, `exists`/`all`/lambdas, collection membership on an attribute
+ * (`"x" in R.attr.tags`), principal variables, unmapped attributes — throws
+ * {@link CerbosPlanUnsupportedError}; callers should fail closed.
+ */
+export declare function cerbosPlanToScope(plan: CerbosPlanLike, field?: CerbosFieldMapper): ScopeConstraint;
+//# sourceMappingURL=plan.d.ts.map

package/dist/cerbos/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/cerbos/plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EAKrB,MAAM,aAAa,CAAC;AAErB,mGAAmG;AACnG,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAAE,GACnD;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAE1E,mFAAmF;AACnF,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AA8DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,cAAc,EACpB,KAAK,GAAE,iBAA4C,GAClD,eAAe,CAOjB"}

package/dist/cerbos/plan.js

@@ -0,0 +1,158 @@
+import { scopeAll, scopeNone, } from '../scope.js';
+/** Thrown when a Cerbos query plan uses something the scope AST cannot express. */
+export class CerbosPlanUnsupportedError extends Error {
+    constructor(message) {
+        super(`Unsupported Cerbos query plan: ${message}`);
+        this.name = 'CerbosPlanUnsupportedError';
+    }
+}
+const ALWAYS_ALLOWED = 'KIND_ALWAYS_ALLOWED';
+const ALWAYS_DENIED = 'KIND_ALWAYS_DENIED';
+const CONDITIONAL = 'KIND_CONDITIONAL';
+/** Cerbos comparison operator → scope operator. */
+const COMPARISON = {
+    eq: 'eq',
+    ne: 'ne',
+    lt: 'lt',
+    gt: 'gt',
+    le: 'lte',
+    ge: 'gte',
+    in: 'in',
+};
+/** Logical negation of a scope operator (used to push `not` down to the leaves). */
+const NEGATED = {
+    eq: 'ne',
+    ne: 'eq',
+    lt: 'gte',
+    gte: 'lt',
+    gt: 'lte',
+    lte: 'gt',
+    in: 'nin',
+    nin: 'in',
+    isNull: 'isNotNull',
+    isNotNull: 'isNull',
+};
+/** Swap sides of a comparison (`value < attr` ⇔ `attr > value`). */
+const FLIPPED = {
+    eq: 'eq',
+    ne: 'ne',
+    lt: 'gt',
+    gt: 'lt',
+    lte: 'gte',
+    gte: 'lte',
+};
+const isExpression = (o) => typeof o.operator === 'string';
+const isVariable = (o) => typeof o.name === 'string';
+const isValue = (o) => 'value' in o;
+const RESOURCE_ATTR_PREFIXES = ['request.resource.attr.', 'R.attr.'];
+const RESOURCE_ID = new Set(['request.resource.id', 'R.id']);
+function attributeOf(name) {
+    if (RESOURCE_ID.has(name))
+        return 'id';
+    for (const prefix of RESOURCE_ATTR_PREFIXES) {
+        if (name.startsWith(prefix))
+            return name.slice(prefix.length);
+    }
+    return undefined;
+}
+const always = (allowed) => ({ kind: allowed ? 'and' : 'or', nodes: [] });
+/**
+ * Translate a Cerbos `PlanResources` result into the ORM-neutral {@link ScopeConstraint} that
+ * `gate.scope()` returns (and every ORM adapter compiles to a WHERE):
+ *
+ * - `KIND_ALWAYS_ALLOWED` → `allow-all`, `KIND_ALWAYS_DENIED` → `deny-all`;
+ * - `KIND_CONDITIONAL` → the condition tree: `and`/`or` → groups, `not` pushed down to the leaves
+ *   (De Morgan; `eq`↔`ne`, `lt`↔`gte`, `in`↔`nin`, …), comparisons `eq ne lt gt le ge in` against
+ *   a resource attribute → leaf conditions (`eq null` → `isNull`). Operands may appear in either
+ *   order (`value < attr` is flipped).
+ *
+ * Anything else — arithmetic, `exists`/`all`/lambdas, collection membership on an attribute
+ * (`"x" in R.attr.tags`), principal variables, unmapped attributes — throws
+ * {@link CerbosPlanUnsupportedError}; callers should fail closed.
+ */
+export function cerbosPlanToScope(plan, field = (attribute) => attribute) {
+    if (plan.kind === ALWAYS_ALLOWED)
+        return scopeAll;
+    if (plan.kind === ALWAYS_DENIED)
+        return scopeNone;
+    if (plan.kind !== CONDITIONAL || !plan.condition) {
+        throw new CerbosPlanUnsupportedError(`unknown plan kind ${JSON.stringify(plan.kind)}`);
+    }
+    return toNode(plan.condition, false, field);
+}
+function toNode(operand, negate, field) {
+    if (isValue(operand)) {
+        if (typeof operand.value !== 'boolean') {
+            throw new CerbosPlanUnsupportedError('a non-boolean constant used as a condition');
+        }
+        return always(operand.value !== negate);
+    }
+    if (isVariable(operand)) {
+        // A bare boolean attribute (`R.attr.public`).
+        return leaf(operand.name, 'eq', !negate, field);
+    }
+    if (!isExpression(operand))
+        throw new CerbosPlanUnsupportedError('malformed operand');
+    const { operator, operands } = operand;
+    if (operator === 'not') {
+        const [inner] = operands;
+        if (operands.length !== 1 || !inner)
+            throw new CerbosPlanUnsupportedError('`not` arity');
+        return toNode(inner, !negate, field);
+    }
+    if (operator === 'and' || operator === 'or') {
+        // De Morgan: ¬(a ∧ b) = ¬a ∨ ¬b.
+        const isAnd = (operator === 'and') !== negate;
+        return {
+            kind: isAnd ? 'and' : 'or',
+            nodes: operands.map((child) => toNode(child, negate, field)),
+        };
+    }
+    const op = COMPARISON[operator];
+    if (!op)
+        throw new CerbosPlanUnsupportedError(`operator "${operator}"`);
+    const [left, right] = operands;
+    if (operands.length !== 2 || !left || !right) {
+        throw new CerbosPlanUnsupportedError(`\`${operator}\` arity`);
+    }
+    let variable;
+    let value;
+    let effective = op;
+    if (isVariable(left) && isValue(right)) {
+        variable = left;
+        value = right.value;
+    }
+    else if (isValue(left) && isVariable(right)) {
+        const flipped = FLIPPED[op];
+        if (!flipped) {
+            throw new CerbosPlanUnsupportedError(`"${operator}" with the attribute on the right (collection membership)`);
+        }
+        variable = right;
+        value = left.value;
+        effective = flipped;
+    }
+    else {
+        throw new CerbosPlanUnsupportedError(`"${operator}" must compare one attribute with one value`);
+    }
+    if (value === null && (effective === 'eq' || effective === 'ne')) {
+        effective = effective === 'eq' ? 'isNull' : 'isNotNull';
+    }
+    if (effective === 'in' && !Array.isArray(value)) {
+        throw new CerbosPlanUnsupportedError('`in` needs a list value');
+    }
+    return leaf(variable.name, negate ? NEGATED[effective] : effective, value, field);
+}
+function leaf(variable, op, value, field) {
+    const attribute = attributeOf(variable);
+    if (attribute === undefined) {
+        throw new CerbosPlanUnsupportedError(`variable "${variable}" is not a resource attribute`);
+    }
+    const mapped = field(attribute);
+    if (mapped === undefined) {
+        throw new CerbosPlanUnsupportedError(`resource attribute "${attribute}" is not mapped`);
+    }
+    return op === 'isNull' || op === 'isNotNull'
+        ? { kind: 'condition', field: mapped, op }
+        : { kind: 'condition', field: mapped, op, value };
+}
+//# sourceMappingURL=plan.js.map

package/dist/cerbos/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/cerbos/plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,QAAQ,EACR,SAAS,GACV,MAAM,aAAa,CAAC;AAqBrB,mFAAmF;AACnF,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,kCAAkC,OAAO,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAC7C,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAC3C,MAAM,WAAW,GAAG,kBAAkB,CAAC;AAEvC,mDAAmD;AACnD,MAAM,UAAU,GAAkC;IAChD,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,IAAI;CACT,CAAC;AAEF,oFAAoF;AACpF,MAAM,OAAO,GAAyC;IACpD,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,KAAK;IACT,GAAG,EAAE,IAAI;IACT,EAAE,EAAE,KAAK;IACT,GAAG,EAAE,IAAI;IACT,EAAE,EAAE,KAAK;IACT,GAAG,EAAE,IAAI;IACT,MAAM,EAAE,WAAW;IACnB,SAAS,EAAE,QAAQ;CACpB,CAAC;AAEF,oEAAoE;AACpE,MAAM,OAAO,GAAkD;IAC7D,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;CACX,CAAC;AAEF,MAAM,YAAY,GAAG,CACnB,CAAoB,EACsC,EAAE,CAC5D,OAAQ,CAA4B,CAAC,QAAQ,KAAK,QAAQ,CAAC;AAC7D,MAAM,UAAU,GAAG,CAAC,CAAoB,EAAyB,EAAE,CACjE,OAAQ,CAAwB,CAAC,IAAI,KAAK,QAAQ,CAAC;AACrD,MAAM,OAAO,GAAG,CAAC,CAAoB,EAA2B,EAAE,CAAC,OAAO,IAAK,CAAY,CAAC;AAE5F,MAAM,sBAAsB,GAAG,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAC;AACrE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7D,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,KAAK,MAAM,MAAM,IAAI,sBAAsB,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,MAAM,GAAG,CAAC,OAAgB,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;AAE9F;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAoB,EACpB,QAA2B,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS;IAEnD,IAAI,IAAI,CAAC,IAAI,KAAK,cAAc;QAAE,OAAO,QAAQ,CAAC;IAClD,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa;QAAE,OAAO,SAAS,CAAC;IAClD,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QACjD,MAAM,IAAI,0BAA0B,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,MAAM,CAAC,OAA0B,EAAE,MAAe,EAAE,KAAwB;IACnF,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACvC,MAAM,IAAI,0BAA0B,CAAC,4CAA4C,CAAC,CAAC;QACrF,CAAC;QACD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,8CAA8C;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;QAAE,MAAM,IAAI,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;IAEtF,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACvC,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC;QACzB,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,0BAA0B,CAAC,aAAa,CAAC,CAAC;QACzF,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC5C,iCAAiC;QACjC,MAAM,KAAK,GAAG,CAAC,QAAQ,KAAK,KAAK,CAAC,KAAK,MAAM,CAAC;QAC9C,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;YAC1B,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;SAC7D,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,0BAA0B,CAAC,aAAa,QAAQ,GAAG,CAAC,CAAC;IACxE,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC;IAC/B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7C,MAAM,IAAI,0BAA0B,CAAC,KAAK,QAAQ,UAAU,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,QAA0B,CAAC;IAC/B,IAAI,KAAc,CAAC;IACnB,IAAI,SAAS,GAAkB,EAAE,CAAC;IAClC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACtB,CAAC;SAAM,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,0BAA0B,CAClC,IAAI,QAAQ,2DAA2D,CACxE,CAAC;QACJ,CAAC;QACD,QAAQ,GAAG,KAAK,CAAC;QACjB,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACnB,SAAS,GAAG,OAAO,CAAC;IACtB,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,0BAA0B,CAAC,IAAI,QAAQ,6CAA6C,CAAC,CAAC;IAClG,CAAC;IAED,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,IAAI,CAAC,EAAE,CAAC;QACjE,SAAS,GAAG,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC;IAC1D,CAAC;IACD,IAAI,SAAS,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,0BAA0B,CAAC,yBAAyB,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AACpF,CAAC;AAED,SAAS,IAAI,CACX,QAAgB,EAChB,EAAiB,EACjB,KAAc,EACd,KAAwB;IAExB,MAAM,SAAS,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,0BAA0B,CAAC,aAAa,QAAQ,+BAA+B,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,0BAA0B,CAAC,uBAAuB,SAAS,iBAAiB,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,WAAW;QAC1C,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;QAC1C,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AACtD,CAAC"}

package/dist/decision-provider.d.ts

@@ -0,0 +1,58 @@
+import type { Type } from '@nestjs/common';
+import type { ScopeConstraint } from './scope.js';
+import type { PolicyResult, Resource, User } from './types.js';
+/**
+ * What a {@link DecisionProvider} answers for one `(user, ability, resource)`:
+ *
+ * - `true` / `{ allowed: true }` → **allow** (short-circuits the Gate);
+ * - `false` / `{ allowed: false, message? }` → **deny** (short-circuits the Gate — unlike the
+ *   grant-only {@link PermissionProvider}, a decision provider CAN deny);
+ * - `undefined` / `null` → **abstain**: the provider has no opinion (e.g. the resource kind or
+ *   the tenant isn't governed by the external engine) and the Gate continues with its normal
+ *   resolution (permission provider → policy → ad-hoc gate).
+ */
+export type DecisionVerdict = PolicyResult | undefined;
+/** One `(ability, resource)` pair in a {@link DecisionProvider.decideMany} batch. */
+export interface DecisionRequest {
+    ability: string;
+    resource?: Resource;
+}
+/**
+ * Optional seam for an **external policy decision point** (Cerbos, OPA, OpenFGA, a remote
+ * authz service, …) — the authoritative, resource-aware counterpart of the grant-only
+ * {@link PermissionProvider}. Register it under the {@link DECISION_PROVIDER} token.
+ *
+ * ## Precedence (single decision)
+ *
+ * 1. global `superAdmin` hook (receives the resource as 3rd argument) — allow/deny short-circuit;
+ * 2. **decision provider** `decide` — allow/deny short-circuit, `undefined` abstains;
+ * 3. permission provider grant (RBAC, grant-only);
+ * 4. policy `before` → policy method, else ad-hoc gate;
+ * 5. global `after` hook (only when the path above had no opinion).
+ *
+ * The provider is also consulted for anonymous callers (`user` is `undefined`) so an engine can
+ * allow public access; abstain to keep the Gate's default anonymous-deny.
+ *
+ * ## Batching
+ *
+ * `gate.allowsMany(...)` calls {@link decideMany} ONCE for the whole batch when implemented (a
+ * list page with N cards costs one engine round-trip instead of N); otherwise `decide` per item.
+ *
+ * ## Query scopes
+ *
+ * `gate.scope(Entity, ability)` calls {@link planScope} right after the `superAdmin` hook. A
+ * returned {@link ScopeConstraint} is used as-is (e.g. an engine's query plan mapped onto the scope
+ * AST — see `@dudousxd/nestjs-authz/cerbos`); `undefined` abstains and the Gate falls back to the
+ * permission-provider grant / the policy's `scope` method.
+ *
+ * Errors thrown by the provider propagate (the check fails loudly). Providers that talk to a
+ * remote engine should decide their own failure mode — the Cerbos adapter fails CLOSED (deny).
+ */
+export interface DecisionProvider {
+    decide(user: User, ability: string, resource?: Resource): DecisionVerdict | Promise<DecisionVerdict>;
+    /** Optional batch form; must return one verdict per request, in order. */
+    decideMany?(user: User, requests: DecisionRequest[]): Promise<DecisionVerdict[]>;
+    /** Optional query-plan → scope mapping. `undefined` = abstain. */
+    planScope?(user: User, entity: Type<unknown>, ability: string): ScopeConstraint | undefined | Promise<ScopeConstraint | undefined>;
+}
+//# sourceMappingURL=decision-provider.d.ts.map

package/dist/decision-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-provider.d.ts","sourceRoot":"","sources":["../src/decision-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,SAAS,CAAC;AAEvD,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CACJ,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,QAAQ,GAClB,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9C,0EAA0E;IAC1E,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACjF,kEAAkE;IAClE,SAAS,CAAC,CACR,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,EACrB,OAAO,EAAE,MAAM,GACd,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;CACvE"}

package/dist/decision-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=decision-provider.js.map

package/dist/decision-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-provider.js","sourceRoot":"","sources":["../src/decision-provider.ts"],"names":[],"mappings":""}

package/dist/diagnostics.d.ts

@@ -30,7 +30,7 @@ export interface AuthzDecisionDiagnostic {
     resourceId: string | number | null;
 }
 /** The resolution path that produced a decision — the "why" behind a 403 (or a grant). */
-export type AuthzDecisionReason = 'super-admin' | 'permission-provider' | 'policy-before' | 'policy' | 'gate' | 'after' | 'anonymous';
+export type AuthzDecisionReason = 'super-admin' | 'decision-provider' | 'permission-provider' | 'policy-before' | 'policy' | 'gate' | 'after' | 'anonymous';
 /**
  * Publish a decision to the channel, but only when something is listening. Never
  * throws — building the payload or notifying a subscriber must not break a check.