@lenne.tech/nest-server 11.32.3 → 11.33.0

package/docs/REQUEST-LIFECYCLE.md

@@ -40,7 +40,9 @@ The `CoreModule` is a dynamic module that bootstraps the entire framework:
 | **Dual API Support** | GraphQL and REST in the same application |
 | **Security Pipeline** | 4 global interceptors, global validation pipe, middleware stack |
 | **Mongoose Plugins** | Auto-registration of ID, password, audit, and role guard plugins |
-| **GraphQL Subscriptions** | WebSocket support with JWT/session authentication |
+| **GraphQL Subscriptions** | WebSocket support with JWT/session authentication (cluster-wide when `redis` is configured — see the Subscriptions row under GraphQL Features) |
+| **Central Redis (optional)** | `CoreRedisService` — globally provided **and exported** by `CoreModule`, always present but **inert unless `redis` is configured** ("presence implies enabled"). Injected with `@Optional()`; every consumer keeps a process-local fallback. One service serves all features: shared client (`getClient()`), one cached subscriber (`getSubscriber()` — a subscribing client cannot run commands), dedicated connections (`createClient(label)`); all tracked and quit on shutdown. Keys are namespaced by the framework per key via `key(...)`, **not** through ioredis's own `keyPrefix` (that would collide with BullMQ's prefix). Requires the OPTIONAL peer `ioredis` — configured but missing **fails the boot**. Switches on: exact cross-replica rate limits, cron deduplication, `CoreRedisPubSub` as `PUB_SUB`, tenant-cache invalidation broadcast, Hub collector mirroring, MCP session registry |
+| **Central S3 (optional)** | `CoreS3Service` — globally provided **and exported** by `CoreModule`, inert unless `s3` is configured *and* names a `bucket` (a bucket-less block is ignored with a warning). Backs `file.storage: 's3'` and TUS staging (`tus.s3Staging`). Requires the OPTIONAL peers `@aws-sdk/client-s3` (+ `@aws-sdk/s3-request-presigner` for `presignedDownloads`) — configured but missing **fails the boot** |
 | **Configuration System** | `config.env.ts` with ENV variables, `NEST_SERVER_CONFIG` JSON, `NSC__*` prefixes |
 | **Cookie Handling** | Enabled by default (`cookies: true`), configurable via `ICookiesConfig` with `exposeTokenInBody` option |
 | **Unified CORS** | Single `cors` config propagates to GraphQL, REST, and BetterAuth layers |
@@ -61,7 +63,7 @@ Modern OAuth-compatible authentication with plugin architecture:
 | **Social Login** | OAuth providers: Google, GitHub, Apple, Discord, etc. (plugin) |
 | **Email Verification** | Configurable email verification flow |
 | **Sign-Up Validation** | Custom validation hooks for registration |
-| **Rate Limiting** | Per-endpoint rate limits (configurable) |
+| **Rate Limiting** | Per-endpoint rate limits (`betterAuth.rateLimit`, configurable). Counters live behind a `RateLimitStore`: `RedisRateLimitStore` when `redis` is configured, so `max` is enforced **exactly across replicas** instead of `max × replicas`; otherwise the process-local `InMemoryRateLimitStore` as before. `check()` / `reset()` / `clear()` are **async** since 11.33.0. On a Redis outage it degrades to the in-memory counter and logs once per transition — never a 500, never "allowed". Counters are keyed on `request.ip`, which Express derives from `X-Forwarded-For` only as far as `trust proxy` allows — set `trustProxy` (§ServerOptions) behind a reverse proxy or every client resolves to the proxy and shares ONE bucket; unset with a limiter enabled logs a boot warning |
 | **Cross-Subdomain Cookies** | Automatic cookie domain configuration |
 | **Organization / Multi-Tenant** | Teams and organization management (plugin) |
 | **3 Registration Patterns** | Zero-config, overrides parameter, or manual (`autoRegister: false`) |
@@ -75,7 +77,7 @@ JWT-based authentication for existing projects:
 | **JWT Authentication** | Bearer token auth with Passport strategies |
 | **Refresh Tokens** | Automatic token renewal |
 | **Sign In / Sign Up / Logout** | GraphQL mutations + REST endpoints |
