@lenne.tech/nest-server 11.32.4 → 11.33.1

package/migration-guides/11.32.x-to-11.33.x.md

@@ -0,0 +1,1584 @@
+# Migration Guide: 11.32.x → 11.33.x
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | **File downloads, the file GraphQL members and TUS uploads are no longer public (§A, §B) — this one affects every project, not just multi-replica ones.** `CoreBetterAuthRateLimiter` and `LegacyAuthRateLimiter`: `check()` / `reset()` / `clear()` are **async** now (§1). Hub collector reads are async (§2). `getFileStream()` / `getFileStreamByName()` are typed `Readable` instead of `GridFSBucketReadStream` (§3) |
+| **New Features** | `file.downloadRoles` / `uploadRoles` / `deleteRoles` and `tus.roles`; per-file authorization via `checkRights()` with real metadata support (§A). Optional central `redis` (rate limits, cron dedup, GraphQL subscriptions, tenant-cache invalidation, MCP session registry, Hub collectors); optional `s3`; three file storage drivers via `file.storage` (`'filesystem'` is new) with a derived default and fail-fast enforcement; `tus.s3Staging`; `shutdownDelayMs`; `trustProxy` (§11c — **configure it if you rate-limit behind a reverse proxy**); per-job cron `distributed`; `multerFileToUpload()` for REST uploads into central storage |
+| **Behaviour Changes** | The migration lock is **on by default** for `migrate up` (§4). Initial-admin auto-creation takes an atomic claim (§5). The `src/server` reference implementation stores avatars and GraphQL uploads in the central file storage instead of pod-local disk (§10) |
+| **Bugfixes** | Migration lock gained heartbeat + stale-break + bounded wait; `runOnInit` cron dedup no longer keyed on each replica's boot clock and no longer crashes the process on a failed startup run; BullMQ worker no longer swallows a tick delivered during bootstrap; rate limiters degrade instead of 500-ing on a Redis outage; Hub buffer mirror failures no longer recurse through the Logger they buffer; the email-verification cooldown timer can no longer expire a later cooldown early; a presigned S3 download no longer serves the file under a different name than the streamed one (§14) |
+| **Under the hood (§14)** | Two new MongoDB collections (`s3-files`, `filesystem-files` — include them in backups), new public exports, a bucket-less `s3` block is now ignored, NestJS 11.1.28 → 11.1.29, plus two dependency MAJORS: `js-sha256` 0.12.0 → 1.0.0 (**digests unchanged — no password-hash break**) and `graphql-query-complexity` 1.1.1 → 2.0.0 |
+| **Dependency Housekeeping** | The framework's own `pnpm audit` went from 20 findings to 0. Those are `pnpm-workspace.yaml` overrides, which **do not reach npm consumers** — run your own audit (§13) |
+| **Migration Effort** | **Start with §A and §B — they are the only changes that can break a single-replica project, and they break it silently** (no crash, just 401/403 on `/files/**` and `/tus`). Then **§11a / §11b if your config already contains a `redis` or an `s3` key** — the framework reads both now, and an existing `s3` key makes the boot FAIL until you act. Everything else is opt-in: read §1 if you call or override the rate limiters, §2 if you override Hub services, §4 before your next multi-replica deploy, §10 if you copied the avatar upload from `src/server`, **§11c if you rate-limit behind a reverse proxy** (a boot warning will tell you), §13 for what the security overrides do and do not do for you |
+
+Most of this release exists to make one deployment shape possible: **more than one replica**. Nothing there is required to keep running on one.
+
+**Two changes are different and apply to every project: §A and §B.** The file endpoints and TUS were
+public by default and are not any more. Read those two first.
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.33.0
+pnpm run build
+pnpm test
+```
+
+No configuration change is required for the multi-replica features, and no new package needs
+installing unless you opt into one (see §12). **§A and §B are the exception** — if your project
+serves files to non-admins or accepts anonymous uploads, they need action.
+
+**Vendor-mode projects, before you start:** if your vendored baseline is older than 11.32.0, check
+your `@getbrevo/brevo` pin. The core's `common/services/brevo.service.ts` was rewritten for the
+Brevo SDK **v6** (`BrevoClient`, `transactionalEmails.sendTransacEmail()`); none of that API exists
+in v3/v5, so syncing the file onto an older pin leaves a core that neither type-checks nor runs.
+Bump to `6.0.2` in the same change. This bites only vendor mode — npm consumers get the version
+through the package's own dependency. Found by syncing a real project pinned at `3.0.4`.
+
+**Vendor-mode projects:** this is a large sync. All **14** newly added code files under `src/core/`:
+
+```
+common/helpers/graceful-shutdown.helper.ts
+common/helpers/project-name.helper.ts
+common/services/core-cron-jobs.initializer.ts
+common/services/core-cron-jobs.registry.ts
+common/services/core-redis-pubsub.ts
+common/services/core-redis.service.ts
+common/services/core-s3.service.ts
+common/services/rate-limit-store.ts
+modules/file/file-roles.helper.ts
+modules/file/file-storage.helper.ts
+modules/file/filesystem-file.helper.ts
+modules/file/s3-file.helper.ts
+modules/hub/hub-buffer.ts
+modules/tus/tus-redis-locker.ts
+```
+
+Plus one new documentation file, `modules/file/INTEGRATION-CHECKLIST.md`, which carries no code and
+can be taken separately.
+
+All **33** modified code files under `src/core/` (plus the two top-level files `src/index.ts` and
+`src/core.module.ts`):
+
+```
+common/helpers/file.helper.ts
+common/interfaces/cron-job-config.interface.ts
+common/interfaces/server-options.interface.ts
+common/services/core-cron-jobs.service.ts
+modules/ai/core-ai-mcp.controller.ts
+modules/ai/services/core-ai.service.ts
+modules/auth/core-auth.module.ts
+modules/auth/guards/legacy-auth-rate-limit.guard.ts
+modules/auth/services/legacy-auth-rate-limiter.service.ts
+modules/better-auth/core-better-auth-email-verification.service.ts
+modules/better-auth/core-better-auth-rate-limit.middleware.ts
+modules/better-auth/core-better-auth-rate-limiter.service.ts
+modules/better-auth/core-better-auth-user.mapper.ts
+modules/file/core-file.controller.ts
+modules/file/core-file.resolver.ts
+modules/file/core-file.service.ts
+modules/file/interfaces/file-service-options.interface.ts
+modules/file/interfaces/file-upload.interface.ts
+modules/hub/core-hub.controller.ts
+modules/hub/services/core-hub-mailbox.service.ts
+modules/hub/services/hub-log-buffer.service.ts
+modules/hub/services/hub-query-profiler.service.ts
+modules/hub/services/hub-trace-buffer.service.ts
+modules/migrate/helpers/migration.helper.ts
+modules/migrate/migration-runner.ts
+modules/migrate/mongo-state-store.ts
+modules/system-setup/core-system-setup.service.ts
+modules/tenant/core-tenant.guard.ts
+modules/tenant/core-tenant.module.ts
+modules/tus/core-tus.controller.ts
+modules/tus/core-tus.service.ts
+modules/tus/interfaces/tus-config.interface.ts
+modules/tus/tus.module.ts
+```
+
+Six `README.md` files also changed (`modules/ai`, `modules/file`, `modules/hub`, `modules/migrate`,
+`modules/system-setup`, `modules/tus`). Those are documentation-only and safe to take separately.
+
+**Also removed from `src/core/`:** every co-located `*.spec.ts` (they moved to `tests/unit/`, since
+`src/` is what ships in the tarball and what vendor mode copies verbatim). A sync that only *adds*
+and *updates* leaves those orphans behind in your tree, where they reference helpers that no longer
+sit next to them. Delete any `src/core/**/*.spec.ts` your baseline still has.
+
+**This sync has an atomic file-set hazard**, and the four files most easily missed are exactly the
+ones that break the build:
+
+| Missing file | Breaks |
+|--------------|--------|
+| `common/helpers/project-name.helper.ts` | `common/services/core-redis.service.ts` (default `keyPrefix`) |
+| `modules/file/file-storage.helper.ts` | `modules/file/core-file.service.ts`, `modules/tus/core-tus.service.ts` |
+| `modules/file/filesystem-file.helper.ts` | `modules/file/core-file.service.ts`, `modules/tus/core-tus.service.ts` |
+| `modules/file/file-roles.helper.ts` | `src/core.module.ts` |
+
+The same applies to the services: adopting
+`modules/auth/services/legacy-auth-rate-limiter.service.ts` without
+`common/services/rate-limit-store.ts` and `common/services/core-redis.service.ts` does not compile.
+Take the whole code set or none of it.
+
+---
+
+## A. Breaking: file downloads, uploads and the GraphQL members are role-gated
+
+Six members moved from `@Roles(RoleEnum.S_EVERYONE)` to a configurable role list, defaulting to
+`[RoleEnum.ADMIN]`:
+
+| Member | Kind | Now gated by |
+|--------|------|--------------|
+| `GET /files/id/:id` | REST | `file.downloadRoles` |
+| `GET /files/:filename` | REST | `file.downloadRoles` |
+| `getFileInfo` | GraphQL query | `file.downloadRoles` |
+| `uploadFile` | GraphQL mutation | `file.uploadRoles` |
+| `uploadFiles` | GraphQL mutation | `file.uploadRoles` |
+| `deleteFile` | GraphQL mutation | `file.deleteRoles` |
+
+`S_EVERYONE` was not merely permissive. The roles guard treats it as an unconditional `return true`
+**before authenticating at all**, and because handler and class roles are UNIONed rather than
+overridden, the handler-level `S_EVERYONE` silently defeated the class-level `@Roles(ADMIN)` both
+classes already carried. `deleteFile` was reachable anonymously.
+
+**Symptom if you skip this:** no crash, no error — `401`/`403` on `/files/**`, showing up as broken
+images and empty avatars.
+
+### A.1 — Check your own controller FIRST
+
+If your `FileController` re-declares the roles, your downloads were never affected by the old
+default and are still public today:
+
+```typescript
+// If you find THIS, the config below will not reach these routes:
+@Get('id/:id')
+@Roles(RoleEnum.S_EVERYONE)
+override async getFileById(@Param('id') id: string, @Res() res: Response): Promise<Response> {
+  return super.getFileById(id, res);
+}
+```
+
+Role metadata lives on the **function object**, so an override carries its own and opts out of
+`file.downloadRoles` permanently. Delete such overrides and configure the roles instead.
+
+Two further consequences:
+
+- An override that omits `@Get(...)` **unregisters the route** — Nest finds no `PATH_METADATA` on the
+  subclass function and never maps it. 404 for everyone, no error, no warning.
+- A class-level `@Roles()` on your subclass **cannot** relax an inherited member, because the
+  inherited function carries its own handler-level roles and the two are unioned.
+
+`nest-server-starter` shipped exactly this override — added only to attach Swagger annotations — and
+is corrected in the same release.
+
+### A.2 — Configure
+
+```typescript
+// src/config.env.ts
+file: {
+  downloadRoles: [RoleEnum.ADMIN],  // default
+  uploadRoles:   [RoleEnum.ADMIN],  // default
+  deleteRoles:   [RoleEnum.ADMIN],  // default
+},
+```
+
+Plain role strings, so project-specific roles work: `downloadRoles: ['company-admin', 'editor']`.
+
+- **ADMIN always keeps access** (the class-level `@Roles(ADMIN)` is unioned in). These knobs cannot
+  exclude admins.
+- **`[]` 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.
+- Roles resolve against `user.roles`, never `membership.role`: both classes now carry
+  `@SkipTenantCheck()`. GridFS and the S3 metadata collection are reached outside Mongoose, so
+  `mongooseTenantPlugin` never scopes them — a role name alone cannot express a per-tenant rule.
+
+### A.3 — The better answer: authorize per file
+
+The real requirement is usually "which files", not "which roles". Write an owner at upload time and
+decide per file:
+
+```typescript
+await this.fileService.createFile(file, { metadata: { ownerId: currentUser.id } });
+
+export class FileService extends CoreFileService {
+  protected override async checkRights(
+    input: any,
+    options?: FileServiceOptions & { checkInputType: FileInputCheckType },
+  ): Promise<boolean> {
+    // Writes, list queries and forced (system) calls stay on the coarse role gate
+    if (options?.force || (options?.checkInputType !== 'filename' && options?.checkInputType !== 'id')) {
+      return true;
+    }
+    if (options.currentUser?.hasRole?.([RoleEnum.ADMIN])) {
+      return true;
+    }
+    const raw = options.checkInputType === 'id'
+      ? await this.getRawFileInfo(input)
+      : await this.getRawFileInfoByName(input);
+    // Fails closed without a user, and on a file that records no owner.
+    return !!raw?.metadata?.ownerId && String(raw.metadata.ownerId) === String(options.currentUser?.id);
+  }
+}
+```
+
+**Cover the `filename` branch, not only `id`.** An id-only rule is enough while bytes are streamed —
+the filename route resolves an id and checks it again — but not once `s3.presignedDownloads` is on
+(the filename route then authorizes on the by-name lookup alone and redirects), and not for
+`deleteFileByName()`, which authorizes by name only. This is not hypothetical: 11.33.0 shipped a
+`deleteFileByName()` that authorized the caller and then re-resolved the file with an EMPTY context,
+so an overridden `checkRights()` was asked two different questions about one request and the owner
+got `File not found` for their own file. Both halves — the by-name branch and the forwarding — are
+covered by the reference server as of the next release.
+
+**Do not add an `if (!options.currentUser) return true` branch.** It reads as "system-internal call,
+the guard already decided", and that is not what it means: "no user in context" is also exactly what
+an ANONYMOUS request looks like. While `downloadRoles` is narrower than `S_EVERYONE` the coarse gate
+rejects those first and the branch looks harmless — widen the gate, which §A.2 explicitly offers, and
+the same branch hands every file to everyone. The ownership rule then evaporates precisely when it
+starts to matter. For the same reason the final comparison requires `metadata.ownerId` to be
+**present**: `String(undefined) === String(undefined)` would match an owner-less file against an
+absent user.
+
+Callers that genuinely are internal should say so, rather than relying on the omission:
+`{ force: true }` where a role decorator has already decided (an `@Roles(ADMIN)` admin endpoint), or
+the real `{ currentUser }` where the user is in scope (a controller cleaning up a file it just
+replaced — that delete should be COVERED by the ownership rule, not exempt from it). The reference
+server does both; see `src/server/modules/file/` and `src/server/modules/user/avatar.controller.ts`.
+
+The reference server also **runs** the rule above rather than documenting it: `src/config.env.ts`
+sets `file: { downloadRoles: [RoleEnum.S_USER] }` in every environment and
+`src/server/modules/file/file.service.ts` implements `checkRights()`. Copy from there — it is
+compiled and exercised by the test suite; this guide is not.
+
+Three new pieces make this possible, and all three were missing before: `createFile()` now forwards
+`serviceOptions.metadata` to storage; `getRawFileInfo()` / `getRawFileInfoByName()` read the raw
+document (the public `getFileInfo()` runs `prepareOutput` → `check()` and strips the very field the
+decision rests on); and the core controller and resolver now pass `currentUser` into every service
+call. `getRawFileInfo()` checks S3 metadata first, then the **filesystem** store, then GridFS — all
+three stores, in the same order as `getFileInfo()`, so a rule sees the file the download would
+actually serve (§7). Omitting a store from your own version of this lookup is not a cosmetic
+difference: the rule then decides on a document that is not the one being served.
+
+With that in place, `downloadRoles: [RoleEnum.S_USER]` means "signed-in users may fetch **their
+own** files" rather than "everything in the bucket".
+
+A refused `checkRights()` answers **404**, deliberately the same as an unknown id, so the endpoint
+cannot be used to probe which files exist.
+
+### A.4 — Browser `<img>` / `<a download>`, and presigned URLs
+
+Markup-driven requests cannot send an `Authorization` header, and a CORS preflight sends no
+credentials. Anything stricter than `S_EVERYONE` therefore only works from markup when the session
+travels as a **cookie** on a same-site request. If your frontend is Bearer-only, gated file URLs
+will not render in markup at all — fetch them programmatically and build an object URL, or expose a
+separate public route for exactly the files meant to be public.
+
+If you enable presigned S3 downloads (§7), note that the issued URL is a **bearer capability**:
+anyone holding it can fetch the object until it expires, with no session. Authorization happens once,
+when the URL is issued. Keep the expiry short, and do not enable it for files whose audience is
+narrower than "anyone who was ever given the link".
+
+### A.5 — Also new: `Cache-Control: private, no-store` on downloads
+
+An authorization-gated response with no cache directive may be stored by a shared cache under
+RFC 9111 — a reverse proxy or CDN with a blanket `/files/*` rule could hand an authorized response to
+the next, unauthorized requester. **Review any CDN rule you have on `/files/*`.** Override
+`setFileHeaders()` on your controller if you serve genuinely public, cacheable assets.
+
+### A.6 — Fix your tests
+
+```typescript
+const res = await testHelper.download(`/files/id/${id}`, { token: adminToken });
+expect(res.statusCode).toEqual(200);
+
+expect((await testHelper.download(`/files/id/${id}`)).statusCode).toEqual(401);           // anonymous
+expect((await testHelper.download(`/files/id/${id}`, { token: userToken })).statusCode)
+  .toEqual(403);                                                                           // no right
+```
+
+Assert the exact code, not `[401, 403]` — SPA auth layers branch on 401 to trigger logout, so
+conflating them hides a real regression.
+
+---
+
+## B. Breaking: TUS uploads require a session
+
+`tus.roles` now defaults to `[RoleEnum.S_USER]`; it was `S_EVERYONE`.
+
+A TUS upload writes into the **same file store** the download routes guard — GridFS or S3, whichever
+`file.storage` selects — and the termination extension (on by default) can delete from it. Anonymous
+writes into a store only privileged callers may read is the wrong way round.
+
+```typescript
+tus: { roles: [RoleEnum.S_USER] },          // default
+tus: { roles: [RoleEnum.S_EVERYONE] },      // opt back in to anonymous uploads
+tus: { roles: ['editor', 'contributor'] },  // project-specific roles work too
+```
+
+**If you accept attachments on a public form, you must set `S_EVERYONE` explicitly** — a public
+support or contact form with file upload is the common case, and it breaks at the very first
+request otherwise.
+
+`roles: []` is rejected with a warning rather than honoured, for the same reason as in §A.2.
+
+`OPTIONS` stays public regardless: it is the CORS preflight, which browsers send without
+credentials, and it returns only server capabilities. Gating it would make every browser upload fail
+before it starts.
+
+**Watch the pairing with §A.** `tus.roles` and `file.downloadRoles` are separate, so with both at
+their defaults a signed-in user may upload but cannot read the result back. Either widen
+`downloadRoles`, or — better — write an owner into the metadata at upload time and authorize per
+file (§A.3). TUS uploads already carry `metadata.tusUploadId` and the original TUS metadata, so
+there is a natural place for it.
+
+---
+
+## 1. Breaking: the rate limiters are async
+
+**What changed:** `check()`, `reset()` and `clear()` on `CoreBetterAuthRateLimiter` and
+`LegacyAuthRateLimiter` return promises now. Their counters moved behind a `RateLimitStore`
+abstraction so the same code can count in a process-local `Map` (unchanged behaviour) or in Redis
+(shared across replicas).
+
+This is the reason this release is a MINOR rather than a PATCH.
+
+**Who is affected:** only projects that call these methods directly or override the classes. The
+framework's own callers — `LegacyAuthRateLimitGuard.canActivate()` and
+`CoreBetterAuthRateLimitMiddleware.use()` — were made async in the same commit, so an untouched
+project needs no change.
+
+**Before:**
+
+```typescript
+const result = this.rateLimiter.check(ip, '/iam/sign-in');
+if (!result.allowed) {
+  throw new HttpException(this.rateLimiter.getMessage(), HttpStatus.TOO_MANY_REQUESTS);
+}
+
+// e.g. in a test teardown
+rateLimiter.clear();
+rateLimiter.reset('127.0.0.1');
+```
+
+**After:**
+
+```typescript
+const result = await this.rateLimiter.check(ip, '/iam/sign-in');
+if (!result.allowed) {
+  throw new HttpException(this.rateLimiter.getMessage(), HttpStatus.TOO_MANY_REQUESTS);
+}
+
+await rateLimiter.clear();
+await rateLimiter.reset('127.0.0.1');
+```
+
+If you **override** one of these methods, the override must return a promise as well, and a guard or
+middleware that called it must be made `async`:
+
+```typescript
+// Before
+export class MyRateLimitGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const result = this.rateLimiter.check(ip, endpoint);
+    // ...
+  }
+}
+
+// After
+export class MyRateLimitGuard implements CanActivate {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const result = await this.rateLimiter.check(ip, endpoint);
+    // ...
+  }
+}
+```
+
+`getMessage()`, `isEnabled()`, `configure()` and `getStats()` are unchanged and still synchronous.
+
+**One nuance in `getStats()`:** `activeEntries` is `-1` when the Redis store is in use — Redis does
+not know the count cheaply, and reporting `0` would read as "no one is rate limited". Without Redis
+it is the map size, exactly as before.
+
+**The AI module's per-user limit** moved to the same store, but
+`CoreAiService.checkRateLimit()` was already `async` before this release — a project that overrode
+it needs no change. The new `protected getRateLimitStore()` is the extension point if you want to
+substitute a store.
+
+**On a Redis outage the limiters do not fail requests.** `RedisRateLimitStore` degrades to a
+process-local in-memory counter and logs once, then logs again on recovery. Both alternatives are
+worse: letting the error escape turns every sign-in and password-reset into a 500 for the duration
+of a blip, and treating the error as "allowed" silently removes brute-force protection. Degrading
+keeps a real bound — the per-replica one that applied before Redis existed.
+
+---
+
+## 2. Breaking: Hub collector reads are async
+
+**What changed:** the Hub's diagnostic buffers gained an optional Redis mirror, so reading them is
+now an I/O operation:
+
+| Class | Method | Now returns |
+|-------|--------|-------------|
+| `HubLogBufferService` | `getData(since?)` | `Promise<HubLogsData>` |
+| `HubTraceBufferService` | `getData(since?)` | `Promise<HubTracesData>` |
+| `HubQueryProfilerService` | `getData()` | `Promise<HubQueriesData>` |
+| `CoreHubMailboxService` | `getMailbox(since?)` | `Promise<HubMailboxData>` |
+| `CoreHubMailboxService` | `getMailHtml(seq)` | `Promise<string \| undefined>` |
+| `CoreHubController` | `logsJson` / `tracesJson` / `queriesJson` / `mailboxJson` / `mailboxHtml` / `diagnosticsJson` | `Promise<void>` |
+| `CoreHubController` | `protected collectorBuffers()` | `Promise<Record<…>>` |
+
+**Who is affected:** only projects that pass a `hub: { controller, service, htmlService, … }` override
+to `CoreModule.forRoot()` and override one of these methods. Everyone else sees no change — the Hub
+keeps working identically, and without Redis every buffer is still the same process-local ring buffer.
+
+**Action:** `await` the call in your override and widen its return type to a promise.
+
+**`captureAndGetSeq()` caveat:** it still returns the **process-local** seq synchronously. When the
+mailbox is Redis-backed, the seq that the panels and `getMailHtml()` use comes from the shared
+counter and will differ. Read it from `getMailbox()` instead of assuming the returned value.
+
+---
+
+## 3. Breaking (type level only): file stream return types widened
+
+`CoreFileService.getFileStream()` and `getFileStreamByName()` are declared `Promise<Readable>`
+instead of `Promise<mongo.GridFSBucketReadStream>`, because an S3-stored file returns an SDK stream
+rather than a GridFS one. At runtime nothing changes for a GridFS-backed project — the same object
+comes back.
+
+**Action:** only if you annotated a variable with the concrete type:
+
+```typescript
+// Before
+const stream: mongo.GridFSBucketReadStream = await this.fileService.getFileStream(id);
+
+// After
+import { Readable } from 'stream';
+const stream: Readable = await this.fileService.getFileStream(id);
+```
+
+`createFile()` / `createFiles()` accept the new, narrower `FileUploadSource` interface instead of
+`FileUpload`. That is a **widening** of what they accept: `FileUpload` now extends
+`FileUploadSource`, so every existing caller still type-checks. It exists so a multer REST upload
+(which has no graphql-upload `capacitor`) can use the same service method — see §10.
+
+`CoreFileService`'s protected constructor gained an optional third parameter
+(`options?: CoreFileServiceOptions`). Existing `super(connection)` and `super(connection, 'fs')`
+calls compile unchanged; you only pass it to enable S3 (§7).
+
+---
+
+## 4. The migration lock is active by default
+
+**What changed:** `createMigrationStore()` now defaults its third parameter, `lockCollectionName`,
+to `'migrations_lock'`, and `MigrationRunner.up()` — what the `migrate up` CLI command runs —
+acquires that lock around the whole run.
+
+**Why it matters, in deployment terms:** the container entrypoint runs migrations on **every** boot.
+Without a lock, N replicas starting together each read the same empty state, each decide the same
+migration is pending, and each apply it. A migration that inserts seed data inserts it N times; one
+that is not idempotent corrupts on the second run.
+
+With the lock, the replicas that lose the race wait, then re-read the migration state **inside** the
+lock and find nothing pending. Reading inside the lock is the part that makes it correct — a waiter
+that re-used a state snapshot taken before the wait would apply the migrations a second time.
+
+**With a single replica nothing changes.** The lock is acquired and released uncontended, costing one
+insert and one delete per boot.
+
+**What the lock does when a holder dies.** Migrations run on every boot, so a lock nobody holds is not
+a rare event — a container SIGKILLed mid-migration (OOM, node drain, failed deploy) leaves one behind,
+and without recovery every future boot of every replica would wait on it forever. Three mechanisms
+prevent that:
+
+| Mechanism | Value | Meaning |
+|-----------|-------|---------|
+| Heartbeat | every **15 s** | The holder refreshes `acquiredAt` while it works |
+| Stale threshold | **60 s** without a heartbeat | Another replica may break and take over the lock |
+| Wait timeout | **15 minutes** | A waiter gives up with a diagnosable error rather than hanging forever |
+
+The heartbeat is what makes breaking safe: a lock is only ever broken when its holder **stopped
+refreshing it**, which a live process cannot do. A migration that legitimately runs for hours keeps
+its lock the whole time — the 60 s threshold is not a cap on migration runtime. The break itself
+matches on the exact `acquiredAt` it observed, so if another waiter already broke and re-acquired the
+lock, the delete matches nothing.
+
+**If the wait ever times out**, the error names the collection so you can inspect it:
+
+```
+Timed out after 15 minutes waiting for the migration lock in collection "migrations_lock".
+Another replica is still migrating, or the lock is held by a process that is alive but stuck.
+Inspect it with: db.getCollection("migrations_lock").find({}) — and remove the document only
+once you are sure no migration is running.
+```
+
+Manual recovery:
+
+```javascript
+// 1. Look at the holder. `owner` is "<hostname>:<pid>" and `acquiredAt` is the last heartbeat.
+db.getCollection('migrations_lock').find({})
+
+// 2. Confirm no migration is actually running (check the pod/container named by `owner`).
+// 3. Only then:
+db.getCollection('migrations_lock').deleteOne({ lock: 'lock' })
+```
+
+**Opting out** — a project that deliberately wants unsynchronised migrations passes an empty string:
+
+```javascript
+// migrations/state-store.js
+module.exports = createMigrationStore(uri, 'migrations', ''); // no locking
+```
+
+A `MongoStateStore` constructed **directly** is unaffected: it still locks only when you pass
+`lockCollectionName` yourself. The default lives in `createMigrationStore()`. The legacy
+`synchronizedMigration()` / `synchronizedUp()` helpers use the same lock and still require the name
+to be set explicitly (they throw otherwise).
+
+---
+
+## 5. Initial-admin auto-creation takes an atomic claim
+
+**What changed:** `systemSetup.initialAdmin` auto-creation guarded itself with a zero-user check.
+That is check-then-act: N replicas booting together each see zero users and each proceed. Before
+creating, an instance now claims the setup by upserting `{ _id: 'initial-admin' }` into a
+`system-setup-locks` collection — an atomic operation exactly one instance wins. The others log a
+debug line and skip. If creation then fails, the marker is removed so a later boot can retry.
+
+**Action: none.** The unique email index already prevented duplicate *users*; this removes the noisy
+failures and the ambiguity about which replica actually did the setup. A new collection
+`system-setup-locks` appears in the database with a single small document.
+
+---
+
+## 6. New: optional central Redis
+
+```typescript
+// config.env.ts
+{
+  redis: true,                                   // localhost:6379, db 0, keyPrefix = your package name
+  // or
+  redis: { host: 'redis', port: 6379, keyPrefix: 'my-app' },
+  // or
+  redis: { url: 'redis://user:pass@redis:6379/0' },
+  // pre-configured but off:
+  redis: { enabled: false, host: 'redis' },
+}
+```
+
+Full shape: `url` **or** `host`/`port`/`username`/`password`/`db`, plus `keyPrefix`, `enabled` and
+`options` (passed through to `ioredis`, e.g. `maxRetriesPerRequest`).
+
+Two of these matter more than they look:
+
+- **`db`** — picks the numbered Redis database. Sharing one Redis instance between environments
+  without separating them is how a staging deploy flushes production's rate-limit counters.
+- **`keyPrefix`** — namespaces every key this application writes. Two deployments on one Redis with
+  the same prefix invalidate each other's tenant caches and share each other's cron leases. It
+  defaults to the project slug, so distinct projects are already separated; two STAGES of the same
+  project are not, unless you set it (or `db`).
+
+**ioredis 5 and 6 both work.** The peer range deliberately spans both majors, so a project
+already using ioredis 5 for its own code does not have to jump. Note that **6 defaults to the RESP3
+wire protocol** where 5 used RESP2; every framework path (rate-limit counters, cron leases, tus
+locks, pub/sub, Hub buffers) is exercised against 6 in CI. If something in your infrastructure
+cannot speak RESP3 — an older proxy, for instance — pin the protocol through the pass-through
+options:
+
+```typescript
+redis: { host: 'redis', options: { protocol: 2 } },
+```
+
+Follows "presence implies enabled": **no `redis` key means no Redis**, and every feature below keeps
+its process-local behaviour. Requires the optional peer dependency `ioredis` (§12); when `redis` is
+configured and the package is missing, the boot **fails fast** with an actionable error rather than
+crashing later on first use.
+
+What switches on when Redis is enabled — all of it automatically, with no further config:
+
+| Feature | Without Redis | With Redis |
+|---------|---------------|------------|
+| Auth + AI rate limits | Counter per replica, so the effective limit is `max × replicas` | Shared counters, `max` enforced exactly |
+| Cron jobs | Every replica runs every tick | Deduplicated — see §9 |
+| GraphQL subscriptions | Delivered only to clients connected to the publishing replica | Delivered cluster-wide (`CoreRedisPubSub` replaces the in-memory `PubSub`) |
+| Tenant membership cache | `invalidateUser()` clears only the local cache; other replicas stay stale until `cacheTtlMs` | Invalidation is broadcast to all replicas |
+| Hub collectors | Each pod shows only its own logs/traces/queries/mails | Merged cluster-wide view, "clear" clears everywhere |
+| MCP sessions | Wrong-replica request answers `404 Unknown or expired MCP session` | Answers `409` naming both instances — sticky sessions are still **required**, the failure just stops looking like an expiry bug |
+
+**GraphQL subscription payloads must be JSON-serialisable** once Redis is in play — they go over the
+wire as JSON. Class instances, `Date` objects, `Map`/`Set` and `undefined` values do not survive the
+round trip. An in-process `PubSub` never had this constraint, so a payload that worked on one replica
+can lose fields on a cluster. Publish plain objects and ISO strings.
+
+`keyPrefix` (default: your `package.json` name, slugified — `@acme/api` → `acme-api`) is applied by
+the framework per key, not via ioredis's own
+`keyPrefix` option — that would conflict with BullMQ's prefix handling. Set it when several
+applications share one Redis instance.
+
+`CoreRedisService` is exported and provided by `CoreModule`, so you can inject it for your own keys:
+
+```typescript
+constructor(@Optional() private readonly redis?: CoreRedisService) {}
+
+async cacheSomething(): Promise<void> {
+  if (!this.redis?.enabled) {
+    return; // keep a non-Redis fallback — the framework does the same everywhere
+  }
+  await this.redis.getClient().set(this.redis.key('my-feature', 'thing'), '1', 'EX', 60);
+}
+```
+
+Use `getSubscriber()` for pub/sub (a subscribing client cannot run other commands) and
+`createClient(label)` for a dedicated connection. All connections are tracked and quit on shutdown.
+
+---
+
+## 7. New: three file storage drivers (S3, GridFS, filesystem)
+
+`file.storage` picks where the bytes live: `'s3'`, `'gridfs'` or `'filesystem'`. All three offer the
+same operations through `CoreFileService`.
+
+**Left unset it is derived**, most capable first: `'s3'` when `s3.bucket` is configured, else
+`'gridfs'` when a database is, else `'filesystem'`. **An existing project keeps GridFS** — it has no
+`s3` block, so the cascade lands on step 2, exactly where it was before.
+
+**Set it and it is enforced.** If the chosen store is unavailable the boot FAILS:
+
+```
+file.storage is set to 's3', but that storage is not available.
+Configure `s3` (bucket, credentials/endpoint) and install `@aws-sdk/client-s3`, …
+```
+
+This replaces a silent fallback to GridFS. The old behaviour kept the app running while files landed
+in a store the operator did not believe they were in — and afterwards nobody can tell which file went
+where. A derived driver is enforced the same way: `s3.bucket` in the config makes S3 the default, but
+the bytes go nowhere unless your `FileService` forwards the services to `super()` (see below).
+
+**Metadata always lives in the database**, whichever driver holds the bytes — filename, content type,
+length and the custom `metadata` a per-file rule reads have to stay queryable. `'filesystem'` moves
+the bytes off the database, not the bookkeeping.
+
+**`'filesystem'` is pod-local.** Not shared between replicas, lost on restart unless `storageDir` is a
+mounted volume. Right for a single instance or a real volume; wrong for a scaled service.
+
+**Switching is forward-only.** Reads consult every store, so files written under a previous driver
+stay readable — no migration step, no cut-over. The driver in use is logged at boot:
+`[CoreFileStorage] File storage: s3 (defaulted — s3.bucket is configured)`.
+
+```typescript
+// config.env.ts
+{
+  file: {
+    storage: 's3',                         // omit to derive it
+    storageDir: 'uploads/files',           // only for 'filesystem'
+  },
+  s3: {
+    bucket: 'my-app-files',
+    region: 'eu-central-1',
+    // self-hosted (MinIO, RustFS):
+    endpoint: 'http://minio:9000',
+    forcePathStyle: true,
+    accessKeyId: '…',                      // omit to use the AWS default credential chain
+    secretAccessKey: '…',
+    presignedDownloads: { expiresInSeconds: 300 },   // or `true` for the 300 s default
+    stagingBucket: 'my-app-tus',           // defaults to `bucket`
+    autoCreateBucket: false,               // default: false
+  },
+}
+```
+
+**`autoCreateBucket`** creates a missing bucket at boot instead of only reporting it. Off by default
+for a reason: managed S3 credentials usually carry no `CreateBucket` permission, and silently
+creating a bucket because of a typo in the name is worse than a clear error. Turn it on for a
+self-hosted MinIO/RustFS, where provisioning the bucket by hand is the only alternative.
+
+**`enabled: false`** pre-configures S3 without activating it — the same "presence implies enabled"
+shape the rest of the config uses.
+
+**A block without `bucket` is ignored entirely** (with a warning), since a bucket is the one thing
+S3 cannot default — see §14.
+
+Requires `@aws-sdk/client-s3`, plus `@aws-sdk/s3-request-presigner` when `presignedDownloads` is on
+(§12). Both are lazy-imported; a missing package fails the boot with a named error.
+
+**`s3` now also decides the DEFAULT.** Previously `s3` alone only made `CoreS3Service` available
+(TUS staging, your own code) and files moved to S3 only when `file.storage: 's3'` was set as well.
+Now a configured `s3.bucket` makes S3 the derived default. If you want S3 available for staging while
+files stay in GridFS, say so explicitly:
+
+```typescript
+file: { storage: 'gridfs' },
+s3: { bucket: 'my-app-tus' },
+```
+
+`file.storage` sits alongside the role knobs from §A — one object configures the file module: where
+the bytes live and who may reach them. The two are orthogonal, and a per-file rule in
+`checkRights()` works under either driver (`getRawFileInfo()` checks S3 metadata first, then GridFS).
+
+**Existing GridFS files stay readable.** Reads check the S3 metadata collection first and fall back
+to GridFS, so a switch to `'s3'` is forward-only: new files land in S3, old files keep being served
+from GridFS. There is no migration step and no cut-over moment. `findFileInfo()` returns the union
+of every store, paged once over the merged result.
+
+File metadata lives in a new collection `s3-files` (filename, contentType, length, uploadDate,
+custom `metadata`) — and `filesystem-files` for the filesystem driver, see §14 —
+S3 has no queryable metadata store, so this is the equivalent of GridFS's `fs.files`. The object key
+in the bucket is the string form of `_id`.
+
+**`presignedDownloads` changes what `GET /files/id/:id` answers**: a `302` redirect to a
+time-limited S3 URL instead of a streamed body, which takes the bytes off the API. It is
+deliberately fail-soft — a missing presigner package, an S3 outage, or a project `FileService`
+predating `getDownloadUrl()` all fall through to the streaming path, which runs the same rights
+check. A client that follows redirects (every browser, every HTTP library by default) needs no
+change; a client with `redirect: 'manual'` does.
+
+**To enable S3 in your project's `FileService`**, pass the two services through:
+
+```typescript
+@Injectable()
+export class FileService extends CoreFileService {
+  constructor(
+    @InjectConnection() protected override readonly connection: Connection,
+    protected readonly configService: ConfigService,
+    @Optional() protected readonly s3Service?: CoreS3Service,
+  ) {
+    super(connection, 'fs', { configService, s3Service });
+  }
+}
+```
+
+**Do not read the third argument as optional once `s3` is configured.** `CoreFileService`'s
+constructor runs `assertFileStorageAvailable()`, so if the resolved driver is `'s3'` — whether you
+set `file.storage: 's3'` or merely configured `s3.bucket` and let it be derived — a `FileService`
+that does not forward `s3Service` to `super()` **fails the boot**:
+
+```
+File storage 's3' was selected automatically (s3.bucket is configured) but is not available.
+```
+
+That is the intended behaviour: the alternative would be a silent fallback to GridFS, files landing
+in a store the operator does not believe they are in, and no way afterwards to tell which file went
+where. Either forward the services as shown above, or pin `file: { storage: 'gridfs' }` (§11b).
+
+`super(connection)` / `super(connection, 'fs')` on a project **without** any `s3` config is
+unaffected — the driver derives to `'gridfs'`, which is available, and nothing changes.
+
+**If you call `CoreS3Service.putObject()` directly, pass the length for large files.** The signature
+is `putObject(key, body, contentType?, contentLength?)`. The AWS SDK cannot sign a stream whose
+length it does not know — it fails on `x-amz-decoded-content-length` — so when `body` is a stream and
+`contentLength` is omitted, the service reads the whole stream into memory to measure it. For a
+multi-gigabyte upload that is the difference between a constant-memory transfer and an OOM:
+
+```typescript
+// Streams the file without buffering it
+await this.s3Service.putObject(key, createReadStream(path), 'video/mp4', statSync(path).size);
+
+// Reads the entire stream into a Buffer first — fine for small payloads, not for large ones
+await this.s3Service.putObject(key, createReadStream(path), 'video/mp4');
+```
+
+A `Buffer` or `string` body needs nothing: the length is taken from the value itself.
+
+---
+
+## 8. New: `tus.s3Staging`
+
+When `s3` is configured, in-progress TUS uploads are staged in the S3 staging bucket
+(`@tus/s3-store`) instead of on local disk — **default `true`**, so configuring `s3` is enough. Set
+`tus: { s3Staging: false }` to force local disk.
+
+Why it matters: a chunk written to `uploads/tus` lives on one pod's filesystem. Without sticky
+sessions the next chunk of the same upload lands elsewhere and the upload cannot be resumed; a
+restart discards it either way. With S3 staging, resumable uploads survive replica restarts and need
+no sticky sessions.
+
+Requires `@tus/s3-store` (§12). Missing package → a warning and a fall back to local disk, not a
+boot failure.
+
+**Give the staging bucket a lifecycle rule that expires incomplete multipart uploads.** The
+local-disk store is swept by the framework's own expiration cleanup; the S3 store is not — that
+cleanup is skipped in S3 mode, because S3 is the right place to express the policy. Aborted uploads
+otherwise accumulate parts nothing removes.
+
+---
+
+## 9. New: cron deduplication across replicas
+
+A new per-job option, `distributed`:
+
+```typescript
+const cronJobs = {
+  cleanUpTempFiles: { cronTime: CronExpression.EVERY_HOUR },
+  refreshLocalCache: { cronTime: CronExpression.EVERY_MINUTE, distributed: false },
+  sendDigest: { cronTime: CronExpression.EVERY_DAY_AT_6AM, distributed: true },
+};
+```
+
+**Default: `true` when `redis` is configured, `false` otherwise.** That default is the point — a
+single-replica project that upgrades does not silently gain a `cron-locks` collection, a lease write
+per tick, and a new way for a tick to be skipped. A **Redis-less multi-replica fleet opts in per
+job** with `distributed: true`, which uses a MongoDB lease.
+
+How a deduplicated job runs:
+
+| Setup | Mechanism |
+|-------|-----------|
+| Redis + `bullmq` installed, `cronTime` is a **string** and no `utcOffset` | The job becomes a BullMQ job scheduler — exactly one worker in the cluster picks up each tick |
+| Redis, but `cronTime` is a `Date` or `utcOffset` is set | Local timer per replica; each tick first takes a Redis `SET NX` lease |
+| Redis configured, `bullmq` **not** installed | Warning, then local timer + Redis lease |
+| No Redis, `distributed: true` | Local timer + a `cron-locks` document in MongoDB (TTL-indexed) |
+| No Redis, `distributed` unset | No lease at all — byte-identical to 11.32.x |
+
+**Leases fail open.** An unreachable lease store runs the tick on every replica rather than stopping
+it everywhere. A lease exists to prevent a *duplicate* run; treating an outage as "someone else won"
+would turn a Redis blip into a silent, fleet-wide outage of every scheduled job — the worse failure.
+
+**`runOnInit` deduplicates over a 5-minute window, and you should know what that means.** A
+scheduled tick has an instant every replica computes identically, so its lease key comes from the
+schedule. A *startup* has no such instant — replicas boot milliseconds to minutes apart, so a key
+built from each replica's own clock would be different everywhere and deduplicate nothing. Since
+`runOnInit` defaults to `true`, that would leave the most common path undeduplicated. The init lease
+therefore uses one **fixed key per job** with a 5-minute TTL:
+
+- Replicas that boot within 5 minutes of each other run the startup tick **once between them**.
+- A replica that restarts *inside* that window — a crash-loop, a rolling deploy, a rescheduled pod —
+  **skips its startup tick**. If a job's `runOnInit` work must happen on every process start (warming
+  a process-local cache, for instance), set `distributed: false` on it.
+- A replica joining later (autoscaling, a much later restart) runs it again, which is the intended
+  behaviour for a genuinely new instance.
+
+**No constructor change is needed.** `CoreCronJobs` is abstract and instantiated by your project, so
+the framework cannot inject into it. `CoreModule` populates a registry
+(`setCronJobsInfrastructure()`) that the base class reads lazily, so existing
+`super(schedulerRegistry, cronJobs, { log })` calls gain deduplication untouched. You *may* pass
+`connection` / `redisService` explicitly in the options object; values passed there win.
+
+With neither source available the service warns once ("Cron job deduplication is inactive …") and
+behaves as before.
+
+---
+
+## 10. Reference implementation: uploads go to central storage
+
+`src/server/` is the framework's own test implementation, but consumer projects are generated from
+the same shapes. **If you copied the avatar upload or the GraphQL multi-upload example, you have
+pod-local disk writes that break with more than one replica** — the file lands on whichever pod
+served the request, is unreadable from every other pod, and is gone after a restart.
+
+### 10.1 `UserService.setAvatar()` changed signature
+
+It takes the **stored file id** and returns the **previous** avatar id, so the caller can delete the
+orphan. It no longer touches the filesystem.
+
+**Why the storing moved to the controller:** `UserService` is instantiated by `CoreAuthModule`,
+which knows nothing about the project's `FileModule`. It cannot depend on `FileService`. The
+controller can.
+
+**Before:**
+
+```typescript
+// user.service.ts
+async setAvatar(file: Express.Multer.File, user: User): Promise<string> {
+  const dbUser = await this.mainDbModel.findOne({ id: user.id }).exec();
+  if (!dbUser) {
+    throw new UnauthorizedException();
+  }
+  if (!file) {
+    throw new UnprocessableEntityException('Missing avatar file');
+  }
+  if (user.avatar) {
+    fs.unlink(`${this.configService.configFastButReadOnly.staticAssets.path}/avatars/${user.avatar}`, …);
+  }
+  dbUser.avatar = file.filename;
+  await dbUser.save();
+  return file.filename;
+}
+
+// avatar.controller.ts
+@UseInterceptors(FileInterceptor('file', multerOptionsForImageUpload({
+  destination: `${envConfig.staticAssets.path}/avatars`,
+})))
+uploadFile(@UploadedFile() file: Express.Multer.File, @CurrentUser() user: User): Promise<string> {
+  return this.usersService.setAvatar(file, user);
+}
+```
+
+**After:**
+
+```typescript
+// user.service.ts
+/** @returns the PREVIOUS avatar id, so the caller can delete the orphaned file */
+async setAvatar(avatarId: string, user: User): Promise<string> {
+  const dbUser = await this.mainDbModel.findOne({ id: user.id }).exec();
+  if (!dbUser) {
+    throw new UnauthorizedException();
+  }
+  if (!avatarId) {
+    throw new UnprocessableEntityException('Missing avatar file');
+  }
+  const previousAvatar = dbUser.avatar;
+  dbUser.avatar = avatarId;
+  await dbUser.save();
+  return previousAvatar;
+}
+
+// avatar.controller.ts — `memory: true`, NOT a disk destination
+@UseInterceptors(FileInterceptor('file', multerOptionsForImageUpload({ memory: true })))
+async uploadFile(@UploadedFile() file: Express.Multer.File, @CurrentUser() user: User): Promise<string> {
+  const stored = await this.fileService.createFile(multerFileToUpload(file));
+  const previousAvatar = await this.usersService.setAvatar(stored.id, user);
+
+  // A failure here must not fail the upload: the new avatar is already stored and
+  // referenced, so an orphan is a cleanup concern, not a request error.
+  if (previousAvatar) {
+    try {
+      await this.fileService.deleteFile(previousAvatar);
+    } catch (error) {
+      this.logger.warn(`Could not remove previous avatar ${previousAvatar}: …`);
+    }
+  }
+
+  return stored.id;
+}
+```
+
+`AvatarController` now injects `FileService` in addition to `UserService`. In the reference
+implementation that made `UserModule` and `FileModule` reference each other, resolved with
+`forwardRef(() => FileModule)` on the `UserModule` side (`FileModule` already had one on the other).
+
+**Frontend impact — this changes what `user.avatar` contains.** It used to be a filename served from
+the static-assets directory; it is now a **file id** served via `GET /files/id/:id`. Existing avatar
+values in the database still point at old static filenames. Either migrate them (upload the files
+into the store and rewrite the field) or have the frontend fall back to the old URL shape for values
+that are not valid ObjectIds.
+
+### 10.2 GraphQL multi-upload
+
+**Before:**
+
+```typescript
+for (const file of files) {
+  const { createReadStream, filename } = await file;
+  await fs.promises.mkdir('./uploads', { recursive: true });
+  createReadStream().pipe(createWriteStream(`./uploads/${filename}`));
+}
+```
+
+`./uploads` is relative to the process working directory — one pod's disk.
+
+**After:**
+
+```typescript
+await this.fileService.createFiles(files);
+```
+
+### 10.3 `multerFileToUpload()`
+
+The new helper adapts a multer upload to what `CoreFileService` consumes, so a REST/multer endpoint
+writes to the same central storage as the GraphQL path:
+
+```typescript
+import { multerFileToUpload, multerOptionsForImageUpload } from '@lenne.tech/nest-server';
+
+@UseInterceptors(FileInterceptor('file', multerOptionsForImageUpload({ memory: true })))
+async upload(@UploadedFile() file: Express.Multer.File) {
+  return this.fileService.createFile(multerFileToUpload(file));
+}
+```
+
+It **requires `memory: true`** on the multer options — a disk-stored file has no `buffer`, and the
+helper throws with that exact instruction rather than silently storing an empty file. The returned
+`createReadStream` is callable more than once, matching graphql-upload's contract.
+
+### 10.4 `PUB_SUB` provider
+
+Both `CoreAuthModule` and the reference `UserModule` build `PUB_SUB` from a factory now: a
+`CoreRedisPubSub` when Redis is enabled, the in-memory `PubSub` otherwise. If your project provides
+its own `PUB_SUB` with `useValue: new PubSub()`, subscriptions stay single-replica. Mirror the
+factory to fix that:
+
+```typescript
+{
+  provide: 'PUB_SUB',
+  useFactory: (redisService?: CoreRedisService) =>
+    redisService?.enabled ? new CoreRedisPubSub(redisService) : new PubSub(),
+  inject: [{ optional: true, token: CoreRedisService }],
+}
+```
+
+---
+
+## 11. New: `shutdownDelayMs`
+
+```typescript
+{ shutdownDelayMs: 5000 }  // default: 0 (no delay, previous behaviour)
+```
+
+On a rolling deploy the orchestrator sends SIGTERM and deregisters the instance from the load
+balancer at the same time — but deregistration is not instant, so requests keep arriving for a
+moment after the signal. `installGracefulShutdown()` waits in the SIGTERM/SIGINT handler itself,
+*before* `close()` is entered, so those in-flight requests land on a fully healthy instance.
+
+A NestJS lifecycle hook cannot do this. `close()` runs `onModuleDestroy` →
+`beforeApplicationShutdown` → dispose (close the HTTP server) → `onApplicationShutdown`, so a delay
+in `beforeApplicationShutdown` waits *after* every module is torn down while the socket still
+accepts — worse than not waiting at all.
+
+**Wire it in `main.ts` as a REPLACEMENT for `server.enableShutdownHooks()`:**
+
+```typescript
+import { installGracefulShutdown } from '@lenne.tech/nest-server';
+
+installGracefulShutdown(server);   // instead of server.enableShutdownHooks()
+```
+
+Do **not** keep `enableShutdownHooks()` alongside it. Nest would register its own listener for the
+same signals and close the app immediately, in parallel with the wait — the delay then silently
+never happens. With `shutdownDelayMs` unset or zero, `installGracefulShutdown()` *is*
+`enableShutdownHooks()`, so this line is correct either way.
+
+**Keep the value well below your orchestrator's grace period, and leave room for the drain that
+follows it.** Docker/Compose `stop_grace_period` defaults to 10s, Kubernetes
+`terminationGracePeriodSeconds` to 30s, and `installProcessDiagnostics()` force-exits after 30s.
+Exceed any of them and the process is SIGKILLed mid-wait, running no shutdown hook at all. Values
+above 10s log a warning; above 60s the delay is capped. Inert — no delay, no log — when unset or
+zero.
+
+---
+
+## 11a. Check whether you ALREADY have a `redis` key
+
+`redis` did not exist as a server option before 11.33.0, so the framework ignored it — which means a
+project may already carry one in its server options for its **own** client, and never think about it
+again. From 11.33.0 the framework reads it, and because activation follows "presence implies
+enabled", the mere presence of that key switches on every distributed path at once: rate limits,
+cron deduplication, the email-verification cooldown, tenant-cache invalidation, Hub buffer
+mirroring, MCP session ownership and — if you use GraphQL — subscriptions over Redis pub/sub.
+
+Nothing about that is wrong, but you get it without asking for it. Three consequences are worth
+knowing before you upgrade:
+
+- **Limits get stricter, not looser.** A rate limit of `max` was effectively `max × replicas`
+  before; now it is `max`. That is the bug being fixed, but a deployment tuned around the old
+  behaviour will throttle earlier.
+- **Subscription payloads must be JSON-serializable** once pub/sub goes through Redis. `Date` is
+  revived on parse; class instances, `Map`, `Set` and `undefined` are not.
+- **The limit is only as exact as the client IP — configure `trustProxy` (new in 11.33.0).**
+  See §11c: behind a reverse proxy this is now the difference between one bucket per client and
+  one bucket for your entire user base.
+
+The boot log now states this explicitly — `CoreRedisService` logs the endpoint, the key prefix and
+the list of subsystems that switched, once, at startup. If you do not want any of it yet, set
+`redis: { enabled: false, ... }`: the config stays in place and the framework stays out.
+
+This was found by upgrading a real project that had carried a `redis` block in all five of its
+environments for its own BullMQ queues.
+
+---
+
+## 11b. Check whether you ALREADY have an `s3` key — this one FAILS THE BOOT
+
+Same shape as §11a, but with a louder failure mode. `s3` did not exist as a server option before
+11.33.0 either, so a project may already carry one for its **own** SDK client — a report export, a
+backup job, a media pipeline. From 11.33.0 the framework reads it, and `s3.bucket` alone now makes
+S3 the **derived** default for `file.storage` (§7).
+
+The consequence is not subtle. `CoreFileService`'s constructor asserts that the resolved driver is
+actually usable, so a project whose `FileService` still calls `super(connection, 'fs')` — which is
+every project that has not read §7 — stops at boot:
+
+```
+File storage 's3' was selected automatically (s3.bucket is configured) but is not available.
+```
+
+You are looking at a startup crash, not at misplaced files. That is deliberate: before 11.33.0 the
+same situation silently fell back to GridFS, and a silent fallback is unrecoverable — nobody can
+tell afterwards which file went to which store.
+
+**Three ways out, in order of how likely they are to be what you want:**
+
+```typescript
+// 1. Your `s3` block is NOT meant for file storage (own client, TUS staging only).
+//    Pin the driver and nothing changes:
+file: { storage: 'gridfs' },
+
+// 2. Your `s3` block IS meant for file storage — adopt it properly (§7):
+//    forward { configService, s3Service } to super() in your FileService,
+//    and install @aws-sdk/client-s3 (§12).
+
+// 3. You want the config parked, inert, for later:
+s3: { enabled: false, bucket: 'my-app-files', /* … */ },
+```
+
+Two more things worth knowing before the upgrade:
+
+- **`tus.s3Staging` defaults to `true` whenever `s3` is usable** (§8). A pre-existing `s3` block
+  therefore also moves in-progress TUS uploads off local disk into `s3.stagingBucket` (which
+  defaults to `bucket`). That is the better behaviour for more than one replica, but it puts
+  objects into a bucket you may have provisioned for something else — set `stagingBucket`, or
+  `tus: { s3Staging: false }`.
+- **A block without `bucket` is now ignored** with a warning (§14), where it used to make
+  `CoreS3Service.enabled` true. If you kept a bucket-less `s3` block around, TUS staging switched
+  itself on against a bucket that did not exist; that failure is gone, and so is the block's effect.
+
+`s3` is checked at boot, so unlike §11a there is no version of this you can discover in production
+three days later.
+
+---
+
+## 11c. New: `trustProxy` — required if you run behind a reverse proxy AND rate-limit
+
+**Applies to:** every deployment where something terminates TLS in front of the app — Caddy, nginx,
+Traefik, a Kubernetes ingress, a cloud load balancer — **and** `auth.rateLimit` or
+`betterAuth.rateLimit` is enabled. That is the normal production shape.
+
+### What changed
+
+Both rate limiters key their counter on the client IP. Up to 11.32.x they took the first entry of
+`X-Forwarded-For` themselves and trusted it unconditionally, which meant any client could pick its
+own bucket by sending a fresh value per request — the counter never reached the limit and the
+brute-force protection was effectively off.
+
+11.33.0 reads `request.ip` instead, which is the correct source: Express derives it from the
+forwarded chain **only as far as the app's `trust proxy` setting allows**, and reports the socket
+peer otherwise. That closes the bypass — but `trust proxy` defaults to `false`, and until 11.33.0
+this framework had no way to set it. Left unset behind a proxy, every request now resolves to the
+**proxy's** address, so:
+
+> All your clients share ONE rate-limit bucket. With `auth.rateLimit: { max: 10, windowSeconds: 60 }`
+> the 11th sign-in attempt per minute from *anybody* returns 429 to *everybody*.
+
+And because §6 makes the counter Redis-backed, that limit is enforced exactly fleet-wide rather than
+once per replica — so the collapse is total, not diluted by your replica count.
+
+### What to configure
+
+```typescript
+// config.env.ts — one reverse proxy in front of the app (the usual case)
+{
+  trustProxy: 1,
+}
+```
+
+`trustProxy` is passed verbatim to Express's `app.set('trust proxy', …)` by `CoreModule`, so you do
+**not** touch `main.ts`. Accepted values:
+
+| Value | Meaning |
+|-------|---------|
+| `false` | Trust nothing, use the socket address (Express default). Also the explicit "nothing proxies me" answer — it silences the boot warning below |
+| `1`, `2`, … | Trust exactly N hops closest to the app. One reverse proxy is `1`; a proxy behind a CDN is `2` |
+| `'loopback'` / `'linklocal'` / `'uniquelocal'` | Trust those address ranges |
+| `'10.0.0.0/8'`, `['loopback', '10.0.0.0/8']` | Trust specific addresses or subnets |
+| `true` | Trust the LEFTMOST entry — i.e. whatever the client sent. **Never on a public deployment**; it hands every caller its own bucket and restores the old bypass |
+
+**Count the hops.** Trusting more than actually sit in front of the app is the bypass in the other
+direction: a client prepends its own entry and the app believes it.
+
+A predicate function is deliberately not accepted, although Express supports one — the value has to
+survive `NEST_SERVER_CONFIG` / `NSC__*` (JSON) and the ConfigService deep clone. If you need one,
+leave `trustProxy` unset and call `app.set('trust proxy', fn)` in your own `main.ts`: an unset value
+is never applied, so nothing overwrites it. Conversely, a value that IS configured is applied during
+module init — which runs inside `app.init()`/`listen()`, i.e. **after** `main.ts` — so it takes
+precedence over a hand-written `app.set()`.
+
+### If you do not configure it
+
+Nothing fails at boot, but you get a warning naming the consequence:
+
+```
+Rate limiting is enabled (auth.rateLimit) but Express "trust proxy" is not set. Behind a reverse
+proxy (Caddy, nginx, a Kubernetes ingress) request.ip is then the PROXY address for every request,
+so every client behind a reverse proxy shares one bucket and the limit throttles all of them at once.
+```
+
+The warning exists because this misconfiguration is otherwise silent: nothing in the request path
+can tell that every caller resolved to the same address, so the first symptom is users locked out of
+sign-in with no matching attack anywhere in the logs.
+
+It is not emitted when `trustProxy` is set (including to `false`), when you set `trust proxy`
+yourself in `main.ts`, or when no IP-keyed limiter is enabled. `ai.rateLimit` keys on the user id and
+is unaffected either way.
+
+### Still worth doing at the proxy
+
+Configuring `trustProxy` correctly makes header spoofing ineffective, but **overwriting**
+`X-Forwarded-For` at your edge rather than appending to it remains good practice — it removes the
+question of hop counting entirely.
+
+---
+
+## 12. Optional peer dependencies
+
+Five new **optional** peers. `pnpm install` does not pull any of them; install only what you use.
+
+| Package | Peer range | Needed for | Missing → |
+|---------|-----------|-----------|-----------|
+| `ioredis` | `>=5.0.0 <7` | any `redis` feature | **Boot fails** with a named error |
+| `bullmq` | `>=5.16.0 <7` | BullMQ cron schedulers | Warning; cron falls back to per-tick leases |
+| `@aws-sdk/client-s3` | `>=3.1045.0 <4` | any `s3` feature | **Boot fails** with a named error |
+| `@aws-sdk/s3-request-presigner` | `>=3.1045.0 <4` | `s3.presignedDownloads` | Throws on first presign; the controller catches it and streams instead |
+| `@tus/s3-store` | `>=2.0.5 <3` | `tus.s3Staging` | Warning; TUS stages on local disk |
+
+**If you already use BullMQ, you do NOT have to upgrade it.** The floor is `5.16.0` because that is
+the release that introduced the Job Scheduler API (`upsertJobScheduler` / `removeJobScheduler` /
+`getJobSchedulers`) — verified against 5.15.0 (absent) and 5.16.0 (present). Everything the
+framework calls exists throughout 5.x, so a project on BullMQ 5 keeps its own queue code untouched.
+This matters because the projects most likely to want distributed cron are exactly the ones that
+already run BullMQ, and forcing them to 6.x breaks *their* code: `job.discard()`,
+`repeat` in `JobsOptions`, `getRepeatableJobs()`, `removeRepeatableByKey()` and `queue.client` were
+all removed or renamed in 6.0.
+
+```bash
+pnpm add ioredis bullmq                                          # distributed rate limits + cron
+pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner        # S3 file storage
+pnpm add @tus/s3-store                                           # resumable uploads staged in S3
+```
+
+Per `.claude/rules/package-management.md`, pin exact versions in your own `package.json` — the
+ranges declared here are peer ranges, not an invitation to float.
+
+---
+
+## 13. Dependency housekeeping — and what it does *not* do for you
+
+The framework's `pnpm-workspace.yaml` overrides were raised to newly published patch levels
+(`brace-expansion` 1.1.18 / 5.0.9, `js-yaml` 4.3.1, `fast-uri` 3.1.5) and five were added
+(`ip-address`, `nanoid`, `postcss`, `undici`, `hono`). `pnpm audit` inside this repository went from
+20 findings to 0.
+
+**That number is about this repository, not about yours.** pnpm `overrides:` apply only to the
+**root** project of an install, so nothing in the framework's `pnpm-workspace.yaml` travels with the
+published npm package. Your project resolves its own tree with *your* overrides — by default, none.
+A green audit here says nothing about a consumer tree. See
+[`docs/security-overrides.md`](../docs/security-overrides.md).
+
+**Action required: run your own `pnpm audit`.** It is the only thing that tells you about your tree.
+
+**What you still have to replicate is unchanged by this release: the same three entries.** They are
+the ones whose parent packages **exact-pin** a vulnerable version, or ship no fix inside the declared
+major, so no amount of updating resolves them forward:
+
+| Override | Why it cannot resolve forward |
+|----------|-------------------------------|
+| `ws@>=8.0.0 <8.21.0` → `8.21.3` | `@nestjs/graphql` exact-pins `ws@8.20.1` |
+| `js-yaml@>=5.0.0 <5.2.2` → `5.2.2` | `@nestjs/swagger` exact-pins `js-yaml@5.2.1` |
+| `@hono/node-server@<2.0.10` → `2.0.11` | `@modelcontextprotocol/sdk` declares `^1.19.9` with no 1.x fix line |
+
+**The `ws` target changed in this release** (`8.21.1` → `8.21.3`) and is not a cosmetic bump. It has
+to equal the version you carry as a **direct** `ws` dependency: under `nodeLinker: hoisted` a lower
+override target leaves a second, older `ws` copy in the tree beside the direct one. If you copied
+the old block, raise the target and re-resolve.
+
+`docs/security-overrides.md` carries the full rationale and the copy-pasteable block.
+
+**None of the five new entries joins that list.** Every one of them sits behind a caret range
+(`@modelcontextprotocol/sdk` declares `hono@^4.11.4`, `@hono/node-server` peers `hono@^4`,
+`express-rate-limit@^8.2.1` pulls `ip-address`, and `nanoid`/`postcss`/`undici` are dev-only
+transitives), so a **fresh** resolve in your project lands on a patched version by itself. The
+caveat is the word *fresh*: an existing `pnpm-lock.yaml` keeps whatever it already pinned until you
+re-resolve. Update the lockfile and re-run `pnpm audit` rather than assuming the caret did the work.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| No `redis` / `s3` / `shutdownDelayMs` config | **Unchanged** | Every new service is inert; rate limits, cron, subscriptions, files and Hub behave exactly as in 11.32.x |
+| Single replica | **Unchanged**, plus one uncontended lock acquire/release per `migrate up` | |
+| `CoreCronJobs` subclass with `super(schedulerRegistry, cronJobs, { log })` | **Compatible** | Deduplication arrives via the registry, no constructor change |
+| Project `FileService extends CoreFileService` with `super(connection)`, **no `s3` config** | **Compatible** | Driver derives to GridFS; forward the options object to enable S3 (§7) |
+| Project `FileService extends CoreFileService` with `super(connection)`, **`s3.bucket` already configured** | **Boot fails — action required** | S3 becomes the derived driver and the constructor asserts it. Forward `{ configService, s3Service }`, or pin `file: { storage: 'gridfs' }` — §11b |
+| An existing `s3` key in the server options (own client, backups, media) | **Action required** | The framework reads it now and it changes `file.storage` and `tus.s3Staging` — §11b |
+| Project `TusService` / `TusModule` usage | **Compatible** | `TusModule` injects the new dependencies itself |
+| Direct calls to `rateLimiter.check/reset/clear` | **Action required** | Await them (§1) |
+| Rate limiting enabled **behind a reverse proxy** | **Action required** | Set `trustProxy` (hop count) or every client shares one bucket — §11c. A boot warning names it |
+| Rate limiting enabled with **nothing in front of the app** | **Unchanged**, plus a boot warning | Set `trustProxy: false` to state it explicitly and silence the warning |
+| Project overriding `CoreFileService.getFileInfo()` | **Action required for `GET /files/id/:id`** | That route now resolves through `resolveFile()`; override it too — §14 |
+| Project calling `findFileInfo()` **without** a `sort`, with `file.storage` other than `gridfs` | **Ordering changed** | The merged multi-store page defaults to `uploadDate` descending — §14 |
+| Overridden Hub collector `getData()` / mailbox reads | **Action required** | Await and widen the return type (§2) |
+| `const s: GridFSBucketReadStream = await getFileStream(...)` | **Action required** | Type is `Readable` now (§3) |
+| Custom `PUB_SUB` with `useValue: new PubSub()` | **Works, but stays single-replica** | Mirror the factory (§10.4) |
+| Copied avatar upload from `src/server` | **Action required for >1 replica** | §10.1 — including the frontend impact |
+| `createMigrationStore(uri, 'migrations', 'my_lock')` | **Unchanged** | An explicit lock name still wins |
+| `MongoStateStore` constructed directly | **Unchanged** | Locks only when you pass `lockCollectionName` |
+| GraphQL subscription payloads with `Date` / class instances | **Breaks only once Redis is enabled** | Publish JSON-serialisable payloads (§6) |
+| `/ai/mcp` behind a load balancer | **Still requires sticky sessions** | Redis only improves the error message, it does not make sessions portable |
+| `/hub` behind a load balancer | **Without Redis: route it to one replica** | Each pod otherwise shows only its own slice |
+
+---
+
+## 14. What else changed under the hood
+
+Nothing here needs action, but it is the kind of thing an operator or a reviewer wants to know
+before it shows up unannounced.
+
+### New MongoDB collections
+
+| Collection | Written when | Holds |
+|------------|--------------|-------|
+| `s3-files` | `file.storage: 's3'` | filename, contentType, length, uploadDate, custom `metadata` |
+| `filesystem-files` | `file.storage: 'filesystem'` | the same fields |
+
+Metadata always lives in the database, whichever driver holds the bytes — it has to stay queryable
+for `findFileInfo()` and for the per-file rules `checkRights()` evaluates (§A.3). Include them in
+backups: with `'filesystem'` or `'s3'`, losing this collection orphans the bytes, because nothing
+else records what a file is called.
+
+GridFS keeps using `fs.files` / `fs.chunks` unchanged.
+
+### New public exports
+
+```typescript
+import {
+  // Storage driver selection
+  resolveFileStorage, assertFileStorageAvailable, FileStorageDriver, FILE_STORAGE_DRIVERS,
+  // Filesystem driver
+  FilesystemFileHelper, FilesystemFileInfo, FILESYSTEM_FILES_COLLECTION, DEFAULT_FILESYSTEM_DIR,
+  // Config-driven role application
+  applyFileRoles, FILE_ROLE_DEFAULTS,
+  // Content-Disposition rendering, shared by the streamed and presigned download paths
+  buildContentDisposition,
+  // Infrastructure (see §6, §7)
+  CoreRedisService, CoreS3Service, CoreRedisPubSub,
+  RateLimitStore, installGracefulShutdown,
+  // Cron infrastructure registry (see §9) — a registry OBJECT, not a class
+  CronJobsInfrastructure, getCronJobsInfrastructure, setCronJobsInfrastructure,
+} from '@lenne.tech/nest-server';
+```
+
+You need none of them for a normal upgrade. They are exported because a project overriding
+`CoreFileService` or writing its own storage-aware code otherwise has to reach into deep paths.
+
+The cron registry is deliberately **not** a class. `core-cron-jobs.registry.ts` is an import-free
+leaf holding module-level state (`CronJobsInfrastructure` is the shape, `get…`/`set…` the accessors),
+because a class there would put a runtime import edge back on a cycle — see
+`.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)". `CoreModule` calls
+`setCronJobsInfrastructure()`; you only need it yourself if you register your own Mongoose connection
+or `CoreRedisService` for cron leases.
+
+### Behaviour change: `GET /files/id/:id` resolves through `resolveFile()`, not `getFileInfo()`
+
+The download route used to call the public `getFileInfo()` and then `getFileStream()`, so the id was
+resolved twice — once for the metadata, once for the bytes, with the two lookups free to disagree
+about which store the file lives in. It now makes a single `resolveFile()` call that returns the
+metadata **and** the storage location together. `resolveFile()` runs the very same `checkRights()`
+that `getFileInfo()` did, so authorization is unchanged.
+
+**What this costs a project that OVERRODE `getFileInfo()`** — for a tenant filter, a custom store, or
+to strip extra fields. The override is still honoured on `getFileInfoByName()`, on the GraphQL
+resolver and on `deleteFile()`, but **no longer on that route**. If the override carried behaviour
+you rely on for downloads, override `resolveFile()` as well:
+
+```typescript
+export class FileService extends CoreFileService {
+  override async resolveFile(id, serviceOptions?) {
+    const resolved = await super.resolveFile(id, serviceOptions);
+    // …the same narrowing your getFileInfo() override applies
+    return resolved;
+  }
+}
+```
+
+Authorization rules do **not** belong here — put those in `checkRights()` (§A.3), which both paths
+call.
+
+### Behaviour change: presigned S3 downloads keep the file's real name
+
+`s3.presignedDownloads` sets `response-content-disposition` on the signed URL, and S3 echoes it back
+as the response header. That value was rendered separately from the streamed branch's, and rendered
+wrongly: the filename was percent-encoded inside an RFC 6266 quoted-string — which nothing
+percent-decodes, so `Jahresbericht 2024.pdf` was saved as `Jahresbericht%202024.pdf` — and there was
+no `filename*` parameter at all, so a non-ASCII name was lost outright.
+
+Both paths now render the value with the same exported helper (`buildContentDisposition`), so a file
+keeps its name whichever branch serves it. **If you enabled `presignedDownloads`, downloaded
+filenames change** — to the correct ones. Nothing to configure.
+
+### Behaviour change: `findFileInfo()` default ordering depends on `file.storage`
+
+With `file.storage: 'gridfs'` (or a derived GridFS driver) nothing was ever written to the other
+stores, so the query stays a single database query and keeps MongoDB's natural order — unchanged.
+
+With `'s3'` or `'filesystem'`, rows come from up to three collections and have to be merged before
+they can be paged; concatenating them would interleave by store and page the wrong rows. The merge
+therefore re-sorts, and **when the filter args carry no `sort`, it falls back to `uploadDate`
+descending** (newest first).
+
+So the same `findFileInfo()` call returns a different default order depending on the configured
+driver. An explicit `sort` in the filter args is honoured on both paths and removes the difference —
+pass one if your UI depends on the ordering.
+
+### Behaviour change: an `s3` block without a `bucket` is now ignored
+
+`CoreS3Service.enabled` used to be true for any `s3` block. A bucket is the one thing S3 cannot
+default — region, endpoint and credentials all have fallbacks — so a bucket-less block enabled the
+service while nothing could be written to it. `tus.s3Staging` (default `true`) keys off exactly that
+flag, so staging switched on against a bucket that did not exist and failed at the first upload.
+
+Now such a block is ignored with a warning, and `CoreS3Service.enabled` agrees with the storage
+resolver about what "usable" means.
+
+### Dependency bumps
+
+`@nestjs/common`, `@nestjs/core` and `@nestjs/platform-express` move 11.1.28 → 11.1.29 (core import
+lookup, middleware regex, SSE, multer field-nesting errors). The release also fixes the Redis pub/sub
+client type in `@nestjs/microservices` — not used here: this framework talks to Redis through
+`ioredis` directly, because the microservices transport is a message bus and cannot express the
+atomic counters, leases and Lua scripts the rate limiter, cron dedup and tus locker need.
+
+**Two `dependencies` also cross a MAJOR**, and because they are ordinary dependencies of this
+package they get installed into your project whether you asked for them or not. Neither needs
+action; both are listed here because a major in a lockfile diff deserves an answer rather than a
+shrug.
+
+| Package | Move | What it means for you |
+|---------|------|-----------------------|
+| `js-sha256` | 0.12.0 → **1.0.0** | **No hash change.** Verified against the standard vector: `sha256('abc')` is `ba7816bf…f20015ad` on 1.0.0, byte-identical to 0.12.0. The 1.0.0 release is a packaging/API-surface milestone, not an algorithm change — a hash function whose output changed would not be SHA-256 any more. |
+| `graphql-query-complexity` | 1.1.1 → **2.0.0** | API-compatible at this framework's only call site. |
+
+**Why the `js-sha256` answer matters:** the framework pre-hashes passwords with SHA-256 before
+BCrypt/scrypt when `sha256: true` is configured (`mongoose-password.plugin.ts`,
+`service.helper.ts`, `core-auth.service.ts`). A changed digest would have invalidated **every stored
+password hash** on upgrade — silently, with the symptom "all users can suddenly no longer sign in".
+It does not: the digests are identical, existing hashes keep verifying, and no password migration
+is needed.
+
+**`graphql-query-complexity` 2.0.0**: `src/core/common/plugins/complexity.plugin.ts` uses
+`getComplexity`, `simpleEstimator` and `fieldExtensionsEstimator`, all still exported with unchanged
+signatures in 2.x — nothing in this framework had to be touched.
+
+v2 adds a second, node-count-based DoS bound alongside the existing complexity bound:
+`maxQueryNodes`, defaulting to **10 000** evaluated selection-set nodes. Exceeding it aborts the
+traversal with `GraphQLError: Query exceeds the maximum allowed number of nodes.` — so a document
+that is cheap per field but enormous in shape is now rejected before its complexity score finishes
+being computed, where v1 would have walked all of it. The framework does not pass the option, so it
+inherits the default; `graphQl.maxComplexity` is unaffected and still applies on top.
+
+One caveat about coverage rather than about the library: `src/core.module.ts:298` deliberately does
+**not** register `ComplexityPlugin` under Vitest (a dual-GraphQL-loading issue), so this repository's
+own test suite does not exercise the v2 code path at all. If you rely on complexity limits, verify
+them against your own schema after the upgrade — in particular any legitimate query that is large in
+node count rather than in cost.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Redis is configured (ServerOptions.redis) but the optional peer dependency "ioredis" is not installed` | Boot-time fail-fast | `pnpm add ioredis`, or remove the `redis` config |
+| `S3 is configured (ServerOptions.s3) but the optional peer dependency "@aws-sdk/client-s3" is not installed` | Boot-time fail-fast | `pnpm add @aws-sdk/client-s3` |
+| `file.storage is set to 's3', but that storage is not available` | Boot-time fail-fast — replaces the old silent fallback to GridFS | Forward `{ configService, s3Service }` to `super()` in your `FileService` and install `@aws-sdk/client-s3` — or pin `file: { storage: 'gridfs' }` — §7 |
+| `File storage 's3' was selected automatically (s3.bucket is configured) but is not available` | Same, but the driver was DERIVED: an `s3` block makes S3 the default — the usual cause is an `s3` key the project already had for its OWN client | If S3 is only meant for tus staging or your own code, say so: `file: { storage: 'gridfs' }` — §11b |
+| `Query exceeds the maximum allowed number of nodes.` on a GraphQL request | `graphql-query-complexity` 2.0.0 adds a node-count bound (default 10 000) next to the complexity bound | §14 — split the query, or the document is genuinely pathological |
+| `Ignoring the \`s3\` configuration: no \`bucket\` is set` warning, and S3 stays off | A bucket is the one thing S3 cannot default | Set `s3.bucket`. Without it `tus.s3Staging` would have staged against a bucket that does not exist |
+| Files land in GridFS although `s3` is configured | Your `FileService` does not forward the services to `super()` | §7 — the boot error above now catches this instead of failing silently |
+| Uploaded files disappear after a container restart | `file.storage: 'filesystem'` on ephemeral storage | Mount a volume at `file.storageDir`, or use `'s3'` / `'gridfs'` — §7 |
+| `TS2345: Argument of type 'Promise<RateLimitResult>' is not assignable…` | A rate-limiter call is not awaited | §1 |
+| A guard/middleware that calls `check()` compiles but never rate-limits | It returns a truthy promise, not a boolean | Make it `async` and `await` the call — §1 |
+| `Timed out … waiting for the migration lock in collection "migrations_lock"` | Another replica is migrating, or a stuck process holds the lock | §4 — inspect `owner` / `acquiredAt`, delete only when sure |
+| `Breaking stale migration lock …` warning on boot | A previous run was killed and stopped heart-beating | Expected recovery, no action |
+| Migrations now take noticeably longer to start on a rolling deploy | Replicas serialise on the lock | Intended — §4 |
+| A cron job stopped running on every replica after adding `redis` | It is deduplicated now | Set `distributed: false` if it must run everywhere |
+| A `runOnInit` job skips its startup tick after a restart | Restarted inside the 5-minute init window | §9 — `distributed: false` if the startup work is per-process |
+| `Redis is configured but the optional peer dependency "bullmq" is not installed` | Warning only | Install `bullmq`, or ignore — leases still deduplicate |
+| `Cron job deduplication is inactive: neither a Redis service nor a Mongoose connection…` | `distributed: true` without any lease backend | Configure `redis`, or pass `connection` in the options object |
+| `Redis rate limiting unavailable … Falling back to per-replica in-memory limits` | Redis outage | Requests keep working with per-replica limits; a recovery line follows — §1 |
+| Uploads now return an ObjectId where a filename was expected | Avatars are file ids now | §10.1 — including the frontend fallback |
+| `multerFileToUpload() needs an in-memory upload` | Multer wrote the file to disk | Pass `memory: true` to `multerOptionsForImageUpload()` |
+| Downloads answer `302` instead of the file body | `s3.presignedDownloads` is enabled | Intended; follow the redirect, or disable presigned downloads — §7 |
+| Heap blows up on a large `putObject()` of a stream | No `contentLength`, so the stream is buffered to measure it | Pass the fourth argument — §7 |
+| `pnpm audit` still reports findings in your project after updating | Framework overrides do not travel with the npm package | §13 — replicate the three load-bearing entries and re-resolve your lockfile |
+| Subscription payload arrives with missing/mangled fields after enabling Redis | Payload is not JSON-serialisable | §6 |
+| Hub panels look empty or lossy across pods | Collectors are process-local without Redis | Configure `redis`, or route `/hub` to one replica |
+| TUS staging bucket fills with abandoned parts | No lifecycle rule on the staging bucket | §8 |
+
+---
+
+## Verification
+
+```bash
+pnpm test
+```
+
+New coverage:
+
+- `tests/unit/redis-rate-limiters.spec.ts` — the store abstraction, exact limits across "replicas", the outage fallback, and glob escaping in caller-controlled key parts
+- `tests/unit/core-cron-jobs-dedup.spec.ts` — the three dedup modes, the `runOnInit` fixed-key lease, fail-open on an unreachable lease store, the BullMQ worker start order
+- `tests/unit/migration-store-lock.spec.ts` and `tests/migrate/mongo-state-store.e2e-spec.ts` — heartbeat, stale-break and bounded wait
+- `tests/unit/performance-caches.spec.ts` — tenant-cache invalidation broadcast and the no-Redis path
+- `tests/unit/hub-buffer.spec.ts` — the Redis mirror, sequence-number continuity, fallback on a read failure
+- `tests/redis-infra.e2e-spec.ts` / `tests/s3-infra.e2e-spec.ts` — round trips against a real Redis and a real S3-compatible store
+- `tests/redis-consumers.e2e-spec.ts` — the framework's own Redis consumers seen from two replicas
+- `tests/file-storage-s3.e2e-spec.ts` — `CoreFileService` against a real S3 store
+- `tests/graceful-shutdown.e2e-spec.ts` — `installGracefulShutdown()` with real connections to close
+- `tests/redis-s3-bootstrap.e2e-spec.ts` — boots the assembled `CoreModule` with both configured, covering the wiring itself (an unresolvable provider or a lifecycle hook that throws on a real connection passes every other spec and fails on a consumer's first `nest start`)
+- `tests/multi-replica.e2e-spec.ts` — the acceptance test: two independent service instances sharing one Redis, asserting that a scheduled tick and a startup tick each run exactly once, that one rate limit is enforced instead of one per replica, and that a severed Redis still yields a decision instead of an error
+
+Those **seven** infrastructure suites need real containers. They do **not** skip when nothing is
+reachable — a silently skipped infrastructure test is how an untested driver ships — and most of
+them name the exact `docker run` line in the failure:
+
+```bash
+docker run -d --name nest-server-2985-redis -p 6380:6379 redis:7.4-alpine
+docker run -d --name nest-server-2985-rustfs -p 9102:9000 \
+  -e RUSTFS_ROOT_USER=rustfs -e RUSTFS_ROOT_PASSWORD=rustfs-secret \
+  -e RUSTFS_VOLUMES=/data rustfs/rustfs:latest server /data
+```
+
+Port 6380 rather than 6379 is deliberate: on `lt dev` machines 6379 is occupied by an
+auth-protected Redis. Override with `REDIS_HOST` / `REDIS_PORT` and `S3_ENDPOINT` /
+`S3_ACCESS_KEY` / `S3_SECRET_KEY`. CI starts both containers in `build.yml` and `publish.yml`.
+
+---
+
+## Module Documentation
+
+### Migrate
+
+- **README:** [src/core/modules/migrate/README.md](../src/core/modules/migrate/README.md) — "Locking Mechanism" and `createMigrationStore()`
+- **Key Files:** `mongo-state-store.ts` (lock, heartbeat, stale-break), `migration-runner.ts` (`up()` under the lock), `helpers/migration.helper.ts` (`createMigrationStore()` default)
+
+### File
+
+- **README:** [src/core/modules/file/README.md](../src/core/modules/file/README.md) — new "Access control" section (roles vs. `checkRights()`)
+- **Integration Checklist:** [src/core/modules/file/INTEGRATION-CHECKLIST.md](../src/core/modules/file/INTEGRATION-CHECKLIST.md) — new in this release
+- **Reference Implementation:** `src/server/modules/file/`
+- **Key Files:** `core-file.service.ts` (storage driver selection, GridFS read fallback, `getRawFileInfo()`), `s3-file.helper.ts` (`s3-files` metadata collection), `core-file.controller.ts` (presigned redirect, fail-soft, `setFileHeaders()`), `file-roles.helper.ts` (config-driven role application)
+
+### TUS
+
+- **README:** [src/core/modules/tus/README.md](../src/core/modules/tus/README.md) — `tus.roles`, OPTIONS handling
+- **Key Files:** `core-tus.controller.ts` (separate public `@Options()` handlers), `tus.module.ts` (`applyRoles()`), `interfaces/tus-config.interface.ts` (`roles` default, `s3Staging`), `core-tus.service.ts` (S3 staging store), `tus-redis-locker.ts` (cross-replica upload lock)
+
+### Hub
+
+- **README:** [src/core/modules/hub/README.md](../src/core/modules/hub/README.md) — new "Multi-replica" section
+- **Key Files:** `hub-buffer.ts` (optional Redis mirror), `core-hub.controller.ts` (async panel handlers)
+
+### AI
+
+- **README:** [src/core/modules/ai/README.md](../src/core/modules/ai/README.md) — new "Multi-replica / sticky sessions" section
+- **Integration Checklist:** [src/core/modules/ai/INTEGRATION-CHECKLIST.md](../src/core/modules/ai/INTEGRATION-CHECKLIST.md)
+
+### System Setup
+
+- **README:** [src/core/modules/system-setup/README.md](../src/core/modules/system-setup/README.md) — bootstrap claim
+- **Key File:** `core-system-setup.service.ts` (`system-setup-locks`)
+
+### Tenant (Multi-Tenancy)
+
+- **README:** [src/core/modules/tenant/README.md](../src/core/modules/tenant/README.md)
+- **Key File:** `core-tenant.guard.ts` (cross-replica cache invalidation)
+
+---
+
+## References
+
+- [`.claude/rules/configurable-features.md`](../.claude/rules/configurable-features.md) — the "presence implies enabled" pattern every new option follows
+- [`docs/native-driver-security.md`](../docs/native-driver-security.md) — why `cron-locks`, `system-setup-locks` and `s3-files` use the native driver
+- [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed versions for the optional peers you install
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)