@dudousxd/nestjs-authz 0.5.1 → 0.6.0

package/dist/permission-cache.js

@@ -0,0 +1,48 @@
+import { permissionSatisfied } from './permission-matcher.js';
+/**
+ * A memo over a {@link PermissionProvider}'s `getPermissions(user)` so a user's
+ * granted-permission set is fetched AT MOST ONCE per logical scope (a single
+ * `allowsMany` batch, or — when wired to nestjs-context — a single HTTP request).
+ *
+ * Without it, every `gate.allows(...)` re-fetches the set (an N+1 within a list
+ * page, since each card runs its own check). The cache keys by the resolved
+ * `user` identity so two checks for the SAME user share one fetch while a
+ * different user still triggers its own.
+ *
+ * Only the `getPermissions` (full-set, wildcard-matched) path is memoized — the
+ * exact-match `hasPermission` fast path is left to the provider, which is free to
+ * memoize internally. A provider WITHOUT `getPermissions` makes this a no-op.
+ */
+export class PermissionCache {
+    // Keyed by the user object identity. `Map` (not WeakMap) because a batch/request
+    // cache is short-lived and we also accept primitive ids/refs as keys.
+    byUser = new Map();
+    /**
+     * Resolve the user's granted-permission set via the provider, memoized for the
+     * cache's lifetime. Returns `undefined` when the provider can't list grants
+     * (no `getPermissions`, or it yielded nullish) so the caller falls back to the
+     * exact-match `hasPermission` path.
+     */
+    async getPermissions(provider, user) {
+        if (typeof provider.getPermissions !== 'function')
+            return undefined;
+        const cached = this.byUser.get(user);
+        if (cached)
+            return cached;
+        const pending = Promise.resolve(provider.getPermissions(user)).then((granted) => granted == null ? undefined : new Set(granted));
+        this.byUser.set(user, pending);
+        return pending;
+    }
+    /**
+     * True when the user's (memoized) granted set satisfies `ability` under the
+     * core's wildcard matcher. `undefined` when no set is available (caller should
+     * defer to `hasPermission`).
+     */
+    async satisfies(provider, user, ability) {
+        const set = await this.getPermissions(provider, user);
+        if (set === undefined)
+            return undefined;
+        return permissionSatisfied(set, ability);
+    }
+}
+//# 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":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAI9D;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,eAAe;IAC1B,iFAAiF;IACjF,sEAAsE;IACrD,MAAM,GAAG,IAAI,GAAG,EAAqD,CAAC;IAEvF;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAClB,QAA4B,EAC5B,IAAU;QAEV,IAAI,OAAO,QAAQ,CAAC,cAAc,KAAK,UAAU;YAAE,OAAO,SAAS,CAAC;QACpE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAC9E,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAC/C,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CACb,QAA4B,EAC5B,IAAU,EACV,OAAe;QAEf,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACtD,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACxC,OAAO,mBAAmB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/dist/permission-matcher.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Laravel/spatie-style wildcard permission matching.
+ *
+ * A GRANTED permission (the left-hand side) may contain `*` wildcard segments;
+ * the REQUIRED ability (the check) is always a concrete, literal string. Matching
+ * is segment-based on the `.` separator:
+ *
+ * - exact string equality matches (`posts.update` ⇒ `posts.update`).
+ * - a trailing `*` segment matches ONE-OR-MORE remaining segments
+ *   (`posts.*` ⇒ `posts.update`, `posts.update.draft`) — but not zero
+ *   (`posts.*` does NOT match the bare `posts`).
+ * - a bare `*` grant matches anything.
+ * - `*` only matches at a segment boundary, so `posts.*` does NOT match
+ *   `comments.update`.
+ *
+ * Only the GRANTED side is expanded — a `*` in the required ability is treated
+ * literally, since a check is never a pattern.
+ */
+export declare function permissionMatches(granted: string, required: string): boolean;
+/** True when ANY permission in the granted set satisfies the required ability. */
+export declare function permissionSatisfied(granted: Iterable<string>, required: string): boolean;
+//# sourceMappingURL=permission-matcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permission-matcher.d.ts","sourceRoot":"","sources":["../src/permission-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CA0B5E;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKxF"}

package/dist/permission-matcher.js