-| **Rate Limiting** | Configurable per-endpoint rate limits |
+| **Rate Limiting** | Configurable per-endpoint rate limits (`auth.rateLimit`). Same `RateLimitStore` selection, async signatures and Redis-outage degradation as the BetterAuth row above (namespace `legacy-auth`) |
 | **Legacy Endpoint Controls** | Disable legacy endpoints after migration (`auth.legacyEndpoints`) |
 | **Migration Tracking** | `betterAuthMigrationStatus` query for monitoring |
 
@@ -158,9 +160,10 @@ JWT-based authentication for existing projects:
 | Feature | Description |
 |---------|-------------|
 | **File Module** | Upload/download with MongoDB GridFS storage |
-| **REST Endpoints** | `GET /files/:id`, `POST /files/upload`, `DELETE /files/:id` |
-| **GraphQL Endpoints** | `uploadFile`, `file`, `fileByFilename`, `deleteFile` |
-| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration) |
+| **REST Endpoints** | `GET /files/id/:id`, `GET /files/:filename` (core, gated by `file.downloadRoles`, default ADMIN); `POST /files/upload`, `DELETE /files/:id` (project-specific) |
+| **GraphQL Endpoints** | `getFileInfo` (`file.downloadRoles`), `uploadFile` / `uploadFiles` (`file.uploadRoles`), `deleteFile` (`file.deleteRoles`) — all default ADMIN |
+| **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
+| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight |
 | **GridFS Migration** | Completed TUS uploads auto-migrate to GridFS |
 | **CORS Support** | Automatic CORS headers for browser uploads |
 
@@ -201,7 +204,7 @@ JWT-based authentication for existing projects:
 |---------|-------------|
 | **Apollo Server** | Full GraphQL server with schema-first or code-first |
 | **Custom Scalars** | `Date`, `DateTime` (timestamp), `JSON`, `Any` |
-| **Subscriptions** | WebSocket support via `graphql-ws` with auth |
+| **Subscriptions** | WebSocket support via `graphql-ws` with auth. The `PUB_SUB` provider is built from a factory: `CoreRedisPubSub` when `redis` is configured (delivery is then cluster-wide), the in-memory `PubSub` otherwise (delivery only to clients connected to the publishing replica). **Constraint once Redis is in play: every published payload must be JSON-serializable** — it crosses the wire as JSON, so `Date`, class instances, `Map`/`Set` and `undefined` do not survive the round trip. An in-process `PubSub` never had this constraint, so a payload that worked on one replica can silently lose fields on a cluster. Publish plain objects and ISO strings |
 | **Complexity Analysis** | Query cost calculation to prevent DoS attacks |
 | **Enum Registration** | `registerEnum()` helper for GraphQL enum types |
 | **Upload Support** | `graphqlUploadExpress()` for multipart file uploads |
@@ -214,7 +217,8 @@ JWT-based authentication for existing projects:
 | **Error Code Module** | Centralized error registry with unique IDs |
 | **Permissions Report** | Interactive HTML dashboard, JSON, and Markdown reports |
 | **Hub (Operator Cockpit)** | Build-free ADMIN-gated dashboard at `/hub` (config-gated per environment). Adds an optional HTTP trace middleware (registered by `CoreHubModule.configure()` only when traces are enabled), a chaining `Logger.overrideLogger()` delegate for the log buffer, an optional `EmailService` capture hook (`HUB_EMAIL_CAPTURE` token) for the mailbox, and — when the query profiler is enabled — opts the MongoDB driver into `monitorCommands` from `core.module.ts`. See `src/core/modules/hub/README.md`. |
-| **Process Diagnostics** | Opt-in process-level exit diagnostics (`installProcessDiagnostics()` + `handleFatalBootstrapError`, `src/core/common/helpers/process-diagnostics.helper.ts`). Wired into `main.ts` — **NOT** into `CoreModule.forRoot()`, because it must run before `NestFactory.create()` and installs a `process.exit(1)` path that must never arm inside `Test.createTestingModule()`. Logs unhandled rejections without crashing (configurable), uncaught exceptions before the exit, non-zero exit codes, and labels SIGTERM/SIGINT/SIGHUP/SIGQUIT as external terminations. Pair with `server.enableShutdownHooks()` — see the helper docblock |
+| **Process Diagnostics** | Opt-in process-level exit diagnostics (`installProcessDiagnostics()` + `handleFatalBootstrapError`, `src/core/common/helpers/process-diagnostics.helper.ts`). Wired into `main.ts` — **NOT** into `CoreModule.forRoot()`, because it must run before `NestFactory.create()` and installs a `process.exit(1)` path that must never arm inside `Test.createTestingModule()`. Logs unhandled rejections without crashing (configurable), uncaught exceptions before the exit, non-zero exit codes, and labels SIGTERM/SIGINT/SIGHUP/SIGQUIT as external terminations. Pair with `installGracefulShutdown(server)` — **not** with `server.enableShutdownHooks()`, see the Graceful Shutdown row below |
+| **Graceful Shutdown** | `installGracefulShutdown(app)` (`src/core/common/helpers/graceful-shutdown.helper.ts`), wired in `main.ts`. It **REPLACES** `server.enableShutdownHooks()` and must not be used alongside it: with `shutdownDelayMs` set, Nest would register its own listener for the same signals and close the app in parallel with the wait, so the delay silently never happens. At `shutdownDelayMs: 0` (the default) the helper simply *is* `enableShutdownHooks()`, so the single call is correct either way. With a delay it waits **inside the SIGTERM/SIGINT handler, before `close()` is entered** — a NestJS lifecycle hook cannot do this, because `close()` runs `onModuleDestroy` → `beforeApplicationShutdown` → dispose → `onApplicationShutdown`, i.e. a delay in a hook would wait with every module already torn down while the socket still accepts. A second signal cancels the pending wait and closes immediately. Warns above 10 000 ms, capped at 60 000 ms — keep it below the orchestrator grace period (Compose 10 s, Kubernetes 30 s) and below `installProcessDiagnostics()`'s 30 s force-exit |
 | **System Setup Module** | Initial admin creation for fresh deployments |
 | **Cron Jobs** | `CoreCronJobsService` with timezone/UTC offset support |
 | **Model Documentation** | Auto-generated model docs via `ModelDocService` |
