@dudousxd/nestjs-authz 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @dudousxd/nestjs-authz
 
+## 0.6.4
+
+### Patch Changes
+
+- [#15](https://github.com/DavideCarvalho/nestjs-authz/pull/15) [`10fb1d1`](https://github.com/DavideCarvalho/nestjs-authz/commit/10fb1d154f4dc7a8294b366f213ec38c26a9c678) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Ship TanStack Intent agent skills (SKILL.md) inside the package.
+
+- [#15](https://github.com/DavideCarvalho/nestjs-authz/pull/15) [`7294ff5`](https://github.com/DavideCarvalho/nestjs-authz/commit/7294ff5c01454d9fea6d42a6c3f80eff2f00dc48) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Fix the exported `VERSION` const shipping as `'0.0.0'`.
+
+  The build is plain `tsc` with no version injection, and `changeset version` only bumps `package.json` — leaving the `export const VERSION` in `src/index.ts` stale, so the published dist reported `'0.0.0'`. The const is now corrected to match each package's `package.json`, and a new `scripts/sync-version.mjs` (chained into the `version-packages` script) re-syncs it on every release bump to prevent future drift. Run with `--check` to fail a build on mismatch.
+
+## 0.6.3
+
+### Patch Changes
+
+- [`c4a1fe8`](https://github.com/DavideCarvalho/nestjs-authz/commit/c4a1fe876f6539446a1dec3bc241164058045bcb) - Derive authz's own DI tokens (`AUTHZ_MODULE_OPTIONS`, `RESOURCE_RESOLVER`, `RESOURCE_HYDRATOR`, `PERMISSION_PROVIDER`, `ROLE_PROVIDER`) from the `capability()` factory instead of hand-rolled `Symbol.for` strings, and add a conformance test (`assertCapabilityNaming`) that locks their canonical naming. Resolves to byte-identical symbols — fully non-breaking.
+
 ## 0.6.2
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.0.0";
+export declare const VERSION = "0.6.4";
 export { Gate, BoundGate } from './gate.js';
 export type { BatchAbility, BatchResult } from './gate.js';
 export { PermissionCache } from './permission-cache.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.0.0';
+export const VERSION = '0.6.4';
 export { Gate, BoundGate } from './gate.js';
 export { PermissionCache } from './permission-cache.js';
 export { authzDecisionChannel, publishAuthzDecision } from './diagnostics.js';

package/dist/tokens.d.ts

@@ -1,7 +1,7 @@
 /** Injection token holding the resolved {@link AuthzModuleOptions}. */
-export declare const AUTHZ_MODULE_OPTIONS: unique symbol;
+export declare const AUTHZ_MODULE_OPTIONS: symbol;
 /** Injection token for the optional {@link ResourceResolver} registered by the app. */
-export declare const RESOURCE_RESOLVER: unique symbol;
+export declare const RESOURCE_RESOLVER: 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
@@ -16,7 +16,7 @@ export declare const RESOURCE_RESOLVER: unique symbol;
  * 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;
+export declare const RESOURCE_HYDRATOR: 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. */
@@ -34,7 +34,7 @@ export declare const ROLES_METADATA = "nestjs-authz:roles";
  * The token is consulted with `@Optional()` — when absent, the Gate behaves exactly
  * as before (backward-compatible: unknown abilities still throw).
  */
-export declare const PERMISSION_PROVIDER: unique symbol;
+export declare const PERMISSION_PROVIDER: symbol;
 /**
  * Cross-lib injection token for an optional {@link RoleProvider} — the seam an RBAC
  * adapter (`@dudousxd/nestjs-authz-typeorm`) registers so coarse role-checks
@@ -46,7 +46,7 @@ export declare const PERMISSION_PROVIDER: unique symbol;
  * `@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;
+export declare const ROLE_PROVIDER: symbol;
 /**
  * Cross-lib injection token for the current-request context accessor, owned by
  * `@dudousxd/nestjs-context`. Resolved via the ecosystem protocol's typed

package/dist/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAEA,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,QAAoC,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,QAAiC,CAAC;AAEnE,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,QAA2C,CAAC;AAE1E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,QAA2C,CAAC;AAE1E,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,QAA6C,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,QAAuC,CAAC;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,QAAoC,CAAC"}

package/dist/tokens.js

@@ -1,8 +1,8 @@
 import { capability } from '@dudousxd/nestjs-diagnostics';
 /** Injection token holding the resolved {@link AuthzModuleOptions}. */
-export const AUTHZ_MODULE_OPTIONS = Symbol.for('@dudousxd/nestjs-authz:options');
+export const AUTHZ_MODULE_OPTIONS = capability('authz', 'options');
 /** Injection token for the optional {@link ResourceResolver} registered by the app. */
-export const RESOURCE_RESOLVER = Symbol.for('@dudousxd/nestjs-authz:resource-resolver');
+export const RESOURCE_RESOLVER = capability('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
@@ -17,7 +17,7 @@ export const RESOURCE_RESOLVER = Symbol.for('@dudousxd/nestjs-authz:resource-res
  * 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');
+export const RESOURCE_HYDRATOR = capability('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. */
@@ -35,7 +35,7 @@ export const ROLES_METADATA = 'nestjs-authz:roles';
  * The token is consulted with `@Optional()` — when absent, the Gate behaves exactly
  * as before (backward-compatible: unknown abilities still throw).
  */
-export const PERMISSION_PROVIDER = Symbol.for('@dudousxd/nestjs-authz:permission-provider');
+export const PERMISSION_PROVIDER = capability('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
@@ -47,7 +47,7 @@ export const PERMISSION_PROVIDER = Symbol.for('@dudousxd/nestjs-authz:permission
  * `@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');
+export const ROLE_PROVIDER = capability('authz', 'role-provider');
 /**
  * Cross-lib injection token for the current-request context accessor, owned by
  * `@dudousxd/nestjs-context`. Resolved via the ecosystem protocol's typed

package/dist/tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE1D,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,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC"}
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE1D,uEAAuE;AACvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAEnE,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAE1E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAE1E,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,UAAU,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-authz",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "NestJS authorization — Laravel-style Gates & Policies, @Can guard, resource resolver (zero DB).",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,8 @@
   "files": [
     "dist/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "skills"
   ],
   "dependencies": {
     "@dudousxd/nestjs-diagnostics": "^0.5.0"
@@ -45,6 +46,7 @@
   },
   "devDependencies": {
     "@nestjs/common": "^11.0.0",
+    "@tanstack/intent": "^0.3.2",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-express": "^11.0.0",
     "@nestjs/testing": "^11.0.0",
@@ -68,7 +70,8 @@
     "gate",
     "policy",
     "acl",
-    "rbac"
+    "rbac",
+    "tanstack-intent"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/skills/authz-enforcement/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: authz-enforcement
+description: >
+  Enforce authorization in @dudousxd/nestjs-authz with the @Can and @Roles guards and the
+  programmatic Gate. @Can('update', Post) resolves a Post instance via the ResourceResolver
+  and runs PostPolicy.update; @Can('create', Post, { classLevel: true }) skips loading;
+  @Can('access-admin') hits an ad-hoc gate. @Roles('admin','teacher') is the coarse role
+  check. Both guards are auto-registered as APP_GUARD and are inert on un-annotated routes.
+  Covers the ResourceResolver seam (default IdParamResourceResolver reads :id vs a real ORM
+  resolver bound to RESOURCE_RESOLVER) and the Gate API: authorize/allows/denies/allowsMany,
+  forUser(user) BoundGate, define(ability, fn), hasRole/hasAnyRole.
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-authz"
+  library_version: "0.6.3"
+  framework: nestjs
+---
+
+# Enforcing authorization
+
+Two paths: **declarative** guards (`@Can`, `@Roles`) and the **programmatic** `Gate`.
+Both guards are registered as `APP_GUARD` by `AuthzModule.forRoot`, and both are **inert**
+on routes without their decorator (no metadata → allow).
+
+## Setup
+
+```ts
+import { Controller, Param, Patch, Post as HttpPost } from '@nestjs/common';
+import { Can, Roles } from '@dudousxd/nestjs-authz';
+import { Post } from './post.entity';
+
+@Controller('posts')
+export class PostController {
+  @Patch(':id')
+  @Can('update', Post) // load Post by :id, run PostPolicy.update(currentUser, post)
+  update(@Param('id') id: string) {}
+
+  @HttpPost()
+  @Can('create', Post, { classLevel: true }) // run PostPolicy.create(currentUser) — no instance
+  create() {}
+
+  @HttpPost('purge')
+  @Roles('admin', 'teacher') // allow if the user holds ANY of these roles
+  purge() {}
+}
+```
+
+## Core patterns
+
+### Programmatic Gate
+
+Inject `Gate` for checks inside services. `authorize` throws `ForbiddenException` on deny;
+`allows`/`denies` return a boolean.
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { Gate } from '@dudousxd/nestjs-authz';
+
+@Injectable()
+export class PostService {
+  constructor(private readonly gate: Gate) {}
+
+  async update(post: Post) {
+    await this.gate.authorize('update', post);        // throws on deny
+    if (await this.gate.allows('delete', post)) { /* ... */ }
+  }
+}
+```
+
+`forUser(user)` returns a `BoundGate` that bypasses the context accessor — use it when no
+nestjs-context is wired, or to check a user other than the current one:
+
+```ts
+await this.gate.forUser(someUser).authorize('update', post);
+```
+
+`allowsMany` batch-checks one user in a single pass (resolves the user once, shares a
+permission cache — kills the N+1 on a list page):
+
+```ts
+const results = await this.gate.allowsMany([
+  { ability: 'update', resource: post },
+  { ability: 'delete', resource: post },
+]); // → [{ ability:'update', resource, allowed }, ...] (order preserved)
+```
+
+### Ad-hoc gates
+
+Register a model-less, named ability with `define`, then guard or check it:
+
+```ts
+this.gate.define('access-admin', (user) => (user as User).role === 'staff');
+await this.gate.allows('access-admin');   // programmatic
+// @Can('access-admin')                    // declarative (no resource class)
+```
+
+### Custom ResourceResolver
+
+`@Can('update', Post)` needs an instance. The default `IdParamResourceResolver` builds a
+`{ id }` shim from the route `:id`. For real entities, implement `ResourceResolver` and
+bind `RESOURCE_RESOLVER` (or pass `resourceResolver` to `forRoot`):
+
+```ts
+import type { ResourceResolver } from '@dudousxd/nestjs-authz';
+import { RESOURCE_RESOLVER } from '@dudousxd/nestjs-authz';
+import type { ExecutionContext, Type } from '@nestjs/common';
+
+class OrmResourceResolver implements ResourceResolver {
+  async resolve(resource: Type<unknown>, ctx: ExecutionContext) {
+    const req = ctx.switchToHttp().getRequest<{ params: { id: string } }>();
+    return this.repos.get(resource).findOneBy({ id: Number(req.params.id) });
+  }
+}
+// provide: { provide: RESOURCE_RESOLVER, useClass: OrmResourceResolver }
+```
+
+## Common mistakes
+
+### 1. Class-level ability without `{ classLevel: true }`
+
+```ts
+// Wrong — the guard tries to LOAD a Post (by :id) for a creation route that has none,
+// so the resolver returns undefined and the request is denied.
+@HttpPost()
+@Can('create', Post)
+create() {}
+
+// Correct — flag it class-level so the guard skips resource loading.
+@HttpPost()
+@Can('create', Post, { classLevel: true })
+create() {}
+```
+
+Mechanism: with a `resource` and no `classLevel`, the guard loads an instance via the
+resolver; a `undefined` instance is treated as not-found → deny.
+Source: `packages/core/src/guard/can.guard.ts` (`canActivate`), `packages/core/src/decorator/can.decorator.ts`.
+
+### 2. Using the default resolver and expecting real entity fields
+
+```ts
+// Wrong — IdParamResourceResolver only sets `{ id }`; `post.authorId` is undefined,
+// so an ownership policy reading post.authorId can never match.
+AuthzModule.forRoot({ policies: [PostPolicy] });
+
+// Correct — register an ORM-backed resolver so the policy receives a hydrated row.
+AuthzModule.forRoot({ policies: [PostPolicy], resourceResolver: new OrmResourceResolver(...) });
+```
+
+Mechanism: the default resolver produces a `Object.create(resource.prototype)` shim with
+only `id` set (enough for `instance.constructor` matching, not for column reads).
+Source: `packages/core/src/resource-resolver.ts` (`IdParamResourceResolver`).
+
+### 3. Ambiguous class-level ability across multiple policies
+
+```ts
+// Wrong — both PostPolicy and CommentPolicy define create(); with no resource the Gate
+// cannot tell which to run and throws AmbiguousAbilityException.
+await this.gate.allows('create');
+
+// Correct — pass the resource class so the Gate selects the right policy.
+await this.gate.allows('create', Post);                 // programmatic
+// @Can('create', Post, { classLevel: true })            // declarative
+```
+
+Mechanism: with no resource the Gate scans all policies for the method; >1 match is an
+ambiguous (arbitrary) choice, so it throws instead of guessing.
+Source: `packages/core/src/gate.ts` (`resolvePolicy`, `AmbiguousAbilityException`).

package/skills/authz-policies/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: authz-policies
+description: >
+  Write authorization policies for @dudousxd/nestjs-authz the Laravel way. Use the
+  @Policy(Resource) decorator to map a class to a resource; its methods are abilities
+  dispatched by name (view/update/create...) receiving (user, resource). Covers the
+  optional before(user, ability) short-circuit hook (true=allow, false=deny,
+  undefined=fall through), class-level abilities that omit the resource, returning a
+  deny message via PolicyResponse ({ allowed, message }) instead of a bare boolean, and
+  the global superAdmin / after hooks with their override semantics (after can only fill
+  in when the policy returned nullish; default-deny on no opinion).
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-authz"
+  library_version: "0.6.3"
+  framework: nestjs
+---
+
+# Writing policies
+
+A **policy** is a class decorated with `@Policy(Resource)`. Its methods are **abilities**
+dispatched by name: `update(user, post)` answers `gate.authorize('update', post)` and
+`@Can('update', Post)`.
+
+## Setup
+
+```ts
+import { Policy } from '@dudousxd/nestjs-authz';
+import { Post } from './post.entity';
+import { User } from './user.entity';
+
+@Policy(Post)
+export class PostPolicy {
+  // before runs first for any ability this policy defines:
+  //   true → allow (short-circuit), false → deny (short-circuit), undefined → fall through
+  before(user: User, ability: string) {
+    if (user.isAdmin) return true;
+  }
+
+  view(user: User, post: Post) {
+    return post.published || post.authorId === user.id;
+  }
+
+  update(user: User, post: Post) {
+    return post.authorId === user.id;
+  }
+
+  // class-level ability: no resource instance — receives only the user
+  create(user: User) {
+    return user.verified;
+  }
+}
+```
+
+`@Policy` also makes the class `@Injectable()`, so it is auto-discovered from the Nest
+container (you do not have to list it in `policies: []`, though you may). Register it via
+`AuthzModule.forRoot({ policies: [PostPolicy] })` or rely on auto-discovery.
+
+## Core patterns
+
+### Deny messages with PolicyResponse
+
+Return `{ allowed, message }` instead of a bare boolean to surface a reason. The message
+rides the thrown `ForbiddenException` body and the diagnostics decision.
+
+```ts
+update(user: User, post: Post) {
+  if (post.locked) return { allowed: false, message: 'Post is locked' };
+  return post.authorId === user.id;
+}
+```
+
+### Global superAdmin and after hooks
+
+Configured on the module, not the policy. `superAdmin` runs **before** any policy/gate;
+truthy grants. `after` (Laravel `Gate::after`) runs **after** resolution:
+
+```ts
+AuthzModule.forRoot({
+  superAdmin: (user, ability) => (user as User).role === 'root', // truthy → allow
+  after: (user, ability, result) => {
+    // result is the policy/gate verdict, or undefined when it had "no opinion".
+    if (result === undefined) return ability.startsWith('public.'); // only fills in a gap
+  },
+});
+```
+
+### Inheritance
+
+A subclass of a `@Policy`-decorated class still resolves the inherited resource
+(`getPolicyResource` uses `getMetadata`, walking the prototype chain), so you can share a
+base policy and override individual ability methods.
+
+## Common mistakes
+
+### 1. Falling off the end of a policy method (implicit deny)
+
+```ts
+// Wrong — no return on the non-owner branch yields `undefined` = "no opinion" = DENY,
+// even for a published post you meant to allow.
+view(user: User, post: Post) {
+  if (post.authorId === user.id) return true;
+}
+
+// Correct — return an explicit boolean for every path.
+view(user: User, post: Post) {
+  return post.published || post.authorId === user.id;
+}
+```
+
+Mechanism: a nullish policy return is normalized to `allowed: undefined`, which
+default-denies in `resolve` (after giving an `after` hook a chance).
+Source: `packages/core/src/gate.ts` (`resolveBase` / `resolve`, `normalizeResult`).
+
+### 2. Putting a `before` grant for an ability the policy does not define
+
+```ts
+// Wrong — `before` grants 'publish', but there is no publish() method, so the ability
+// is unresolved and throws AbilityNotResolvedException instead of being allowed.
+@Policy(Post)
+class PostPolicy {
+  before(user: User, ability: string) { if (ability === 'publish') return true; }
+}
+
+// Correct — define the method; `before` may then short-circuit it.
+@Policy(Post)
+class PostPolicy {
+  before(user: User, ability: string) { if (ability === 'publish') return true; }
+  publish(user: User, post: Post) { return post.authorId === user.id; }
+}
+```
+
+Mechanism: the Gate gates the `before` hook on method existence FIRST — a `before` cannot
+answer an ability the policy never declared.
+Source: `packages/core/src/gate.ts` (`resolveBase`, "gate it on method existence FIRST").
+
+### 3. Expecting `after` to overturn an explicit policy verdict
+
+```ts
+// Wrong — the policy already returned `false`; `after` is observe-only here and its
+// return is ignored, so this does NOT re-grant access.
+after: (user, ability, result) => true;
+
+// Correct — `after` can only supply a verdict when the policy/gate had no opinion.
+after: (user, ability, result) => (result === undefined ? true : undefined);
+```
+
+Mechanism: `after` overrides ONLY when `result === undefined` (the base produced no
+explicit verdict); when the policy decided, `after` is purely an observer.
+Source: `packages/core/src/types.ts` (`AfterHook` docs), `packages/core/src/gate.ts` (`resolve`).

package/skills/authz-query-scopes/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: authz-query-scopes
+description: >
+  Filter collections to the rows a user may access with @dudousxd/nestjs-authz query
+  scopes — the accessibleBy / Pundit policy_scope / Cerbos query-plan concept. gate.scope(
+  Entity, ability='viewAny') returns an ORM-neutral ScopeConstraint AST built from scopeAll
+  / scopeNone and the where(field, op, value) / eq(field, value) / and(...) / or(...)
+  helpers (operators eq, ne, gt, gte, lt, lte, in, nin, isNull, isNotNull). A @Policy scope(
+  user, Entity) method produces it (returning true=allow-all, false/nullish=deny-all sugar);
+  an ORM adapter such as @dudousxd/nestjs-authz-typeorm's applyScope / applyScopeConstraint
+  compiles it to a parameterized, identifier-safe WHERE. Mirrors the Gate's grant order:
+  super-admin / permission-provider grant → allow-all; anonymous / no scope → deny-all.
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-authz"
+  library_version: "0.6.3"
+  framework: nestjs
+---
+
+# Query scopes (filtering collections)
+
+A policy **method** decides yes/no for ONE resource. A policy **scope** produces a
+constraint that filters a COLLECTION at the DB layer — instead of over-fetch-then-filter.
+This is the `accessibleBy` / Pundit `policy_scope` / Cerbos query-plan idea, represented
+as a small, serializable condition AST (`ScopeConstraint`).
+
+## Setup
+
+Add a `scope(user, Entity)` method to a `@Policy` class, returning a `ScopeConstraint`
+built from the core helpers:
+
+```ts
+import { Policy, eq, and, where, scopeAll } from '@dudousxd/nestjs-authz';
+import { Post } from './post.entity';
+import { User } from './user.entity';
+
+@Policy(Post)
+export class PostPolicy {
+  scope(user: User, _entity: typeof Post) {
+    if (user.isAdmin) return scopeAll;                 // sugar: every row
+    // editors see published OR their own posts:
+    return and(
+      eq('tenantId', user.tenantId),
+      where('authorId', 'eq', user.id),
+    );
+  }
+}
+```
+
+Resolve it for the current (context) user and apply it with an adapter:
+
+```ts
+import { Gate } from '@dudousxd/nestjs-authz';
+import { applyScopeConstraint, applyScope } from '@dudousxd/nestjs-authz-typeorm';
+
+const constraint = await this.gate.scope(Post);        // ScopeConstraint (ability defaults to 'viewAny')
+const qb = repo.createQueryBuilder('post');
+applyScopeConstraint(qb, constraint);                  // adds a parameterized WHERE
+const posts = await qb.getMany();
+
+// or fold both steps for the current user:
+await applyScope(qb, this.gate, Post);
+```
+
+## Core patterns
+
+### The constraint vocabulary
+
+- `scopeAll` (`{ kind: 'all' }`) — every row; no WHERE added.
+- `scopeNone` (`{ kind: 'none' }`) — no rows; an always-false predicate.
+- `where(field, op, value)` / `eq(field, value)` — a leaf condition. Operators: `eq`,
+  `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `isNull`, `isNotNull`.
+- `and(...nodes)` / `or(...nodes)` — boolean groups. Empty `and()` → allow-all; empty
+  `or()` → deny-all; a single node is returned as-is.
+
+### Grant order mirrors the single-resource Gate
+
+`gate.scope` resolves consistently with `gate.allows`: a `superAdmin` grant or a
+permission-provider grant for the ability → `scopeAll`; an anonymous user, or no
+`scope`/`viewAny` method → `scopeNone`; otherwise the policy's `scope` constraint. A
+policy `before` returning `true`/`false` scopes to allow-all/deny-all too.
+
+### Return-value sugar
+
+A `scope` method may return `true` (→ `scopeAll`), `false`/`null`/`undefined` (→
+`scopeNone`), or a `ScopeConstraint`. `normalizeScope` handles the coercion.
+
+## Common mistakes
+
+### 1. Hand-filtering after fetching instead of scoping the query
+
+```ts
+// Wrong — loads every row then filters in memory: leaks counts, paginates wrong, slow.
+const all = await repo.find();
+const visible = all.filter((p) => p.authorId === user.id);
+
+// Correct — push the constraint into the SQL WHERE.
+const qb = repo.createQueryBuilder('post');
+await applyScope(qb, this.gate, Post);
+const visible = await qb.getMany();
+```
+
+Mechanism: `gate.scope` returns a pure-data AST the adapter compiles to a parameterized
+WHERE, so the DB does the filtering and pagination/counts stay correct.
+Source: `packages/core/src/scope.ts` (`ScopeConstraint`), `packages/typeorm/src/scope.ts`
+(`applyScope` / `applyScopeConstraint`).
+
+### 2. Interpolating user input into a field name
+
+```ts
+// Wrong — concatenating a dynamic column name risks SQL injection and is rejected.
+return where(`${userSuppliedColumn}` as string, 'eq', value);
+
+// Correct — use known, static field names; values are always bound parameters.
+return eq('authorId', user.id);
+```
+
+Mechanism: adapters validate every interpolated identifier against `SAFE_IDENTIFIER`
+(`/^[A-Za-z_][A-Za-z0-9_]*$/`) and **bind** values as parameters — never concatenate them.
+Source: `packages/core/src/scope.ts` (`SAFE_IDENTIFIER`, `assertSafeIdentifier`,
+`ScopeCondition` "value is bound as a parameter").
+
+### 3. Returning `undefined` from a scope and expecting "all rows"
+
+```ts
+// Wrong — a nullish return is deny-all (no rows), not allow-all.
+scope(user: User) {
+  if (user.isAdmin) return; // oops
+}
+
+// Correct — be explicit; nullish/false = deny-all, true/scopeAll = allow-all.
+scope(user: User) {
+  return user.isAdmin ? scopeAll : eq('authorId', user.id);
+}
+```
+
+Mechanism: `normalizeScope` maps `null`/`undefined`/`false` to `scopeNone` (default-deny),
+consistent with the Gate's deny-by-default posture.
+Source: `packages/core/src/scope.ts` (`normalizeScope`, `ScopeResult`).

package/skills/authz-rbac-seams/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: authz-rbac-seams
+description: >
+  Add persisted roles & permissions to @dudousxd/nestjs-authz through its optional,
+  grant-only seams. PERMISSION_PROVIDER (a PermissionProvider with hasPermission and an
+  optional getPermissions) is the Laravel/spatie Gate::before grant — when the user holds
+  a named permission the ability is allowed regardless of policies; getPermissions enables
+  segment wildcard matching (granted posts.* satisfies posts.update, * satisfies anything).
+  ROLE_PROVIDER (a RoleProvider.getRoles) feeds coarse checks gate.hasRole / @Roles, unioned
+  with the user-object defaultRoleResolver (reads user.roles / user.role). Both tokens are
+  capability symbols the ORM adapters (@dudousxd/nestjs-authz-typeorm / -prisma / -mikro-orm)
+  register via AuthzRbacModule; seams are grant-only — a false result never DENIES, it falls
+  through. Covers resolveRoles override and zero-table role checks.
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-authz"
+  library_version: "0.6.3"
+  framework: nestjs
+---
+
+# Persisted RBAC seams
+
+The core stays zero-DB. Persisted roles/permissions plug in through two **optional,
+grant-only** seams the Gate consults via `@Optional()` capability tokens:
+
+- `PERMISSION_PROVIDER` → a `PermissionProvider` (the Laravel/spatie `Gate::before` grant).
+- `ROLE_PROVIDER` → a `RoleProvider` (feeds `gate.hasRole` / `@Roles`).
+
+When neither is registered, the Gate behaves exactly as before. **Grant-only** means a
+provider returning `false`/nullish never DENIES — it falls through to normal resolution.
+
+## Setup
+
+The simplest path is an ORM adapter's `AuthzRbacModule`, which builds a store and
+registers both seams. Example with the Prisma adapter (the TypeORM and MikroORM siblings
+have an identical `AuthzRbacModule` surface):
+
+```ts
+import { Module } from '@nestjs/common';
+import { AuthzModule } from '@dudousxd/nestjs-authz';
+import { AuthzRbacModule } from '@dudousxd/nestjs-authz-prisma';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+@Module({
+  imports: [
+    AuthzModule.forRoot({ policies: [PostPolicy] }),
+    AuthzRbacModule.forRoot({ client: prisma }), // builds the store, registers the seams
+  ],
+})
+export class AppModule {}
+```
+
+Grant permissions/roles through the store, then the Gate consults them automatically:
+
+```ts
+await store.givePermissionToRole('editor', 'posts.publish');
+await store.assignRole({ type: 'user', id: 7 }, 'editor');
+
+await gate.forUser(user).allows('posts.publish'); // true via PERMISSION_PROVIDER
+await gate.forUser(user).hasRole('editor');        // true via ROLE_PROVIDER
+```
+
+## Core patterns
+
+### A hand-rolled PermissionProvider
+
+Implement the interface and bind `PERMISSION_PROVIDER` yourself when you do not use an
+adapter. Implement `getPermissions` to opt into wildcard matching:
+
+```ts
+import type { PermissionProvider, User } from '@dudousxd/nestjs-authz';
+import { PERMISSION_PROVIDER } from '@dudousxd/nestjs-authz';
+
+class MyPermissions implements PermissionProvider {
+  hasPermission(user: User, permission: string) {
+    return this.exactGrants(user).includes(permission); // exact-match fast path
+  }
+  getPermissions(user: User) {
+    return this.grantsFor(user); // e.g. ['posts.*'] — core matches posts.update against it
+  }
+}
+// provide: { provide: PERMISSION_PROVIDER, useClass: MyPermissions }
+```
+
+The core runs segment-based wildcard matching against `getPermissions`: a granted
+`posts.*` satisfies `posts.update`; `*` satisfies anything. `hasPermission` is the
+exact-match contract for providers that do not list grants.
+
+### Zero-table role checks (no provider)
+
+`gate.hasRole` / `@Roles` work with **no** RBAC tables: the `defaultRoleResolver` reads
+`user.roles` (`string[]`) OR `user.role` (`string | string[]`) off the user object.
+Override the shape with `resolveRoles`:
+
+```ts
+AuthzModule.forRoot({
+  resolveRoles: (user) => (user as { groups: string[] }).groups, // derive roles differently
+});
+```
+
+When BOTH a `ROLE_PROVIDER` and the resolver yield roles, the Gate takes their **union**.
+
+## Common mistakes
+
+### 1. Expecting a PermissionProvider to DENY
+
+```ts
+// Wrong — returning false to "block" an ability does nothing: the seam is grant-only,
+// so a policy/gate can still allow it. This is not how you revoke access.
+hasPermission(user: User, permission: string) {
+  return this.isBanned(user) ? false : this.grants(user).includes(permission);
+}
+
+// Correct — denial belongs in the policy/superAdmin; the provider only GRANTS.
+hasPermission(user: User, permission: string) {
+  return this.grants(user).includes(permission); // false simply falls through
+}
+```
+
+Mechanism: the provider grant mirrors `Gate::before` — `true` short-circuits to allow;
+`false`/`undefined` falls through to policy/gate resolution and never denies.
+Source: `packages/core/src/permission-provider.ts` (grant semantics),
+`packages/core/src/gate.ts` (`permissionProviderGrants`, `resolveBase`).
+
+### 2. Re-implementing wildcard matching in your adapter
+
+```ts
+// Wrong — manually expanding wildcards inside hasPermission duplicates core logic and
+// drifts (e.g. handling 'posts.*' but not '*').
+hasPermission(user, permission) {
+  return this.grants(user).some((g) => g === '*' || permission.startsWith(g.replace('.*','')));
+}
+
+// Correct — expose getPermissions and let the core do segment matching.
+getPermissions(user) { return this.grants(user); } // 'posts.*', '*' handled by core
+```
+
+Mechanism: when `getPermissions` is present the core applies `permissionSatisfied`
+segment matching, so wildcard semantics are identical across every adapter.
+Source: `packages/core/src/permission-provider.ts` (getPermissions docs),
+`packages/core/src/permission-matcher.ts` (`permissionSatisfied`).
+
+### 3. Granting permissions for an anonymous request
+
+```ts
+// Wrong — assuming the permission seam runs for unauthenticated callers.
+await gate.allows('posts.publish'); // anonymous → seam is skipped, denies
+
+// Correct — the seam only grants for an authenticated user; resolve/pass one.
+await gate.forUser(user).allows('posts.publish');
+```
+
+Mechanism: the permission-provider grant is gated on `maybeUser !== NO_USER`, so an
+anonymous request never reaches it and follows the default-deny path.
+Source: `packages/core/src/gate.ts` (`resolveBase` — `maybeUser !== NO_USER && permissionProviderGrants(...)`).

package/skills/authz-setup/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: authz-setup
+description: >
+  Set up @dudousxd/nestjs-authz in a NestJS app — install, peer deps, and wire
+  AuthzModule.forRoot / forRootAsync (global module that registers the Gate,
+  CanGuard + RolesGuard as APP_GUARD, PolicyRegistry, default IdParamResourceResolver,
+  and the opt-in POST /authz/can endpoint). Covers the optional @dudousxd/nestjs-context
+  peer (CONTEXT_ACCESSOR) for the current user, and the load-bearing resolveUser hook
+  that hydrates the full user entity from a UserRef ({type,id}) so superAdmin and
+  policy checks like user.isAdmin / post.authorId === user.id actually see real columns.
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-authz"
+  library_version: "0.6.3"
+  framework: nestjs
+---
+
+# Setting up @dudousxd/nestjs-authz
+
+`@dudousxd/nestjs-authz` is **authorization, not authentication**: it reads the
+current user and decides what they may do, Laravel Gate/Policy style. The core has
+**zero database** dependencies.
+
+## Setup
+
+```sh
+pnpm add @dudousxd/nestjs-authz
+```
+
+Peer deps: `@nestjs/common`, `@nestjs/core`, `reflect-metadata`.
+`@dudousxd/nestjs-context` is an **optional** peer — when present the Gate reads the
+current user for free; when absent you pass the user explicitly via `gate.forUser(...)`.
+
+Register the module once (it is `global: true`, so every module sees the `Gate` and the
+guards):
+
+```ts
+import { Module } from '@nestjs/common';
+import { AuthzModule } from '@dudousxd/nestjs-authz';
+import { PostPolicy } from './post.policy';
+
+@Module({
+  imports: [
+    AuthzModule.forRoot({
+      policies: [PostPolicy], // optional — @Policy classes are also auto-discovered
+      superAdmin: (user) => (user as { isAdmin?: boolean }).isAdmin === true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`forRoot` registers: `Gate`, `PolicyRegistry`, `CanGuard` **and** `RolesGuard` (both as
+`APP_GUARD`, so `@Can` / `@Roles` enforce app-wide), a default `IdParamResourceResolver`
+bound to `RESOURCE_RESOLVER`, and a bootstrap provider that fills the `PolicyRegistry` on
+init from `policies: []` **and** auto-discovered `@Policy` providers.
+
+## Core patterns
+
+### forRootAsync (config from DI)
+
+Use when policy lists or hooks depend on injected config. Policies returned from the
+factory are registered too (the bootstrap reads the **resolved** options).
+
+```ts
+AuthzModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    policies: [PostPolicy],
+    superAdmin: (user) => (user as { role?: string }).role === config.get('SUPER_ROLE'),
+  }),
+});
+```
+
+`canEndpoint` and `resourceLoaders` may be declared **statically** on the async options
+too (controllers are registered at module-definition time, before the factory resolves).
+
+### Wiring the current user via nestjs-context
+
+The Gate resolves the current user structurally through the well-known capability token
+`CONTEXT_ACCESSOR` (`capability('context','accessor')` ===
+`Symbol.for('@dudousxd/nestjs-context:accessor')`). Install and configure
+`@dudousxd/nestjs-context` so requests carry a user; the Gate then needs no wiring. With
+**no** accessor and no explicit user, checks treat the request as anonymous and **deny**.
+
+### resolveUser — hydrate the real entity (the critical hook)
+
+On the **context path**, the value handed to `superAdmin`, `after`, `resolveRoles`, and
+your policy methods is the raw **`UserRef`** (`{ type, id }`) from nestjs-context — **not**
+your hydrated user row. Provide `resolveUser` to load the entity before those run:
+
+```ts
+AuthzModule.forRoot({
+  resolveUser: (ref) => userRepo.findOneBy({ id: Number(ref.id) }), // ref: { type, id }
+  superAdmin: (user) => (user as User).isAdmin, // now sees a real column
+});
+```
+
+`resolveUser` returning nullish is treated as "no user" (deny). It is **only** applied on
+the context path — `gate.forUser(entity)` always uses the value you pass verbatim.
+
+## Common mistakes
+
+### 1. Expecting `superAdmin: u => u.isAdmin` to work without `resolveUser`
+
+```ts
+// Wrong — on the context path `user` is just { type, id }; `isAdmin` is undefined,
+// so the super-admin grant never fires from a route or gate.allows(...).
+AuthzModule.forRoot({ superAdmin: (u) => (u as User).isAdmin });
+
+// Correct — hydrate the entity first.
+AuthzModule.forRoot({
+  resolveUser: (ref) => userRepo.findOneBy({ id: Number(ref.id) }),
+  superAdmin: (u) => (u as User).isAdmin,
+});
+```
+
+Mechanism: the context accessor yields only a `UserRef` (`{ type, id }`); `resolveUser`
+is the hook that turns that ref into your `User` entity before hooks/policies run.
+Source: `packages/core/src/types.ts` (`AuthzModuleOptions.superAdmin` / `resolveUser` docs),
+`packages/core/src/gate.ts` (`currentUser`).
+
+### 2. Importing AuthzModule in every feature module
+
+```ts
+// Wrong — forRoot is global; re-importing creates duplicate providers/options.
+@Module({ imports: [AuthzModule.forRoot({ policies: [PostPolicy] })] })
+export class PostsModule {}
+
+// Correct — register once in the root module; the Gate is exported globally.
+@Module({ imports: [AuthzModule.forRoot({ policies: [PostPolicy] })] })
+export class AppModule {}
+```
+
+Mechanism: `forRoot`/`forRootAsync` return `{ global: true }`, so a single root
+registration exports `Gate`, the guards, and `RESOURCE_RESOLVER` to the whole app.
+Source: `packages/core/src/module.ts` (`forRoot` returns `global: true`).
+
+### 3. Reaching for the `canEndpoint` before it is enabled
+
+```ts
+// Wrong — POST /authz/can returns 404; the endpoint is OFF by default.
+AuthzModule.forRoot({ policies: [PostPolicy] });
+
+// Correct — opt in (true = default path 'authz/can', or pass a custom string).
+AuthzModule.forRoot({ policies: [PostPolicy], canEndpoint: true });
+```
+
+Mechanism: `canControllers` registers the fallback controller only when `canEndpoint` is
+truthy; it is the last-resort path for abilities not already hydrated on the client.
+Source: `packages/core/src/module.ts` (`canControllers`), `packages/core/src/types.ts`
+(`canEndpoint`).