@lenne.tech/nest-server 11.43.3 → 12.1.0

package/.claude/rules/architecture.md

@@ -52,6 +52,11 @@ config is present, and keep their previous single-process behaviour when it is n
 `@Optional()` and always keep the non-configured fallback path — that is the pattern every core
 consumer follows. See `.claude/rules/configurable-features.md` for the full option reference.
 
+**MongoDB itself is optional since 12.1.0** — the same pattern one level down: `mongoose`, `@nestjs/mongoose` and
+`mongodb` are optional peers, reached only through `common/persistence/mongo/` (never a static value import in
+`src/core/`), and `CoreModule` connects MongoDB only when a data source uses it. `pnpm run check:without-mongodb`
+proves the build loads and runs with them unresolvable. Rules: `.claude/rules/persistence.md`.
+
 ## Core Modules (`src/core/modules/`)
 
 | Module | Purpose |
@@ -62,7 +67,7 @@ consumer follows. See `.claude/rules/configurable-features.md` for the full opti
 | **ErrorCode** | Centralized error codes with unique identifiers |
 | **File** | File upload/download with GridFS storage |
 | **HealthCheck** | Application health monitoring |
-| **Hub** | Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 16 panels, runtime collectors, mailbox, admin actions) |
+| **Hub** | Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 17 panels, runtime collectors, mailbox, admin actions) |
 | **Migrate** | Database migration utilities |
 | **Permissions** | ADMIN-gated security-map report (routes + roles + `@Restricted` fields); also surfaced in the Hub's "Routes / Permissions" panel |
 | **SystemSetup** | Initial admin creation for fresh deployments |
@@ -76,6 +81,88 @@ consumer follows. See `.claude/rules/configurable-features.md` for the full opti
 - `CheckResponseInterceptor` - Filters restricted fields
 - `CheckSecurityInterceptor` - Processes `securityCheck()` methods
 
