@dudousxd/nestjs-authz 0.2.0 → 0.4.0

package/dist/policy-registry.js

@@ -41,6 +41,48 @@ let PolicyRegistry = class PolicyRegistry {
     all() {
         return [...this.byResource.values()];
     }
+    /** All registered resource classes (insertion order). */
+    resources() {
+        return [...this.byResource.keys()];
+    }
+    /**
+     * Enumerate the CLASS-LEVEL ability method names declared on each registered
+     * policy, keyed by resource class. Used by integrations that pre-resolve a
+     * user's class-level abilities (e.g. to share them as Inertia props).
+     *
+     * Walks the policy prototype chain and collects own function-valued members,
+     * excluding `constructor` and the reserved `before` hook. Inherited Object
+     * members are skipped.
+     *
+     * Only methods that take NO resource instance are included — heuristically,
+     * arity `<= 1` (just `user`, e.g. `create(user)` / `viewAny(user)`). An
+     * instance method like `update(user, post)` is excluded: dispatching it
+     * against the resource CLASS would call it with the class constructor as
+     * `post` and write a bogus class-level verdict.
+     */
+    classAbilities() {
+        const out = [];
+        for (const [resource, policy] of this.byResource) {
+            const abilities = new Set();
+            let proto = Object.getPrototypeOf(policy);
+            while (proto && proto !== Object.prototype) {
+                for (const name of Object.getOwnPropertyNames(proto)) {
+                    if (name === 'constructor' || name === 'before')
+                        continue;
+                    const member = policy[name];
+                    // Class-level abilities take only `user` (arity <= 1). A method that
+                    // also declares a resource param (arity >= 2) is instance-scoped and
+                    // must not be dispatched against the class.
+                    if (typeof member === 'function' && member.length <= 1) {
+                        abilities.add(name);
+                    }
+                }
+                proto = Object.getPrototypeOf(proto);
+            }
+            out.push({ resource, abilities: [...abilities] });
+        }
+        return out;
+    }
 };
 PolicyRegistry = __decorate([
     Injectable()

package/dist/policy-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy-registry.js","sourceRoot":"","sources":["../src/policy-registry.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAGrE;;;GAGG;AAEI,IAAM,cAAc,GAApB,MAAM,cAAc;IACR,UAAU,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEvE;;;OAGG;IACH,QAAQ,CAAC,MAAsB;QAC7B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,QAAQ,CAAC;YAClD,MAAM,IAAI,2BAA2B,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,wEAAwE;IACxE,WAAW,CAAC,QAAuB;QACjC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,+EAA+E;IAC/E,WAAW,CAAC,QAAgB;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,WAA4B,CAAC,CAAC;IACpE,CAAC;IAED,+DAA+D;IAC/D,GAAG,CAAC,QAAuB;QACzB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,2DAA2D;IAC3D,GAAG;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;CACF,CAAA;AAnCY,cAAc;IAD1B,UAAU,EAAE;GACA,cAAc,CAmC1B"}
+{"version":3,"file":"policy-registry.js","sourceRoot":"","sources":["../src/policy-registry.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAGrE;;;GAGG;AAEI,IAAM,cAAc,GAApB,MAAM,cAAc;IACR,UAAU,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEvE;;;OAGG;IACH,QAAQ,CAAC,MAAsB;QAC7B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,QAAQ,CAAC;YAClD,MAAM,IAAI,2BAA2B,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,wEAAwE;IACxE,WAAW,CAAC,QAAuB;QACjC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,+EAA+E;IAC/E,WAAW,CAAC,QAAgB;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,WAA4B,CAAC,CAAC;IACpE,CAAC;IAED,+DAA+D;IAC/D,GAAG,CAAC,QAAuB;QACzB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,2DAA2D;IAC3D,GAAG;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,yDAAyD;IACzD,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,cAAc;QACZ,MAAM,GAAG,GAA4D,EAAE,CAAC;QACxE,KAAK,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;YACpC,IAAI,KAAK,GAAkB,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YACzD,OAAO,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;gBAC3C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;oBACrD,IAAI,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,QAAQ;wBAAE,SAAS;oBAC1D,MAAM,MAAM,GAAI,MAAkC,CAAC,IAAI,CAAC,CAAC;oBACzD,qEAAqE;oBACrE,qEAAqE;oBACrE,4CAA4C;oBAC5C,IAAI,OAAO,MAAM,KAAK,UAAU,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;wBACvD,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBACtB,CAAC;gBACH,CAAC;gBACD,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YACvC,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF,CAAA;AA9EY,cAAc;IAD1B,UAAU,EAAE;GACA,cAAc,CA8E1B"}

package/dist/role-provider.d.ts

@@ -0,0 +1,40 @@
+import type { User } from './types.js';
+/**
+ * Optional seam that lets a persisted RBAC layer supply a user's roles.
+ *
+ * This mirrors {@link PermissionProvider} but for COARSE, role-based checks
+ * (`gate.hasRole('teacher')`, `@Roles('admin')`). The core does NOT implement
+ * this — `@dudousxd/nestjs-authz-typeorm` (and the other RBAC adapters) provide an
+ * implementation and register it under the shared {@link ROLE_PROVIDER} token.
+ * When no provider is registered the default {@link RoleResolver} (reading roles
+ * off the user object) is the only source.
+ *
+ * `user` is the current user (whatever the app's auth layer produced; `undefined`
+ * when anonymous). Return the role names the user holds — an empty array (or
+ * nullish) contributes no roles. When both this provider and the default resolver
+ * yield roles, the Gate takes their UNION.
+ */
+export interface RoleProvider {
+    getRoles(user: User): string[] | undefined | Promise<string[] | undefined>;
+}
+/**
+ * Strategy that derives a user's roles from the user object itself, with ZERO RBAC
+ * tables. The {@link defaultRoleResolver} reads `user.roles` (`string[]`) OR
+ * `user.role` (`string | string[]`) and normalizes both to a `string[]`. Apps that
+ * already carry a role on the user thus get role-checks for free; an app that needs
+ * a different shape overrides it via `AuthzModule.forRoot({ resolveRoles })`.
+ */
+export type RoleResolver = (user: User) => string[] | undefined | Promise<string[] | undefined>;
+/**
+ * Default {@link RoleResolver}: read roles directly off the user object.
+ *
+ * - `user.roles` is a `string[]` → used as-is.
+ * - `user.role` is a `string` → wrapped to `[role]`.
+ * - `user.role` is a `string[]` → used as-is.
+ * - neither present (or anonymous) → `[]` (no roles).
+ *
+ * Non-string entries are filtered out so a malformed field can never leak a
+ * truthy match.
+ */
+export declare function defaultRoleResolver(user: User): string[];
+//# sourceMappingURL=role-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"role-provider.d.ts","sourceRoot":"","sources":["../src/role-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CAC5E;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAEhG;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAaxD"}

package/dist/role-provider.js

@@ -0,0 +1,32 @@
+/**
+ * Default {@link RoleResolver}: read roles directly off the user object.
+ *
+ * - `user.roles` is a `string[]` → used as-is.
+ * - `user.role` is a `string` → wrapped to `[role]`.
+ * - `user.role` is a `string[]` → used as-is.
+ * - neither present (or anonymous) → `[]` (no roles).
+ *
+ * Non-string entries are filtered out so a malformed field can never leak a
+ * truthy match.
+ */
+export function defaultRoleResolver(user) {
+    if (user == null || typeof user !== 'object')
+        return [];
+    const u = user;
+    const out = [];
+    if (Array.isArray(u.roles)) {
+        for (const r of u.roles)
+            if (typeof r === 'string')
+                out.push(r);
+    }
+    if (typeof u.role === 'string') {
+        out.push(u.role);
+    }
+    else if (Array.isArray(u.role)) {
+        for (const r of u.role)
+            if (typeof r === 'string')
+                out.push(r);
+    }
+    return out;
+}
+//# sourceMappingURL=role-provider.js.map

package/dist/role-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-provider.js","sourceRoot":"","sources":["../src/role-provider.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAU;IAC5C,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACxD,MAAM,CAAC,GAAG,IAA2C,CAAC;IACtD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK;YAAE,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI;YAAE,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/tokens.d.ts

@@ -2,10 +2,27 @@
 export declare const AUTHZ_MODULE_OPTIONS: unique symbol;
 /** Injection token for the optional {@link ResourceResolver} registered by the app. */
 export declare const RESOURCE_RESOLVER: unique symbol;
+/**
+ * Injection token holding the optional resource-loader map consulted by the opt-in
+ * `POST /authz/can` endpoint to rehydrate a `{ type, id }` shim into the REAL entity
+ * instance before authorizing — so an instance-bound `@Policy` matches by constructor.
+ *
+ * Resolves to a `ResourceLoaderMap` (`Record<type, (id) => instance | Promise<instance>>`)
+ * keyed by the resource `type` name the client/codegen emits. Populated from the
+ * `resourceLoaders` forRoot option; an adapter MAY also bind this token to register
+ * loaders, mirroring the {@link PERMISSION_PROVIDER}/{@link ROLE_PROVIDER} seam.
+ *
+ * Shared via `Symbol.for(key)` (global registry) so an external package binding this
+ * same key resolves to the SAME symbol instance. Consulted with `@Optional()` — absent
+ * or empty, the endpoint behaves exactly as before (class-level / ad-hoc only).
+ */
+export declare const RESOURCE_HYDRATOR: unique symbol;
 /** Metadata key for `@Policy(Resource)` — stores the resource class on the policy. */
 export declare const POLICY_RESOURCE_METADATA = "nestjs-authz:policy-resource";
 /** Metadata key for `@Can(ability, Resource?)` — stores the ability descriptor on a route. */
 export declare const CAN_METADATA = "nestjs-authz:can";
+/** Metadata key for `@Roles(...roles)` — stores the allowed role names on a route. */
+export declare const ROLES_METADATA = "nestjs-authz:roles";
 /**
  * Cross-lib injection token for an optional {@link PermissionProvider} — the seam the
  * RBAC adapter (`@dudousxd/nestjs-authz-typeorm`) registers so that a model-less,
@@ -18,6 +35,18 @@ export declare const CAN_METADATA = "nestjs-authz:can";
  * as before (backward-compatible: unknown abilities still throw).
  */
 export declare const PERMISSION_PROVIDER: unique symbol;
+/**
+ * Cross-lib injection token for an optional {@link RoleProvider} — the seam an RBAC
+ * adapter (`@dudousxd/nestjs-authz-typeorm`) registers so coarse role-checks
+ * (`gate.hasRole('teacher')`, `@Roles('admin')`) consult a persisted role store.
+ *
+ * Like {@link PERMISSION_PROVIDER}, it shares the global symbol registry via
+ * `Symbol.for(key)` so an RBAC package registering this same key resolves to the
+ * SAME symbol instance without importing core internals. Consulted with
+ * `@Optional()`: when absent, only the default {@link RoleResolver} (roles read off
+ * the user object) supplies roles. When BOTH yield roles, the Gate unions them.
+ */
+export declare const ROLE_PROVIDER: unique symbol;
 /**
  * Cross-lib injection token for the current-request context accessor, owned by
  * `@dudousxd/nestjs-context`. We do NOT import nestjs-context — instead we share

package/dist/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,eAA+C,CAAC;AAEjF,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,eAAyD,CAAC;AAExF,sFAAsF;AACtF,eAAO,MAAM,wBAAwB,iCAAiC,CAAC;AAEvE,8FAA8F;AAC9F,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,eAA2D,CAAC;AAE5F;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,eAAkD,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,eAA+C,CAAC;AAEjF,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,eAAyD,CAAC;AAExF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,eAAyD,CAAC;AAExF,sFAAsF;AACtF,eAAO,MAAM,wBAAwB,iCAAiC,CAAC;AAEvE,8FAA8F;AAC9F,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAE/C,sFAAsF;AACtF,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,eAA2D,CAAC;AAE5F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,eAAqD,CAAC;AAEhF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,eAAkD,CAAC"}

package/dist/tokens.js

@@ -2,10 +2,27 @@
 export const AUTHZ_MODULE_OPTIONS = Symbol.for('@dudousxd/nestjs-authz:options');
 /** Injection token for the optional {@link ResourceResolver} registered by the app. */
 export const RESOURCE_RESOLVER = Symbol.for('@dudousxd/nestjs-authz:resource-resolver');
+/**
+ * Injection token holding the optional resource-loader map consulted by the opt-in
+ * `POST /authz/can` endpoint to rehydrate a `{ type, id }` shim into the REAL entity
+ * instance before authorizing — so an instance-bound `@Policy` matches by constructor.
+ *
+ * Resolves to a `ResourceLoaderMap` (`Record<type, (id) => instance | Promise<instance>>`)
+ * keyed by the resource `type` name the client/codegen emits. Populated from the
+ * `resourceLoaders` forRoot option; an adapter MAY also bind this token to register
+ * loaders, mirroring the {@link PERMISSION_PROVIDER}/{@link ROLE_PROVIDER} seam.
+ *
+ * Shared via `Symbol.for(key)` (global registry) so an external package binding this
+ * same key resolves to the SAME symbol instance. Consulted with `@Optional()` — absent
+ * or empty, the endpoint behaves exactly as before (class-level / ad-hoc only).
+ */
+export const RESOURCE_HYDRATOR = Symbol.for('@dudousxd/nestjs-authz:resource-hydrator');
 /** Metadata key for `@Policy(Resource)` — stores the resource class on the policy. */
 export const POLICY_RESOURCE_METADATA = 'nestjs-authz:policy-resource';
 /** Metadata key for `@Can(ability, Resource?)` — stores the ability descriptor on a route. */
 export const CAN_METADATA = 'nestjs-authz:can';
+/** Metadata key for `@Roles(...roles)` — stores the allowed role names on a route. */
+export const ROLES_METADATA = 'nestjs-authz:roles';
 /**
  * Cross-lib injection token for an optional {@link PermissionProvider} — the seam the
  * RBAC adapter (`@dudousxd/nestjs-authz-typeorm`) registers so that a model-less,
@@ -18,6 +35,18 @@ export const CAN_METADATA = 'nestjs-authz:can';
  * as before (backward-compatible: unknown abilities still throw).
  */
 export const PERMISSION_PROVIDER = Symbol.for('@dudousxd/nestjs-authz:permission-provider');
+/**
+ * Cross-lib injection token for an optional {@link RoleProvider} — the seam an RBAC
+ * adapter (`@dudousxd/nestjs-authz-typeorm`) registers so coarse role-checks
+ * (`gate.hasRole('teacher')`, `@Roles('admin')`) consult a persisted role store.
+ *
+ * Like {@link PERMISSION_PROVIDER}, it shares the global symbol registry via
+ * `Symbol.for(key)` so an RBAC package registering this same key resolves to the
+ * SAME symbol instance without importing core internals. Consulted with
+ * `@Optional()`: when absent, only the default {@link RoleResolver} (roles read off
+ * the user object) supplies roles. When BOTH yield roles, the Gate unions them.
+ */
+export const ROLE_PROVIDER = Symbol.for('@dudousxd/nestjs-authz:role-provider');
 /**
  * Cross-lib injection token for the current-request context accessor, owned by
  * `@dudousxd/nestjs-context`. We do NOT import nestjs-context — instead we share

package/dist/tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAEjF,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;AAExF,sFAAsF;AACtF,MAAM,CAAC,MAAM,wBAAwB,GAAG,8BAA8B,CAAC;AAEvE,8FAA8F;AAC9F,MAAM,CAAC,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;AAE5F;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC"}
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAEjF,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;AAExF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;AAExF,sFAAsF;AACtF,MAAM,CAAC,MAAM,wBAAwB,GAAG,8BAA8B,CAAC;AAEvE,8FAA8F;AAC9F,MAAM,CAAC,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAE/C,sFAAsF;AACtF,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;AAE5F;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC"}

package/dist/types.d.ts

@@ -31,6 +31,18 @@ export type PolicyInstance = Record<string, unknown> & {
  * An ad-hoc gate: a model-less ability resolved by name via `gate.define`.
  */
 export type GateFn = (user: User, resource?: Resource) => boolean | Promise<boolean>;
+/**
+ * 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
+ * `{ type, id }` shim before authorizing, so an instance-bound `@Policy` matches by
+ * constructor. Returning nullish signals "not found" (the endpoint denies). May be async.
+ */
+export type ResourceLoader = (id: string | number) => unknown | Promise<unknown>;
+/**
+ * Resource loaders keyed by the resource `type` name as emitted by the client/codegen
+ * (e.g. `'Post'`). See {@link AuthzModuleOptions.resourceLoaders}.
+ */
+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.
@@ -69,6 +81,19 @@ export interface AuthzModuleOptions {
      * you pass directly and never invokes this hook.
      */
     resolveUser?: (ref: UserRef) => User | undefined | Promise<User | undefined>;
+    /**
+     * Override the default {@link RoleResolver} used by coarse role-checks
+     * (`gate.hasRole('teacher')`, `@Roles('admin')`). The default reads `user.roles`
+     * (`string[]`) OR `user.role` (`string | string[]`) off the user object, so
+     * role-checks work with ZERO RBAC tables. Provide this to derive roles from a
+     * different shape. When the optional `ROLE_PROVIDER` seam is ALSO registered, the
+     * Gate unions both sources' roles.
+     *
+     * On the context path the resolver receives whatever the context produced (the
+     * raw {@link UserRef} unless `resolveUser` hydrated the entity); on the explicit
+     * `gate.forUser(entity)` path it receives exactly what you passed.
+     */
+    resolveRoles?: (user: User) => string[] | undefined | Promise<string[] | undefined>;
     /**
      * Override the default {@link ResourceResolver} used to load an instance for
      * `@Can(ability, Resource)` routes. Defaults to {@link IdParamResourceResolver}
@@ -83,6 +108,35 @@ export interface AuthzModuleOptions {
      * is supplied.
      */
     idParam?: string;
+    /**
+     * Opt-in `POST /authz/can` fallback endpoint. **Off by default.** When enabled,
+     * registers a controller that runs `gate.allows(ability, resource?)` for the
+     * current (context) user and returns `{ allowed: boolean }`. This is the
+     * last-resort path the codegen-emitted `can()` helper targets.
+     *
+     * - `true` → mount at the default path `authz/can`.
+     * - `string` → mount at that path (e.g. `'api/authz/can'`).
+     * - `false`/omitted → no endpoint is registered.
+     *
+     * Prefer the no-request paths (shared Inertia props, per-resource `can` maps)
+     * — this endpoint exists only for abilities not already hydrated on the client.
+     */
+    canEndpoint?: boolean | string;
+    /**
+     * Resource loaders keyed by the resource `type` name the client/codegen emits
+     * (e.g. `'Post'`). They close the per-instance gap in the {@link canEndpoint}
+     * fallback: when the endpoint receives `{ ability, resource: { type, id } }` and a
+     * loader is registered for `type`, it `await`s `loader(id)` and authorizes the REAL
+     * entity — so an instance-bound `@Policy` matches by constructor and its method runs
+     * with the loaded resource. A loader returning nullish is treated as "not found"
+     * (the endpoint denies). Types WITHOUT a loader keep the prior behavior (class-level
+     * / ad-hoc only; a resource-bound ability still denies). Opt-in: unset → unchanged.
+     *
+     * ```ts
+     * resourceLoaders: { Post: (id) => postRepo.findOneBy({ id: Number(id) }) }
+     * ```
+     */
+    resourceLoaders?: ResourceLoaderMap;
 }
 export interface AuthzModuleOptionsFactory {
     createAuthzOptions(): Promise<AuthzModuleOptions> | AuthzModuleOptions;
@@ -93,5 +147,18 @@ export interface AuthzModuleAsyncOptions {
     useClass?: Type<AuthzModuleOptionsFactory>;
     useFactory?: (...args: unknown[]) => Promise<AuthzModuleOptions> | AuthzModuleOptions;
     inject?: unknown[];
+    /**
+     * Opt-in `POST /authz/can` fallback endpoint (see {@link AuthzModuleOptions.canEndpoint}).
+     * Declared statically here because controllers are registered at module-definition
+     * time, before the async options factory resolves. Off by default.
+     */
+    canEndpoint?: boolean | string;
+    /**
+     * Resource loaders for the {@link canEndpoint} fallback
+     * (see {@link AuthzModuleOptions.resourceLoaders}). May also be returned from the
+     * async options factory; either way the endpoint reads them from the resolved
+     * options, so this declaration is for the rarer case of supplying them statically.
+     */
+    resourceLoaders?: ResourceLoaderMap;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,KACZ,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;AAExD,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACrD,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAErF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,KACZ,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IACvC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAC7E;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,kBAAkB,IAAI,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;CACxE;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC9C,QAAQ,CAAC,EAAE,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC3C,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IACtF,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB"}
+{"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.2.0",
+  "version": "0.4.0",
   "description": "NestJS authorization — Laravel-style Gates & Policies, @Can guard, resource resolver (zero DB).",
   "license": "MIT",
   "repository": {