@dudousxd/nestjs-authz 0.8.1 → 0.9.0

package/dist/types.d.ts

@@ -1,219 +1,100 @@
 import type { Type } from '@nestjs/common';
 import type { UserRef } from './context-accessor.js';
 import type { ResourceResolver } from './resource-resolver.js';
-/**
- * A resource instance passed to policy methods. `unknown` because authz never
- * inspects the resource itself — the policy method does.
- */
+/** A resource passed to a policy ability. authz never inspects it; the policy does. */
 export type Resource = object;
 /**
- * The current user as seen by a policy/gate. authz does not model the user; it
- * is whatever the app's auth layer produced (or `undefined` when unauthenticated).
+ * The user a policy or gate sees: whatever authentication produced, `null` for a
+ * guest. authz does not model it.
  */
 export type User = unknown;
 /**
- * The richer result a policy method / ad-hoc gate may return instead of a bare
- * boolean: a verdict plus an optional human-readable `message` explaining a denial.
- * The message is surfaced on the thrown `ForbiddenException` (so a 403 is debuggable)
- * and published on the diagnostics decision. Returning a bare boolean is unchanged.
- *
- * Mirrors Laravel's `Response::allow()/deny('message')`.
+ * A verdict with an optional reason. What a {@link DecisionProvider} may answer instead of
+ * a bare boolean. Only `allowed` is used: `@nestjs/authorization` has no deny-with-reason, so a
+ * route denial is the official 403 and the `message` is dropped (README, "Migrating from 0.8").
  */
 export interface PolicyResponse {
     allowed: boolean;
     message?: string;
 }
-/**
- * What a policy method / gate / hook may return: a bare boolean (unchanged) or the
- * richer {@link PolicyResponse}. Hooks additionally allow `void`/`undefined` to mean
- * "no opinion — fall through".
- */
+/** A bare boolean or a {@link PolicyResponse}. */
 export type PolicyResult = boolean | PolicyResponse;
+/** An ad-hoc, model-less gate registered with `gate.define(name, fn)`. */
+export type GateFn = (user: User, resource?: Resource) => boolean | Promise<boolean>;
 /**
- * A policy method: decides a single ability for a `(user, resource?)` pair.
- * Class-level abilities (e.g. `create`) omit the resource. May be async. May return
- * a bare boolean (unchanged) or a richer {@link PolicyResponse} with a deny message.
+ * The global super-admin hook. `true` grants any check; anything else falls through.
+ * Policies honor it when they extend `AuthzPolicy` (or call `superAdminBefore` from
+ * their `before()`); `RolePolicy` and `PermissionPolicy` do. The `Gate`'s string
+ * abilities and `gate.scope()` ask it first.
  */
-export type PolicyMethod = (user: User, resource?: Resource) => PolicyResult | Promise<PolicyResult>;
-/**
- * Optional per-policy `before` hook. Runs before the ability method.
- * - return `true`  → allow (short-circuit)
- * - return `false` → deny (short-circuit)
- * - return `void`/`undefined` → fall through to the ability method
- */
-export type PolicyBeforeHook = (user: User, ability: string) => PolicyResult | undefined | Promise<PolicyResult | undefined>;
-/** A policy instance is an arbitrary object whose methods are abilities. */
-export type PolicyInstance = Record<string, unknown> & {
-    before?: PolicyBeforeHook;
-};
-/**
- * An ad-hoc gate: a model-less ability resolved by name via `gate.define`.
- * May return a bare boolean (unchanged) or a richer {@link PolicyResponse}.
- */
-export type GateFn = (user: User, resource?: Resource) => PolicyResult | Promise<PolicyResult>;
-/**
- * Global `after` hook. Mirrors Laravel's `Gate::after()`: runs AFTER policy/gate
- * resolution and may observe or override the decision.
- *
- * `result` is the verdict produced by the policy/gate (`true`/`false`), or
- * `undefined` when the policy/gate returned a nullish value (it had "no opinion").
- *
- * Override semantics (Laravel-idiomatic): the hook's return value REPLACES the
- * decision ONLY when the policy/gate produced no explicit verdict (`result` is
- * `undefined`). When the policy/gate DID decide (returned a boolean), `after` is
- * purely an observer and its return value is ignored — so it can never silently
- * overturn an explicit allow/deny. Returning `void`/`undefined` always leaves the
- * decision untouched. Like a policy, it may return a {@link PolicyResponse} to
- * attach a deny message.
- */
-export type AfterHook = (user: User, ability: string, result: boolean | undefined, resource?: Resource) => PolicyResult | undefined | Promise<PolicyResult | undefined>;
+export type SuperAdminHook = (user: User, ability: string, 
 /**
- * A resource loader: turns an `id` into the REAL entity instance for a resource
- * `type`. Used by the opt-in `POST /authz/can` endpoint to rehydrate the client's
- * `{ type, id }` shim before authorizing, so an instance-bound `@Policy` matches by
- * constructor. Returning nullish signals "not found" (the endpoint denies). May be async.
+ * What the check targets: the resource of a single check (the policy's first
+ * argument), or the entity class for `gate.scope(...)`. `undefined` for a model-less
+ * ability. Lets the hook scope the bypass (e.g. to one tenant's resources).
  */
+resource?: Resource) => boolean | null | undefined | Promise<boolean | null | undefined>;
+/** Loads the real entity for a client `{ type, id }` reference (the `POST /authz/can` endpoint). */
 export type ResourceLoader = (id: string | number) => unknown | Promise<unknown>;
