@dudousxd/nestjs-authz 0.8.0 → 0.9.0

package/skills/authz-enforcement/SKILL.md

@@ -1,167 +1,103 @@
 ---
 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.
+  Enforce authorization with @dudousxd/nestjs-authz 0.9 on top of @nestjs/authorization.
+  Routes use the official @Can(Policy, 'ability', argsResolver) and its global guard; our
+  helpers go inside it: byId(Post) (loads the :id record with the ResourceResolver, kept for
+  the handler via authorizedResource), roles(), permission(), ability(), staticCanArgs()
+  (static, marked with Symbol.for('@dudousxd/static-can-args')), and the sugar @Roles /
+  @Permission. Services use the Gate: allows/denies/authorize with a policy class or a string
+  ability, allowsMany, forUser, define, hasRole. Covers migrating the 0.8 string @Can.
 metadata:
   type: core
   library: "@dudousxd/nestjs-authz"
-  library_version: "0.6.3"
+  library_version: "0.9.0"
   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.
+## Routes
 
 ```ts
-import { Injectable } from '@nestjs/common';
-import { Gate } from '@dudousxd/nestjs-authz';
-
-@Injectable()
-export class PostService {
-  constructor(private readonly gate: Gate) {}
+import { Can } from '@nestjs/authorization';
+import { GatePolicy, PermissionPolicy, Roles, ability, authorizedResource, byId, permission } from '@dudousxd/nestjs-authz';
 
-  async update(post: Post) {
-    await this.gate.authorize('update', post);        // throws on deny
-    if (await this.gate.allows('delete', post)) { /* ... */ }
-  }
+@Patch(':id')
+@Can(PostPolicy, 'update', byId(Post))            // 403 if the Post is not found
+update(@Req() req: Request) {
+  const post = authorizedResource(req, Post);       // the record byId loaded
 }
-```
 
-`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:
+@Post(':id/publish')
+@Can(PermissionPolicy, 'has', permission('posts.publish')) // or @Permission('posts.publish')
+publish() {}
 
-```ts
-await this.gate.forUser(someUser).authorize('update', post);
-```
+@Get('admin')
+@Roles('admin', 'editor')                           // any of; RolePolicy.hasAll for all of
+admin() {}
 
-`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):
+@Get('reports')
+@Can(GatePolicy, 'allows', ability('access-admin')) // a gate.define() gate
+reports() {}
 
-```ts
-const results = await this.gate.allowsMany([
-  { ability: 'update', resource: post },
-  { ability: 'delete', resource: post },
-]); // → [{ ability:'update', resource, allowed }, ...] (order preserved)
+@Get('me')
+@Can.Anyone()                                       // the official way to open a route
+me() {}
 ```
 
-### Ad-hoc gates
+Class-level and method-level requirements all apply (AND); a method's `Can.Anyone()` lifts the
+class's. Argument resolvers run in the guard, before pipes, with no DI: `byId` reads the
+`ResourceResolver` `AuthzModule` registered at boot.
 
-Register a model-less, named ability with `define`, then guard or check it:
+## Services
 
 ```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)
+await gate.forUser(user).authorize(PostPolicy, 'update', post); // = AuthorizationService.authorize
+await gate.forUser(user).allows('update', post);                // policy linked with @PolicyFor(Post)
+await gate.forUser(user).allows('posts.publish');               // persisted permission
+await gate.forUser(user).allowsMany([{ ability: 'update', resource: post }]);
+gate.define('access-admin', (user) => user.isStaff);
 ```
 