+## Module Format: an ESM package whose source is valid as CommonJS AND ESM (12.0.0+)
+
+All NestJS 12 packages are ESM-only, and so is this one since 12.0.0: `package.json` declares `"type": "module"`,
+`dist/` is one ESM build. A CommonJS project loads it through Node's `require(esm)` (Node 20.19+ / 22.12+;
+`engines.node` is `>= 22.15`) exactly as it loads every `@nestjs/*` package — verified against the unchanged
+nest-server-starter (type check, all tests, build, `migrate:list`, production start). `tsconfig.json` uses `module` /
+`moduleResolution: nodenext`, so `tsc` resolves exactly like Node, `exports` maps included, plus `isolatedModules`
+(NestJS 12's default; SWC compiles one file at a time anyway).
+
+**`require()` of the package must keep working, so the package must never contain top-level `await`** —
+`require(esm)` refuses a graph with it (`ERR_REQUIRE_ASYNC_MODULE`), and every CommonJS project would stop loading.
+
+**Two contracts stay CommonJS, through a directory-level `package.json` with `"type": "commonjs"`:**
+`src/core/modules/migrate/helpers/` (the TypeScript loader `ts-compiler.js`, whose path and function export every
+project's `--compiler ts:…` and `node -r …` name) and `bin/` (`bin/migrate.js`, the `migrate` binary). Both
+`package.json` files reach `dist/` and vendor projects like any other file, so the contracts hold in CommonJS and ESM
+projects alike.
+
+**No CommonJS module may sit inside the core's ES module graph and load other core modules.** Found the hard way:
+with `migration.helper.ts` compiled as CommonJS in `helpers/` and imported by the barrel, `require('@lenne.tech/nest-server')`
+returned the helper's exports instead of the barrel's — Node mixed up the module objects while a CommonJS module
+required ES modules of the graph it was being loaded for. The helper therefore lives in `migrate/migration.helper.ts`
+(ESM like the rest); `helpers/migration.helper.ts` is a CommonJS forwarder for the path existing
+`migrations-utils/migrate.js` files require, and nothing in the core imports it.
+
+**Enforced in three places, because vitest sees none of it** (it imports sources through its own module runner):
+`tests/unit/module-format-invariants.spec.ts` refuses a runtime import from a CommonJS directory into the graph and any
+top-level `await` (mutation `barrel-imports-cjs-forwarder`); `tests/unit/package-format-contracts.spec.ts` loads
+`bin/migrate.js`, the loader and the forwarder in place, in a child process, and checks that every CommonJS `.js` file
+sits in a CommonJS scope and that nest-cli copies the nested manifests into `dist/` (mutations
+`bin-manifest-type-module`, `nest-cli-assets-drop-json`, `migration-helper-forwarder-emptied`); and
+`pnpm run check:manifest` (after the build in `check`) does the same against the PACKED package, plus `require()` vs
+`import()` of `dist/index.js` in two fresh processes — the export lists must match.
+
+The **source** of `src/core/` must additionally be valid as **ESM**, because a vendor-mode project may be an ESM
+project (`"type": "module"`, what `nest new` generates since NestJS 12) and then compiles and runs the vendored core as
+ESM. Rules for code in `src/core/`, `src/index.ts`, `src/core.module.ts` and `src/test/`:
+
+| Rule | Why |
+|------|-----|
+| Relative specifiers name the emitted file: `./x.js`, `./dir/index.js` — never `./x` or `./dir` | ESM resolves no extension and no directory. `tsc` under `nodenext` keeps the specifier as written; the SWC loader and vitest map `.js` to `.ts` in a source run |
+| No `require()`, `__dirname` / `__filename`, `import x = require()`, `export =` (CommonJS only) and no `import.meta` (ESM only). Use static imports, `createRequire(join(process.cwd(), 'package.json'))` to load a PROJECT file, `callerDirectory()` (`common/helpers/module-location.helper.ts`) for "the directory of this file" | each of them fails in the other module system — inside a function only when it runs. Enforced by `tests/unit/module-format-invariants.spec.ts` (mutation `core-uses-dirname`), because `check:esm` sees only what fails while a module LOADS |
+| A CommonJS package without `__esModule` is a DEFAULT import (`import _ from 'lodash'`), one WITH it (graphql) a named or namespace import. Never a named import Node cannot see (`import { cloneDeep } from 'lodash'`, mongoose's `Connection` as a value) | ESM gets a CommonJS module's names from `cjs-module-lexer`, which misses lodash's and mongoose's. Under CommonJS the same line works, so only `pnpm run check:esm` notices |
+| `import type` for types — also in decorated signatures; `export type` for re-exported types | `isolatedModules` (TS1272 / TS1205): a value import of a type links under CommonJS and fails under ESM |
+| A cycle that forces laziness is broken with an import-free leaf, never with a lazy `require()` | `core-better-auth.registry.ts` → `isBetterAuthHandlerClass()` is how the tenant guard recognises the IAM handlers |
+| No deep imports into `@nestjs/*` packages whose `exports` map lists only the root (`jwt`, `mongoose`, `passport`, `schedule`, `swagger`, `terminus`) | `ERR_PACKAGE_PATH_NOT_EXPORTED` at runtime, `TS2307` at compile time. `@nestjs/common`, `core`, `platform-express` and `graphql` export `./*`, so their subpaths still resolve |
+| No relative dynamic `import()` at all | under `nodenext` a dynamic `import()` in CommonJS output stays a NATIVE `import()` and follows ESM resolution, while a source run in a CommonJS project turns it into `require()`. vitest accepts both, so only `tests/unit/module-format-invariants.spec.ts` sees it — the 12.0.0 migration runner shipped `await import('./helpers/migration.helper.js')` with every suite green |
+| A dual package (separate CJS and ESM builds — `@aws-sdk/*`, `@modelcontextprotocol/sdk`, `@getbrevo/brevo`, `bullmq`) is either lazy everywhere or static everywhere | a native `import()` loads the ESM build, a static import the CJS build — two module instances, and an `instanceof` across them fails. Take its types from the import EXPRESSION (`const load = () => import('x'); type X = Awaited<ReturnType<typeof load>>`), never from an `import type`: TypeScript types an `import()` the way it is emitted (ESM under `nodenext`, CJS under `module: commonjs`), while any fixed `import type` matches only one of the two (TS2322 in the other). And keep such a derived CLASS type out of public/protected signatures — under `module: commonjs` with declarations it cannot be named (TS2883); give the extension point a structural interface instead (`IBrevoSdkClient`) |
+| Write code that compiles under BOTH `nodenext` and `module: commonjs` | vendor consumers compile `src/core/` with their own tsconfig. Under TypeScript 6, `module: commonjs` without `moduleResolution` resolves as `bundler` and keeps the `require()` emit for `import()`. Enforced by `pnpm run typecheck:vendor` (`scripts/check-vendor-declarations.mjs` + `tsconfig.vendor-commonjs.json`, part of `check`): it compiles under `module: commonjs`, emits the declarations and fails on `typeof import("<package>")` or `import("<pkg>/…/dist/…")` in them — references that resolve in this repo's HOISTED `node_modules` and break in a consumer's isolated pnpm layout (TS2883). The nodenext build alone passed three 12.0.0 errors that only a vendor project saw |
+
+**`pnpm run check:esm`** (`scripts/check-esm-core.mjs`, part of `check`) is the proof of the ESM half: it copies what a
+vendor project receives into a temporary `"type": "module"` package, compiles it with `nodenext` and imports EVERY
+module plus the barrel in one process. It catches what no other step can — a named import Node cannot see, a type
+imported as a value, a missing extension — and reports each distinct cause once.
+
+**The TypeScript loader is three files.** `helpers/ts-compiler.cjs` is the implementation, `ts-compiler-hooks.mjs` the
+ESM hooks it registers through `module.register()` (resolve `.js` → `.ts`, compile ESM-scoped `.ts` with SWC — import
+attributes kept — and hand CommonJS-scoped files back), and `ts-compiler.js` the established entry path, a one-line
+CommonJS shim that `helpers/package.json` keeps CommonJS in every project. The SWC build (`check:swc-tdz`) does not
+emit `.cjs` / `.mjs` sources; its guard places them like `tsc` does. That guard also pins the SWC build to CommonJS
+(`tsconfig.swc-tdz.json`), because it checks what a CommonJS project runs under `nest start -b swc`; `@nestjs/cli` would
+otherwise emit ES modules for this `"type": "module"` package.
+
+**The build `target` stays `es2022`**, although NestJS 12's template uses `ES2023`: a vendor project compiles the core
+with its own lib, and the starter's is es2022 — see `tests/unit/toolchain-contract.spec.ts`. ES2023 changes no emitted
+syntax on Node 22, only which APIs the type-checker allows.
+
+**Type-aware lint.** `pnpm run lint` runs `oxlint --type-aware` (needs `oxlint-tsgolint`) with
+`typescript/no-floating-promises` as an error, as NestJS 12's template does: an un-awaited promise's rejection is
+unhandled, and Node ends the process on that by default. Mark a deliberate fire-and-forget with `void` and say why it
+cannot reject. The other type-aware rules the categories would turn on are switched off in `.oxlintrc.json`, each
+with the reason; `tests/unit/lint-type-aware.spec.ts` pins the flag, the backend and the rule, because without either
+half oxlint skips the rule silently.
+
+The SWC build (`nest start -b swc`, `check:swc-tdz`), the SWC source loader and vitest transform `import()`
+themselves; none of them is affected by the tsconfig's `module` setting. `tsconfig.tests.json` uses
+`module: preserve` + `moduleResolution: bundler` because that is how vitest resolves the specs. **Both vitest configs
+set `resolve.extensions` in Node's order** (`.js` before `.mjs`): graphql declares an extensionless `main` next to an
+`index.mjs`, Vite probes `.mjs` first, and an `import` of graphql then loaded a second, ESM copy — every subscription
+closed with 4500 ("Cannot use GraphQLSchema from another module or realm"). Pinned by
+`tests/unit/vitest-node-resolution.spec.ts`. Background: `migration-guides/11.43.x-to-12.0.x.md` §2–§3 and §17.
+
 ## DI Token Placement (SWC-Safe)
 
 **Rule: DI tokens belong in an import-free leaf file (`*.constants.ts` / `*.enums.ts`) — never in `*.module.ts` or `*.service.ts`.**

package/.claude/rules/better-auth.md

@@ -504,6 +504,51 @@ this protection must set `betterAuth.options.advanced.disableOriginCheck: false`
 removed. `tests/better-auth-signin-csrf.e2e-spec.ts` does; mutations `iam-signin-csrf-check-skipped` /
 `iam-signup-csrf-check-skipped`.
 
+## 11. Better-Auth on a SQL source — it follows the users table (db-agnostic phase 3)
+
+Better-Auth keeps its data where the user model lives. `DataSourceRuntime.iamStorage()` finds the persisted model whose
+table is `users`; when that model is routed to a SQL source, `CoreBetterAuthModule.createInstance()` hands Better-Auth
+the application role's `pg` pool of that source, and Better-Auth runs its own Kysely adapter on it (it recognises a pool
+by its `connect` method — the core imports no Kysely). On MongoDB nothing changes.
+
+| Piece | Where | Rule |
+|---|---|---|
+| Naming | `withSqlStorage()` in `better-auth-sql.helper.ts` | `user` → `users`, every table and field snake_case — the plugins' too, on copies, never the plugin objects; ids are ObjectId hex (`generateId`), so a Better-Auth user id IS the framework's id and `iamId` equals it |
+| One row per user | the same helper + `registerForeignColumns('users', …)` | Better-Auth's own columns (`name`, `email_verified`, `image`) live in the framework's `users` table; its required ones are added nullable first, so a row the user model writes alone stays valid, and the framework's schema planner does not report them as undeclared |
+| Schema | `applyBetterAuthSchema()` | Better-Auth validates its schema when the instance is created, so its migrations run BEFORE, as the owner, under the framework's schema lock, followed by the grants and the safe-role check. Without an owner connection the boot stops while anything is pending — the application role never runs DDL |
+| Framework access | `BetterAuthSqlStore` (`core-better-auth-sql.store.ts`), reached through the import-free leaf `core-better-auth-sql.registry.ts` | framework fields of the user row go through the user model's `DataStore` (its policies apply); Better-Auth's own fields and tables go through Better-Auth's `internalAdapter` / `adapter` (its hooks run — a deleted session reaches `wsSessionRevocationPlugin()`). Every MongoDB path keeps its code; the SQL branch sits beside it (`*OnSql` in the user mapper) |
+| Passkey challenges | `storeChallenge()` | Better-Auth verification values with the identifier prefix `lt-passkey-challenge:` — no table of the framework's own, expiry checked on read, expired ones removed as new ones arrive |
+| Expired rows | `BetterAuthSqlStore.deleteExpired()`, scheduled by `CoreBetterAuthService.startExpirySweep()` | Better-Auth never deletes an expired session and clears expired verification values only when one is looked up; on MongoDB the verification TTL index does it. On SQL the expiry sweep (`scheduleExpirySweep()`, every 15 min, one replica per interval) removes both — through Better-Auth's adapter, so its naming applies. Stopped in `onModuleDestroy()`, before the data sources close (mutation `iam-expired-sessions-kept`) |
+| Per-request path | token service, middlewares, guard, web and cookie helpers | ids are strings; only `BetterAuthMongoUsers` (`core-better-auth-mongo.users.ts`) knows what an ObjectId is. Pinned by `tests/unit/iam-request-path-ids.spec.ts` |
+| Boot steps | `CoreBetterAuthService.onModuleInit()` | `ensureIndices()` and the account-issuer backfill concern MongoDB's collections and are skipped on SQL |
+| Counting | `BetterAuthSqlStore.migrationCounts()` | counts in SQL (`count(*)`, `EXISTS` over `account`), names from `$context.tables`. **Never read a whole table through Better-Auth's `adapter.findMany()`**: without a `limit` it stops at 100 rows (`defaultFindManyLimit`), which capped the migration status at 100 migrated users (mutation `iam-migration-status-capped-at-a-page`) |
+| Readers outside the module | `CoreAiMcpOAuthService.loadUser()` | every native read of `users` needs the SQL branch too — an OAuth subject's roles came from MongoDB, i.e. nobody or a stale copy (mutation `mcp-oauth-user-on-mongo`). Find candidates with `grep -rn "collection('users')" src/core` |
+
+**Sign-up holds a pool connection while it hashes (accepted).** Better-Auth runs its Kysely adapter with transactions
+on a `pg` pool, and `/sign-up/email` hashes the password inside its transaction — on the framework's application pool
+(10 connections). A burst of concurrent sign-ups therefore makes other queries wait (measured: ~0.16 s at 20, ~1.3 s
+at 100). Kept on purpose: it is Better-Auth's standard behaviour on PostgreSQL, it makes user and account creation
+atomic, and switching it off would need a Kysely instance the core cannot rely on (`kysely` is an optional peer).
+`betterAuth.rateLimit` bounds it.
+
+**Not on SQL, and why that is no gap:** the account-issuer backfill (§8) repairs account documents better-auth 1.6
+wrote to MongoDB before the field existed. On a SQL source every account row is written with what the installed line
+expects — by Better-Auth itself, and by the framework's own writes through the issuer helper (`migrateAccountToIamOnSql()`,
+the system setup) — so there is nothing to backfill. Nothing is copied from MongoDB when a project routes its users to
+SQL.
+
+**The challenge cookie is named by Better-Auth.** The API middleware reads the passkey challenge token from the cookie
+Better-Auth sets and asks the instance for its name (`createAuthCookie(<key>).name`, `iam.better-auth-passkey` by
+default) — a hard-coded `better-auth.` prefix missed it after the cookie prefix began to follow the base path, so no
+mapping was stored and no `challengeId` returned, on every database (mutation `passkey-challenge-cookie-unprefixed`).
+`passkey.webAuthnChallengeCookie` is the KEY; it reaches the plugin as `advanced.webAuthnChallengeCookie`, the only
+place the plugin reads it.
+
+Tests: every IAM suite runs on MongoDB and on PostgreSQL with each engine (`.claude/rules/testing.md` → the IAM
+projects); `tests/better-auth-storage-paths.e2e-spec.ts` covers the four paths the stories pass either way (session
+token as bearer, token service, passkey challenge, e-mail verified), `tests/persistence-sql-wiring.e2e-spec.ts` the
+boot (one row, ownership, a second boot, the system setup).
+
 ## Summary
 
 | Principle | Requirement |
@@ -518,3 +563,4 @@ removed. `tests/better-auth-signin-csrf.e2e-spec.ts` does; mutations `iam-signin
 | `account` reads / writes | Reads filter on `providerId` alone, never `issuer`. Writes set `issuer` only on better-auth 1.7.0–1.7.2, via the helper (§8) |
 | `openAPI()` plugin | Registered internally for `setupSwagger()`, kept off the router (`SERVER_ONLY`) unless the project registered it — never by a path check (§9) |
 | Direct `api.*` calls | Hand Better-Auth the request (CSRF headers only) + `asResponse: false`, or its login-CSRF check is skipped (§10) |
+| SQL source | Better-Auth follows the users table; the framework reaches its data through `BetterAuthSqlStore`, ids stay strings (§11) |

package/.claude/rules/configurable-features.md

@@ -321,7 +321,8 @@ This pattern is currently applied to:
 | Translate Response Interceptor | `security.translateResponseInterceptor` | Boolean Shorthand | `true` (enabled) |
 | Mongoose CastError Filter | `security.mongooseCastErrorFilter` | Explicit Boolean — **safe default** | **`true` since 11.42.16.** `MongooseCastErrorFilter`, registered by `CoreModule` as `APP_FILTER` (so `main.ts` and `Test.createTestingModule()` setups need nothing). A malformed id reached Mongoose and its `CastError` — not an `HttpException` — escaped every `@Catch(HttpException)` filter, so `GET /users/<malformed-id>` and every other `:id` route answered **500**. The filter decides by WHERE the failing value came from: a route parameter or a top-level GraphQL argument → **404** `ErrorCode.RESOURCE_NOT_FOUND` (answered like an unknown id); the query string, an update or filter body, or a nested GraphQL input → **400** `ErrorCode.INVALID_FIELD_FORMAT [<path>]`; a value the request does not contain (a broken stored id, a server-computed value) → **stays a 500**, with Nest's own body and log line (context `ExceptionsHandler`), because that is a data or code defect monitoring must keep seeing — relabelling it as a client error is the mistake the refusal tests pin (mutations `cast-error-server-value-relabelled-*`). Only primitives and arrays of primitives (`$in`) are matched: an object cast as a whole yields no candidates, so its inner strings cannot match the body by coincidence. Never sends the Mongoose message (it names the model). REST bodies use the `HttpExceptionLogFilter` shape (`{ ...exception }`). A project's own catch-all filter via `app.useGlobalFilters()` is consulted first and wins. Covers casts Mongoose raises while running a QUERY or an UPDATE (`findById`, filters, `findByIdAndUpdate` — `CrudService.update()`). NOT covered, both stay a 500: a malformed id in a document being CREATED (`save()` / `create()` / `insertMany()` — `CrudService.create()`), which Mongoose reports as a `ValidationError` wrapping the CastError (validate in the input: `validator: () => [IsMongoId()]`); and a `BSONError` from `new Types.ObjectId(bad)`, which carries no value (check the id in the service, `CoreFileService.isMalformedFileId()`). `false` restores the 500. Implementation: `common/filters/mongoose-cast-error.filter.ts` |
 | Secret Fields Removal | `security.secretFields` | Array | `['password', 'verificationToken', ...]` |
-| Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | **`excludeSchemas` is an OFF SWITCH for isolation, per model** — a listed schema gets no tenant filter at all; since 11.35.0 the plugin WARNS once per model when the excluded schema declares `tenantId` (i.e. was built for isolation). The framework's own docs recommended `['User', 'Session']` until then; that is withdrawn — it is only right for the global-user model. Since 11.35.0 GraphQL operations over the WEBSOCKET also run inside a `RequestContext` (`CoreModule` installs a context-aware `execute`/`subscribe` pair inside `subscriptions`, where `ApolloDriver` forwards it): the tenant comes from the handshake header validated against an active membership, else from the subscriber's memberships, and an unresolvable tenant leaves the safety net to refuse the read rather than returning everything. `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `invalidateUser(userId)` / `invalidateAll()` are **instance** methods on the singleton `CoreTenantGuard` — inject it and call `this.tenantGuard?.invalidateUser(userId)`, never `CoreTenantGuard.invalidateUser(...)` (there is no static). With `redis` configured, both additionally BROADCAST the invalidation to every replica (`<keyPrefix>:tenant-cache:invalidate` pub/sub); without Redis they clear the local process only, so other replicas stay stale until `cacheTtlMs`. A received broadcast clears locally without re-publishing. **`isTenantActive` (11.42.0)**: optional hook `(tenantId, { connection }) => boolean \| Promise<boolean>`, absent = every tenant active (no change). Asked AFTER the membership check on every path that establishes a tenant: 403 on header paths and for tenant API tokens, no enrichment on `S_EVERYONE`, dropped from the header-less tenant list, no tenant for a NEW WebSocket subscription, and since 11.42.3 an OPEN one is closed with 4403 on `invalidateTenant()` (or at its next event once `graphQl.subscriptionRevalidationMs` has passed — see the GraphQL Subscription Re-check row); an admin under `adminBypass` is exempt (someone must be able to switch it back on). Only `false` deactivates. Cached for `cacheTtlMs`; `invalidateTenant(tenantId)` clears and broadcasts (`{ scope: 'tenant' }`). A function, so `config.env.ts` only — not reachable through `NSC__*`. **`adminBypass: false` (11.42.0)** additionally withholds two things that went around it: `CoreUserService.update()` refuses changing another account's e-mail or password (`assertCredentialChangeAllowed()`, administrator targets included — promote-then-change — system work without a current user exempt), and the AI tool registry grants no ADMIN bypass |
+| Data Sources | `database` | Explicit Value — absent = today's `mongoose` config | **Absent → the `mongoose` configuration is the only data source, exactly as before; nothing SQL is loaded or installed.** A URL string (`'postgres://…'`) sets the default source (driver from the scheme, `sqlEngine` defaults to `typeorm`; `kysely` and `drizzle` are the alternatives — optional peers, each with `pg`); an object adds `ownerUrl` (default source), `sources` (name → URL or `{ url, ownerUrl, sqlEngine }`) and per-model exceptions (`models`); `false` means no database. Precedence for a model: `database.models` > the `dataSource` of a `CorePersistenceModule.forFeature()` definition > `@PersistedModel({ dataSource })` (read from the definition's `model:` class, otherwise from the decorated class named like the model; two such classes naming different sources refuse to guess) > default. When `database` sets a default and the project ALSO configures `mongoose` explicitly, that MongoDB becomes the source `mongoose` — only the project's own `mongoose` counts, because `CoreModule.forRoot()` always merges a fallback URI. **Since phase 1 (DEV-3829) PostgreSQL sources are wired**: only models registered with `CorePersistenceModule.forFeature()` are routed — **since phase 2 (DEV-3830) that includes the core's own models**: the user model (the reference `UserModule`), tenant memberships and API tokens, whose services switch to the routed store (a service that only received `@InjectModel()` follows its model's store; the Mongoose model of a model routed to SQL refuses every data access with a named error, so a direct `mainDbModel` call cannot split a model's data). **Since phase 3 (DEV-3831) Better-Auth follows the user model**: with the user model (table `users`) on a SQL source, Better-Auth runs its built-in Kysely adapter on that source's application pool — ONE `users` row per user shared with the user model (Better-Auth's own columns `name`, `email_verified`, `image` beside the framework's; its required ones are added nullable, so a row the user model writes alone stays valid), snake_case tables (`session`, `account`, `verification`, `jwks`, `two_factor`, `passkey`), ObjectId-hex ids. Its schema is applied as the OWNER at boot, under the same schema lock and grants as the framework's tables; without `ownerUrl` the application role only verifies and the boot stops while Better-Auth's migrations are pending. The framework's own reads and writes of Better-Auth's data follow it (session lookup by token, token service, JWKS, passkey challenge mappings — as Better-Auth verification values —, the e-mail-verified hook, user mapper, system setup, migration status — counted in SQL —, the MCP OAuth subject's roles); the MongoDB boot steps (indices, account-issuer backfill) are skipped there. Nothing is copied from MongoDB: a project that moves its users brings them over itself. **Since phase 4 (DEV-3832) the remaining core persistence follows too**: the AI module's eleven models and the three MCP OAuth stores (clients, codes, refresh tokens) are registered through `CorePersistenceModule.forFeature()` and run on their routed store (one code path; an upsert is update-then-insert with a retry on a duplicate, `sum()` replaces the budget aggregation, `find(…, { exclude })` the `-field` projection); the S3 and filesystem file metadata are two framework models (`CoreS3File`, `CoreFilesystemFile`, tables `s3_files` / `filesystem_files`) read and written through `fileMetadataCollection()` by the file service, the TUS hand-off and the Hub — GridFS stays MongoDB-only. A collection name with a hyphen becomes a table with an underscore. A TTL (`expires`, `index: { expireAfterSeconds }`) is a plain index on SQL; an **expiry sweep** (`scheduleExpirySweep()`, every 15 min, one replica per interval through a lease in the default SQL source's `lt_locks`, fail-open) deletes the expired rows of every routed TTL model, and — with Better-Auth on SQL — expired sessions and verification values. Nothing relies on it for correctness: every reader checks the expiry (an MCP authorization code older than ten minutes is refused on read on both databases). MongoDB keeps its TTL indexes and gets no sweep. The framework's leases (system-setup claim, cron, migrations) live in the default source: on MongoDB in the 12.0.0 documents (a rolling deploy with older replicas shares them), on SQL in `lt_locks`, namespaced, swept an hour after expiry. With `healthCheck.configs.database` every SQL source answers as `<key>:<source>`; `createMigrationStore(<owner URL>)` keeps the migration state in `lt_migrations` with an advisory run lock, on the first SQL engine installed (the CLI cannot read `database.sqlEngine`), and the Hub refuses to run migrations while that table is empty and the MongoDB collection is not (a `migrate.js` still writing MongoDB); the Hub's Persistence panel shows the routing. a SQL model's table is migrated as the OWNER (`ownerUrl`) when its store is created — without `ownerUrl` the application role only verifies and the boot stops while changes are pending; ONE owner connection per source, released once the application is bootstrapped — and the boot refuses an application role that is superuser, has `BYPASSRLS`, owns (or inherits the owner of) a framework table or may `TRUNCATE` it. Two roles in every environment (plan §3.9). Changes the framework never applies on its own (type change, new unique index, rename collision) stop the boot with the suggested statements; `migrate create <name> --sql` + `runSqlMigration()` apply them after review. **Since phase 5 (DEV-3833, 12.1.0) MongoDB is optional**: `mongoose`, `@nestjs/mongoose` and `mongodb` are optional peers, loaded through `common/persistence/mongo/mongo-packages.ts`; `CoreModule` connects MongoDB only when a source uses it (`usesMongoDb()` — `mongoose` configured explicitly, `database` naming MongoDB, or `database` absent), otherwise `@InjectConnection()` receives `null` and a model token without a connection is a stand-in that refuses data access. A configured MongoDB feature without the packages fails the boot with `MongoPackagesMissingError`. `database: false` runs a service without any database: a registered model's store refuses with the reason, Better-Auth is refused at boot. Proven by `pnpm run check:without-mongodb` (dist, packages hidden) and `check:without-mongodb:package` (the tarball installed without them, publish path). **Since phase 6 (DEV-3848) MySQL 8.4 and MariaDB 11.8 sources are wired** (`mysql://`, `mariadb://` — the scheme must name the server the URL reaches): `mysql2` is an optional peer beside the engine, all three engines run on one pool the framework creates (strict session with backslash escapes, UTC), `MysqlDataStore` writes the statements, the owner grants the application account `SELECT, INSERT, UPDATE, DELETE` on the database once and the boot refuses an application account that may alter, drop, index, trigger or grant; leases, migration state (`createMigrationStore()` / `runSqlMigration()` under `GET_LOCK`), the expiry sweep, health check and Hub work there. **Neither database has row-level security**: tenant isolation is the store's, the boot warns once per source, and native / raw access on a tenant table must filter by tenant itself. Better-Auth is refused at boot while the user model lives there. An indexed text field is `varchar(255)` (longer: 400); a DDL run is not transactional. Still refused with a named `DataSourceConfigError`: a second MongoDB source, and an `ownerUrl` without `url` — what `NSC__DATABASE__OWNER_URL` leaves of a `database` given as a URL string, because the environment merge replaces the string with an object (write `database: { url }`, or set `NSC__DATABASE__URL` too). An update path the model does not declare is dropped on SQL as by MongoDB's strict mode (`CrudService.update()` adds `updatedBy` to every update with a current user). URLs appear in errors and logs as scheme + host only. Implementation: `common/persistence/data-source.config.ts`, `data-source.runtime.ts`, `sql/` (plan: `.claude/plans/db-agnostic/PLAN.md` §3.9) |
+| Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | **`excludeSchemas` is an OFF SWITCH for isolation, per model** — a listed schema gets no tenant filter at all; since 11.35.0 the plugin WARNS once per model when the excluded schema declares `tenantId` (i.e. was built for isolation). The framework's own docs recommended `['User', 'Session']` until then; that is withdrawn — it is only right for the global-user model. Since 11.35.0 GraphQL operations over the WEBSOCKET also run inside a `RequestContext` (`CoreModule` installs a context-aware `execute`/`subscribe` pair inside `subscriptions`, where `ApolloDriver` forwards it): the tenant comes from the handshake header validated against an active membership, else from the subscriber's memberships, and an unresolvable tenant leaves the safety net to refuse the read rather than returning everything. `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `invalidateUser(userId)` / `invalidateAll()` are **instance** methods on the singleton `CoreTenantGuard` — inject it and call `this.tenantGuard?.invalidateUser(userId)`, never `CoreTenantGuard.invalidateUser(...)` (there is no static). With `redis` configured, both additionally BROADCAST the invalidation to every replica (`<keyPrefix>:tenant-cache:invalidate` pub/sub); without Redis they clear the local process only, so other replicas stay stale until `cacheTtlMs`. A received broadcast clears locally without re-publishing. **`isTenantActive` (11.42.0)**: optional hook `(tenantId, { connection, store }) => boolean \| Promise<boolean>`, absent = every tenant active (no change). `store(modelName)` (12.x, db-agnostic) is the data store of a model registered with `CorePersistenceModule.forFeature()`, wherever `database` routes it, and THROWS for any other model — an `undefined` would read as "active" in a hook written with `?.` and open every deactivated tenant. Asked AFTER the membership check on every path that establishes a tenant: 403 on header paths and for tenant API tokens, no enrichment on `S_EVERYONE`, dropped from the header-less tenant list, no tenant for a NEW WebSocket subscription, and since 11.42.3 an OPEN one is closed with 4403 on `invalidateTenant()` (or at its next event once `graphQl.subscriptionRevalidationMs` has passed — see the GraphQL Subscription Re-check row); an admin under `adminBypass` is exempt (someone must be able to switch it back on). Only `false` deactivates. Cached for `cacheTtlMs`; `invalidateTenant(tenantId)` clears and broadcasts (`{ scope: 'tenant' }`). A function, so `config.env.ts` only — not reachable through `NSC__*`. **`adminBypass: false` (11.42.0)** additionally withholds two things that went around it: `CoreUserService.update()` refuses changing another account's e-mail or password (`assertCredentialChangeAllowed()`, administrator targets included — promote-then-change — system work without a current user exempt), and the AI tool registry grants no ADMIN bypass |
 | GraphQL Subscription Re-check | `graphQl.subscriptionRevalidationMs` | Numeric — `0` = STRICTEST, `false` = off, invalid → default (a fifth shape: Family C's "invalid never means unbounded", but `0` asks for MORE checking, not less) | **30000 since 11.42.3.** Before, a WebSocket was authorized once, at the handshake, and every event and operation on it ran on that snapshot until the client reconnected. Every connection a `CoreModule` `onConnect` accepts is now registered (`registerWsConnection()`) and re-checked — at once when an invalidation names it (`CoreTenantGuard.invalidateUser()` / `invalidateTenant()` / `invalidateAll()`, `CoreUserService.setRoles()` and role/verification `update()`s, the legacy password reset, and Better-Auth deleting a session through `wsSessionRevocationPlugin()`), and otherwise before the next event or operation once the last check is older than this value. The check re-runs the handshake's own authentication (session store, Better-Auth JWT signature/expiry, or for legacy tokens `CoreAuthService.verifyJwt()` — signature/expiry, verified on the WebSocket since 11.42.3 — plus the device binding) and the tenant resolution; any difference in user id, roles, verification state or tenant scope closes the socket with **4403**, which the graphql-ws client retries — the user continues with current rights or is refused at the handshake. `0` re-checks on every event and operation (one session lookup each); `false` switches only the TIME-based check off, invalidations still apply. Process-local registry: an invalidation reaches other replicas only where the tenant guard's Redis broadcast carries it; everything else is bounded by the interval. A project that replaces `onConnect` through `graphQl.driver.subscriptions` must call `registerWsConnection()` itself to keep this. Implementation: `common/helpers/graphql-ws-connection.helper.ts` |
 | API Tokens | `apiTokens` | Boolean Shorthand + Presence Implies Enabled — absent = off | `prefix: 'ltt'`, `scopes: []` (vocabulary; empty = no token creatable, boot warning), `manageRole`: highest hierarchy role, `maxAssertionLifetimeSeconds: 900` (invalid → default, never unbounded — Family C), `rateLimit: { max: 600, windowSeconds: 60 }` per token (**on by default**, `false` disables; Redis-shared when configured), `userTokens: true`, `tenantTokens: true` (effective only with `multiTenancy`), `encryptionKey` → `SECRETS_ENCRYPTION_KEY` → dev default (boot FAILS in production/staging). Top-level, NOT under `multiTenancy`: user tokens must work without it. **Deny by default**: every guard refuses a token on a route without `@ApiTokenScopes()`, public routes included, via ONE shared function (`enforceApiTokenRoute`) called BEFORE each guard's public-route shortcut. USER tokens act as their user with global roles REMOVED (no admin bypass); TENANT tokens act with the lowest hierarchy role in their own tenant, and a route guarded ONLY by `S_SELF` / `S_CREATOR` refuses them (a tenant token is nobody's self — skipping those roles would grant for any target). A tenant token depends on no member, so it outlives an off-boarded or deleted tenant until the project calls `deleteAllForTenant()`. The boot refuses a hierarchy in which that lowest role reaches `manageRole`. A prefixed credential that fails answers 401 on every route (not anonymous); `CoreBetterAuthMiddleware` skips prefixed credentials entirely, cookie fallback included. A password reset that ends the user's sessions ends their USER tokens too (legacy reset always; IAM reset while `betterAuth.emailAndPassword.revokeSessionsOnPasswordReset` is on), wired through `core-api-token.registry.ts` so neither reset path imports the optional module. Implementation: `src/core/modules/api-token/` |
 | BetterAuth Tenant Skip | `betterAuth.skipTenantCheck` | Explicit Boolean | `true` (default). When `true` and no `X-Tenant-Id` header is sent, IAM endpoints (controller + resolver) skip `CoreTenantGuard` tenant validation. When header IS present, normal membership validation runs regardless. Set `false` for tenant-aware auth scenarios (subdomain-based, invite links, SSO per tenant) |
@@ -332,7 +333,7 @@ This pattern is currently applied to:
 | Central Redis | `redis` | Boolean Shorthand + Presence Implies Enabled | `host: 'localhost'`, `port: 6379`, `db: 0`, `keyPrefix: <package.json name, slugified>` (per APPLICATION, not per framework — a constant default silently collides when two apps share one Redis; set it explicitly when sharing IS intended); `url` (takes precedence over host/port/db/credentials), `username`/`password`, `options` (passed to the ioredis constructor). `true` / `{}` enables with defaults; `{ enabled: false }` pre-configures without enabling; **absent = every consumer keeps its process-local fallback** (that fallback is the whole backward-compatibility story of 11.33.0). Requires the OPTIONAL peer `ioredis` — configured-but-missing **fails the boot** with a named error rather than crashing on first use. `keyPrefix` is applied by the framework per key, NOT as ioredis `keyPrefix` (that would collide with BullMQ's own prefix). One `CoreRedisService` serves all features: shared client (`getClient()`), one cached subscriber (`getSubscriber()` — a subscribing client cannot run commands), dedicated connections (`createClient(label)`); all are tracked and quit on shutdown. Switches on automatically: exact cross-replica rate limits via `RedisRateLimitStore` (see the Legacy Auth / BetterAuth / AI rate-limit rows), cron dedup (see Cron Job Deduplication row), `CoreRedisPubSub` as `PUB_SUB` for cluster-wide GraphQL subscriptions (**payloads must be JSON-serializable — `Date`, class instances, `Map`/`Set`, `undefined` do not survive**), tenant-cache invalidation broadcast, Hub collector mirroring, MCP session registry (turns a wrong-replica request from a misleading `404` into a `409` — `/ai/mcp` still REQUIRES sticky sessions, sessions are not portable) |
 | File Access Roles | `file.downloadRoles`, `file.uploadRoles`, `file.deleteRoles` | Config-Driven Role List | `[RoleEnum.ADMIN]` each. **These are the only breaking change a single-replica project gets in 11.33.0** — six members moved from `@Roles(S_EVERYONE)` to these knobs: `GET /files/id/:id`, `GET /files/:filename` and `getFileInfo` (`downloadRoles`), `uploadFile` / `uploadFiles` (`uploadRoles`), `deleteFile` (`deleteRoles`). Plain role STRINGS, not `RoleEnum` members, so project roles work (`['company-admin', 'editor']`). Applied at boot by `applyFileRoles()` via `Reflect.defineMetadata('roles', …)` on the base-class methods — the same runtime mechanism `CorePermissionsModule` uses, because the value is only known from config. **`[]`, a non-array, or an array holding a non-string is REJECTED with a warning and the default applies** — an all-empty role set reads to the guards as "no roles required" and would OPEN the route, the exact opposite of the intent. **ADMIN is always unioned in**: both `CoreFileController` and `CoreFileResolver` carry a class-level `@Roles(RoleEnum.ADMIN)` and the guards UNION class + handler metadata, so these knobs can grant but never exclude admins. Both classes also carry `@SkipTenantCheck()` — GridFS and the S3 metadata collection are reached outside Mongoose, so `mongooseTenantPlugin` never scopes them and a role name alone cannot express a per-tenant rule; roles resolve against `user.roles`, never `membership.role`. **A subclass that OVERRIDES a member opts out permanently** (decorator metadata lives on the function object, and an override is a different function) — inherit the member instead. **Since 11.35.1 that opt-out is REPORTED**: `CoreFileAccessAuditInitializer` reads the roles off the class the project actually registered at `onApplicationBootstrap` (the earliest point at which the route table exists, which is why it is a provider and not part of `applyFileRoles()`) and warns when a member is open beyond ADMIN for a reason the configuration cannot explain — the case the construction-time warning below is structurally blind to. It only REPORTS: overwriting an override's metadata, the way `TusModule.applyRoles()` does, would silently relax a route a project pinned on purpose. Roles are the coarse filter only; per-file rules belong in `CoreFileService.checkRights()`, which now receives `currentUser` and can read raw metadata via `getRawFileInfo()`. **Since 11.35.0 a reused FILENAME resolves to the most recent file** in all three stores (`uploadDate` desc, `_id` tie-break) and every by-name read path resolves a document and then reads by ID — under GridFS the by-name metadata lookup answered the oldest document while `openDownloadStreamByName()` served the newest, so a per-file rule approved one file and the bytes of another came back. Consequence: `duplicateById()` keeps the source's filename and the copy carries no metadata, so the copy now wins the name and an `ownerId` rule refuses it — give the copy its own metadata or its own name. **Since 11.35.0 `CoreFileService` WARNS at construction** when `multiTenancy` is active AND a knob names a role other than ADMIN AND `checkRights()` is not overridden — the file stores are reached outside Mongoose, so these role names resolve against `user.roles` (global) and every holder reaches every tenant's files; only `checkRights()` can narrow that. Silent on the admin-only default and silent when a per-file rule exists. Implementation: `src/core/modules/file/file-roles.config.ts` (`FILE_ROLE_DEFAULTS`, `FILE_ROLE_MEMBERS`, the three warnings, the shared `hasDeclaredFilePolicy()` silencer) + `file-roles.helper.ts` (`applyFileRoles`) + `core-file-access-audit.initializer.ts` (the registered-class audit) |
 | TUS Roles | `tus.roles` | Config-Driven Role List | `[RoleEnum.S_USER]` (was `S_EVERYONE` — breaking). A TUS upload writes into the SAME store the download routes guard, and the termination extension (on by default) can delete from it, so anonymous writes into a store only privileged callers may read is the wrong way round. Applied by `TusModule.applyRoles()` onto the registered controller class **and** onto `handleTus` / `handleTusWithId`. Same rejection rule as the file roles: `[]` / non-array / non-string → warning + `DEFAULT_TUS_CONFIG.roles`. **`OPTIONS` is deliberately exempt**: `handleTusOptions` / `handleTusOptionsWithId` keep their own handler-level `@Roles(RoleEnum.S_EVERYONE)`, because that is the CORS preflight — browsers send it WITHOUT credentials, and it returns server capabilities only. Gating it would make every browser upload fail before the first byte. `CoreTusController` also carries `@SkipTenantCheck()`. A custom controller is covered as long as it INHERITS the handlers; one that re-declares `@All()` / `@Roles()` carries its own metadata and thereby opts out — the documented way to hard-code a policy config must not be able to change. **Set `roles: [RoleEnum.S_EVERYONE]` explicitly if you accept attachments on a public form.** **Since 11.35.0 `tus.roles` is no longer the only gate**: `onUploadCreate` records the authenticated creator under `TUS_OWNER_METADATA_KEY` (`ltOwnerId`, always OVERWRITING any client-supplied value) and `onIncomingRequest` refuses HEAD/PATCH/DELETE naming an upload the caller does not own — with **404**, the file module's refusal policy. Before that, any authenticated caller who learned an upload id could APPEND BYTES to somebody else's upload, which are then migrated into the file store under the victim's filename. The finished file also gains `metadata.ownerId`, without which the documented per-file ownership rule could never authorize a tus-uploaded file (admin-only in practice). An OWNER-LESS upload stays reachable — uploads predating 11.35.0 have none, and neither does a deliberately public form. `readRequestUserId()` / `assertUploadOwnership()` are `protected`. **Since 11.41.9 the tenant is recorded too, but ONLY with `multiTenancy` configured** (not `enabled: false`) and a tenant guard registered: `onUploadCreate` validates the tenant header against the caller's active memberships through `core-tenant-context.registry.ts` (the routes carry `@SkipTenantCheck()`, so the guard did not), refuses a non-member with **403**, writes it under `TUS_TENANT_METADATA_KEY` (`ltTenantId`, always overwritten like the owner key) and the finished file gains `metadata.tenantId`. No header → tenant-less, as before; without `multiTenancy` nothing is read or written. A project hooks in through `TusModule.forRoot({ service })` (a `CoreTusService` subclass, constructed by the module as `(connection, options)` — project providers come from `options.moduleRef` at call time) and the `protected onUploadCreate(req, upload)`, the one point where `Upload-Length` is known and nothing is stored yet; an override must return `super.onUploadCreate()`. Note that `@tus/server` v2 hands its hooks a WHATWG `ServerRequest`, so a guard's `req.user` is reachable only via `runtime.node.req`. **CORS (11.42.1)**: the tus handler's `Access-Control-Allow-Origin` comes from `buildCorsConfig()` (or `tus.allowedOrigins`), plus `allowedCredentials` — without it `@tus/server` answered `*`, which browsers refuse on a credentialed request, so cookie-authenticated uploads across split app/API origins failed in every browser while the server answered 201; no credentialed CORS configured → the `*` default stays. **compression (11.42.2)**: `@tus/server` finishes responses with `res.end(callback)`, which `compression`'s two-argument `res.end(chunk, encoding)` patch reads as a chunk (`ERR_INVALID_ARG_TYPE … Received function`); with the starter's `filter: () => true, threshold: 0` every finished upload HUNG without an answer AFTER the file was stored (headers already sent, so no error response could follow). `CoreTusService` wraps `server.handle()` and normalises `res.end` per response (`normalizeEndCallback()`, callback on `finish`/`close`), so no `main.ts` change is needed. Implementation: `src/core/modules/tus/tus.module.ts`, `src/core/modules/tus/core-tus.service.ts`, `src/core/modules/tus/tus.constants.ts` |
-| File Storage | `file.storage` + `file.storageDir` + `s3` | Explicit Enum with DERIVED default | `'filesystem' \| 'gridfs' \| 's3'`. **Unset → derived**, most capable first: `'s3'` when `s3.bucket` is set, else `'gridfs'` when `mongoose.uri` is set, else `'filesystem'`. **Set → enforced**: an unavailable store FAILS THE BOOT (`assertFileStorageAvailable()`), it never falls back — a silent fallback puts files in a store the operator does not believe they are in, unrecoverably. A DERIVED driver is enforced too (`s3.bucket` set but `s3Service` not forwarded to `super()` → boot error). Metadata always lives in MongoDB whichever driver holds the bytes (`fs.files` / `s3-files` / `filesystem-files`) — it has to stay queryable for `findFileInfo()` and `checkRights()`. Reads consult ALL stores so switching drivers is forward-only with no migration; writes go to the active driver only. `'filesystem'` is pod-local: not shared between replicas, lost on restart unless `storageDir` is a mounted volume. `s3`: `bucket` (required — the one thing S3 cannot default, hence the eligibility test), `region: 'us-east-1'`, `forcePathStyle: false`, `autoCreateBucket: false` (off by design: production buckets come from infrastructure code, whose credentials usually cannot CreateBucket), `stagingBucket: bucket`, `presignedDownloads: false` (`true`/`{}` → `expiresInSeconds: 300`), `endpoint` (MinIO/RustFS), `accessKeyId`/`secretAccessKey` (omit → AWS default credential chain), `enabled: false` to pre-configure. Requires the OPTIONAL peer `@aws-sdk/client-s3`, plus `@aws-sdk/s3-request-presigner` for presigned downloads. **Uploads are never buffered on the S3 path** (11.41.7): a known length (`FileUploadSource.size`, TUS, a buffer) goes up as one streamed PutObject up to `CoreS3Service.MAX_SINGLE_PUT_BYTES` (5 GiB — AWS S3 refuses more in one request, `EntityTooLarge`) and as a multipart upload above it, an unknown one — every GraphQL and streamed REST upload — as a multipart upload via the OPTIONAL peer `@aws-sdk/lib-storage`. Missing peer → one boot warning and the old in-memory buffering, NOT a boot failure (multipart optimises a path that works without it). `size` must be the file's EXACT length — never a multipart request's `Content-Length`; anything but a positive integer counts as unknown (`isKnownUploadSize()`), and the recorded length of an unknown-length upload comes from a HEAD of the stored object. `presignedDownloads` makes `GET /files/id/:id` answer `302` to a time-limited S3 URL instead of streaming — the URL is a bearer capability, authorized once at issue time. The resolved driver is logged at boot (`[CoreFileStorage] File storage: …`) |
+| File Storage | `file.storage` + `file.storageDir` + `s3` | Explicit Enum with DERIVED default | `'filesystem' \| 'gridfs' \| 's3'`. **Unset → derived**, most capable first: `'s3'` when `s3.bucket` is set, else `'filesystem'` with `database: false` or when `database` routes the file metadata to a SQL source (`fileMetadataSqlSource()`; GridFS would put bytes and metadata into MongoDB — an explicit `'gridfs'` keeps working), else `'gridfs'` when `mongoose.uri` is set, else `'filesystem'`. **Set → enforced**: an unavailable store FAILS THE BOOT (`assertFileStorageAvailable()`), it never falls back — a silent fallback puts files in a store the operator does not believe they are in, unrecoverably. A DERIVED driver is enforced too (`s3.bucket` set but `s3Service` not forwarded to `super()` → boot error). Metadata stays queryable whichever driver holds the bytes (`fs.files` / `s3-files` / `filesystem-files`, the latter two as the tables `s3_files` / `filesystem_files` when `database` routes them to a SQL source) — `findFileInfo()` and `checkRights()` need it. Reads consult ALL stores so switching drivers is forward-only with no migration; writes go to the active driver only. `'filesystem'` is pod-local: not shared between replicas, lost on restart unless `storageDir` is a mounted volume. `s3`: `bucket` (required — the one thing S3 cannot default, hence the eligibility test), `region: 'us-east-1'`, `forcePathStyle: false`, `autoCreateBucket: false` (off by design: production buckets come from infrastructure code, whose credentials usually cannot CreateBucket), `stagingBucket: bucket`, `presignedDownloads: false` (`true`/`{}` → `expiresInSeconds: 300`), `endpoint` (MinIO/RustFS), `accessKeyId`/`secretAccessKey` (omit → AWS default credential chain), `enabled: false` to pre-configure. Requires the OPTIONAL peer `@aws-sdk/client-s3`, plus `@aws-sdk/s3-request-presigner` for presigned downloads. **Uploads are never buffered on the S3 path** (11.41.7): a known length (`FileUploadSource.size`, TUS, a buffer) goes up as one streamed PutObject up to `CoreS3Service.MAX_SINGLE_PUT_BYTES` (5 GiB — AWS S3 refuses more in one request, `EntityTooLarge`) and as a multipart upload above it, an unknown one — every GraphQL and streamed REST upload — as a multipart upload via the OPTIONAL peer `@aws-sdk/lib-storage`. Missing peer → one boot warning and the old in-memory buffering, NOT a boot failure (multipart optimises a path that works without it). `size` must be the file's EXACT length — never a multipart request's `Content-Length`; anything but a positive integer counts as unknown (`isKnownUploadSize()`), and the recorded length of an unknown-length upload comes from a HEAD of the stored object. `presignedDownloads` makes `GET /files/id/:id` answer `302` to a time-limited S3 URL instead of streaming — the URL is a bearer capability, authorized once at issue time. The resolved driver is logged at boot (`[CoreFileStorage] File storage: …`) |
 | TUS S3 Staging | `tus.s3Staging` | Explicit Boolean (default ON when S3 configured) | `true` when `s3` is configured, otherwise inert. Stages in-progress uploads in `s3.stagingBucket` via `@tus/s3-store` instead of `tus.uploadDir` on local disk, so resumable uploads survive replica restarts and need no sticky sessions. Set `false` to force local disk. Missing OPTIONAL peer `@tus/s3-store` → warning + fall back to local disk (NOT a boot failure). **Give the staging bucket a lifecycle rule expiring incomplete multipart uploads** — the framework's own expiration cleanup is skipped in S3 mode (S3 is the right place for that policy), so aborted uploads otherwise accumulate parts nothing removes |
 | TUS Configuration Source, Path & Extensions | `tus` (server config) / `TusModule.forRoot({ config })` | Enabled by Default + explicit-config-wins | **Since 11.42.9 `TusModule.forRoot()` without `config` reads the server config's `tus` key** (`ConfigService.get('tus')`, the zero-config rule `CoreBetterAuthModule.forRoot()` follows); an explicit `config` wins. Before, the key was never read: `tus: false`, `allowedTypes`, `maxSize`, `roles` in `config.env.ts` did nothing — real projects had upload restrictions they believed were enforced. **`path`** has three readings (`applyPath()`): unset → follows the controller's route; a new route (`/uploads`) → mounts the registered controller there (writes `PATH_METADATA`, config wins like the roles; the declared route is remembered per class and restored by a later `forRoot()` without `path`); a path ENDING with the controller's route (`/api/tus`, `/files/tus`) → the PUBLIC URL: the controller stays and upload URLs use it. The third reading is load-bearing: it was the only working setting under a global prefix or a prefix-stripping proxy before 11.42.9, and treating it as a route doubled the prefix (`/api/api/tus`, 404 on every upload — caught in the second pre-release review). The upload URL (`Location`) is built from the path the creation request arrived at (`uploadCollectionPath(req)`), or from `path` when that is longer and ends with it (proxy strip); `@tus/server` built it from `path` alone, which broke every resume below a global prefix, a URI version or a project route. **`relativeLocation`** (new): the framework owns `generateUrl`, which takes precedence over `@tus/server`'s option of that name, so it is honoured from `tus.relativeLocation` AND from the tus server's own options (a vendored core may pass it there). **Extensions**: `@tus/server` consults no flag, so `creation`, `creationWithUpload` and `termination` are enforced by `CoreTusService` — the store's advertised `extensions` are narrowed, and `assertExtensionEnabled()` answers 501 inside the server's `onIncomingRequest` / `onUploadCreate` options (not in the overridable hook, so an override without `super` cannot reopen it). `checksum` / `concatenation` have no effect: neither built-in store supports them. `configure(false)` now yields a DISABLED config (before it kept the defaults and started a tus server behind a module with no endpoint). Implementation: `tus.module.ts`, `core-tus.service.ts` |
 | Health Check | `healthCheck` | Presence Implies Enabled | Absent → no endpoints. Any object registers `GET /health-check` + the `healthCheck` query; **`enabled: false` leaves them out (honoured since 11.42.9 — before, it was declared and ignored)**. Individual checks under `configs.*` each have their own `enabled`. Implementation: `core.module.ts` |

package/.claude/rules/module-deprecation.md

@@ -4,7 +4,7 @@ This document describes the deprecation strategy for Legacy Auth and the migrati
 
 ## Authentication System Roadmap
 
-### v11.x (Current - Backward Compatible)
+### v11.x – v12.x (Current - Backward Compatible)
 
 - **Legacy Auth** (CoreAuthService) is available for backwards compatibility
 - **BetterAuth** (IAM) can run standalone or alongside Legacy Auth
@@ -228,7 +228,8 @@ both Legacy Auth and BetterAuth transparently.
 | Version | Status | Changes |
 |---------|--------|---------|
 | v11.6.x | Released | BetterAuth introduced |
-| v11.7.x | Current | Legacy endpoint controls, IAuthProvider, migration status |
+| v11.7.x | Released | Legacy endpoint controls, IAuthProvider, migration status |
+| v12.0.x | Current | NestJS 12 — Legacy Auth unchanged, still available alongside IAM |
 | Future | Planned | BetterAuth default, simplified API, Legacy optional |
 
 ## Related Documentation

package/.claude/rules/package-management.md

@@ -169,11 +169,20 @@ Two ordering rules, both enforced by the contract test:
 Package overrides live in the `overrides:` section of **`pnpm-workspace.yaml`** (they moved out of `package.json`'s `pnpm.overrides` in the pnpm 11 upgrade). They force transitive dependencies to a security-patched version.
 
 **Keep the set minimal.** On the pnpm 11 upgrade the list was pruned from 36 to the 9 then still
-load-bearing (it has since grown back to 20, mostly as new advisories landed) — an override is only necessary if removing it lets the package resolve back INTO its vulnerable range (verify with a with/without lockfile diff; `pnpm audit` is the arbiter). Each surviving entry carries its CVE rationale as a comment. Remove an entry once its parent dependency ships a fixed version.
-
-**The one exception is a peer conflict nobody downstream can fix.** `'@nestjs/cli>webpack'` (added
-2026-10-20) carries no advisory: @nestjs/cli exact-pins a webpack that a newer transitive
-`schema-utils` refuses as a peer, so every fresh resolve fails `pnpm peers check`. Such an entry
+load-bearing (it has since grown back to as many as 20, mostly as new advisories landed). On
+2026-10-24 (nest-server 12.0.0) two fresh resolves showed that 16 of the remaining 18 changed nothing,
+and they were removed, leaving `@graphql-tools/utils` and `multer`, both on an upstream EXACT pin with
+an open advisory. Those two left on 2026-10-29 (nest-server 12.1.0), once `@nestjs/graphql` 14.1.0 and
+`@nestjs/platform-express` 12.3.2 moved their pins past the fixes: **the set is empty** (`overrides: {}`,
+written explicitly so `check:overrides` reads it as a decision). An override is only necessary if removing it lets the package resolve
+back INTO its vulnerable range (verify with a with/without lockfile diff; `pnpm audit` is the arbiter).
+"Cheap insurance against a parent re-pinning downwards" is not a reason to keep one: `pnpm audit` and
+`check:overrides` run on every `check` and report such a regression the day it happens. Each surviving entry carries its CVE rationale as a comment. Remove an entry once its parent dependency ships a fixed version.
+
+**The one exception is a peer conflict nobody downstream can fix.** `'@nestjs/cli>webpack'`
+(2026-10-20 until the move to @nestjs/cli 12 in nest-server 12.0.0, where webpack became an optional
+peer) carried no advisory: @nestjs/cli 11 exact-pinned a webpack that a newer transitive
+`schema-utils` refused as a peer, so every fresh resolve failed `pnpm peers check`. Such an entry
 is parent-scoped (`parent>child`), so only the stale pin moves, and it states the release that
 lets it go. For such an entry `pnpm peers check` is the arbiter, not `pnpm audit`.
 
@@ -256,9 +265,9 @@ from a casual read.
 
 **How to spot both — and the check that does NOT work.** "The same package appears twice under
 `overrides:`" is the obvious heuristic and it is wrong: several packages legitimately need one entry
-per major, because different majors coexist in the tree. This repo has three `brace-expansion`
-entries (1.x, 2.x, 5.x) and two for `js-yaml` (4.x, 5.x), all correct. Flagging those trains the
-reader to ignore the check.
+per major, because different majors coexist in the tree. This repo carried three `brace-expansion`
+entries (1.x, 2.x, 5.x) and two for `js-yaml` (4.x, 5.x) until 12.0.0, all correct. Flagging those
+trains the reader to ignore the check.
 
 The reliable tells are narrower:
 
@@ -330,6 +339,26 @@ on `FIX AVAILABLE` (a `first_patched_version` now exists) or on a withdrawn advi
 API is reported as `UNVERIFIED` and tolerated locally — but **fails under `CI`**, because a skip
 nobody reads is indistinguishable from a check that ran.
 
+**A fix nobody named is still a fix.** GitHub leaves `first_patched_version` null on some advisories
+after a release outside the vulnerable range shipped: GHSA-86w9-cpqp-85rv (node-forge) read
+`<= 1.4.0` / null a day after 1.4.1 was published. Until 12.0.x the guard skipped such an advisory,
+so its suppression passed every run. It now reads the package's packument from the registry pnpm
+installs from and, per vulnerable copy in the lockfile, looks for a stable release above it that
+lies outside **every** range the advisory lists. A deprecated release is held back, not ruled out: it
+counts only when every such release is deprecated, because some packages deprecate all of them
+(node-sass: 132 of 132 stable releases), and ruling them out reads a published fix as "no fix" for good.
+
+| Finding | Verdict |
+|---------|---------|
+| every copy has such a release, past `minimumReleaseAge` | `FIX AVAILABLE`, naming it — `unusableFixConsumers` applies as for a named fix |
+| one is published but younger than `minimumReleaseAge` | passes, printed as `pending` with the date the gate clears (pnpm would refuse it, so failing would order a `minimumReleaseAgeExclude` nobody decided on) |
+| some copy has none | passes — the suppression is still justified |
+| no version the lockfile resolves is in the range any more | `NOT IN TREE` — the entry hides nothing |
+| registry or lockfile unreadable | `UNVERIFIED`, with the reason (fails under `CI`) |
+
+`--advisory-file` runs stay offline: they take packuments from `--packument-file` and never ask the
+registry.
+
 One consequence worth knowing before you reach for this mechanism: the guard fires when the advisory
 has a patched version for **any** affected range. For most findings that is the honest outcome — a
 fix exists, take it, and the case is an override problem rather than a suppression problem.
@@ -401,12 +430,16 @@ plus one for the opposite failure, a guard that rejects a declaration which is s
 matters just as much: a check that cries wolf on correct entries is a check that gets switched off,
 which is how the hole this feature closes came about in the first place.
 
-**Current entry (since 2026-10-11):** `GHSA-vfj7-8cjw-p6xm` (braces, via nodemon / npm-watch), a
-dev-tooling-only path of an advisory with no patched release at all; the justification sits next to
-the entry in `pnpm-workspace.yaml`. **Do not copy it into nest-server-starter without thinking it
-through:** since lt CLI 1.42.0 the starter's `auditConfig` is hoisted as a union into every
-generated project, so an entry there hides the advisory in every customer workspace — including
-production paths this repository does not have.
+**No current entry (since 2026-10-24).** `GHSA-vfj7-8cjw-p6xm` (braces, via nodemon / npm-watch) was
+listed from 2026-10-11 to 2026-10-24: a dev-tooling-only path of an advisory with no patched release
+at all. GitHub withdrew the advisory on 2026-10-23, and `check:overrides` reported the entry as
+obsolete on the next run — the guard doing exactly its job, since a withdrawal changes nothing in
+this repository and `pnpm audit` simply stops mentioning it. The entry and its scope guard in
+`tests/unit/audit-suppression-scope.spec.ts` left together; the history is in git (the comment
+block above `ignoreGhsas` in `pnpm-workspace.yaml` before 12.0.0). **Before adding an entry, and before copying one into
+nest-server-starter:** since lt CLI 1.42.0 the starter's `auditConfig` is hoisted as a union into
+every generated project, so an entry there hides the advisory in every customer workspace —
+including production paths this repository does not have.
 
 **An entry whose package has left the declared range goes, even when the new version is no fix.**
 `GHSA-ch52-4w7c-c8xp` (http-cache-semantics `<= 4.2.0`) was listed from 2026-10-03 to 2026-10-11.
@@ -414,7 +447,7 @@ production paths this repository does not have.
 as "up to the newest release" and never followed. On 4.3.0 the suppression hid nothing and would
 have swallowed a range extension unseen; without it, an extension turns `pnpm audit` red, and that
 is the moment to re-argue the case. Do not record such a lift as the advisory being fixed. Write
-down that the version is merely outside the range, as `pnpm-workspace.yaml` does.
+down that the version is merely outside the range.
 
 ### Safe Override Workflow
 

package/.claude/rules/persistence.md

@@ -0,0 +1,100 @@
+# Persistence Rules (MongoDB, PostgreSQL, MySQL and MariaDB)
+
+These rules apply to every model, service and query — in `src/core/` and in projects. The design and its
+reasoning are in `.claude/plans/db-agnostic/PLAN.md` (framework repository); which database a project uses is decided by
+`docs/choosing-a-database.md`; the configuration reference is the "Data Sources" row of
+`.claude/rules/configurable-features.md`.
+
+## One pipeline, one store per model
+
+`CrudService` runs every call through the same security pipeline (`process()`) and hands the database work to the
+model's **data store** (`DataStore<T>`, `common/persistence/data-store.interface.ts`): `MongooseDataStore` on MongoDB,
+`SqlDataStore` on PostgreSQL, `MysqlDataStore` (the same policies, MySQL's statements) on MySQL and MariaDB. What else
+differs per SQL database — schema, role check, leases — is the source's `SqlDialect` (`sql/sql-dialect.ts`). A model
+reaches its store by being registered with
+`CorePersistenceModule.forFeature([{ name, schema, model }])`; `database` routes it to a source.
+
+| Do | Never |
+|---|---|
+| Register a model with `CorePersistenceModule.forFeature()` | `MongooseModule.forFeature()` for a model that may live in SQL — it stays on MongoDB and nothing routes it |
+| Declare models with the framework's `Schema`, `Prop`, `SchemaFactory`, `InjectModel` (from `@lenne.tech/nest-server`, or `common/persistence/mongo/mongoose-compat.js` inside the core) | Import them from `@nestjs/mongoose` in the core — the core must load where MongoDB's libraries are not installed (`pnpm run check:without-mongodb`) |
+| Reach a model through `this.dataStore` in a `CrudService`, or `@InjectStore(Model)` elsewhere | Call `this.mainDbModel.find(…)` — on a model routed to SQL the Mongoose model refuses every data method (`routed-model.guard.ts`) |
+| Write ids as 24-hex strings (`generateId()`, `newObjectId()`, `isObjectIdLike()`) | `new Types.ObjectId()` / `instanceof Types.ObjectId` in the core — Mongoose may not be installed |
+| Query with the Mongo-operator subset the SQL compiler supports (`$eq $ne $gt $gte $lt $lte $in $nin $exists $type $regex $not $and $or $nor $elemMatch $all $size`, dotted paths) | Build an aggregation pipeline for something the port offers (`count`, `sum`, `distinct`, `find` with `sort` / `skip` / `limit` / `sample`) |
+
+## MongoDB's libraries are optional peers (12.1.0+)
+
+`mongoose`, `@nestjs/mongoose` and `mongodb` are loaded through `common/persistence/mongo/mongo-packages.ts` — never by
+a static value import in `src/core/`. `import type` is fine (erased), and so is the compat module, which records each
+declaration and applies the real decorator where Mongoose is installed.
+
+| Need | Use |
+|---|---|
+| The packages, where a feature cannot work without them (GridFS, a MongoDB migration) | `requireMongoPackages('<feature, in configuration words>')` — throws `MongoPackagesMissingError` naming what to install |
+| Whether they are there | `optionalMongoPackages()` / `hasMongoPackages()` |
+| A GridFS bucket | `createGridFsBucket(db, { bucketName })` |
+| A Mongoose query check | `isMongooseQuery(value)` |
+| An inline schema (no class) | `createSchema(definition, options)`; free-form fields `{ type: Object }` |
+| An ObjectId field type in a decorator | `objectIdType()` |
+
+Where Mongoose is not installed, a model's descriptor comes from what its decorators recorded
+(`mongo/model-declarations.ts`), read through `mongo/declared-schema.view.ts`, which builds paths and indexes exactly
+as Mongoose would. `tests/unit/persistence-model-descriptor.spec.ts` proves both sources agree for every shipped
+model — **a new model the framework ships goes into `SHIPPED_MODELS` there.**
+
+`CoreModule` connects MongoDB only when a source uses it (`usesMongoDb()`); otherwise `NoMongoConnectionModule`
+provides `null` for the connection token, and `@InjectConnection()` receives `null`. A service that uses the connection
+on its MongoDB path checks it.
+
+## Native access in three tiers
+
+| Tier | API | What still protects the data |
+|---|---|---|
+| 1 | `CrudService` / `DataStore` | everything: before-layer policies, database layer (RLS on PostgreSQL), tenant row check, output pipeline |
+| 2 | `store.native(reason)` — the engine's own API, bound to the store's transaction | MongoDB: the Mongoose plugins. PostgreSQL: row-level security (same connection). MySQL / MariaDB: **nothing in the database**. HTTP interceptors |
+| 3 | `store.raw(reason)` / `getNativeConnection(reason)` | PostgreSQL: row-level security. HTTP interceptors. Nothing else |
+
+`reason` is mandatory and logged. Parameters only — an identifier (table, column) never comes from user input.
+
+**MySQL and MariaDB: tenant isolation is the application's.** Neither database has row-level security, and a trigger
+guard was measured and rejected (plan, phase 6). On these sources a tier-2/3 query on a tenant-scoped table MUST filter
+by `tenantId` (and a write MUST set it) itself — a review treats a missing filter there as a cross-tenant leak, not a
+style issue. The boot warns once per source.
+
+## High-frequency paths
+
+The "use direct Mongoose in system-internal hot paths" advice in `CLAUDE.md` applies to MongoDB, where the Mongoose
+plugins still fire on `Model.create()` / `findByIdAndUpdate()`. The database-neutral form of the same advice is the
+data store: `this.dataStore.insert()`, `updateById()`, `findById()`, `pushToArray()` skip `process()` (no cloning, no
+output pipeline) and keep every policy — on MongoDB through the plugins, on PostgreSQL in the store. Prefer the store in
+new code; it is the fast path on both databases.
+
+## Schema on SQL
+
+The framework creates and evolves tables from the model descriptors when a store is created, as the **owner** role:
+new tables, columns, indexes and grants are applied; anything that could lose or reject data (type change, new unique
+index, a rename collision, a table losing tenant isolation) stops the boot with the suggested statements — write a
+migration (`migrate create <name> --sql`, `runSqlMigration()`). Declare a renamed field with
+`@UnifiedField({ renamedFrom: 'oldName' })`. Never enable an engine's own `synchronize` or migration generator.
+
+On MySQL / MariaDB a text field that is part of an index is `varchar(255)` (a longer value: 400), every other text
+`longtext` — so adding an index to an existing text field is a type change. An index over more than 3072 bytes indexes a
+prefix when it is a lookup index and is refused when unique. DDL commits on its own there: a run is serialized by
+`GET_LOCK`, not a transaction, and a failed change leaves the statements before it applied.
+
+## Updates on MySQL / MariaDB
+
+Two operators on one path, or on a path and a path inside it, are refused (`Updating the path … would create a
+conflict`) — MongoDB's own rule; PostgreSQL chains them. Write such an update as one operator per path.
+
+On every SQL database a path segment `__proto__`, `constructor` or `prototype` is refused: a compiler that builds an
+object from path segments would otherwise reach `Object.prototype` — on MySQL that switched tenant isolation off for the
+whole process. Never build an update path from request data without validating it against the model.
+
+## Tests
+
+A suite proves a behaviour on both databases: the `e2e` vitest project runs it on MongoDB, the `postgres` project on
+PostgreSQL (`.claude/rules/testing.md`). MySQL and MariaDB are proven through the matrices (persistence, core modules,
+where parity) and their own suites, not by a third run of the whole e2e suite. Read and prepare data through `tests/helpers/iam-test-db.ts` or the
+application's stores — never through a MongoDB client of the suite's own, which reads the wrong database on
+PostgreSQL. A contract with several implementations is a matrix (`tests/helpers/persistence-matrix.ts`).

package/.claude/rules/role-system.md

@@ -417,6 +417,15 @@ otherwise lets the role guard check `user.roles` — fail-closed, warned once. P
 **Configured is not registered.** When you add a guard that delegates to another one, ask whether
 the other one RUNS, not whether it is configured.
 
+**Registered is not ordered (DEV-3830).** Global guards run in registration order, and `CoreModule` registers
+`CoreTenantModule` ahead of a project's `AuthModule` — so with legacy JWTs (no middleware identifies them) the tenant
+guard ran before the role guard, found nobody on the request and answered every tenant route with 401. Never noticed
+because every multi-tenant suite signed in through IAM, where the middleware sets the user first. The tenant guard now
+lets the application's role guard identify the caller when nobody is on the request yet (`ROLE_GUARD` token, provided by
+the module that registers the role guard, resolved through `ModuleRef` so it is always THIS application's guard). The
+role guard then runs twice on such a request; it is stateless, and its 401/403 is the answer either way. Pinned by
+`tests/core-module-parity.e2e-spec.ts` (mutation `tenant-guard-before-identification`).
+
 ## Every entry point, not just the route (11.42.0)
 
 A `@Roles()` decides who may call a ROUTE. An operation is also reached from MCP tools, AI tools,
@@ -484,6 +493,15 @@ socket therefore ends with its token: at expiry or at the next token refresh.
 **A guard that asks "is this request allowed?" once is not enough for a connection that outlives the
 answer.** When you add a long-lived channel (SSE, a WebSocket of your own), register it the same way.
 
+**Refusing the handshake itself (12.0.0).** `onConnect` refuses a missing or non-authenticating credential with
+`return refuseWsHandshake(extra.socket, reason)` — close code **4401**, which the graphql-ws client does not retry.
+Never by throwing: graphql-ws's ws adapter answers a throw with 4500 and logs "Internal error occurred during
+message handling. Please check your implementation." (until 12.0.0 that happened for every expired token). Never
+by a bare `false`: that closes with 4403, which the client RETRIES — with the same refused credential. 4403 stays
+reserved for a socket whose rights changed while it was open (above). Pinned by
+`tests/subscription-session-iam.e2e-spec.ts` / `tests/subscription-session-legacy.e2e-spec.ts` (mutations
+`iam-ws-handshake-refusal-throws`, `legacy-ws-handshake-refusal-throws`).
+
 ## Role Check Implementation
 
 The role system is evaluated in: