nestjs-boost 0.0.0-stage → 1.2.0

package/skills/nestjs-architecture/references/scopes-lifecycle.md

@@ -0,0 +1,98 @@
+# Injection scopes, lifecycle hooks, ModuleRef and lazy loading
+
+Sources: [Injection scopes](https://docs.nestjs.com/fundamentals/injection-scopes) · [Lifecycle events](https://docs.nestjs.com/fundamentals/lifecycle-events) · [Module reference](https://docs.nestjs.com/fundamentals/module-ref) · [Lazy-loading modules](https://docs.nestjs.com/fundamentals/lazy-loading-modules) · [Discovery service](https://docs.nestjs.com/fundamentals/discovery-service)
+
+## Contents
+- Choosing a scope
+- How REQUEST scope spreads
+- Accessing the request; INQUIRER
+- Durable providers (multi-tenant)
+- Lifecycle hooks and shutdown
+- ModuleRef, lazy loading, discovery
+
+## Choosing a scope
+
+| Scope | Instance | Use when |
+| --- | --- | --- |
+| `DEFAULT` (singleton) | One per app, created at bootstrap | Almost always. Recommended by the docs. |
+| `REQUEST` | One per request, garbage-collected after | The provider itself must hold per-request state |
+| `TRANSIENT` | One per consumer | Stateful helpers each consumer needs its own copy of (e.g. a logger with context) |
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class TenantService {}
+
+{ provide: 'CACHE_MANAGER', useClass: CacheManager, scope: Scope.TRANSIENT }   // long-hand form
+@Controller({ path: 'cats', scope: Scope.REQUEST })                             // controller scope
+```
+
+**Prefer singletons plus `AsyncLocalStorage`** when a provider only needs to *read* per-request values (current user, tenant, locale). Every provider stays a singleton, and it works in HTTP, microservices and gateways (see the nestjs-logging skill).
+
+## How REQUEST scope spreads
+
+- REQUEST scope **bubbles up**: anything that injects a request-scoped provider becomes request-scoped, including the controller. Making a widely used provider (DB connection, logger) request-scoped makes most of the app request-scoped.
+- TRANSIENT does **not** bubble up: a singleton injecting a transient provider stays a singleton.
+- Request-scoped providers cost a new instance tree per request. The docs expect ≤ ~5% latency in a well-designed app.
+- Must stay singletons: Passport strategies, cron jobs.
+- Since v12, WebSocket gateways support request-scoped providers, scoped to the socket connection.
+
+## Accessing the request; INQUIRER
+
+```typescript
+import { REQUEST, INQUIRER } from '@nestjs/core';
+
+@Injectable({ scope: Scope.REQUEST })
+export class CatsService {
+  constructor(@Inject(REQUEST) private readonly request: Request) {}   // GraphQL: @Inject(CONTEXT) from @nestjs/graphql
+}
+
+@Injectable({ scope: Scope.TRANSIENT })
+export class ScopedLogger {
+  constructor(@Inject(INQUIRER) private readonly parent: object) {}   // the class that injected this provider
+}
+```
+
+Injecting `REQUEST` makes the provider request-scoped automatically.
+
+## Durable providers (multi-tenant)
+
+With a few tenants, avoid rebuilding the tree per request: register a `ContextIdStrategy` that maps requests to one DI sub-tree per tenant, and mark providers `durable: true`. Durability bubbles up like request scope. Not suitable for very many tenants. See the docs section "Durable providers" for the strategy code.
+
+## Lifecycle hooks and shutdown
+
+| Hook | When |
+| --- | --- |
+| `onModuleInit()` | Host module's dependencies resolved |
+| `onApplicationBootstrap()` | All modules initialized, before listening |
+| `onModuleDestroy()` | Termination started (signal or `app.close()`) |
+| `beforeApplicationShutdown(signal?)` | After all `onModuleDestroy()` complete |
+| `onApplicationShutdown(signal?)` | After connections close; last step of `app.close()` |
+
+- `onModuleInit`/`onApplicationBootstrap` may be `async`; bootstrap waits for them.
+- Init hooks run module by module: the most deeply imported modules (and global modules) first, the root module last. In v12, hooks are ordered by component hierarchy level, so don't depend on the order between siblings.
+- Shutdown hooks need `app.enableShutdownHooks()` in `main.ts` to react to `SIGTERM`/`SIGINT`. They are off by default because the listeners use memory; avoid enabling them in many parallel test apps. On Windows, `SIGTERM` never fires.
+- Hooks are **not** called for request-scoped classes or in lazy-loaded modules.
+
+## ModuleRef, lazy loading, discovery
+
+```typescript
+constructor(private readonly moduleRef: ModuleRef) {}
+
+this.moduleRef.get(Service);                          // singleton, current module
+this.moduleRef.get(Service, { strict: false });       // look in the whole app
+await this.moduleRef.resolve(ScopedService);          // transient/request-scoped: new instance per call
+const id = ContextIdFactory.create();
+await this.moduleRef.resolve(ScopedService, id);      // same instance for the same contextId
+await this.moduleRef.create(SomeClass);               // instantiate a class not registered as provider
+```
+
+Lazy loading (no lifecycle hooks run in the loaded module):
+
+```typescript
+constructor(private readonly lazyModuleLoader: LazyModuleLoader) {}
+const { ReportsModule } = await import('./reports/reports.module.js');
+const moduleRef = await this.lazyModuleLoader.load(() => ReportsModule);
+const reports = moduleRef.get(ReportsService);
+```
+
+`DiscoveryService` (from `@nestjs/core`) lists providers and controllers at runtime, e.g. to find every provider carrying a custom decorator's metadata. See the docs chapter for its API.

package/skills/nestjs-architecture/references/troubleshooting.md

@@ -0,0 +1,77 @@
+# Troubleshooting DI and module errors
+
+Sources: [Common errors](https://docs.nestjs.com/faq/common-errors) · [Circular dependency](https://docs.nestjs.com/fundamentals/circular-dependency) · [SWC](https://docs.nestjs.com/recipes/swc)
+
+## Contents
+- Procedure for any startup DI error
+- "Cannot resolve dependency" with a token name
+- "... at index [n] is available in the current module" (no token name)
+- Circular dependency between providers or modules
+- Monorepo: ModuleRef cannot be resolved
+- "File change detected" loops endlessly (Windows)
+
+## Procedure for any startup DI error
+
+1. Read the error: which **provider** is being built, which **token** at which **index** is missing, and in which **module** Nest looked.
+2. Open that module. For the missing token, it must be either in the module's `providers`, or exported by a module listed in its `imports`.
+3. If the token belongs to another feature module: add it to that module's `exports` and import that module. Do not copy the provider into the failing module's `providers`.
+4. If it still fails, run once with `NEST_DEBUG=1` to see each resolution step and the module searched.
+5. Rebuild and **start the app** to confirm. Compilation alone doesn't prove the fix.
+
+## "Cannot resolve dependency" with a token name
+
+```
+Nest can't resolve dependencies of the OrdersService (?). Please make sure that the argument UsersService at index [0] is available in the OrdersModule module.
+```
+
+Causes, most common first:
+- The provider isn't exported by its module, or that module isn't imported. Fix: `exports: [UsersService]` in `UsersModule`, and `imports: [UsersModule]` in `OrdersModule`.
+- An `@Injectable()` class was put in `imports` instead of `providers`. Nest reports this explicitly; move it.
+- The same provider is listed in both a feature module and the root module, so Nest instantiates it twice, the second time without its dependencies. Keep it in one module and export it.
+- Self-injection: the missing token equals the provider being built.
+
+## "... at index [n] is available in the current module" (no token name)
+
+The dependency is `undefined` or `Object` at runtime. Causes:
+1. **Circular file import**: two files import each other (e.g. a module file declares a token and imports a provider that imports the token back). Move shared constants to their own file.
+2. **Injection by interface or type alias**: use a class, an abstract class, or `@Inject(TOKEN)`.
+3. **`import type { X }`** for an injectable class: use a value import.
+
+## Circular dependency between providers or modules
+
+```
+Nest cannot create the <module> instance.
+The module at index [<n>] of the <module> "imports" array is undefined.
+```
+
+First try to break the cycle: extract the shared logic into a third provider or module that both depend on. If the cycle is genuine:
+
+```typescript
+// Providers: forwardRef on BOTH sides
+@Injectable()
+export class CatsService {
+  constructor(@Inject(forwardRef(() => CommonService)) private readonly common: WrapperType<CommonService>) {}
+}
+@Injectable()
+export class CommonService {
+  constructor(@Inject(forwardRef(() => CatsService)) private readonly cats: WrapperType<CatsService>) {}
+}
+
+// Modules: forwardRef on BOTH sides
+@Module({ imports: [forwardRef(() => CatsModule)] })
+export class CommonModule {}
+```
+
+- `WrapperType<T> = T` (define it once, e.g. `src/common/wrapper-type.ts`) stops the type being stored in decorator metadata. It is required with SWC and ESM, where emitted types otherwise trigger circular-import errors. ORMs provide an equivalent, e.g. TypeORM's `Relation<T>`.
+- Instantiation order is indeterminate: constructors must not call into the other side.
+- Request-scoped providers in a cycle can end up `undefined`.
+- Alternatively, inject `ModuleRef` and get the other provider lazily at call time.
+- Barrel files (`index.ts`) importing modules and providers are a frequent hidden cause.
+
+## Monorepo: ModuleRef cannot be resolved
+
+`... the argument ModuleRef at index [n] is available ...` usually means two copies of `@nestjs/core` are installed (e.g. one nested under a workspace package). For pnpm, declare `@nestjs/core` as a peer dependency of the internal package and use `dependenciesMeta.<pkg>.injected: true`. For Yarn workspaces, use `nohoist`.
+
+## "File change detected" loops endlessly (Windows)
+
+Add to `tsconfig.json`: `"watchOptions": { "watchFile": "fixedPollingInterval" }`.

package/skills/nestjs-authentication/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: nestjs-authentication
+description: Adds sign-in to NestJS 12 with the first-party @nestjs/authentication package — global AuthenticationGuard with @Public(), credential providers (SessionCookieProvider, JwtBearerProvider, ApiKeyProvider) registered on AuthenticationRegistry, scrypt PasswordHasher, SignInService sessions in __Host- cookies, TokenService access and rotating refresh tokens, @CurrentUser/@Authenticate/AuthenticationContext, email verification, password reset, TOTP two-factor, magic links, OpenID Connect (Google, GitHub, Microsoft), session management, API keys, database stores and the production guard. Use when building sign-up/sign-in, sessions or JWTs, protecting routes, reading the current user, adding 2FA, social login, passwordless login or API keys, in a project that has or can add @nestjs/authentication. Not for role/permission checks (nestjs-authorization), the Passport recipe (nestjs-passport-auth) or CSRF/rate-limit setup in general (nestjs-security-hardening).
+compatibility: NestJS 12.x (12.1+ for enableCsrfProtection); @nestjs/authentication; optional @nestjs/throttler, @nestjs/mail, @nestjs/drizzle or TypeORM for stores
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS authentication (@nestjs/authentication)
+
+Detect first: if the project already uses `@nestjs/passport`, keep it and use nestjs-passport-auth unless the user asks to migrate. For new auth, prefer `@nestjs/authentication`: it ships sessions, hashing, tokens, 2FA, OIDC and API keys built on Node built-ins. Don't hand-roll bcrypt + `@nestjs/jwt` guards.
+
+```bash
+npm i @nestjs/authentication
+```
+
+## Core setup
+
+```typescript
+// auth/session-auth.provider.ts — a credential provider: request → user or null
+@Injectable()
+export class SessionAuth extends SessionCookieProvider<User> {
+  constructor(private readonly users: UsersRepository, registry: AuthenticationRegistry) {
+    super();
+    registry.registerProvider(this);             // order 0; JwtAuth { order: 1 }, ApiKeyAuth { order: 2 }
+  }
+  validate(session: SessionRecord) { return this.users.findById(session.userId); }   // null ends the session
+}
+
+// app.module.ts — options are plain values; classes register themselves
+AuthenticationModule.forRoot({ session: { absoluteTtl: '14d', idleTtl: '3d' } }),
+```
+
+- The module registers a **global guard: every route needs a user** (401 `missing_credentials`). Mark open routes/controllers with `@Public()` (health checks, sign-in, catalog).
+- Lifetimes are ms or strings (`'15m'`, `'14d'`). Unlike `@nestjs/jwt`, numbers are **milliseconds**: `3600` is 3.6 s.
+- Your user store stays yours: providers and handlers call your repository. Never return password hashes from it.
+- Type the user once: `declare module '@nestjs/authentication' { interface AuthenticationTypes { user: User } }`.
+
+## Sign-up and sign-in (password → session cookie)
+
+```typescript
+// credentials.service.ts
+async verify(email: string, password: string) {
+  const found = await this.users.findCredentials(email);
+  const valid = await this.passwordHasher.verify(password, found?.passwordHash);   // dummy hash when unknown: no timing leak
+  if (!valid || !found?.passwordHash) return null;
+  if (this.passwordHasher.needsRehash(found.passwordHash))
+    await this.users.updatePasswordHash(found.user.id, await this.passwordHasher.hash(password));
+  return found.user;
+}
+
+// auth.controller.ts
+@Public() @Controller('auth')
+export class AuthController {
+  @Post('sign-in') @HttpCode(200)
+  async signIn(@Body() body: SignInDto) {
+    const user = await this.credentials.verify(body.email, body.password);
+    if (!user) throw new UnauthorizedException('Invalid email or password');
+    const { session } = await this.signInService.signIn(user.id, { method: 'password' });
+    return { mfaRequired: session.mfa === 'pending' };
+  }
+}
+```
+
+`signIn()` sets the `__Host-sid` cookie (HttpOnly, Secure, SameSite=Lax; hash stored), replaces the previous session (fixation defence) and rejects cross-origin posts (login CSRF). `http://localhost` accepts Secure cookies in development.
+
+## Reading the user and route options
+
+- `@CurrentUser()` / `@CurrentUser('id')`, `@CurrentSession()` in handlers; `AuthenticationContext.requireUser()` in services (AsyncLocalStorage-backed singleton).
+- `@Authenticate({ optional: true })` lets guests through with `null`; `{ verifiedEmail: true }` → 403 `email_unverified`; `{ mfa: true }` requires a verified second factor; `{ providers: [ApiKeyAuth] }` restricts providers.
+- `globalGuard: false` makes routes open until `@UseGuards(AuthenticationGuard)`.
+
+## Bearer tokens for mobile/API clients
+
+`accessToken: { key: JWT_SECRET (≥32 bytes, or an ES256/RS256/EdDSA private key), issuer, audience, ttl: '15m' }`, a `JwtBearerProvider` subclass whose `validate({ sub })` loads the user, and `TokenService.issue(user.id, { method: 'password', claims: { amr: ['pwd'] } })` / `refresh(refreshToken)` behind `@Public()` routes. Refresh tokens rotate and reuse revokes the family. `refreshToken: false` issues access tokens only (declare `refreshTokens: false` in `AuthenticationTypes` too).
+
+## More flows
+
+Each needs its options **and** a registered handler of the same name (`registry.registerHandler('emailVerification', this)`), or startup fails:
+- email verification and password reset (`EmailVerificationHandler`, `PasswordResetHandler` + `@nestjs/mail`)
+- TOTP 2FA (`MfaService`, `SignInService.confirmMfa/completeMfa`, `mfa.encryption.keys`)
+- OIDC (`OidcAccountResolver`, `OidcService.start/finish`, `google()`/`github()`/`microsoft()`)
+- magic links (`MagicLinkHandler`, `MagicLinkService`)
+- sessions list/sign-out everywhere (`SessionService`, `signOut()`, `signOutEverywhere()`)
+- API keys (`ApiKeyProvider` with `findKey(id)`)
+
+Read `references/flows.md` for each.
+
+## Production rules
+
+- Register a database store implementing the six contracts (`sessions`, `refreshTokens`, `mfa`, `magicLinks`, `oidcStates`, `emailTokens`) via `AuthenticationStorage.registerSource()`. With `NODE_ENV=production` the module refuses in-memory storage for configured features.
+- HTTPS; list other web origins in `session.trustedOrigins`; call `app.enableCsrfProtection()` (12.1+) with the same origins.
+- Rate-limit sign-in with `@nestjs/throttler` using a per-IP and a per-email+IP definition (shared Redis storage in clusters).
+- Rotate on privilege change (`SignInService.rotateSession()`); after password/2FA changes revoke other sessions and tokens.
+- Import `AuthenticationModule` **before** `AuthorizationModule`.
+- Never use `LogMailTransport` in production: it logs sign-in links.
+- Reset/verify pages must POST the token (mail scanners follow GET links).
+- scrypt uses 128 MiB per hash on the libuv pool: size servers and in tests use `new PasswordHasher({ logN: 10 })`.
+
+## Workflow
+
+- [ ] 1. Install; define the `User` type and repository; add `SessionAuth` (and `JwtAuth`/`ApiKeyAuth` if needed).
+- [ ] 2. Register `AuthenticationModule.forRoot[Async]()` with config from `ConfigService`; add `@Public()` to routes that must stay open.
+- [ ] 3. Add sign-up/sign-in controllers with validated DTOs or schemas; add each extra flow with its handler.
+- [ ] 4. Add the database store and migrations; throttler; `enableCsrfProtection()`.
+- [ ] 5. E2E tests: real `AppModule`, PGlite for the DB, `InMemoryMailTransport`, cheap `PasswordHasher`; assert cookies, 401s, `mfa_required`. Existing e2e tests now need credentials or `@Public()`.
+- [ ] 6. Build, lint, run unit and e2e tests, start the app.
+
+## Reference files
+
+- `references/flows.md`: email verification, password reset, 2FA, OIDC, magic link, session management, API keys, GraphQL/WebSocket use, store contract, testing, module options, events and errors. Read when adding any flow beyond password sign-in or writing the store.
+
+Sources: [Authentication](https://docs.nestjs.com/security/authentication)

package/skills/nestjs-authentication/references/flows.md

@@ -0,0 +1,180 @@
+# @nestjs/authentication flows and reference
+
+## Contents
+- Handler pattern
+- Email verification
+- Password reset
+- Two-factor authentication (TOTP)
+- OpenID Connect (Google, GitHub, Microsoft)
+- Magic links
+- Session management
+- API keys
+- GraphQL and WebSockets
+- Database store contract
+- Testing
+- Module options
+- Events and errors
+
+## Handler pattern
+
+Features with side effects (sending mail, finding accounts) need a handler registered under the feature's name. Handlers are your `@Injectable()` classes:
+
+```typescript
+@Injectable()
+export class EmailVerificationMailer extends EmailVerificationHandler {
+  constructor(private readonly users: UsersRepository, private readonly mailer: Mailer, registry: AuthenticationRegistry) {
+    super();
+    registry.registerHandler('emailVerification', this);
+  }
+  async send(link: EmailVerificationLink) { await this.mailer.send(VerifyEmailMail, { to: link.email, data: link }); }
+  markVerified(userId: string, email: string) { return this.users.markEmailVerified(userId, email); }   // conditional: only if email unchanged
+}
+```
+
+Names: `emailVerification`, `passwordReset`, `magicLink`, `oidc`. Option without handler (or vice versa) fails startup. Mail through `@nestjs/mail` (nestjs-mail).
+
+## Email verification
+
+- Options: `emailVerification: { url: `${APP_URL}/verify-email`, ttl? ('24h') }`.
+- `EmailVerificationService.send(user)` after sign-up (or a resend route); `verify(token)` from a POST route the page calls.
+- `markVerified()` must update only while the stored email still matches (`UPDATE … WHERE id = $1 AND email = $2`).
+- `@Authenticate({ verifiedEmail: true })` gates routes on it.
+
+## Password reset
+
+- Options: `passwordReset: { url: `${APP_URL}/reset-password`, ttl? ('1h') }`.
+- Handler (`PasswordResetHandler`): `findUser(email)` → `{ id, email (stored), passwordHash } | null`, `send(link)`, `updatePassword(userId, passwordHash)`.
+- `forgot` route: call `passwordResetService.request(email)` **without awaiting** and answer 202 every time (no account enumeration).
+- `reset` route: `passwordResetService.reset(token, password, { signIn: true })` → `null` for invalid links; result has `signedIn?.session.mfa`.
+- A reset revokes the user's sessions and refresh tokens. Links stop working after any password or email change.
+
+## Two-factor authentication (TOTP)
+
+```typescript
+mfa: { issuer: 'example.com', encryption: { keys: [process.env.TOTP_ENCRYPTION_KEY!] } },   // ≥32 random chars; newest key first
+```
+
+- Enroll: `mfaService.enroll(user.id, user.email)` (QR/otpauth data); `{ replace: true }` to swap authenticators (else `MfaAlreadyEnrolledError` 409).
+- Confirm: `signInService.confirmMfa(userId, code)`, then show `mfaService.generateRecoveryCodes(userId)` once.
+- Sign-in with an enrolled user creates a **pending** session: protected routes answer 401 `mfa_required`. A `@Public()` `verify` route calls `signInService.completeMfa({ code, recoveryCode })`, which rotates to `mfa: 'verified'`. Pending sessions expire after `mfa.pendingTtl` (10m).
+- Disable: verify a code with `mfaService.verifyTotp(userId, code)`, `mfaService.disable(userId)`, then `sessionService.revokeAll(userId, { except: current.id })` and `tokenService.revokeAll(userId)`.
+- Tokens: `tokenService.issue()` answers `mfa_required` for enrolled users until a code is given; put `amr` claims in tokens so `@Authenticate({ mfa: true })` works for bearer clients.
+- Every app sharing the user database must configure `mfa`, or users bypass it via another app.
+- Lockout: `maxAttempts` (5) per `lockoutWindow` (15m).
+
+## OpenID Connect (Google, GitHub, Microsoft)
+
+```typescript
+oidc: {
+  callbackUrl: `${process.env.APP_URL}/auth/oidc/:provider/callback`,
+  providers: { google: google({ clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET! }) },
+},
+
+@Public() @Controller('auth/oidc')
+export class OidcController {
+  @Get(':provider/login') @Redirect()
+  login(@Param('provider') p: string, @Query('redirectTo') redirectTo?: string, @Query('link') link?: string) {
+    return this.oidcService.start(p, { redirectTo, link: link === 'true' });
+  }
+  @Get(':provider/callback') @Redirect()
+  callback(@Param('provider') p: string, @Query() query: Record<string, string>) { return this.oidcService.finish(p, query); }
+}
+```
+
+Resolver (`OidcAccountResolver`, registered as `'oidc'`): `resolveUser(profile, tokens, { linkTo })`.
+- With `linkTo` (a "Connect Google" link flow): link to that user unless the identity belongs to someone else.
+- Known identity → its user.
+- New identity: only trust `profile.email` if `profile.emailVerified`; link to an existing account only if **that account's** email is verified (prevents pre-hijacking); otherwise return `null` (403) or throw `ForbiddenException`.
+- `redirectTo` must be relative; `microsoft()` takes a `tenant`. Errors: 400 forged callback, 502 provider unreachable.
+
+## Magic links
+
+- Options: `magicLink: { url: `${APP_URL}/sign-in/magic`, ttl? ('15m'), bindToBrowser? (true) }`.
+- Handler (`MagicLinkHandler`): `send(link)`, `resolveUser(email)` (create the account on first use; refuse unverified password accounts with 403).
+- `magicLinkService.create(email, { redirectTo })` → always answer 202. `consume(token)` → `null` or `{ session, redirectTo }`.
+- A link works only in the browser that requested it (`__Host-magic_link_tx`); otherwise 401 `not_this_browser`.
+
+## Session management
+
+- `session.metadata: (req) => ({ userAgent: req.headers['user-agent'] })` stores data with each session.
+- `sessionService.list(userId)`, `sessionService.revoke(id, { userId })`, `signInService.signOut()`, `signInService.signOutEverywhere(userId)`, `tokenService.revoke(refreshToken)`.
+
+## API keys
+
+```typescript
+@Injectable()
+export class ApiKeyAuth extends ApiKeyProvider<User> {
+  constructor(@InjectDrizzle() private readonly db: NodePgDatabase, private readonly users: UsersRepository, registry: AuthenticationRegistry) {
+    super({ prefix: 'cat', realm: 'store' });          // keys: cat_<16-hex id>_<secret>
+    registry.registerProvider(this, { order: 2 });
+  }
+  async findKey(id: string) {
+    const [key] = await this.db.select().from(apiKeys).where(eq(apiKeys.id, id));
+    const user = key && (await this.users.findById(key.userId));
+    return user ? { hash: key.hash, user, expiresAt: key.expiresAt } : null;
+  }
+}
+```
+
+- Your table stores `id`, `userId`, `hash` (SHA-256), `createdAt`, `expiresAt`. `generate()` returns `{ key, id, hash }`: show `key` once.
+- Keys never satisfy `@Authenticate({ mfa: true })`; requests with keys emit no events (log `keyId` from `@CurrentSession()`).
+- Password reset / sign-out everywhere leave keys alone; revoke them yourself if needed. Add the prefix to secret scanning.
+
+## GraphQL and WebSockets
+
+- GraphQL: `context: ({ req, res, extra }) => ({ req: req ?? extra?.request, res })` (must be a function), `fieldResolverEnhancers: ['guards', 'interceptors']` if field resolvers need it.
+- Gateways: no guards on `handleConnection()`; call `wsAuthenticator.authenticateConnection(client, request)` (closes with 1008; pass `{ required: false }` as third arg to allow guests).
+
+## Database store contract
+
+One `@Injectable()` class (or several) calling `storage.registerSource({ sessions: this, refreshTokens: this, mfa: this, magicLinks: this, oidcStates: this, emailTokens: this })` with `AuthenticationStorage` injected. Contracts used by configured features are mandatory in production.
+
+Atomicity rules (one conditional statement, never read-then-write):
+- `touchSession()`: conditional UPDATE moving `lastActiveAt` forward only.
+- `deleteSession()`: DELETE resolving whether a row was deleted.
+- `markRefreshTokenUsed()`: `UPDATE … WHERE used_at IS NULL`, count rows.
+- `saveTotp()`: upsert keeping the larger `lastUsedStep` (`GREATEST`, raw SQL on Prisma).
+- `claimTotpStep()`, `consumeRecoveryCode()`: conditional UPDATE/DELETE.
+- `recordMfaFailure()`: insert, then count, each committed separately.
+- `saveRecoveryCodes()`: one transaction (delete + insert).
+- `consumeMagicLink()`, `consumeOidcState()`, `consumeEmailToken()`: `DELETE … RETURNING`.
+
+`getSession()` may return the user in `extra` (one query per request). Test with `authenticationStoreContract()` from `@nestjs/authentication/testing`, `{ concurrent: true }`, against PostgreSQL with a pool.
+
+## Testing
+
+```typescript
+const moduleRef = await Test.createTestingModule({ imports: [AppModule] })
+  .overrideProvider(getDrizzleToken()).useValue(drizzle({ client: new PGlite() }))
+  .overrideProvider(MailTransport).useValue(mailbox)                       // InMemoryMailTransport
+  .overrideProvider(PasswordHasher).useValue(new PasswordHasher({ logN: 10 }))
+  .compile();
+```
+
+Read the session cookie from `res.headers['set-cookie'][0].split(';')[0]`; read links with `mailbox.assertSent({ to, mail: VerifyEmailMail }).link('/verify-email').searchParams.get('token')`. Set test env vars (JWT secret ≥32 bytes, TOTP key) in the test runner config.
+
+## Module options
+
+`forRootAsync()` factory returns everything except `isGlobal` and `globalGuard`. Lifetimes up to 100 years; every clocked group takes `now` for tests.
+
+| Option | Default |
+| --- | --- |
+| `globalGuard` / `isGlobal` / `allowInMemoryStorage` | `true` / `true` / `false` |
+| `session.cookieName` | `__Host-sid` (`sid` without the prefix rules) |
+| `session.absoluteTtl` / `idleTtl` / `touchInterval` | `'7d'` / `'1d'` / `'1m'` (shorter than `idleTtl`) |
+| `session.cookie` | `secure: true, sameSite: 'lax', path: '/'`, always HttpOnly |
+| `session.trustedOrigins`, `session.metadata` | none |
+| `password.logN` (`r`, `p`, `keyLength`, `saltLength`) | 17 (8, 1, 32, 16) |
+| `accessToken.key` / `alg` / `issuer` / `audience` / `ttl` / `kid` / `type` | required / from key / – / – / `'15m'` / – / `JWT` |
+| `refreshToken` (`ttl`, `absoluteTtl`) / `false` | on (`'30d'`, `'90d'`) |
+| `mfa.encryption` / `issuer` / `window` / `maxAttempts` / `lockoutWindow` / `recoveryCodes` / `pendingTtl` | required / – / 1 / 5 / `'15m'` / 10 / `'10m'` |
+| `emailVerification.url` / `passwordReset.url` / `magicLink.url` | required when enabled |
+| `oidc.callbackUrl`, `providers`, `redirectAfterLogin` (`/`), `transactionTtl` (`'10m'`), `discoveryTtl` (`'1h'`), `clockTolerance` (`'30s'`) | |
+
+A value outside its range (including `NaN` from an unset env var) fails startup.
+
+## Events and errors
+
+`AuthenticationEvents.events$` and diagnostics channels `nestjs:authentication:<type>`: `sign-in`, `sign-out`, `mfa-verified`, `mfa-failed` (`locked`), `mfa-enabled`, `mfa-disabled`, `recovery-codes-generated`, `refresh-token-reused`, `password-reset-requested`, `password-reset`, `email-verified`, `magic-link-refused`, `session-touch-failed`. Keep them as an audit trail and alert on locked MFA failures and touch failures.
+
+Errors: `AuthenticationError` (base; `status`, `code` → `errorCode`, `details`, `challenge`), `JwtError` 401, `RefreshTokenError` 401 (`reason`), `MagicLinkError` 401 `not_this_browser`, `MfaAlreadyEnrolledError` 409. Guard codes: `missing_credentials` 401, `mfa_required` 401, `email_unverified` 403. Errors are converted for GraphQL (`UNAUTHENTICATED`), WebSockets (`WsException`) and microservices (`RpcException`).

package/skills/nestjs-authorization/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: nestjs-authorization
+description: Adds permissions to NestJS 12 with the first-party @nestjs/authorization package — @Policy() classes whose type-checked ability methods decide what a user may do, a deny-by-default global AuthorizationGuard with @Can(Policy, 'ability', argsFn) and @Can.Anyone(), record-level checks in services with AuthorizationService.authorize()/can(), before() admin bypass, policies that inject services, 401 vs 403 mapping, permission flags for the frontend, denial events, and testing policies. Use when the user asks for roles, permissions, ownership checks ("users can only see their own orders"), admin overrides, RBAC/ABAC, or when a route returns 403 unexpectedly after adding @nestjs/authorization. Not for signing users in (nestjs-authentication, nestjs-passport-auth).
+compatibility: NestJS 12.x; @nestjs/authorization; works with @nestjs/authentication or any guard that sets request.user
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS authorization (@nestjs/authorization)
+
+Prefer policies from `@nestjs/authorization` over hand-written `RolesGuard` + `@Roles()` metadata when the package is installed or the project uses `@nestjs/authentication`. For a tiny role check in a project without it, the guard + `Reflector` pattern in nestjs-request-pipeline is fine.
+
+```bash
+npm i @nestjs/authorization
+```
+
+## Register (after authentication)
+
+```typescript
+@Module({
+  imports: [
+    AuthenticationModule.forRootAsync({ ... }),   // FIRST: its guard sets request.user
+    AuthorizationModule.forRoot(),                 // global, deny-by-default guard
+    ProductsModule,
+  ],
+})
+export class AppModule {}
+```
+
+- Global guards run in module scan order. With `@nestjs/authentication` the wrong order fails at startup; with other auth guards (Passport `AuthGuard`) it only logs an error and **every user looks like a guest** — register those with `APP_GUARD` before the module and cover it with an e2e test.
+- **Deny by default:** a handler with no `@Can()`, `@Can.Anyone()` or `@Public()` gets 403 (user) / 401 (guest). The startup log lists every such handler: start migrations from that list.
+- Custom user source: `AuthorizationModule.forRoot({ getUser: (ctx) => ... })`.
+
+## Write a policy
+
+```typescript
+@Policy()
+export class OrderPolicy implements PolicyBefore<User> {
+  constructor(private readonly limits: RefundLimitsService) {}            // policies are providers
+
+  before(user: User | null, ability: string) {                            // true allow, false deny, undefined → ability decides
+    if (user?.roles.includes('admin') && ability !== 'refund') return true;
+  }
+  viewAll(user: User) { return user.roles.includes('staff'); }
+  view(user: User, order: Order) { return order.userId === user.id || user.roles.includes('staff'); }
+  viewOrdersOf(user: User | null, customerId: string) { return !!user && (user.id === customerId || user.roles.includes('staff')); }
+  async refund(user: User, order: Order) {
+    return user.roles.includes('staff') && order.status === 'paid' && order.total <= (await this.limits.maxRefundFor(user));
+  }
+}
+```
+
+- An ability's first parameter is the user; `User | null` means it also runs for guests. Only a literal `true` allows.
+- Register the policy as a provider of its feature module (discovered automatically), or in `forRoot({ policies, imports })`.
+- Keep policies stateless (singletons).
+- `before()` skips every ability of the policy — don't use it where a rule must bind admins too (e.g. "never refund shipped orders"); check the ability name.
+
+## Where each check goes
+
+| Check depends on | Put it | How |
+| --- | --- | --- |
+| Only the user (create product, admin page) | Route | `@Can(ProductPolicy, 'create')` |
+| A route param, no record load | Route | `@Can(OrderPolicy, 'viewOrdersOf', (ctx) => [ctx.switchToHttp().getRequest().params.customerId] as const)` |
+| A loaded record | Service, after loading | `await this.authz.authorize(OrderPolicy, 'view', user, order)` + `@Can.Anyone()` on the route |
+| A list | Query | `can(OrderPolicy, 'viewAll', user)` then filter in the DB, never per row |
+| A UI flag | Response | `canRefund: await this.authz.can(OrderPolicy, 'refund', user, order)` (never throws) |
+
+- `@Can()` is type-checked: misspelled abilities, missing args or wrong arg types don't compile. Route abilities must accept `null`.
+- The args function runs in the guard **before pipes**: values are raw strings and unvalidated. Pass ids, not records.
+- Other transports: `GqlExecutionContext.create(ctx).getArgs()`, `ctx.switchToWs().getData()`, `ctx.switchToRpc().getData()`.
+- Guests on public routes: combine `@Authenticate({ optional: true })` with `@Can.Anyone()` and pass `@CurrentUser() user: User | null` to the service.
+
+## 401 vs 403
+
+- Guest on a route requiring sign-in → 401 from authentication. Guest denied by a policy on an optional route → 401. Signed-in user denied → 403.
+- `authorize()` throws `AuthorizationError` (`reason: 'unauthenticated' | 'forbidden'`, `status`, `policy`, `ability`), mapped to HTTP/GraphQL/WS/RPC errors when it leaves a handler. Thrown in your own guard or middleware it becomes a **500**: use `can()` there.
+
+## Gotchas
+
+- Hybrid apps: `connectMicroservice(opts, { inheritAppConfig: true })` or `@Can()` isn't enforced on message handlers.
+- GraphQL field resolvers aren't guarded unless `fieldResolverEnhancers: ['guards']`; then each `@ResolveField()` needs a declaration (class-level covers it).
+- Don't put `CacheInterceptor` (URL cache) on routes with record checks; it answers before the policy.
+- Race: re-check state in the write (`UPDATE … WHERE status = 'paid'`).
+- Choose 404 over 403 where record existence is sensitive.
+- Each `can()` flag runs the ability per row, async work included; cache slow lookups.
+
+## Testing
+
+- Unit-test policies as plain classes: `new OrderPolicy(fakeLimits).view(alice, order)`. Direct calls skip `before()`.
+- Service tests: `Test.createTestingModule({ imports: [AuthorizationModule.forRoot()], providers: [OrdersService, OrderPolicy, RefundLimitsService] })` and expect `rejects.toThrow(AuthorizationError)` / `toMatchObject({ reason: 'forbidden', ability: 'refund' })`.
+- E2E: sign in through the real endpoint (cheap `PasswordHasher({ logN: 11 })`), assert 401/403/200. Replace a policy with `.overrideProvider(OrderPolicy).useValue(...)`.
+
+## Workflow
+
+- [ ] 1. Install; import `AuthorizationModule` after the authentication module.
+- [ ] 2. Write one policy per resource; register it in the feature module.
+- [ ] 3. Add `@Can()` to user-only routes, `@Can.Anyone()` + `authorize()` in services for record checks; fix every handler in the startup "denied" log.
+- [ ] 4. Subscribe to `AuthorizationEvents.events$` (`denied`: policy, ability, reason, user id) for auditing.
+- [ ] 5. Add policy unit tests and e2e 401/403 tests.
+- [ ] 6. Build, lint, run unit and e2e tests, start the app.
+
+Sources: [Authorization](https://docs.nestjs.com/security/authorization)