-/**
- * Resource loaders keyed by the resource `type` name as emitted by the client/codegen
- * (e.g. `'Post'`). See {@link AuthzModuleOptions.resourceLoaders}.
- */
+/** Resource loaders keyed by the resource `type` name the client sends (e.g. `'Post'`). */
 export type ResourceLoaderMap = Record<string, ResourceLoader>;
 /**
- * Global super-admin before-hook. Runs before any policy/gate; truthy → allow.
- * `void`/`undefined`/`false` falls through to normal resolution.
+ * What happens to a route that declares no `@Can()` (nor `Can.Anyone()` / `@Public()`):
+ * - `'deny'` (default): nothing special; the official `AuthorizationGuard` denies it.
+ * - `'allow'`: the migration mode. `AuthzModule` registers its own global {@link AuthzGuard},
+ *   which enforces the official requirements exactly as the official guard does and lets
+ *   unannotated routes through. Needs `AuthorizationModule.forRoot({ globalGuard: false })`.
  */
-export type SuperAdminHook = (user: User, ability: string, 
-/**
- * The dispatch target: the resource instance/class of a single check, or the scoped entity
- * class for `gate.scope(...)`. `undefined` for a model-less ability.
- */
-resource?: Resource) => PolicyResult | undefined | Promise<PolicyResult | undefined>;
-export interface AuthzModuleOptions {
+export type UnannotatedRoutes = 'allow' | 'deny';
+/** Options that decide what the module registers, so they are static (read before any factory runs). */
+export interface AuthzModuleStaticOptions {
     /**
-     * Policy classes to register explicitly. Each must be decorated with
-     * `@Policy(Resource)`. Auto-discovery of `@Policy` providers also works, so
-     * this is optional.
+     * Opt-in `POST /authz/can` endpoint for client checks that are not hydrated. `true`
+     * mounts it at `authz/can`; a string at that path. Off by default.
      */
-    policies?: Array<Type<PolicyInstance>>;
+    canEndpoint?: boolean | string;
     /**
-     * Global super-admin before-hook applied to every authorization check. Return
-     * `true` to grant (e.g. super-admins). Returning `void`/`false` falls through.
-     *
-     * ⚠️ IMPORTANT — what `user` is: on the **context path** (no `forUser`), the
-     * `user` passed here is the raw {@link UserRef} from nestjs-context — just
-     * `{ type, id }`, NOT your hydrated user entity. So `superAdmin: u => u.isAdmin`
-     * will NOT fire from a route/`gate.allows(...)` unless you also configure
-     * {@link AuthzModuleOptions.resolveUser} to hydrate the full entity. On the
-     * explicit `gate.forUser(entity)` path you receive exactly what you passed.
+     * Class decorators applied to every controller this module mounts (the `POST /authz/can`
+     * endpoint), after its own: `[UseGuards(JwtAuthGuard), ApiTags('authz')]`. The controllers
+     * are open to the official guard by default (`Can.Anyone()`); a `@Can()` here restricts them.
      */
+    decorators?: ClassDecorator[];
+    /** See {@link UnannotatedRoutes}. Default `'deny'`. */
+    unannotated?: UnannotatedRoutes;
+}
+export interface AuthzModuleOptions extends AuthzModuleStaticOptions {
+    /** The global super-admin hook. See {@link SuperAdminHook}. */
     superAdmin?: SuperAdminHook;
     /**
-     * Global `after` hook (Laravel's `Gate::after()`). Runs AFTER policy/gate
-     * resolution and may observe or override the decision. It can only OVERRIDE the
-     * verdict when the policy/gate produced no explicit result (returned nullish);
-     * when the policy/gate decided explicitly, `after` is observe-only and its return
-     * value is ignored. Returning `void`/`undefined` always leaves the decision
-     * untouched. See {@link AfterHook}.
-     *
-     * Receives the same (possibly un-hydrated) `user` as {@link superAdmin} on the
-     * context path — apply {@link resolveUser} if you need the full entity.
-     */
-    after?: AfterHook;
-    /**
-     * Optional hook to hydrate the full user entity from the context's
-     * {@link UserRef} (`{ type, id }`) before policies / `before` / `superAdmin`
-     * run. WITHOUT this hook, the context path passes only `{ type, id }` to those
-     * functions (it does not load your `User` row), so property checks such as
-     * `superAdmin: u => u.isAdmin` or `post.authorId === user.id` against a real
-     * column will not see hydrated fields. Provide `resolveUser` to load the entity
-     * (e.g. from your ORM) keyed by the ref. Returning `undefined` is treated as
-     * "no user" (deny path), identical to an anonymous request. Within one request
-     * (nestjs-context store) the hook runs once per `type:id`; every later check
-     * reuses that result.
-     *
-     * Only affects the context path; `gate.forUser(entity)` always uses the value
-     * you pass directly and never invokes this hook.
+     * Hydrates the full user from nestjs-context's `{ type, id }` ref for `Gate` calls
+     * made without a user (`gate.allows(...)` rather than `gate.forUser(user)`), when
+     * `@nestjs/authentication`'s `AuthenticationContext` has no user to offer. Runs once
+     * per `type:id` per request (nestjs-context store). Routes never use it: the official
+     * guard reads the user with its own `getUser`.
      */
     resolveUser?: (ref: UserRef) => User | undefined | Promise<User | undefined>;
     /**
-     * Override the default {@link RoleResolver} used by coarse role-checks
-     * (`gate.hasRole('teacher')`, `@Roles('admin')`). The default reads `user.roles`
-     * (`string[]`) OR `user.role` (`string | string[]`) off the user object, so
-     * role-checks work with ZERO RBAC tables. Provide this to derive roles from a
-     * different shape. When the optional `ROLE_PROVIDER` seam is ALSO registered, the
-     * Gate unions both sources' roles.
-     *
-     * On the context path the resolver receives whatever the context produced (the
-     * raw {@link UserRef} unless `resolveUser` hydrated the entity); on the explicit
-     * `gate.forUser(entity)` path it receives exactly what you passed.
+     * Derives roles from the user object. Default: `user.roles` (`string[]`) or
+     * `user.role` (`string | string[]`). Unioned with the RBAC adapter's role store.
      */
     resolveRoles?: (user: User) => string[] | undefined | Promise<string[] | undefined>;
-    /**
-     * Override the default {@link ResourceResolver} used to load an instance for
-     * `@Can(ability, Resource)` routes. Defaults to {@link IdParamResourceResolver}
-     * (reads the route `:id` param), registered automatically by `forRoot`. Apps
-     * needing real ORM entities provide their own here (or bind the
-     * `RESOURCE_RESOLVER` token directly).
-     */
+    /** Loads the resource for `byId(Resource)`. Default: {@link IdParamResourceResolver}. */
     resourceResolver?: ResourceResolver;
-    /**
-     * Route param name the default {@link IdParamResourceResolver} reads to build
-     * the resource shim. Defaults to `'id'`. Ignored when {@link resourceResolver}
-     * is supplied.
-     */
+    /** Route param the default resolver reads. Default `'id'`. */
     idParam?: string;
-    /**
-     * Opt-in `POST /authz/can` fallback endpoint. **Off by default.** When enabled,
-     * registers a controller that runs `gate.allows(ability, resource?)` for the
-     * current (context) user and returns `{ allowed: boolean }`. This is the
-     * last-resort path the codegen-emitted `can()` helper targets.
-     *
-     * - `true` → mount at the default path `authz/can`.
-     * - `string` → mount at that path (e.g. `'api/authz/can'`).
-     * - `false`/omitted → no endpoint is registered.
-     *
-     * Prefer the no-request paths (shared Inertia props, per-resource `can` maps)
-     * — this endpoint exists only for abilities not already hydrated on the client.
-     */
-    canEndpoint?: boolean | string;
-    /**
-     * Resource loaders keyed by the resource `type` name the client/codegen emits
-     * (e.g. `'Post'`). They close the per-instance gap in the {@link canEndpoint}
-     * fallback: when the endpoint receives `{ ability, resource: { type, id } }` and a
-     * loader is registered for `type`, it `await`s `loader(id)` and authorizes the REAL
-     * entity — so an instance-bound `@Policy` matches by constructor and its method runs
-     * with the loaded resource. A loader returning nullish is treated as "not found"
-     * (the endpoint denies). Types WITHOUT a loader keep the prior behavior (class-level
-     * / ad-hoc only; a resource-bound ability still denies). Opt-in: unset → unchanged.
-     *
-     * ```ts
-     * resourceLoaders: { Post: (id) => postRepo.findOneBy({ id: Number(id) }) }
-     * ```
-     */
+    /** Loaders that turn the endpoint's `{ type, id }` into the real entity, keyed by type. */
     resourceLoaders?: ResourceLoaderMap;
 }
 export interface AuthzModuleOptionsFactory {
     createAuthzOptions(): Promise<AuthzModuleOptions> | AuthzModuleOptions;
 }
-export interface AuthzModuleAsyncOptions {
+export interface AuthzModuleAsyncOptions extends AuthzModuleStaticOptions {
     imports?: unknown[];
     useExisting?: Type<AuthzModuleOptionsFactory>;
     useClass?: Type<AuthzModuleOptionsFactory>;
     useFactory?: (...args: unknown[]) => Promise<AuthzModuleOptions> | AuthzModuleOptions;
     inject?: unknown[];
-    /**
-     * Opt-in `POST /authz/can` fallback endpoint (see {@link AuthzModuleOptions.canEndpoint}).
-     * Declared statically here because controllers are registered at module-definition
-     * time, before the async options factory resolves. Off by default.
-     */
-    canEndpoint?: boolean | string;
-    /**
-     * Resource loaders for the {@link canEndpoint} fallback
-     * (see {@link AuthzModuleOptions.resourceLoaders}). May also be returned from the
-     * async options factory; either way the endpoint reads them from the resolved
-     * options, so this declaration is for the rarer case of supplying them statically.
-     */
+    /** See {@link AuthzModuleOptions.resourceLoaders}. */
     resourceLoaders?: ResourceLoaderMap;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dudousxd/nestjs-authz",
-  "version": "0.8.1",
-  "description": "NestJS authorization — Laravel-style Gates & Policies, @Can guard, resource resolver (zero DB).",
+  "version": "0.9.0",
+  "description": "Extras on top of @nestjs/authorization: persisted RBAC policies, @Can helpers (byId, roles, permission), a Gate with batch checks and ad-hoc gates, super-admin, query scoping.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,7 +21,8 @@
     "acl",
     "rbac",
     "tanstack-intent",
-    "cerbos"
+    "cerbos",
+    "nestjs-authorization"
   ],
   "author": "Davi Carvalho <davi@goflip.ai>",
   "type": "module",
@@ -55,24 +56,32 @@
   },
   "peerDependencies": {
     "@dudousxd/nestjs-context": ">=0.1.0",
-    "@nestjs/common": ">=10.0.0",
-    "@nestjs/core": ">=10.0.0",
-    "reflect-metadata": ">=0.1.13"
+    "@nestjs/authentication": "^0.1.5",
+    "@nestjs/authorization": "^0.1.3",
+    "@nestjs/common": "^12.0.0",
+    "@nestjs/core": "^12.0.0",
+    "reflect-metadata": ">=0.1.13",
+    "rxjs": "^7.1.0"
   },
   "peerDependenciesMeta": {
     "@dudousxd/nestjs-context": {
       "optional": true
+    },
+    "@nestjs/authentication": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@cerbos/http": "0.29.0",
+    "@nestjs/authentication": "0.1.5",
+    "@nestjs/authorization": "0.1.3",
     "@nestjs/common": "12.0.1",
     "@nestjs/core": "12.0.1",
     "@nestjs/platform-express": "12.0.1",
     "@nestjs/testing": "12.0.1",
     "@tanstack/intent": "0.4.0",
     "@types/express": "4.17.25",
-    "@types/node": "20.19.43",
+    "@types/node": "22.20.5",
     "@types/supertest": "6.0.3",
     "express": "4.22.2",
     "reflect-metadata": "0.2.2",
@@ -82,12 +91,12 @@
     "vitest": "3.2.7"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --incremental false",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"
   }
 }

package/skills/authz-enforcement/SKILL.md

@@ -1,171 +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). Inside a nestjs-context request, plain
-`allows`/`authorize`/`hasRole` calls also share one `resolveUser`, one permission fetch and
-one role fetch per user for the whole request (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):
+@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`.