-### 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 }
-```
+String abilities ask, in order: `superAdmin` (it receives the resource too), the external
+decision point (`DECISION_PROVIDER`, e.g. the Cerbos adapter — its allow or deny is final,
+`undefined` abstains), the linked policy (official evaluation), the persisted permissions,
+the ad-hoc gate; else `AbilityNotResolvedException`. The policy has the final word: a
+persisted permission named like one of its abilities (`update`) does not bypass it — only
+`superAdmin` short-circuits a policy. `authorize()` throws the official `AuthorizationError`.
+
+Without `forUser()`, the user is `@nestjs/authentication`'s `AuthenticationContext.user`
+when that package is installed and its scope is active for the call (its answer is final,
+so an anonymous call there is a guest), else nestjs-context's user ref
+(hydrated once per request by `resolveUser`), else a guest.
+
+Inside a nestjs-context request, every check shares one `resolveUser`, one permission fetch
+and one role fetch per user for the whole request — the official guard's `RolePolicy` /
+`PermissionPolicy` and the handler's `Gate` calls alike (keyed by the row the user names —
+its class or `type` plus `id`; a plain object without `type` is keyed by identity, so two
+users that only share an `id` never share an entry). `allowsMany` shares one fetch per
+batch even without nestjs-context, and asks a `DECISION_PROVIDER`'s `decideMany` once.
 
 ## Common mistakes
 
-### 1. Class-level ability without `{ classLevel: true }`
+### 1. Writing the 0.8 string form
 
-```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() {}
-```
+0.9 removed it: `@Can` comes from `@nestjs/authorization` and names the policy.
 
-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`.
+| 0.8 | 0.9 |
+| --- | --- |
+| `@Can('update', Post)` | `@Can(PostPolicy, 'update', byId(Post))` |
+| `@Can('create', Post, { classLevel: true })` | `@Can(PostPolicy, 'create')` |
+| `@Can('access-admin')` | `@Can(GatePolicy, 'allows', ability('access-admin'))` |
 
-### 2. Using the default resolver and expecting real entity fields
+### 2. Loading the record again in the handler
 
-```ts
-// Wrong — IdParamResourceResolver only sets `{ id }`; `post.authorId` is undefined,
-// so an ownership policy reading post.authorId can never match.
-AuthzModule.forRoot({ policies: [PostPolicy] });
+Read it with `authorizedResource(req, Post)`.
 
-// 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
+### 3. Writing an inline resolver for constant args
 
-```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
-```
+`@Can(FlagPolicy, 'on', () => ['billing'])` works, but tools cannot read it without a call.
+Use `staticCanArgs('billing')`.
 
-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`).
+Source: `packages/core/src/helpers.ts`, `packages/core/src/gate.ts`, `packages/core/src/decorator/roles.decorator.ts`.

package/skills/authz-policies/SKILL.md

@@ -1,150 +1,76 @@
 ---
 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).
+  Write policies for @dudousxd/nestjs-authz 0.9: they are official @nestjs/authorization
+  policies (@Policy(), abilities taking `user | null`, optional before(), only a literal true
+  allows). Our additions: @PolicyFor(Resource) to link a resource to its policy (for
+  gate.allows('update', post), gate.scope(Post), client ability maps), the AuthzPolicy base
+  class / superAdminBefore() that honor the global superAdmin hook, and a scope(user) method
+  for query scoping. Covers migrating the 0.8 @Policy(Resource).
 metadata:
   type: core
   library: "@dudousxd/nestjs-authz"
-  library_version: "0.6.3"
+  library_version: "0.9.0"
   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;
+import { Policy } from '@nestjs/authorization';
+import { AuthzPolicy, PolicyFor, eq } from '@dudousxd/nestjs-authz';
+
+@Policy()
+@PolicyFor(Post)                            // optional link; also applies @Policy() itself
+export class PostPolicy extends AuthzPolicy { // optional: superAdmin grants every ability
+  update(user: User | null, post: Post) {
+    return post.authorId === user?.id;
   }
-
-  update(user: User, post: Post) {
-    return post.authorId === user.id;
+  create(user: User | null) {
+    return user?.verified === true;           // no record: a class-level ability
   }
-
-  // class-level ability: no resource instance — receives only the user
-  create(user: User) {
-    return user.verified;
+  scope(user: User) {
+    return eq('authorId', user.id);           // not an ability; used by gate.scope(Post)
   }
 }
 ```
 
-`@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.
+- Abilities are the official contract: `ability(user | null, ...args)`, `true` allows,
+  anything else denies. A guest denial is a 401, a signed-in one a 403.
+- `AuthzPolicy.before()` asks `superAdmin(user, ability, resource)`, then the
+  `DECISION_PROVIDER` when one is registered (its allow/deny is final; `undefined` abstains).
+  Own `before()`: override and call `super.before(user, ability, ...args)` first to keep both.
+  Policies that cannot extend `AuthzPolicy` call `superAdminBefore(user, ability, resource)`
+  and `decisionProviderBefore(user, ability, resource)`.
+- A persisted permission named like an ability does not bypass the policy: the policy has the
+  final word.
+- Policies must be singletons (official rule).
 
 ## Common mistakes
 
-### 1. Falling off the end of a policy method (implicit deny)
+### 1. Typing the user as `User`
 
 ```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;
-}
+update(user: User, post: Post) {}          // Wrong — guests reach it as null; @Can rejects it
+update(user: User | null, post: Post) {}   // Correct
 ```
 
-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. Returning `{ allowed, message }` or a truthy value
 
-### 2. Putting a `before` grant for an ability the policy does not define
+0.x accepted `PolicyResponse`. The official evaluator allows only a literal `true`; a
+truthy object denies. Return booleans.
 
-```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; }
-}
-```
+### 3. Expecting superAdmin everywhere
 
-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").
+The official guard runs only the policy's own `before()`. A policy that does not extend
+`AuthzPolicy` (or call `superAdminBefore`) never sees superAdmin on routes.
 
-### 3. Expecting `after` to overturn an explicit policy verdict
+### 4. Writing the 0.8 `@Policy(Post)`
 
-```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);
-```
+0.9 removed it: this package no longer exports `Policy`. Use the official `@Policy()` from
+`@nestjs/authorization` plus `@PolicyFor(Post)` (or `@PolicyFor(Post)` alone, which applies
+`@Policy()` itself).
 
-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`).
+Source: `packages/core/src/links.ts`, `packages/core/src/policies/authz-policy.ts`.

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

@@ -8,12 +8,14 @@ description: >
   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.
+  compiles it to a parameterized, identifier-safe WHERE. Mirrors the Gate's order:
+  super-admin → allow-all; a DECISION_PROVIDER planScope; the policy's scope (a persisted
+  permission never widens it); anonymous → deny-all; no policy method → a permission grant
+  allows all, else deny-all.
 metadata:
   type: core
   library: "@dudousxd/nestjs-authz"
-  library_version: "0.6.3"
+  library_version: "0.9.0"
   framework: nestjs
 ---
 
@@ -30,11 +32,13 @@ Add a `scope(user, Entity)` method to a `@Policy` class, returning a `ScopeConst
 built from the core helpers:
 
 ```ts
-import { Policy, eq, and, where, scopeAll } from '@dudousxd/nestjs-authz';
+import { Policy } from '@nestjs/authorization';
+import { PolicyFor, eq, and, where, scopeAll } from '@dudousxd/nestjs-authz';
 import { Post } from './post.entity';
 import { User } from './user.entity';
 
-@Policy(Post)
+@Policy()
+@PolicyFor(Post)
 export class PostPolicy {
   scope(user: User, _entity: typeof Post) {
     if (user.isAdmin) return scopeAll;                 // sugar: every row
@@ -75,10 +79,13 @@ await applyScope(qb, this.gate, Post);
 
 ### 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.
+`gate.scope` resolves consistently with `gate.allows`: a `superAdmin` grant (it receives the
+entity class) → `scopeAll`; a `DECISION_PROVIDER`'s `planScope` (e.g. Cerbos `PlanResources`),
+when it does not abstain, is used as-is; a policy `before` returning `true`/`false` scopes to
+allow-all/deny-all; an anonymous user → `scopeNone`; otherwise the policy's `scope` constraint.
+The policy has the final word: a persisted `viewAny` permission does not widen it. Only when
+there is no policy `scope`/`viewAny` method does a permission grant for the ability give
+`scopeAll` (else `scopeNone`).
 
 ### Return-value sugar
 

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

@@ -3,10 +3,11 @@ 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
+  optional getPermissions) grants named abilities no policy defines (posts.publish) — it never
+  bypasses a policy that defines the ability (the policy has the final word; only superAdmin
+  short-circuits it); getPermissions enables
   segment wildcard matching (granted posts.* satisfies posts.update, * satisfies anything).
-  ROLE_PROVIDER (a RoleProvider.getRoles) feeds coarse checks gate.hasRole / @Roles, unioned
+  ROLE_PROVIDER (a RoleProvider.getRoles) feeds coarse checks gate.hasRole / @Roles (RolePolicy), 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 / -drizzle)
   register via AuthzRbacModule; seams are grant-only — a false result never DENIES, it falls
@@ -14,7 +15,7 @@ description: >
 metadata:
   type: core
   library: "@dudousxd/nestjs-authz"
-  library_version: "0.6.3"
+  library_version: "0.9.0"
   framework: nestjs
 ---
 
@@ -23,7 +24,8 @@ metadata:
 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).
+- `PERMISSION_PROVIDER` → a `PermissionProvider` (feeds `PermissionPolicy` / `@Permission` and
+  the `Gate`'s named abilities that no policy defines).
 - `ROLE_PROVIDER` → a `RoleProvider` (feeds `gate.hasRole` / `@Roles`).
 
 When neither is registered, the Gate behaves exactly as before. **Grant-only** means a
@@ -32,11 +34,13 @@ provider returning `false`/nullish never DENIES — it falls through to normal r
 ## 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):
+registers both seams. Example with the Prisma adapter (which takes `store` or `client`;
+MikroORM takes `store`; the TypeORM and Drizzle siblings also accept `connectionName` /
+`storeOptions` to build the store from the official connection instead of a prebuilt `store`):
 
 ```ts
 import { Module } from '@nestjs/common';
+import { AuthorizationModule } from '@nestjs/authorization';
 import { AuthzModule } from '@dudousxd/nestjs-authz';
 import { AuthzRbacModule } from '@dudousxd/nestjs-authz-prisma';
 import { PrismaClient } from '@prisma/client';
@@ -45,7 +49,8 @@ const prisma = new PrismaClient();
 
 @Module({
   imports: [
-    AuthzModule.forRoot({ policies: [PostPolicy] }),
+    AuthorizationModule.forRoot(),
+    AuthzModule.forRoot(),
     AuthzRbacModule.forRoot({ client: prisma }), // builds the store, registers the seams
   ],
 })
@@ -62,6 +67,17 @@ await gate.forUser(user).allows('posts.publish'); // true via PERMISSION_PROVIDE
 await gate.forUser(user).hasRole('editor');        // true via ROLE_PROVIDER
 ```
 
+On routes, the same seams answer through the official guard as the core's official policies:
+
+```ts
+@Permission('posts.publish')                                 // = @Can(PermissionPolicy, 'has', permission('posts.publish'))
+@Roles('editor')                                             // = @Can(RolePolicy, 'has', roles('editor'))
+@Can(PermissionPolicy, 'hasAll', permission('posts.publish', 'posts.delete'))
+```
+
+Both extend `AuthzPolicy`, so `superAdmin` grants them; `gate.hasRole()` is a plain fact and
+ignores it.
+
 Admin-UI management lives on every adapter's store too (same semantics everywhere):
 `syncRolePermissions(role, names)` replaces a role's permission set, `getRolePermissions(roles)`
 returns `{ [role]: permissionNames }` (missing roles absent), `deleteRole(role)` removes the role
@@ -95,6 +111,16 @@ The core runs segment-based wildcard matching against `getPermissions`: a grante
 `posts.*` satisfies `posts.update`; `*` satisfies anything. `hasPermission` is the
 exact-match contract for providers that do not list grants.
 
+Within one request (nestjs-context) the Gate fetches `getPermissions` and
+`RoleProvider.getRoles` once per user and reuses them for every check (keyed by the
+row the user names — its class or `type` plus `id`, so ORMs without an identity map
+share entries; a plain object without `type` is keyed by identity, so two users that
+only share an `id` never share an entry); a grant made
+mid-request applies from the next request. When the set misses, the Gate still calls
+`hasPermission` (it may grant on the resource). Set `readonly exhaustivePermissions = true`
+when `getPermissions` already lists everything `hasPermission` can grant, so a miss is
+answered without another lookup; the ORM adapters' providers do.
+
 ### Zero-table role checks (no provider)
 
 `gate.hasRole` / `@Roles` work with **no** RBAC tables: the `defaultRoleResolver` reads
@@ -126,10 +152,11 @@ hasPermission(user: User, permission: string) {
 }
 ```
 
-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`).
+Mechanism: the provider only grants — `false`/`undefined` falls through to the ad-hoc gate and
+never denies. It is asked after the policy: a string ability a linked policy defines is the
+policy's to decide, whatever the user's permissions; only `superAdmin` (and a
+`DECISION_PROVIDER`) come first. Source: `packages/core/src/permission-provider.ts` (grant
+semantics), `packages/core/src/rbac.ts` (`grants`), `packages/core/src/gate.ts` (`decideString`).
 
 ### 2. Re-implementing wildcard matching in your adapter