@dudousxd/nestjs-authz 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @dudousxd/nestjs-authz
 
+## 0.4.0
+
+### Minor Changes
+
+- [#4](https://github.com/DavideCarvalho/nestjs-authz/pull/4) [`8b7711d`](https://github.com/DavideCarvalho/nestjs-authz/commit/8b7711d11bdb25b3407fea742f6c1158afb36296) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add `resourceLoaders` to `AuthzModule.forRoot`/`forRootAsync` options — a map keyed by
+  the resource `type` name (e.g. `{ Post: (id) => postRepo.findOneBy({ id: Number(id) }) }`).
+  Closes the per-instance gap in the opt-in `POST /authz/can` fallback endpoint: when a loader
+  is registered for `resource.type`, the endpoint rehydrates the client's `{ type, id }` shim
+  into the REAL entity before authorizing, so an instance-bound `@Policy` matches by constructor
+  and its method decides correctly. A loader returning nullish is treated as "not found" (deny).
+  Types without a loader keep the prior class-level / ad-hoc-only behavior. Opt-in and additive:
+  unset → endpoint behavior unchanged. Also exposes a `RESOURCE_HYDRATOR` token and the
+  `ResourceLoader`/`ResourceLoaderMap` types.
+
+## 0.3.0
+
+### Minor Changes
+
+- [#2](https://github.com/DavideCarvalho/nestjs-authz/pull/2) [`2ecb0f4`](https://github.com/DavideCarvalho/nestjs-authz/commit/2ecb0f46342fa4527fc01f1097720f2e7bcf9aa7) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add coarse, role-based authorization alongside the granular ability checks.
+
+  - **`@Roles('admin', 'teacher')` + `RolesGuard`**: a route is allowed when the current
+    user holds ANY of the listed roles. Registered as an `APP_GUARD` by `AuthzModule`
+    (inert on un-annotated routes), it resolves the current user exactly as the `Gate`
+    does and denies an unauthenticated request by default.
+  - **`Gate.hasRole(role)` / `Gate.hasAnyRole(roles[])`** (and `gate.forUser(user).hasRole(...)`),
+    async, resolving the user's effective roles and testing membership.
+  - **Pluggable role source, two layers (unioned):**
+    1. A default `RoleResolver` that reads roles off the user object — `user.roles`
+       (`string[]`) OR `user.role` (`string | string[]`), normalized to a `string[]`.
+       This makes role checks work with ZERO RBAC tables. Override via
+       `AuthzModule.forRoot({ resolveRoles })`.
+    2. An OPTIONAL `ROLE_PROVIDER` seam (`Symbol.for('@dudousxd/nestjs-authz:role-provider')`,
+       consulted with `@Optional()`) — mirroring `PERMISSION_PROVIDER` — so an RBAC adapter
+       can supply roles from a store. When both yield roles, the Gate unions them; when
+       neither does, the check denies.
+
+  Exports the `Roles` decorator, `RolesGuard`, `RoleResolver`, `defaultRoleResolver`,
+  `ROLE_PROVIDER`, `ROLES_METADATA`, and a `RoleProvider` interface. Purely additive — the
+  existing permission-provider / can-endpoint / diagnostics behavior is unchanged.
+
+### Patch Changes
+
+- [#2](https://github.com/DavideCarvalho/nestjs-authz/pull/2) [`2ecb0f4`](https://github.com/DavideCarvalho/nestjs-authz/commit/2ecb0f46342fa4527fc01f1097720f2e7bcf9aa7) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add `@dudousxd/nestjs-authz-inertia`: a 3-tier Inertia integration that lets client `can(...)`
+  checks resolve **without a network request** (the Laravel/Inertia model).
+
+  - **Tier 1 — shared props (no request):** `AuthzInertiaModule` (a global interceptor that calls
+    `req.inertia.share(...)`) or `createAuthzShare(gate, policyRegistry)` (a factory for
+    `InertiaModule.forRoot({ share })`) resolves the current user's class-level abilities — all
+    ad-hoc gates + class-level `@Policy` methods — into `props.auth.can` via direct in-process
+    `gate.allows(...)` calls.
+  - **Tier 2 — per-resource map (no request):** `authorizeResource(gate, instance, abilities)`
+    returns a `{ update, delete }` map a controller attaches to a serialized resource.
+  - **Tier 3 — fallback endpoint (last resort):** consumes core's opt-in `POST /authz/can`.
+  - **Framework-neutral client** (`@dudousxd/nestjs-authz-inertia/client`): an `AbilityStore`,
+    `hydrateFromInertiaProps` / `hydrateResource`, and a `createCan` resolver that reads hydrated
+    decisions synchronously (no fetch on a cache hit) and only falls back (fetch the endpoint, or
+    deny) when the ability/resource is unknown.
+  - **Denial filter (`AuthzDenialFilter`):** `AuthzInertiaModule.forRoot` also registers a global
+    `APP_FILTER` that converts `@Roles`/`@Can` denials (`ForbiddenException`) into a friendly 303
+    redirect on Inertia requests (`X-Inertia` header) — `/login` when unauthenticated, `/403` when
+    authenticated-but-forbidden (auth-state read from the optional `CONTEXT_ACCESSOR`). Non-Inertia
+    (REST) requests are rethrown and keep the normal 403 JSON. Configurable via
+    `forRoot({ denial: { loginUrl, forbiddenUrl, enabled, handler } })` (`enabled: false` opts out;
+    `handler(exception, host)` is a full escape hatch). Targets pass the same open-redirect guard
+    nestjs-inertia uses, falling back to a safe default if unsafe.
+
+  `@dudousxd/nestjs-authz` (patch): add an opt-in `POST /authz/can` fallback controller behind
+  `AuthzModule.forRoot({ canEndpoint: true })` (default off; accepts a custom path string). It runs
+  `gate.allows(ability, resource?)` for the current context user and returns `{ allowed }`, failing
+  closed for unresolved abilities. Also exposes `Gate.gateNames()` and `PolicyRegistry.classAbilities()`
+  so integrations can enumerate a user's class-level abilities.
+
+- [#2](https://github.com/DavideCarvalho/nestjs-authz/pull/2) [`2ecb0f4`](https://github.com/DavideCarvalho/nestjs-authz/commit/2ecb0f46342fa4527fc01f1097720f2e7bcf9aa7) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add `@dudousxd/nestjs-authz-telescope`: a `@dudousxd/nestjs-telescope` extension that records every
+  authorization decision the `Gate` reaches (ability, allow/deny, the reason it was decided, the user
+  and the resource) as an `authorization` Telescope entry plus an "Authorization" dashboard page (a
+  top-N of denied abilities and a table of recent decisions) — so a 403 is debuggable. The extension's
+  `AuthorizationWatcher` subscribes to the new `nestjs-authz:decision` diagnostics channel; nothing is
+  emitted (and nothing recorded) when no observer is listening.
+
+  The core `Gate` now publishes each decision on a dependency-free `node:diagnostics_channel`
+  (`nestjs-authz:decision`, exported as `AUTHZ_DECISION_CHANNEL`) after a verdict is reached. The
+  emission is gated on `channel.hasSubscribers` and fully guarded, so it is zero-overhead with no
+  subscriber and can never affect a check. No existing behavior changes.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/can-endpoint.controller.d.ts

@@ -0,0 +1,39 @@
+import { type Type } from '@nestjs/common';
+/**
+ * Request body for the fallback `can` endpoint. Mirrors the payload emitted by
+ * the codegen `can()` helper: `{ ability, resource?: { type, id } | null }`.
+ */
+export interface CanRequestBody {
+    ability: string;
+    resource?: {
+        type: string;
+        id?: string | number;
+    } | null;
+}
+/** Response shape: a single boolean verdict. */
+export interface CanResponseBody {
+    allowed: boolean;
+}
+/**
+ * Build the opt-in fallback controller class, mounted at `path`. Kept as a
+ * factory so the route path is configurable via `AuthzModule.forRoot({ canEndpoint })`.
+ *
+ * The endpoint runs `gate.allows(ability, resource?)` for the CURRENT (context)
+ * user.
+ *
+ * RESOURCE REHYDRATION — how per-instance decisions resolve:
+ * the client sends a `{ type, id }` shim whose constructor is `Object`, which never
+ * matches a registered instance `@Policy` (those are keyed by the entity constructor).
+ * To bridge that, register `resourceLoaders` in `AuthzModule.forRoot({ resourceLoaders })`
+ * (keyed by the `type` name): when a loader exists for `resource.type`, the endpoint
+ * `await`s `loader(id)` and authorizes the REAL entity, so the instance `@Policy`
+ * matches and its method runs. A loader returning nullish → `{ allowed: false }` (not
+ * found). With NO loader for the type the raw shim is forwarded as before, so only
+ * class-level abilities and ad-hoc gates resolve and a resource-bound ability denies
+ * (a deliberate, documented fall-through, not a silent dead-end). An unresolved ability
+ * is likewise treated as a deny (never a 500).
+ */
+export declare function createCanController(path: string): Type<unknown>;
+/** Default mount path for the fallback endpoint (matches codegen's `/authz/can`). */
+export declare const DEFAULT_CAN_ENDPOINT_PATH = "authz/can";
+//# sourceMappingURL=can-endpoint.controller.d.ts.map

package/dist/can-endpoint.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"can-endpoint.controller.d.ts","sourceRoot":"","sources":["../src/can-endpoint.controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAM/E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC1D;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAgD/D;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,cAAc,CAAC"}

package/dist/can-endpoint.controller.js

@@ -0,0 +1,97 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Body, Controller, Inject, Optional } from '@nestjs/common';
+import { Post as HttpPost } from '@nestjs/common';
+import { Gate } from './gate.js';
+import { RESOURCE_HYDRATOR } from './tokens.js';
+/**
+ * Build the opt-in fallback controller class, mounted at `path`. Kept as a
+ * factory so the route path is configurable via `AuthzModule.forRoot({ canEndpoint })`.
+ *
+ * The endpoint runs `gate.allows(ability, resource?)` for the CURRENT (context)
+ * user.
+ *
+ * RESOURCE REHYDRATION — how per-instance decisions resolve:
+ * the client sends a `{ type, id }` shim whose constructor is `Object`, which never
+ * matches a registered instance `@Policy` (those are keyed by the entity constructor).
+ * To bridge that, register `resourceLoaders` in `AuthzModule.forRoot({ resourceLoaders })`
+ * (keyed by the `type` name): when a loader exists for `resource.type`, the endpoint
+ * `await`s `loader(id)` and authorizes the REAL entity, so the instance `@Policy`
+ * matches and its method runs. A loader returning nullish → `{ allowed: false }` (not
+ * found). With NO loader for the type the raw shim is forwarded as before, so only
+ * class-level abilities and ad-hoc gates resolve and a resource-bound ability denies
+ * (a deliberate, documented fall-through, not a silent dead-end). An unresolved ability
+ * is likewise treated as a deny (never a 500).
+ */
+export function createCanController(path) {
+    let AuthzCanController = class AuthzCanController {
+        gate;
+        loaders;
+        constructor(gate, loaders) {
+            this.gate = gate;
+            this.loaders = loaders;
+        }
+        async can(body) {
+            const ability = body?.ability;
+            if (typeof ability !== 'string' || ability.length === 0) {
+                return { allowed: false };
+            }
+            const resource = body?.resource ?? undefined;
+            try {
+                const target = await this.rehydrate(resource);
+                // A registered loader that produced nothing → not found → deny.
+                if (target === null)
+                    return { allowed: false };
+                const allowed = await this.gate.allows(ability, target);
+                return { allowed };
+            }
+            catch {
+                // Unresolved/ambiguous ability — fail closed.
+                return { allowed: false };
+            }
+        }
+        /**
+         * Turn the client's `{ type, id }` shim into the resource the gate authorizes.
+         * - No resource → `undefined` (class-level ability).
+         * - Loader registered for `type` → the loaded entity, or `null` when the loader
+         *   yields nullish ("not found", which the caller maps to a deny).
+         * - No loader for `type` → the raw shim, forwarded as before (class-level / gate only).
+         */
+        async rehydrate(resource) {
+            if (resource == null)
+                return undefined;
+            const loader = this.loaders?.[resource.type];
+            if (typeof loader !== 'function')
+                return resource;
+            const loaded = await loader(resource.id);
+            return loaded == null ? null : loaded;
+        }
+    };
+    __decorate([
+        HttpPost(),
+        __param(0, Body()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object]),
+        __metadata("design:returntype", Promise)
+    ], AuthzCanController.prototype, "can", null);
+    AuthzCanController = __decorate([
+        Controller(path),
+        __param(1, Optional()),
+        __param(1, Inject(RESOURCE_HYDRATOR)),
+        __metadata("design:paramtypes", [Gate, Object])
+    ], AuthzCanController);
+    return AuthzCanController;
+}
+/** Default mount path for the fallback endpoint (matches codegen's `/authz/can`). */
+export const DEFAULT_CAN_ENDPOINT_PATH = 'authz/can';
+//# sourceMappingURL=can-endpoint.controller.js.map

package/dist/can-endpoint.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"can-endpoint.controller.js","sourceRoot":"","sources":["../src/can-endpoint.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAa,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAiBhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IACM,kBAAkB,GADxB,MACM,kBAAkB;QAEH;QAGA;QAJnB,YACmB,IAAU,EAGV,OAA2B;YAH3B,SAAI,GAAJ,IAAI,CAAM;YAGV,YAAO,GAAP,OAAO,CAAoB;QAC3C,CAAC;QAGE,AAAN,KAAK,CAAC,GAAG,CAAS,IAAoB;YACpC,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,CAAC;YAC9B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAC5B,CAAC;YACD,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,SAAS,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;gBAC9C,gEAAgE;gBAChE,IAAI,MAAM,KAAK,IAAI;oBAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;gBAC/C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBACxD,OAAO,EAAE,OAAO,EAAE,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,8CAA8C;gBAC9C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAC5B,CAAC;QACH,CAAC;QAED;;;;;;WAMG;QACK,KAAK,CAAC,SAAS,CACrB,QAAgD;YAEhD,IAAI,QAAQ,IAAI,IAAI;gBAAE,OAAO,SAAS,CAAC;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC7C,IAAI,OAAO,MAAM,KAAK,UAAU;gBAAE,OAAO,QAAkB,CAAC;YAC5D,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,EAAqB,CAAC,CAAC;YAC5D,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,MAAiB,CAAC;QACpD,CAAC;KACF,CAAA;IAlCO;QADL,QAAQ,EAAE;QACA,WAAA,IAAI,EAAE,CAAA;;;;iDAgBhB;IAzBG,kBAAkB;QADvB,UAAU,CAAC,IAAI,CAAC;QAIZ,WAAA,QAAQ,EAAE,CAAA;QACV,WAAA,MAAM,CAAC,iBAAiB,CAAC,CAAA;yCAFH,IAAI;OAFzB,kBAAkB,CA2CvB;IAED,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,MAAM,yBAAyB,GAAG,WAAW,CAAC"}

package/dist/decorator/roles.decorator.d.ts

@@ -0,0 +1,15 @@
+import 'reflect-metadata';
+/**
+ * Guard a route by COARSE role membership: the request is allowed when the current
+ * user holds ANY of the listed roles. This is the broad "is teacher?" check, as
+ * opposed to the granular ability check of `@Can`.
+ *
+ * Roles come from the user object (`user.roles` / `user.role`) by default, plus the
+ * optional `ROLE_PROVIDER` seam (a persisted RBAC store) when registered — see
+ * {@link RolesGuard}.
+ *
+ * @example
+ *   `@Roles('admin', 'teacher')`  // allow if the user is an admin OR a teacher
+ */
+export declare function Roles(...roles: string[]): MethodDecorator & ClassDecorator;
+//# sourceMappingURL=roles.decorator.d.ts.map

package/dist/decorator/roles.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.decorator.d.ts","sourceRoot":"","sources":["../../src/decorator/roles.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAI1B;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,eAAe,GAAG,cAAc,CAE1E"}

package/dist/decorator/roles.decorator.js

@@ -0,0 +1,19 @@
+import 'reflect-metadata';
+import { SetMetadata } from '@nestjs/common';
+import { ROLES_METADATA } from '../tokens.js';
+/**
+ * Guard a route by COARSE role membership: the request is allowed when the current
+ * user holds ANY of the listed roles. This is the broad "is teacher?" check, as
+ * opposed to the granular ability check of `@Can`.
+ *
+ * Roles come from the user object (`user.roles` / `user.role`) by default, plus the
+ * optional `ROLE_PROVIDER` seam (a persisted RBAC store) when registered — see
+ * {@link RolesGuard}.
+ *
+ * @example
+ *   `@Roles('admin', 'teacher')`  // allow if the user is an admin OR a teacher
+ */
+export function Roles(...roles) {
+    return SetMetadata(ROLES_METADATA, roles);
+}
+//# sourceMappingURL=roles.decorator.js.map

package/dist/decorator/roles.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.decorator.js","sourceRoot":"","sources":["../../src/decorator/roles.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAC,GAAG,KAAe;IACtC,OAAO,WAAW,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AAC5C,CAAC"}

package/dist/diagnostics.d.ts

@@ -0,0 +1,42 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+import type { Resource, User } from './types.js';
+/**
+ * Channel name — the cross-repo wire contract with `@dudousxd/nestjs-authz-telescope`'s
+ * authorization watcher (and any other observer). Versioned by the payload's `v` field,
+ * not by name. Keep this string byte-identical on both sides.
+ */
+export declare const AUTHZ_DECISION_CHANNEL = "nestjs-authz:decision";
+/**
+ * Memoized by Node: the same channel object is returned for the same name. Read
+ * `.hasSubscribers` to gate any work before publishing — when nothing subscribes
+ * (the common case) emitting a decision is effectively free.
+ */
+export declare const authzDecisionChannel: diagnostics_channel.Channel<unknown, unknown>;
+/**
+ * Every authorization decision the {@link Gate} reaches, published once per
+ * `allows`/`authorize`/`denies` call. `reason` names which resolution path
+ * produced the verdict so a 403 is debuggable.
+ */
+export interface AuthzDecisionDiagnostic {
+    v: 1;
+    /** The ability checked, e.g. `'update'` or `'access-admin'`. */
+    ability: string;
+    /** The verdict — `true` allow, `false` deny. */
+    allowed: boolean;
+    /** Which resolution path decided it (see {@link AuthzDecisionReason}). */
+    reason: AuthzDecisionReason;
+    /** A label for the resolved user (`<type>#<id>` / constructor name), or `null` when anonymous. */
+    userRef: string | null;
+    /** The resource class name the ability targeted, or `null` for a model-less ability. */
+    resourceType: string | null;
+    /** The resource's `id` when discoverable on the instance, else `null`. */
+    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' | '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.
+ */
+export declare function publishAuthzDecision(ability: string, allowed: boolean, reason: AuthzDecisionReason, user: User, resource: Resource | undefined): void;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,mBAAmB,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,+CAAsD,CAAC;AAExF;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,CAAC,EAAE,CAAC,CAAC;IACL,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,MAAM,EAAE,mBAAmB,CAAC;IAC5B,kGAAkG;IAClG,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wFAAwF;IACxF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,0FAA0F;AAC1F,MAAM,MAAM,mBAAmB,GAC3B,aAAa,GACb,qBAAqB,GACrB,eAAe,GACf,QAAQ,GACR,MAAM,GACN,WAAW,CAAC;AAEhB;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAC7B,IAAI,CAgBN"}

package/dist/diagnostics.js

@@ -0,0 +1,68 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+/**
+ * Channel name — the cross-repo wire contract with `@dudousxd/nestjs-authz-telescope`'s
+ * authorization watcher (and any other observer). Versioned by the payload's `v` field,
+ * not by name. Keep this string byte-identical on both sides.
+ */
+export const AUTHZ_DECISION_CHANNEL = 'nestjs-authz:decision';
+/**
+ * Memoized by Node: the same channel object is returned for the same name. Read
+ * `.hasSubscribers` to gate any work before publishing — when nothing subscribes
+ * (the common case) emitting a decision is effectively free.
+ */
+export const authzDecisionChannel = diagnostics_channel.channel(AUTHZ_DECISION_CHANNEL);
+/**
+ * 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.
+ */
+export function publishAuthzDecision(ability, allowed, reason, user, resource) {
+    if (!authzDecisionChannel.hasSubscribers)
+        return;
+    try {
+        const payload = {
+            v: 1,
+            ability,
+            allowed,
+            reason,
+            userRef: labelUser(user),
+            resourceType: resourceType(resource),
+            resourceId: resourceId(resource),
+        };
+        authzDecisionChannel.publish(payload);
+    }
+    catch {
+        // Observability must never break authorization.
+    }
+}
+/** A short, JSON-safe label for the user — `<type>#<id>`, a constructor name, or `null`. */
+function labelUser(user) {
+    if (user == null)
+        return null;
+    if (typeof user === 'object') {
+        const obj = user;
+        const type = (obj.type ?? obj.constructor?.name);
+        const id = obj.id;
+        if (type && (typeof id === 'string' || typeof id === 'number'))
+            return `${type}#${id}`;
+        if (typeof obj.id === 'string' || typeof obj.id === 'number')
+            return String(obj.id);
+        return obj.constructor?.name ?? null;
+    }
+    return String(user);
+}
+/** The resource's class name (`Post`), or `null` when model-less. A class itself maps to its name. */
+function resourceType(resource) {
+    if (resource == null)
+        return null;
+    if (typeof resource === 'function')
+        return resource.name ?? null;
+    return resource.constructor?.name ?? null;
+}
+/** The resource instance's `id`, when present and primitive; otherwise `null`. */
+function resourceId(resource) {
+    if (resource == null || typeof resource === 'function')
+        return null;
+    const id = resource.id;
+    return typeof id === 'string' || typeof id === 'number' ? id : null;
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,mBAAmB,MAAM,0BAA0B,CAAC;AAG3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAgCxF;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,OAAgB,EAChB,MAA2B,EAC3B,IAAU,EACV,QAA8B;IAE9B,IAAI,CAAC,oBAAoB,CAAC,cAAc;QAAE,OAAO;IACjD,IAAI,CAAC;QACH,MAAM,OAAO,GAA4B;YACvC,CAAC,EAAE,CAAC;YACJ,OAAO;YACP,OAAO;YACP,MAAM;YACN,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC;YACxB,YAAY,EAAE,YAAY,CAAC,QAAQ,CAAC;YACpC,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC;SACjC,CAAC;QACF,oBAAoB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC;AAED,4FAA4F;AAC5F,SAAS,SAAS,CAAC,IAAU;IAC3B,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,IAA+B,CAAC;QAC5C,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,EAAE,IAAI,CAAuB,CAAC;QACvE,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC;QAClB,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,EAAE,KAAK,QAAQ,CAAC;YAAE,OAAO,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;QACvF,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpF,OAAO,GAAG,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC;IACvC,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,sGAAsG;AACtG,SAAS,YAAY,CAAC,QAA8B;IAClD,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAQ,QAA8B,CAAC,IAAI,IAAI,IAAI,CAAC;IACxF,OAAQ,QAAgD,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC;AACrF,CAAC;AAED,kFAAkF;AAClF,SAAS,UAAU,CAAC,QAA8B;IAChD,IAAI,QAAQ,IAAI,IAAI,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACpE,MAAM,EAAE,GAAI,QAAoC,CAAC,EAAE,CAAC;IACpD,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC"}

package/dist/gate.d.ts

@@ -2,6 +2,7 @@ import { ModuleRef } from '@nestjs/core';
 import type { ContextAccessor } from './context-accessor.js';
 import type { PermissionProvider } from './permission-provider.js';
 import { PolicyRegistry } from './policy-registry.js';
+import { type RoleProvider } from './role-provider.js';
 import type { AuthzModuleOptions, GateFn, Resource, User } from './types.js';
 declare const NO_USER: unique symbol;
 type MaybeUser = User | typeof NO_USER;
@@ -21,10 +22,12 @@ export declare class Gate {
     private readonly context?;
     private readonly moduleRef?;
     private readonly permissionProvider?;
+    private readonly roleProvider?;
     private readonly gates;
     private readonly superAdmin;
     private readonly resolveUser;
-    constructor(policies: PolicyRegistry, options: AuthzModuleOptions | undefined, context?: ContextAccessor | undefined, moduleRef?: ModuleRef | undefined, permissionProvider?: PermissionProvider | undefined);
+    private readonly roleResolver;
+    constructor(policies: PolicyRegistry, options: AuthzModuleOptions | undefined, context?: ContextAccessor | undefined, moduleRef?: ModuleRef | undefined, permissionProvider?: PermissionProvider | undefined, roleProvider?: RoleProvider | undefined);
     /**
      * Locate the context accessor. Prefers the value injected into this module;
      * falls back to a non-strict {@link ModuleRef} lookup so an accessor provided
@@ -37,10 +40,22 @@ export declare class Gate {
      * provider registered by ANY module (e.g. the RBAC adapter's global module) is found.
      */
     private resolvePermissionProvider;
+    /**
+     * Locate the optional {@link RoleProvider} (the coarse role seam). Prefers the value
+     * injected into this module; falls back to a non-strict {@link ModuleRef} lookup so a
+     * provider registered by ANY module (e.g. the RBAC adapter's global module) is found.
+     */
+    private resolveRoleProvider;
     /** Register an ad-hoc, model-less gate resolved by `ability` name. */
     define(ability: string, fn: GateFn): this;
     /** True when an ad-hoc gate is registered for `ability`. */
     hasGate(ability: string): boolean;
+    /**
+     * Names of every ad-hoc gate registered via {@link define}. Used by integrations
+     * (e.g. `@dudousxd/nestjs-authz-inertia`) that enumerate the user's class-level
+     * abilities to share them as Inertia props — no network round-trip needed.
+     */
+    gateNames(): string[];
     /**
      * Bind an explicit user, bypassing the context accessor. Use when no
      * nestjs-context is wired, or to check a user other than the current one.
@@ -61,9 +76,31 @@ export declare class Gate {
     allows(ability: string, resource?: Resource): Promise<boolean>;
     denies(ability: string, resource?: Resource): Promise<boolean>;
     authorize(ability: string, resource?: Resource): Promise<void>;
+    /** True when the current user holds `role`. */
+    hasRole(role: string): Promise<boolean>;
+    /** True when the current user holds ANY of `roles`. */
+    hasAnyRole(roles: string[]): Promise<boolean>;
     /** @internal */
     allowsForUser(user: MaybeUser, ability: string, resource?: Resource): Promise<boolean>;
+    /** @internal */
+    hasAnyRoleForUser(user: MaybeUser, roles: string[]): Promise<boolean>;
+    /**
+     * Resolve the user's effective roles and test membership against `roles`. Returns
+     * `false` for an anonymous (NO_USER) caller and whenever no source yields a role
+     * (deny-by-default). Roles come from the UNION of the default/overridden
+     * {@link RoleResolver} (reads the user object) and the optional {@link RoleProvider}
+     * seam (a persisted store) — so an app needs neither to opt in.
+     */
+    private checkRoles;
+    /** The current user's effective role names (resolver ∪ provider). */
+    private rolesOf;
     private check;
+    /**
+     * Resolve an ability to a verdict plus the path that decided it. Throws
+     * {@link AbilityNotResolvedException}/{@link AmbiguousAbilityException} when no
+     * decision can be reached (those paths emit no decision).
+     */
+    private resolve;
     private resolvePolicy;
 }
 /**
@@ -76,6 +113,10 @@ export declare class BoundGate {
     allows(ability: string, resource?: Resource): Promise<boolean>;
     denies(ability: string, resource?: Resource): Promise<boolean>;
     authorize(ability: string, resource?: Resource): Promise<void>;
+    /** True when the bound user holds `role`. */
+    hasRole(role: string): Promise<boolean>;
+    /** True when the bound user holds ANY of `roles`. */
+    hasAnyRole(roles: string[]): Promise<boolean>;
 }
 export {};
 //# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAW,MAAM,uBAAuB,CAAC;AAEtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,KAAK,EACV,kBAAkB,EAClB,MAAM,EAGN,QAAQ,EAER,IAAI,EACL,MAAM,YAAY,CAAC;AAIpB,QAAA,MAAM,OAAO,eAA0B,CAAC;AACxC,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,OAAO,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,qBACa,IAAI;IAMb,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAMzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAG3B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAhBtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;gBAG7C,QAAQ,EAAE,cAAc,EAGzC,OAAO,EAAE,kBAAkB,GAAG,SAAS,EAGtB,OAAO,CAAC,EAAE,eAAe,YAAA,EAEzB,SAAS,CAAC,EAAE,SAAS,YAAA,EAGrB,kBAAkB,CAAC,EAAE,kBAAkB,YAAA;IAM1D;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAUjC,sEAAsE;IACtE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAKzC,4DAA4D;IAC5D,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS;IAI9B;;;;OAIG;YACW,WAAW;IAcnB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpE,gBAAgB;IAChB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;YAIxE,KAAK;IAsDnB,OAAO,CAAC,aAAa;CAwBtB;AAED;;GAEG;AACH,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,SAAS;IAGlC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAKrE"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"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"}