@dudousxd/nestjs-authz 0.8.1 → 0.9.0

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
@@ -136,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
 

package/skills/authz-setup/SKILL.md

@@ -1,153 +1,92 @@
 ---
 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.
+  Set up @dudousxd/nestjs-authz 0.9, the extras on top of NestJS's first-party
+  @nestjs/authorization. Import AuthorizationModule.forRoot() (official: global
+  deny-by-default AuthorizationGuard, @Can, AuthorizationService, getUser) next to
+  AuthzModule.forRoot / forRootAsync (ours: Gate, RolePolicy / PermissionPolicy /
+  GatePolicy, the ResourceResolver byId() uses, superAdmin, the allow+deny decision event,
+  the opt-in POST /authz/can endpoint). Covers the optional peers: @nestjs/authentication
+  (AuthenticationContext.user is the ambient Gate user) and @dudousxd/nestjs-context
+  (fallback ambient user via resolveUser, per-request permission cache, tenant).
 metadata:
   type: core
   library: "@dudousxd/nestjs-authz"
-  library_version: "0.6.3"
+  library_version: "0.9.0"
   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.
+Authorization decisions belong to [`@nestjs/authorization`](https://docs.nestjs.com/security/authorization).
+This package adds RBAC, `@Can` helpers, a service-layer `Gate`, super-admin, query scopes and
+frontend glue. It never authenticates.
 
 ## Setup
 
 ```sh
-pnpm add @dudousxd/nestjs-authz
+pnpm add @nestjs/authorization @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):
+NestJS 12, Node 22+. Peers: `@nestjs/common`, `@nestjs/core`, `@nestjs/authorization`,
+`reflect-metadata`, `rxjs`; optional `@nestjs/authentication` and `@dudousxd/nestjs-context`.
 
 ```ts
-import { Module } from '@nestjs/common';
+import { AuthorizationModule } from '@nestjs/authorization';
 import { AuthzModule } from '@dudousxd/nestjs-authz';
-import { PostPolicy } from './post.policy';
 
 @Module({
   imports: [
+    AuthorizationModule.forRoot({ getUser: (ctx) => ctx.switchToHttp().getRequest().user }),
     AuthzModule.forRoot({
-      policies: [PostPolicy], // optional — @Policy classes are also auto-discovered
-      superAdmin: (user) => (user as { isAdmin?: boolean }).isAdmin === true,
+      superAdmin: (user) => user?.isRoot === true,
+      resourceResolver: new OrmResourceResolver(), // for byId(); default builds { id } from :id
     }),
   ],
+  providers: [PostPolicy], // official policies are discovered wherever they are providers
 })
 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.
+`forRootAsync({ imports, inject, useFactory | useClass | useExisting, canEndpoint, decorators, unannotated })` takes the
+same options. `canEndpoint`, `decorators` and `unannotated` are static (read from the top
+level next to `useFactory`, never from the factory's return — `decorators` and `unannotated` in the factory's return throw).
 
 ## 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.
+- The official module must stay global (its default): the `Gate` injects `AuthorizationService`.
+- `getUser` is the only user on routes. The `Gate`'s ambient user (calls without `forUser`) is
+  `@nestjs/authentication`'s `AuthenticationContext.user` when that package is installed and its
+  scope is active (its answer is final, so an anonymous call there is a guest), else nestjs-context's
+  `{ type, id }` ref, hydrated by `resolveUser` once per request.
+- Every route needs a declaration: the official guard denies a handler with no `@Can()`,
+  `@Can.Anyone()` or `@Public()`.
 
 ## Common mistakes
 
-### 1. Expecting `superAdmin: u => u.isAdmin` to work without `resolveUser`
+### 1. Importing only AuthzModule
 
 ```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,
-});
-```
+// Wrong — no AuthorizationService for the Gate, no guard on routes.
+imports: [AuthzModule.forRoot()]
 
-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`).
+// Correct
+imports: [AuthorizationModule.forRoot(), AuthzModule.forRoot()]
+```
 
-### 2. Importing AuthzModule in every feature module
+### 2. Passing policies to AuthzModule
 
 ```ts
-// Wrong — forRoot is global; re-importing creates duplicate providers/options.
-@Module({ imports: [AuthzModule.forRoot({ policies: [PostPolicy] })] })
-export class PostsModule {}
+// Wrong (0.x) — `policies` is gone from AuthzModuleOptions.
+AuthzModule.forRoot({ policies: [PostPolicy] })
 
-// Correct — register once in the root module; the Gate is exported globally.
-@Module({ imports: [AuthzModule.forRoot({ policies: [PostPolicy] })] })
-export class AppModule {}
+// Correct — register them as providers, or with the official module.
+AuthorizationModule.forRoot({ policies: [PostPolicy] })
 ```
 
-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
+### 3. Leaving routes undeclared after upgrading from 0.x
 
-```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 });
-```
+0.x let un-annotated routes through. The official guard denies them (401 for guests, 403
+otherwise). Add `@Can.Anyone()` to routes anyone may call.
 
-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`).
+Source: `packages/core/src/module.ts`, `packages/core/src/runtime.ts`.

package/dist/decorator/can.decorator.d.ts

@@ -1,29 +0,0 @@
-import 'reflect-metadata';
-import { type Type } from '@nestjs/common';
-export interface CanOptions {
-    /**
-     * Class-level ability (e.g. `create`): the policy method is keyed to the
-     * resource class but receives NO instance, so the guard skips resource loading.
-     */
-    classLevel?: boolean;
-}
-export interface CanMetadata {
-    ability: string;
-    /** Resource class — to load an instance, or (for class-level) to locate the policy. */
-    resource?: Type<unknown>;
-    /** When true, skip resource loading and dispatch against the resource class. */
-    classLevel?: boolean;
-}
-/**
- * Guard a route with an authorization check.
- *
- * @example
- *   `@Can('update', Post)`                    // resolve Post by :id, run PostPolicy.update(user, post)
- *   `@Can('create', Post, { classLevel: true })` // run PostPolicy.create(user) — no instance loaded
- *   `@Can('access-admin')`                    // ad-hoc gate, no resource
- *
- * When a resource class is provided (and not `classLevel`), the guard loads an
- * instance via the registered `ResourceResolver` (default: by route `:id`).
- */
-export declare function Can(ability: string, resource?: Type<unknown>, options?: CanOptions): MethodDecorator & ClassDecorator;
-//# sourceMappingURL=can.decorator.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"can.decorator.d.ts","sourceRoot":"","sources":["../../src/decorator/can.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGxD,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACzB,gFAAgF;IAChF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CACjB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,UAAU,GACnB,eAAe,GAAG,cAAc,CAKlC"}

package/dist/decorator/can.decorator.js

@@ -1,23 +0,0 @@
-import 'reflect-metadata';
-import { SetMetadata } from '@nestjs/common';
-import { CAN_METADATA } from '../tokens.js';
-/**
- * Guard a route with an authorization check.
- *
- * @example
- *   `@Can('update', Post)`                    // resolve Post by :id, run PostPolicy.update(user, post)
- *   `@Can('create', Post, { classLevel: true })` // run PostPolicy.create(user) — no instance loaded
- *   `@Can('access-admin')`                    // ad-hoc gate, no resource
- *
- * When a resource class is provided (and not `classLevel`), the guard loads an
- * instance via the registered `ResourceResolver` (default: by route `:id`).
- */
-export function Can(ability, resource, options) {
-    const meta = { ability };
-    if (resource !== undefined)
-        meta.resource = resource;
-    if (options?.classLevel)
-        meta.classLevel = true;
-    return SetMetadata(CAN_METADATA, meta);
-}
-//# sourceMappingURL=can.decorator.js.map

package/dist/decorator/can.decorator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"can.decorator.js","sourceRoot":"","sources":["../../src/decorator/can.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAa,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkB5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,GAAG,CACjB,OAAe,EACf,QAAwB,EACxB,OAAoB;IAEpB,MAAM,IAAI,GAAgB,EAAE,OAAO,EAAE,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACrD,IAAI,OAAO,EAAE,UAAU;QAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IAChD,OAAO,WAAW,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC"}

package/dist/decorator/policy.decorator.d.ts

@@ -1,18 +0,0 @@
-import 'reflect-metadata';
-import { type Type } from '@nestjs/common';
-/**
- * Marks a class as the policy for `resource`. The class methods become abilities
- * dispatched by name (e.g. `update(user, post)` answers `gate.authorize('update', post)`).
- *
- * Applying `@Policy` also makes the class an `@Injectable()` provider so it can
- * be auto-discovered and resolved from the Nest container.
- */
-export declare function Policy(resource: Type<unknown>): ClassDecorator;
-/**
- * Returns the resource class a policy was declared for, or `undefined`.
- *
- * Uses `getMetadata` (not `getOwnMetadata`) so a subclass of a `@Policy`-decorated
- * class still resolves the inherited resource via the prototype chain.
- */
-export declare function getPolicyResource(policy: Type<unknown> | object): Type<unknown> | undefined;
-//# sourceMappingURL=policy.decorator.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"policy.decorator.d.ts","sourceRoot":"","sources":["../../src/decorator/policy.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAIvD;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,cAAc,CAM9D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,SAAS,CAG3F"}