@@ -425,6 +429,51 @@ The following diagram shows the exact order of execution from HTTP request to re
                     +---------------------+
 ```
 
+### Shutdown Flow (SIGTERM / SIGINT)
+
+The mirror image of the request flow, and the one place where an ordering mistake is invisible until
+a rolling deploy drops requests. Installed in `main.ts` by `installGracefulShutdown(server)` — which
+**replaces** `server.enableShutdownHooks()`, never accompanies it.
+
+```
+  SIGTERM / SIGINT
+        |
+        v
+  +-------------------------------------------------------------+
+  | installGracefulShutdown() signal handler                     |
+  |                                                              |
+  |  shutdownDelayMs === 0 (default)                             |
+  |    -> this IS app.enableShutdownHooks(): close() immediately |
+  |                                                              |
+  |  shutdownDelayMs > 0                                         |
+  |    -> stay FULLY HEALTHY for N ms (routes still served),     |
+  |       so the load balancer can finish deregistering          |
+  |    -> a second signal cancels the wait and closes now        |
+  +----------------------------+---------------------------------+
+                               |  (only after the wait)
+                               v
+  +-------------------------------------------------------------+
+  | app.close()                                                  |
+  |   1. onModuleDestroy                                         |
+  |   2. beforeApplicationShutdown                               |
+  |   3. dispose  (HTTP server socket closes HERE)               |
+  |   4. onApplicationShutdown                                   |
+  |      - CoreRedisService quits every tracked connection       |
+  +-------------------------------------------------------------+
+```
+
+**Why the wait cannot be a lifecycle hook:** the socket only closes at step 3, so a delay placed in
+`beforeApplicationShutdown` (step 2) would keep accepting traffic with every module already torn
+down — strictly worse than not waiting at all.
+
+**Why both together is a bug:** with `enableShutdownHooks()` also installed, Nest registers its own
+listener for the same signals and enters `close()` in parallel with the wait. Nothing errors; the
+delay simply never happens.
+
+| Knob | Default | Notes |
+|------|---------|-------|
+| `shutdownDelayMs` | `0` (no delay, no log) | Warns above `10000`, capped at `60000`. Keep it below the orchestrator grace period (Compose `stop_grace_period` 10 s, Kubernetes `terminationGracePeriodSeconds` 30 s) **and** below `installProcessDiagnostics()`'s 30 s force-exit — exceed any and the process is SIGKILLed mid-wait with no hook running. Non-numeric/negative behaves like `0` |
+
 ---
 
 ## Phase 1: Incoming Request

package/docs/security-overrides.md

@@ -11,16 +11,18 @@ A green `pnpm audit` inside the framework repo says nothing about your tree.
 
 ## What this concretely means for you
 
-The framework pulls in two transitive packages that resolve to a **vulnerable** version unless you
+The framework pulls in three transitive packages that resolve to a **vulnerable** version unless you
 override them yourself:
 
 | Package | Advisory | Why it cannot resolve forward on its own |
 |---------|----------|------------------------------------------|
 | `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | `@nestjs/graphql` declares `"ws": "8.20.1"` — an **exact pin**, not a caret. No amount of updating moves it |
 | `@hono/node-server` | [GHSA-frvp-7c67-39w9](https://github.com/advisories/GHSA-frvp-7c67-39w9) (static-file path traversal) + [GHSA-9mqv-5hh9-4cgg](https://github.com/advisories/GHSA-9mqv-5hh9-4cgg) (unauthenticated memory leak). Patched `>=2.0.10` | `@modelcontextprotocol/sdk` declares `^1.19.9` and ships **no 1.x fix line**, so the fix is only available across a major |
+| `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS). Patched `>=5.2.2` | `@nestjs/swagger` declares `"js-yaml": "5.2.1"` — an **exact pin**, the same shape as the `ws` case. It cannot resolve forward |
 
 `@nestjs/graphql` is a plain `dependencies` entry, so `ws` is installed even when you run with
-`graphQl: false`. Neither package is optional in practice.
+`graphQl: false`. `@nestjs/swagger` is likewise a plain `dependencies` entry. None of the three is
+optional in practice.
 
 ## The fix
 
@@ -31,8 +33,9 @@ Add this to your project's `pnpm-workspace.yaml` (pnpm 11+; in pnpm 10 and earli
 overrides:
   # @nestjs/graphql exact-pins ws@8.20.1 (GHSA-96hv-2xvq-fx4p, high, patched >=8.21.0).
   # An exact pin cannot resolve forward — the override is the only fix.
+  # Keep the target in LOCKSTEP with your direct `ws` dependency (see the note below).
   # Remove once @nestjs/graphql stops pinning it.
-  'ws@>=8.0.0 <8.21.0': '8.21.1'
+  'ws@>=8.0.0 <8.21.0': '8.21.3'
 
   # @modelcontextprotocol/sdk declares @hono/node-server ^1.19.9 with no 1.x fix line
   # (GHSA-frvp-7c67-39w9, GHSA-9mqv-5hh9-4cgg). Deliberately a CROSS-MAJOR override.
@@ -40,8 +43,30 @@ overrides:
   # `(fetchCallback, options?)` is unchanged in 2.x. Engines >=20 and peer hono@^4 both fit.
   # Remove once @modelcontextprotocol/sdk moves its own range to ^2.
   '@hono/node-server@<2.0.10': '2.0.11'
+
+  # @nestjs/swagger exact-pins js-yaml@5.2.1 (GHSA-pm4m-ph32-ghv5, high, patched >=5.2.2).
+  # Same shape as the ws entry: an exact pin cannot resolve forward.
+  # Remove once @nestjs/swagger stops pinning it.
+  'js-yaml@>=5.0.0 <5.2.2': '5.2.2'
 ```
 
+### The `ws` target must stay in lockstep with the declared `ws` version
+
+`8.21.3` is not an arbitrary "latest patch" — it is the version `@lenne.tech/nest-server` declares as
+an ordinary **dependency**, so it is already in your tree whether or not you list `ws` yourself.
+The override target has to equal it.
+
+Under `nodeLinker: hoisted` (what this framework and the starters use), a lower target does not
+merely leave you one patch behind: it puts a **second, older `ws` copy** in the tree next to the
+declared one. The transitive consumers resolve to the override target, the declared dependency stays
+where its `package.json` pins it, and you now carry two `ws` versions — of which only one is visible
+when you read a manifest. The target was raised `8.21.1` → `8.21.3` on 2026-08-10 for exactly this
+reason.
+
+**Rule:** whenever the `ws` version declared by `@lenne.tech/nest-server` (or by your own
+`package.json`, if you list it) moves, move this override target with it in the same commit. The
+same applies to any other override whose package also appears as a declared dependency.
+
 Then:
 
 ```bash
@@ -52,8 +77,8 @@ pnpm test           # nothing should regress
 
 Commit `package.json`/`pnpm-workspace.yaml` **and** `pnpm-lock.yaml` together.
 
-> Projects generated from `nest-server-starter` or `lt-monorepo` already carry both entries. This
-> page is for projects that predate that, or that were assembled by hand.
+> Projects generated from `nest-server-starter` or `lt-monorepo` already carry all three entries.
+> This page is for projects that predate that, or that were assembled by hand.
 
 ## Rules for writing your own overrides
 

package/migration-guides/11.32.3-to-11.32.4.md

@@ -0,0 +1,335 @@
+# Migration Guide: 11.32.3 → 11.32.4
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None in signatures. Six **runtime behaviour** changes you inherit automatically — see §1, §2, §4, §5, §6, §7 |
+| **New Features** | `assertGridFsFileComplete()` — verify a stored GridFS file's chunk completeness; `UploadAllowList` — exact-matching upload filters, with `SCRIPTABLE_UPLOAD_MIME_TYPES` / `SCRIPTABLE_UPLOAD_EXTENSIONS` and the `allowScriptableTypes` opt-out |
+| **Bugfixes** | GridFS uploads no longer report success for incomplete files, no longer hang on an unreadable source, and no longer leak their connection; file downloads answer an honest 404 instead of dropping the socket; the migrate CLI now actually terminates and no longer truncates its own output; the upload filter no longer matches mimetypes and extensions as SUBSTRINGS (`te?xt` accepted `text/html`), no longer reports rejections as a bare string, and `multerOptionsForImageUpload` no longer silently disables all filtering when `fileTypeRegex` is `undefined` |
+| **Migration Effort** | No code changes for most projects, and nothing to configure. Read §1 if you have seed migrations that upload assets, §4 if any test asserts on download error messages, §5–§7 if your project accepts uploads |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.32.4
+pnpm run build
+pnpm test
+```
+
+No configuration change is required. Existing `fileTypeRegex` arguments keep working.
+
+**Vendor-mode projects:** four modified files under `src/core/`
+(`common/helpers/file.helper.ts`, `modules/file/core-file.controller.ts`,
+`modules/migrate/cli/migrate-cli.ts`, `modules/migrate/helpers/migration.helper.ts`) plus
+`bin/migrate.js`. No moved files — there is no atomic file-set hazard for a partial sync.
+
+---
+
+## 1. `uploadFileToGridFS()` now fails loudly instead of quietly
+
+Previously the helper resolved as soon as the write stream emitted `'finish'`. That event says the
+stream ended — it does **not** prove every chunk document is durably stored. A connection lost at the
+wrong moment left a files document promising more bytes than existed, the migration reported success,
+and the defect surfaced much later as a broken download from a record that looked perfectly healthy.
+
+It now verifies chunk completeness before resolving, and **rejects** when the file is incomplete
+(removing the incomplete file so retries do not accumulate orphans).
+
+**What you may notice:** a seed migration that previously "succeeded" while silently storing a broken
+asset now fails.
+
+**What that does to a deployment depends on the `docker-entrypoint.sh` your project copied — check
+yours, and check its default.**
+
+| Your entrypoint | A failed migration |
+|-----------------|--------------------|
+| The one shipped with this framework | Refuses the start (`MIGRATE_FAILURE_POLICY` defaults to `abort`) |
+| From `nest-server-starter` 11.32.4 or newer | Starts the server anyway — the same variable exists, but it defaults to `warn`. Set `MIGRATE_FAILURE_POLICY=abort` per stage to refuse the start |
+| Older, without that variable | Starts the server anyway, with no way to change it short of updating the file |
+
+In the two lower rows the failure is visible only in the container log, and the broken asset still
+ships — so if you deploy from a starter-derived project, decide on `abort` explicitly rather than
+assuming this release stops a bad boot for you.
+
+**Failing is intentional** — finding exactly this is why migrations run before the server. To recover:
+
+```bash
+# 1. Identify the incomplete file from the migration error, which names it:
+#    GridFS file 'logo.png' is incomplete: 1 of 3 chunks stored (id 6a6b…)
+# 2. Verify the source asset is actually present and readable in the image/checkout.
+# 3. Re-run. The helper deletes its own incomplete upload, but a file left behind by
+#    an OLDER version of the helper must be removed manually:
+#      db.getCollection('<bucket>.files').deleteOne({ _id: ObjectId('…') })
+#      db.getCollection('<bucket>.chunks').deleteMany({ files_id: ObjectId('…') })
+```
+
+Two more changes to the same helper, both strictly better and requiring no action:
+
+- **An unreadable source rejects instead of hanging.** `pipe()` does not forward read-stream errors,
+  so a missing file used to leave the promise pending forever — a migration that never returned.
+  It now rejects with the underlying `ENOENT`.
+- **The connection is always closed.** The client it opens is registered and closed on every path.
+  A leaked client keeps an SDAM monitor timer alive, which kept the whole CLI from exiting.
+
+**Note on empty files:** GridFS stores a zero-byte file with **no** chunk documents at all, and the
+completeness check accounts for that. Uploading an empty placeholder asset is valid and passes.
+
+---
+
+## 2. `migrate up` now terminates explicitly
+
+The CLI drains stdout/stderr and then exits, instead of waiting for the event loop to empty. A single
+handle left behind by MongoDB, GridFS or the state store used to keep the process alive after the work
+was done: the CLI printed "All migrations completed successfully" and never returned. On a developer
+machine that is invisible; in CI the job blocks until its timeout, and a container that runs
+migrations before starting the server never reaches the server at all.
+
+Exit codes are unchanged (`0` success, `1` failure), and the drain happens **before** the exit, so no
+output is lost — `process.exit()` does not flush an asynchronous pipe, which is exactly what Docker's
+log driver and CI log collectors are.
+
+**Action required: none**, unless you invoke the CLI in a non-standard way. If you call the CLI
+module directly rather than through the `migrate` / `nest-migrate` bin, use the new exported
+`runCli()` (which drains and exits) instead of `main()` (which merely resolves):
+
+```typescript
+// Before — resolves, but relies on the event loop draining by itself
+const { main } = require('@lenne.tech/nest-server/dist/core/modules/migrate/cli/migrate-cli');
+main();
+
+// After
+const { runCli } = require('@lenne.tech/nest-server/dist/core/modules/migrate/cli/migrate-cli');
+void runCli();
+```
+
+The shipped `bin/migrate.js` already prefers `runCli()` and falls back to `main()`, so a mixed
+version pair keeps working.
+
+---
+
+## 3. New: `assertGridFsFileComplete()`
+
+Exported for direct use when you need to check a file that something else wrote — a restored dump,
+another service, a manual upload:
+
+```typescript
+import { assertGridFsFileComplete, getDb } from '@lenne.tech/nest-server';
+
+const db = await getDb(process.env.MONGODB_URL);
+await assertGridFsFileComplete(db, 'images', fileId, 'logo.png'); // throws if incomplete
+```
+
+It counts chunk documents rather than reading bytes back, so a chunk that was written but truncated
+is not detected. See `src/core/modules/migrate/README.md`.
+
+---
+
+## 4. File downloads: error responses changed
+
+Two changes on `GET /files/id/:id` and `GET /files/:filename`.
+
+**(a) A GridFS read error is now a 404, not a dropped socket.** The stream error previously went
+unhandled, Node destroyed the socket mid-response, and a reverse proxy turned that into
+**502 Bad Gateway** — reading as "the server is down" while every other route answered normally.
+The response is now:
+
+```json
+{ "error": "Not Found", "message": "#LTNS_0500: File not found", "statusCode": 404 }
+```
+
+Once bytes are already on the wire there is no status left to send, so the connection is still closed
+— at that point it genuinely is a truncated transfer.
+
+**(b) Exception messages now carry their ErrorCode.** The controller uses the framework registry
+instead of raw strings, matching every other core module:
+
+| Before | After |
+|--------|-------|
+| `'File not found'` | `ErrorCode.FILE_NOT_FOUND` → `'#LTNS_0500: File not found'` |
+| `'Missing file ID for download'` | `ErrorCode.REQUIRED_FIELD_MISSING` → `'#LTNS_0301: Required field missing'` |
+
+**Action required:** if a test asserts on the exact message, loosen it to a substring match — the old
+text is still contained in the new one. Frontends using `useLtErrorTranslation()` gain a translated
+message where they previously showed raw English.
+
+**Also:** a project that restricted downloads by overriding `CoreFileService.checkRights()` used to
+get a **500** (the refusal produced `null.pipe(res)` → `TypeError`). It is now a **404** —
+deliberately the same answer as an unknown id, so the endpoint cannot be used to probe which files
+exist.
+
+To customise the status, body or logging of the streaming error path, override the new
+`protected pipeFileToResponse()` method on your controller:
+
+```typescript
+export class FileController extends CoreFileController {
+  protected override pipeFileToResponse(stream: Readable, res: Response): Response {
+    // e.g. report a different status, or add your own telemetry
+    return super.pipeFileToResponse(stream, res);
+  }
+}
+```
+
+---
+
+## 5. The upload filter matched substrings, not values
+
+**What changed:** `multerFileFilter` compared the mimetype and the extension by
+`RegExp.test()` — a substring search. Every alternative therefore matched
+anywhere inside either value.
+
+**Why it matters:** an allow-list containing `text` or `txt` also accepted
+`text/html` and `text/xml`. A file named `x.txt` and sent as `text/html` passed
+both halves of a filter whose own comment said "no html". `md` matched every
+mimetype containing "md", `zip` every one containing "zip". The single
+alternative was never the bug — the substring semantics were.
+
+Anchoring the expression was not an option: the SAME expression was tested
+against two different value spaces, so it had to carry mimetype FRAGMENTS
+(`wordprocessingml`, `ms-excel`) next to bare extensions, and no `^…$` satisfies
+both at once.
+
+**What to do:** nothing, if your filter only ever listed image formats — those
+never matched markup. If your filter lists text-ish or document formats, move to
+the new exact-matching form:
+
+```ts
+// Before — substring matching
+multerOptionsForImageUpload({ fileTypeRegex: /jpeg|jpg|png|pdf|te?xt|csv/ });
+
+// After — whole-value matching
+multerOptionsForImageUpload({
+  allowList: {
+    extensions: ['.csv', '.jpeg', '.jpg', '.pdf', '.png', '.txt'],
+    mimeTypes: ['application/pdf', 'image/jpeg', 'image/png', 'text/csv', 'text/plain'],
+  },
+});
+```
+
+The two conditions stay **independent**: either one alone rejects the file, but a
+pair that is odd yet individually allowed (`report.txt` announced as
+`application/pdf`) passes. An extension→mimetype MAPPING is deliberately not
+enforced — user agents genuinely disagree about office and audio types (macOS
+reports `.csv` as `text/plain`), so a mapping rejects legitimate uploads.
+
+`fileTypeRegex` still works and is not removed; it is marked deprecated.
+
+---
+
+## 6. Scriptable types are now rejected on BOTH forms
+
+**What changed:** `text/html`, `text/xml`, `application/xhtml+xml`,
+`image/svg+xml`, JavaScript types and the matching extensions (`.html`, `.svg`,
+`.js`, `.xml`, …) are rejected before the allow-list is consulted — including
+when a legacy `fileTypeRegex` would have matched them.
+
+**Why it matters:** this is what closes §5 for expressions that already exist in
+consumer projects, without anyone having to rewrite them. The danger does not
+depend on what an endpoint meant to accept: a stored upload served back from the
+API origin with one of these content types executes in that origin, with the
+victim's session.
+
+**What to do:** if you deliberately accept SVG logos or HTML fragments, opt out
+explicitly:
+
+```ts
+multerFileFilter(
+  { extensions: ['.svg'], mimeTypes: ['image/svg+xml'] },
+  { allowScriptableTypes: true },
+);
+```
+
+Only do that when the file is never served from an origin that carries a session
+— e.g. a separate download host, or a route that always answers with
+`Content-Disposition: attachment` **and** `X-Content-Type-Options: nosniff`.
+
+---
+
+## 7. `fileTypeRegex: undefined` no longer disables filtering
+
+**What changed:** `multerOptionsForImageUpload` built its config as
+`{ fileTypeRegex: /jpeg|jpg|png/, ...options }` and then installed a filter only
+`if (config.fileTypeRegex)`. Passing the key explicitly as `undefined`
+overwrote the default, so **no filter was installed at all** and every file type
+was accepted — on a helper named "ImageUpload".
+
+**Why it matters:** this is easy to trigger by accident rather than intent:
+
+```ts
+// The author meant "then just the standard image types".
+// Before: they got "then everything".
+multerOptionsForImageUpload({ fileTypeRegex: allowSvg ? /jpeg|jpg|png|svg/ : undefined });
+```
+
+Any optional variable threaded into that option had the same effect.
+
+**What to do:** if a project relied on this to accept arbitrary types, it now
+gets JPEG/PNG only and those uploads start failing. Pass an explicit `allowList`
+naming what the endpoint really accepts. There is intentionally no "accept
+everything" switch — an upload endpoint that takes any type should not be built
+on `multerOptionsForImageUpload`.
+
+---
+
+## 8. Upload rejections are a real `Error`
+
+**What changed:** the filter called `cb('Error: File upload only supports …')`
+with a bare **string**. It now passes an `Error`.
+
+**Why it matters:** a string has no `message`, so NestJS's `transformException`
+could not map it and the request surfaced as a 500 instead of a 4xx.
+
+**What to do:** nothing, unless a test asserts on the exact error value. Assert
+on `error.message` instead.
+
+---
+
+## 9. Dependency housekeeping (no action required)
+
+- `js-yaml` gained an override for [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5)
+  (high). **`@nestjs/swagger` exact-pins `js-yaml@5.2.1`, so your project needs this override too** —
+  a framework override does not reach consumer trees. See
+  [`docs/security-overrides.md`](../docs/security-overrides.md), which now lists all three affected
+  packages.
+- The `minimatch` override range was narrowed to `>=9.0.0`; majors 5–8 export a callable function and
+  would break under a forced lift to 10.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Migration now fails with `is incomplete: N of M chunks stored` | The asset was already broken in the database; the old helper never checked | See §1 — verify the source asset, remove the orphan, re-run |
+| Migration now fails with `ENOENT` | The source path was always wrong; it used to hang instead of failing | Fix the path. It is resolved against the **helper module's** directory |
+| A test asserting `'File not found'` fails | The message now carries its ErrorCode prefix | Match on a substring, or on `ErrorCode.FILE_NOT_FOUND` |
+| A download that returned 500 now returns 404 | `checkRights()` refusal is handled properly instead of crashing | Intended — see §4 |
+| An upload fails with `may execute as script` | The type is markup or script and is now rejected regardless of the filter | Intended — see §6, and opt out only under the conditions named there |
+| An upload of a document type that used to pass now fails | The filter matched it as a substring before | Move to `allowList` naming the type exactly — see §5 |
+| Uploads that accepted every type now accept JPEG/PNG only | `fileTypeRegex: undefined` no longer disables the filter | Pass an explicit `allowList` — see §7 |
+| A test asserting on the filter's rejection string fails | Rejections are an `Error` now, not a string | Assert on `error.message` — see §8 |
+
+---
+
+## Verification
+
+```bash
+pnpm test
+```
+
+`src/core/common/helpers/file.helper.spec.ts` covers the substring class (values that merely CONTAIN
+an allowed token), the scriptable-type rejection on both forms, the opt-out, and that the legacy
+`RegExp` form still accepts what it accepted before.
+`src/core/modules/migrate/helpers/migration.helper.spec.ts` and
+`tests/migrate/upload-file-to-gridfs.e2e-spec.ts` cover the completeness check against a real GridFS
+bucket; `src/core/modules/file/core-file.controller.spec.ts` covers the download error paths.
+
+---
+
+## Related Documentation
+
+- [`src/core/modules/migrate/README.md`](../src/core/modules/migrate/README.md) — `uploadFileToGridFS()`, `assertGridFsFileComplete()`
+- [`src/core/modules/file/README.md`](../src/core/modules/file/README.md) — download endpoints, error responses
+- [`docs/security-overrides.md`](../docs/security-overrides.md) — overrides consumers must replicate