@@ -0,0 +1,55 @@
+/**
+ * Laravel/spatie-style wildcard permission matching.
+ *
+ * A GRANTED permission (the left-hand side) may contain `*` wildcard segments;
+ * the REQUIRED ability (the check) is always a concrete, literal string. Matching
+ * is segment-based on the `.` separator:
+ *
+ * - exact string equality matches (`posts.update` ⇒ `posts.update`).
+ * - a trailing `*` segment matches ONE-OR-MORE remaining segments
+ *   (`posts.*` ⇒ `posts.update`, `posts.update.draft`) — but not zero
+ *   (`posts.*` does NOT match the bare `posts`).
+ * - a bare `*` grant matches anything.
+ * - `*` only matches at a segment boundary, so `posts.*` does NOT match
+ *   `comments.update`.
+ *
+ * Only the GRANTED side is expanded — a `*` in the required ability is treated
+ * literally, since a check is never a pattern.
+ */
+export function permissionMatches(granted, required) {
+    if (granted === required)
+        return true;
+    if (granted === '*')
+        return true;
+    const grantedParts = granted.split('.');
+    const requiredParts = required.split('.');
+    for (let i = 0; i < grantedParts.length; i++) {
+        const g = grantedParts[i];
+        if (g === '*') {
+            // A trailing `*` matches one-or-more remaining required segments.
+            // (Only the final segment may be a wildcard; an interior `*` still works
+            // positionally but a trailing `*` is the idiomatic form.)
+            if (i === grantedParts.length - 1) {
+                return requiredParts.length > i;
+            }
+            // interior wildcard: this single segment is consumed; continue matching.
+            if (requiredParts[i] === undefined)
+                return false;
+            continue;
+        }
+        if (g !== requiredParts[i])
+            return false;
+    }
+    // All granted segments consumed and matched exactly → only a true match when
+    // the required ability has no extra trailing segments.
+    return grantedParts.length === requiredParts.length;
+}
+/** True when ANY permission in the granted set satisfies the required ability. */
+export function permissionSatisfied(granted, required) {
+    for (const g of granted) {
+        if (permissionMatches(g, required))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=permission-matcher.js.map

package/dist/permission-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-matcher.js","sourceRoot":"","sources":["../src/permission-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,QAAgB;IACjE,IAAI,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAE1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACd,kEAAkE;YAClE,yEAAyE;YACzE,0DAA0D;YAC1D,IAAI,CAAC,KAAK,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAClC,OAAO,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;YAClC,CAAC;YACD,yEAAyE;YACzE,IAAI,aAAa,CAAC,CAAC,CAAC,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;YACjD,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IAC3C,CAAC;IAED,6EAA6E;IAC7E,uDAAuD;IACvD,OAAO,YAAY,CAAC,MAAM,KAAK,aAAa,CAAC,MAAM,CAAC;AACtD,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,mBAAmB,CAAC,OAAyB,EAAE,QAAgB;IAC7E,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,iBAAiB,CAAC,CAAC,EAAE,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/permission-provider.d.ts

@@ -18,8 +18,26 @@ import type { Resource, User } from './types.js';
  * when anonymous). `permission` is the ability name passed to `gate.allows(...)`.
  * `resource` is the dispatch target, when one was given; providers MAY ignore it —
  * model-less, named-ability grants (e.g. the typeorm RBAC adapter) do.
+ *
+ * ## Wildcard / hierarchical permissions
+ *
+ * To support Laravel/spatie-style wildcard grants (a granted `posts.*` satisfying a
+ * check for `posts.update`, or `*` satisfying anything), a provider may ALSO expose
+ * {@link PermissionProvider.getPermissions} — the user's full granted permission set.
+ * When present, the core applies segment-based wildcard matching against that set
+ * (see `permission-matcher.ts`), so wildcard semantics work regardless of adapter
+ * and without each adapter re-implementing the matching. `hasPermission` remains the
+ * exact-match fast path (and the sole contract for providers that don't list grants).
  */
 export interface PermissionProvider {
     hasPermission(user: User, permission: string, resource?: Resource): boolean | undefined | Promise<boolean | undefined>;
+    /**
+     * Optional: the full set of permission names granted to `user` (each possibly a
+     * wildcard pattern such as `posts.*` or `*`). When implemented, the core matches
+     * the checked ability against this set using segment-based wildcard semantics, so
+     * a granted `posts.*` satisfies `posts.update`. Return `undefined` to defer to
+     * `hasPermission` (e.g. for an anonymous/unmappable user).
+     */
+    getPermissions?(user: User): Iterable<string> | undefined | Promise<Iterable<string> | undefined>;
 }
 //# sourceMappingURL=permission-provider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"permission-provider.d.ts","sourceRoot":"","sources":["../src/permission-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,CACX,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;CACvD"}
+{"version":3,"file":"permission-provider.d.ts","sourceRoot":"","sources":["../src/permission-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,CACX,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IACtD;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;CACnG"}

package/dist/scope.d.ts

@@ -0,0 +1,84 @@
+import type { Resource, User } from './types.js';
+/**
+ * ORM-neutral query-scope constraint (the `accessibleBy` / Pundit `policy_scope` /
+ * Cerbos `PlanResources` concept). Where a policy METHOD decides yes/no for a SINGLE
+ * resource, a policy SCOPE produces a constraint that filters a COLLECTION to the rows
+ * the user may access — applied at the DB layer instead of over-fetch-then-filter.
+ *
+ * The representation is a small, pure-data condition AST (no callbacks, fully
+ * serializable) so every ORM adapter can walk it and emit a parameterized,
+ * identifier-safe `WHERE`. Compare:
+ *
+ * - **CASL `accessibleBy`** — turns ability rules into an ORM `where` object.
+ * - **Pundit `policy_scope`** — a Scope class returning a narrowed relation.
+ * - **Cerbos Query Plan (`PlanResources`)** — returns `ALWAYS_ALLOWED` /
+ *   `ALWAYS_DENIED` / a condition AST of operands. This AST mirrors that shape.
+ *
+ * Two terminal verdicts bracket the AST and keep it aligned with the Gate's
+ * deny-by-default + super-admin/before-grant semantics:
+ *
+ * - {@link ScopeAll} (`allow-all`) — the user sees every row (super-admin, a
+ *   `before` grant, or a permission-provider grant). No `WHERE` is added.
+ * - {@link ScopeNone} (`deny-all`) — the user sees no rows (anonymous, or a policy
+ *   with no `scope`/`viewAny`). The adapter emits an always-false predicate.
+ */
+export type ScopeConstraint = ScopeAll | ScopeNone | ScopeNode;
+/** Terminal: the user may access every row — no filter is applied. */
+export interface ScopeAll {
+    kind: 'all';
+}
+/** Terminal: the user may access no rows — an always-false predicate is applied. */
+export interface ScopeNone {
+    kind: 'none';
+}
+/** A non-terminal constraint: a single condition or a boolean group of them. */
+export type ScopeNode = ScopeCondition | ScopeGroup;
+/** Comparison operators a {@link ScopeCondition} may use. ORM-neutral; adapters map them. */
+export type ScopeOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'isNull' | 'isNotNull';
+/**
+ * A leaf condition: `field <op> value`. `field` names a COLUMN on the scoped entity
+ * (validated as a safe identifier by the adapter). `value` is bound as a parameter
+ * (never interpolated). `isNull`/`isNotNull` ignore `value`.
+ */
+export interface ScopeCondition {
+    kind: 'condition';
+    field: string;
+    op: ScopeOperator;
+    value?: unknown;
+}
+/** A boolean group: AND/OR over child nodes. An empty group is the group's identity. */
+export interface ScopeGroup {
+    kind: 'and' | 'or';
+    nodes: ScopeNode[];
+}
+/** The allow-all terminal (super-admin / before-grant). */
+export declare const scopeAll: ScopeAll;
+/** The deny-all terminal (anonymous / no access). */
+export declare const scopeNone: ScopeNone;
+/** Build a leaf `field <op> value` condition. */
+export declare function where(field: string, op: ScopeOperator, value?: unknown): ScopeCondition;
+/** Shorthand for the common `field = value` (equality) condition. */
+export declare function eq(field: string, value: unknown): ScopeCondition;
+/** Combine nodes with AND. A single node is returned as-is; empty → allow-all. */
+export declare function and(...nodes: ScopeNode[]): ScopeConstraint;
+/** Combine nodes with OR. A single node is returned as-is; empty → deny-all. */
+export declare function or(...nodes: ScopeNode[]): ScopeConstraint;
+/**
+ * What a policy `scope` method may return:
+ * - a {@link ScopeConstraint} (terminal or AST),
+ * - `true` → allow-all (sugar for {@link scopeAll}),
+ * - `false`/`null`/`undefined` → deny-all (sugar for {@link scopeNone}).
+ *
+ * May be async.
+ */
+export type ScopeResult = ScopeConstraint | boolean | null | undefined;
+/**
+ * A policy scope method. Mirrors Pundit's `Scope#resolve`: given the current user,
+ * return the constraint that filters the entity's collection to the accessible rows.
+ * Conventionally named `scope` on a `@Policy` class (a `viewAny`-style fallback is
+ * also honored by the Gate when no `scope` is present).
+ */
+export type ScopeMethod = (user: User, resource?: Resource) => ScopeResult | Promise<ScopeResult>;
+/** Normalize a {@link ScopeResult} (incl. boolean/nullish sugar) into a {@link ScopeConstraint}. */
+export declare function normalizeScope(result: ScopeResult): ScopeConstraint;
+//# sourceMappingURL=scope.d.ts.map

package/dist/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,KAAK,CAAC;CACb;AAED,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAEpD,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GACrB,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,QAAQ,GACR,WAAW,CAAC;AAEhB;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,aAAa,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,2DAA2D;AAC3D,eAAO,MAAM,QAAQ,EAAE,QAA0B,CAAC;AAElD,qDAAqD;AACrD,eAAO,MAAM,SAAS,EAAE,SAA4B,CAAC;AAErD,iDAAiD;AACjD,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,cAAc,CAIvF;AAED,qEAAqE;AACrE,wBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,cAAc,CAEhE;AAED,kFAAkF;AAClF,wBAAgB,GAAG,CAAC,GAAG,KAAK,EAAE,SAAS,EAAE,GAAG,eAAe,CAI1D;AAED,gFAAgF;AAChF,wBAAgB,EAAE,CAAC,GAAG,KAAK,EAAE,SAAS,EAAE,GAAG,eAAe,CAIzD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,QAAQ,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAElG,oGAAoG;AACpG,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAKnE"}

package/dist/scope.js

@@ -0,0 +1,41 @@
+/** The allow-all terminal (super-admin / before-grant). */
+export const scopeAll = { kind: 'all' };
+/** The deny-all terminal (anonymous / no access). */
+export const scopeNone = { kind: 'none' };
+/** Build a leaf `field <op> value` condition. */
+export function where(field, op, value) {
+    return op === 'isNull' || op === 'isNotNull'
+        ? { kind: 'condition', field, op }
+        : { kind: 'condition', field, op, value };
+}
+/** Shorthand for the common `field = value` (equality) condition. */
+export function eq(field, value) {
+    return { kind: 'condition', field, op: 'eq', value };
+}
+/** Combine nodes with AND. A single node is returned as-is; empty → allow-all. */
+export function and(...nodes) {
+    if (nodes.length === 0)
+        return scopeAll;
+    if (nodes.length === 1)
+        return nodes[0];
+    return { kind: 'and', nodes };
+}
+/** Combine nodes with OR. A single node is returned as-is; empty → deny-all. */
+export function or(...nodes) {
+    if (nodes.length === 0)
+        return scopeNone;
+    if (nodes.length === 1)
+        return nodes[0];
+    return { kind: 'or', nodes };
+}
+/** Normalize a {@link ScopeResult} (incl. boolean/nullish sugar) into a {@link ScopeConstraint}. */
+export function normalizeScope(result) {
+    if (result == null)
+        return scopeNone;
+    if (result === true)
+        return scopeAll;
+    if (result === false)
+        return scopeNone;
+    return result;
+}
+//# sourceMappingURL=scope.js.map

package/dist/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAuEA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,QAAQ,GAAa,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAElD,qDAAqD;AACrD,MAAM,CAAC,MAAM,SAAS,GAAc,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAErD,iDAAiD;AACjD,MAAM,UAAU,KAAK,CAAC,KAAa,EAAE,EAAiB,EAAE,KAAe;IACrE,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,WAAW;QAC1C,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE;QAClC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AAC9C,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,EAAE,CAAC,KAAa,EAAE,KAAc;IAC9C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACvD,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,GAAG,CAAC,GAAG,KAAkB;IACvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAc,CAAC;IACrD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAChC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,EAAE,CAAC,GAAG,KAAkB;IACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAc,CAAC;IACrD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC;AAoBD,oGAAoG;AACpG,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACrC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACrC,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACvC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/types.d.ts

@@ -11,26 +11,62 @@ export type Resource = object;
  * is whatever the app's auth layer produced (or `undefined` when unauthenticated).
  */
 export type User = unknown;
+/**
+ * The richer result a policy method / ad-hoc gate may return instead of a bare
+ * boolean: a verdict plus an optional human-readable `message` explaining a denial.
+ * The message is surfaced on the thrown `ForbiddenException` (so a 403 is debuggable)
+ * and published on the diagnostics decision. Returning a bare boolean is unchanged.
+ *
+ * Mirrors Laravel's `Response::allow()/deny('message')`.
+ */
+export interface PolicyResponse {
+    allowed: boolean;
+    message?: string;
+}
+/**
+ * What a policy method / gate / hook may return: a bare boolean (unchanged) or the
+ * richer {@link PolicyResponse}. Hooks additionally allow `void`/`undefined` to mean
+ * "no opinion — fall through".
+ */
+export type PolicyResult = boolean | PolicyResponse;
 /**
  * A policy method: decides a single ability for a `(user, resource?)` pair.
- * Class-level abilities (e.g. `create`) omit the resource. May be async.
+ * Class-level abilities (e.g. `create`) omit the resource. May be async. May return
+ * a bare boolean (unchanged) or a richer {@link PolicyResponse} with a deny message.
  */
-export type PolicyMethod = (user: User, resource?: Resource) => boolean | Promise<boolean>;
+export type PolicyMethod = (user: User, resource?: Resource) => PolicyResult | Promise<PolicyResult>;
 /**
  * Optional per-policy `before` hook. Runs before the ability method.
  * - return `true`  → allow (short-circuit)
  * - return `false` → deny (short-circuit)
  * - return `void`/`undefined` → fall through to the ability method
  */
-export type PolicyBeforeHook = (user: User, ability: string) => boolean | undefined | Promise<boolean | undefined>;
+export type PolicyBeforeHook = (user: User, ability: string) => PolicyResult | undefined | Promise<PolicyResult | undefined>;
 /** A policy instance is an arbitrary object whose methods are abilities. */
 export type PolicyInstance = Record<string, unknown> & {
     before?: PolicyBeforeHook;
 };
 /**
  * An ad-hoc gate: a model-less ability resolved by name via `gate.define`.
+ * May return a bare boolean (unchanged) or a richer {@link PolicyResponse}.
  */
-export type GateFn = (user: User, resource?: Resource) => boolean | Promise<boolean>;
+export type GateFn = (user: User, resource?: Resource) => PolicyResult | Promise<PolicyResult>;
+/**
+ * Global `after` hook. Mirrors Laravel's `Gate::after()`: runs AFTER policy/gate
+ * resolution and may observe or override the decision.
+ *
+ * `result` is the verdict produced by the policy/gate (`true`/`false`), or
+ * `undefined` when the policy/gate returned a nullish value (it had "no opinion").
+ *
+ * Override semantics (Laravel-idiomatic): the hook's return value REPLACES the
+ * decision ONLY when the policy/gate produced no explicit verdict (`result` is
+ * `undefined`). When the policy/gate DID decide (returned a boolean), `after` is
+ * purely an observer and its return value is ignored — so it can never silently
+ * overturn an explicit allow/deny. Returning `void`/`undefined` always leaves the
+ * decision untouched. Like a policy, it may return a {@link PolicyResponse} to
+ * attach a deny message.
+ */
+export type AfterHook = (user: User, ability: string, result: boolean | undefined, resource?: Resource) => PolicyResult | undefined | Promise<PolicyResult | undefined>;
 /**
  * A resource loader: turns an `id` into the REAL entity instance for a resource
  * `type`. Used by the opt-in `POST /authz/can` endpoint to rehydrate the client's
@@ -47,7 +83,7 @@ export type ResourceLoaderMap = Record<string, ResourceLoader>;
  * Global super-admin before-hook. Runs before any policy/gate; truthy → allow.
  * `void`/`undefined`/`false` falls through to normal resolution.
  */
-export type SuperAdminHook = (user: User, ability: string) => boolean | undefined | Promise<boolean | undefined>;
+export type SuperAdminHook = (user: User, ability: string) => PolicyResult | undefined | Promise<PolicyResult | undefined>;
 export interface AuthzModuleOptions {
     /**
      * Policy classes to register explicitly. Each must be decorated with
@@ -67,6 +103,18 @@ export interface AuthzModuleOptions {
      * explicit `gate.forUser(entity)` path you receive exactly what you passed.
      */
     superAdmin?: SuperAdminHook;
+    /**
+     * Global `after` hook (Laravel's `Gate::after()`). Runs AFTER policy/gate
+     * resolution and may observe or override the decision. It can only OVERRIDE the
+     * verdict when the policy/gate produced no explicit result (returned nullish);
+     * when the policy/gate decided explicitly, `after` is observe-only and its return
+     * value is ignored. Returning `void`/`undefined` always leaves the decision
+     * untouched. See {@link AfterHook}.
+     *
+     * Receives the same (possibly un-hydrated) `user` as {@link superAdmin} on the
+     * context path — apply {@link resolveUser} if you need the full entity.
+     */
+    after?: AfterHook;
     /**
      * Optional hook to hydrate the full user entity from the context's
      * {@link UserRef} (`{ type, id }`) before policies / `before` / `superAdmin`

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-authz",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "NestJS authorization — Laravel-style Gates & Policies, @Can guard, resource resolver (zero DB).",
   "license": "MIT",
   "repository": {