@lenne.tech/nest-server 11.32.2 → 11.32.4

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
 
@@ -40,6 +42,11 @@ 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'
 ```
 
 Then:

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

@@ -0,0 +1,129 @@
+# Migration Guide: 11.32.2 → 11.32.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | `ai.capabilityDriftCheck` — opt-in boot warning when an explicit connection capability contradicts the endpoint; `ai.defaultConnection.contextWindow` — seed a connection's context window from config |
+| **Bugfixes** | The AI connection `contextWindow` admin input now rejects non-positive / non-integer values |
+| **Migration Effort** | ~2 minutes — everything is opt-in; read §3 only if your admin tooling writes `contextWindow` |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.32.3
+pnpm run build
+pnpm test
+```
+
+No configuration change is required. Everything below is opt-in or a
+tightening you inherit automatically.
+
+---
+
+## 1. New: `ai.capabilityDriftCheck` (opt-in, default `false`)
+
+A connection's `supportsNativeTools` / `supportsJsonResponse` flags are
+auto-detected while they are left **undefined**, but an **explicit** value is
+authoritative and is never re-probed. A wrong explicit flag therefore degrades the
+assistant silently — e.g. `supportsNativeTools: false` on a backend that *does*
+support native function calling forces fragile emulated tool-calling.
+
+Enable this opt-in boot self-check to surface such a mismatch:
+
+```typescript
+ai: {
+  capabilityDriftCheck: true,  // default false
+}
+```
+
+When enabled, at startup the module probes each enabled connection that declares an
+explicit flag and logs a **warning** on mismatch. It never changes the stored value
+(your explicit choice stays authoritative — clear the flag in the admin UI to
+re-enable auto-detection).
+
+**It is off by default because it makes outbound calls to the LLM endpoints on
+every boot** (and is additionally skipped in the `ci`/`e2e` runners). Note this is a
+diagnostic log only: if you deliberately override a flag against what the endpoint
+reports (e.g. native tools are advertised but unreliable on your model), the warning
+is expected and can be ignored.
+
+**Action: none** unless you want the diagnostic — then set the flag.
+
+---
+
+## 2. New: `ai.defaultConnection.contextWindow`
+
+The one-time `ai.defaultConnection` seed now accepts `contextWindow`, so a
+config-seeded connection can carry its context window from the start instead of
+relying on auto-detection:
+
+```typescript
+ai: {
+  defaultConnection: {
+    name: 'default',
+    baseUrl: '...',
+    model: '...',
+    contextWindow: 32768,  // optional — omit to auto-detect
+  },
+}
+```
+
+Omit it to keep the existing behaviour (auto-detect by probing the endpoint /
+`knownContextWindow()`, falling back to the global `ai.contextWindow` default of
+8192).
+
+**Action: none** — additive and optional.
+
+---
+
+## 3. Tightened: `contextWindow` admin input validation
+
+The `contextWindow` field on the AI connection create/update input is now validated
+as a **positive integer** (`@IsInt` + `@Min(1)`). Previously any number (including
+`0`, a negative, or a float) was accepted verbatim, and an explicit `0` is not
+"unset" — it would have fed the orchestrator's context budget as a real (broken)
+value instead of falling back to the safe default.
+
+**Action required if** your admin tooling or tests send a non-integer or
+`< 1` `contextWindow` to `createAiConnection` / `updateAiConnection` — those calls
+now return a validation error. Send a positive integer, or omit the field to
+auto-detect.
+
+---
+
+## 4. Documentation: the MCP confirmation-gate boundary
+
+No code change — a clarification of the `IAiTool.destructive` / `.mutating` JSDoc
+(reinforcing §5 of the 11.32.2 guide). Over `/ai/mcp` there is **no confirmation
+gate**: `mcpCallTool` consults neither flag, so a destructive tool executes on the
+first call. The barriers that *do* hold on every path are the registry **role
+filter** (`forUser()`, applied before `execute()`) and the authorization inside
+`execute()` itself — so a destructive tool restricted to a real role stays
+unreachable by lesser-privileged MCP clients; MCP only skips the extra confirmation
+step for clients that may already see the tool.
+
+**Action:** expose `/ai/mcp` only to clients you trust to obtain user consent
+themselves, and keep data-level authorization inside `execute()` (not only in the
+plan-mode `authorize()`).
+
+---
+
+## Module Documentation
+
+- [AI module README](../src/core/modules/ai/README.md) — see "Capability auto-detection"
+- [AI INTEGRATION-CHECKLIST](../src/core/modules/ai/INTEGRATION-CHECKLIST.md) — advanced configuration
+- [Configurable features](../.claude/rules/configurable-features.md) — the AI Assistant row
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Boot logs "capability drift" for a connection | §1 — an explicit flag disagrees with the endpoint | Correct the flag in the admin UI, or clear it to auto-detect; ignore if the override is deliberate |
+| `createAiConnection` rejects `contextWindow` | §3 — it must be a positive integer now | Send an integer `>= 1`, or omit to auto-detect |
+| A destructive tool ran over `/ai/mcp` without confirmation | §4 — MCP has no confirmation gate by design | Only expose MCP to trusted clients; enforce data-level checks in `execute()` |

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

@@ -0,0 +1,323 @@
+# 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. Since `docker-entrypoint.sh` defaults to `MIGRATE_FAILURE_POLICY=abort`, that failure
+keeps the container from starting.
+
+**This 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.32.2",
+  "version": "11.32.4",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

package/src/core/common/helpers/file.helper.spec.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest';
+
+import { IMAGE_UPLOAD_ALLOW_LIST, multerFileFilter, multerOptionsForImageUpload, UploadAllowList } from './file.helper';
+
+/**
+ * The filter used to be ONE unanchored `RegExp`, `.test()`ed against the
+ * mimetype AND the extension. `.test()` searches for a substring, so every
+ * alternative matched anywhere inside either value — `te?xt` matched the "text"
+ * in `text/html`, and a file named `x.txt` sent as `text/html` passed both
+ * halves of a filter documented as "no html".
+ *
+ * Consumer projects hit this for real. The tests below therefore cover three
+ * things: the exact-matching allow-list, that the legacy `RegExp` form still
+ * works, and — the point of the fix — that scriptable types are rejected on
+ * BOTH paths, so an expression that already exists in a consumer project is
+ * safe without being rewritten.
+ */
+
+/** Run a filter the way multer does and report its verdict. */
+function verdict(
+  filter: ReturnType<typeof multerFileFilter>,
+  mimetype: string,
+  originalname: string,
+): { accepted: boolean; error?: string } {
+  let accepted = false;
+  let error: string | undefined;
+  filter({}, { mimetype, originalname }, (err: any, result?: boolean) => {
+    if (err) {
+      error = err instanceof Error ? err.message : String(err);
+    }
+    accepted = result === true;
+  });
+  return { accepted, error };
+}
+
+const DOCUMENTS: UploadAllowList = {
+  extensions: ['.csv', '.pdf', '.txt'],
+  mimeTypes: ['application/pdf', 'text/csv', 'text/plain'],
+};
+
+describe('multerFileFilter', () => {
+  describe('allow-list form', () => {
+    it('accepts a mimetype and extension that are both on the list', () => {
+      expect(verdict(multerFileFilter(DOCUMENTS), 'text/plain', 'notes.txt').accepted).toBe(true);
+      expect(verdict(multerFileFilter(DOCUMENTS), 'application/pdf', 'report.pdf').accepted).toBe(true);
+    });
+
+    it('rejects as soon as one half is missing from the list', () => {
+      expect(verdict(multerFileFilter(DOCUMENTS), 'application/x-msdownload', 'setup.pdf').accepted).toBe(false);
+      expect(verdict(multerFileFilter(DOCUMENTS), 'application/pdf', 'setup.exe').accepted).toBe(false);
+    });
+
+    it('matches whole values, never substrings', () => {
+      // Only an unanchored matcher would let these through.
+      expect(verdict(multerFileFilter(DOCUMENTS), 'evil/text-plain', 'notes.txt').accepted).toBe(false);
+      expect(verdict(multerFileFilter(DOCUMENTS), 'text/plain', 'notes.txtx').accepted).toBe(false);
+    });
+
+    it('ignores mimetype parameters and casing', () => {
+      expect(verdict(multerFileFilter(DOCUMENTS), 'text/plain; charset=utf-8', 'notes.txt').accepted).toBe(true);
+      expect(verdict(multerFileFilter(IMAGE_UPLOAD_ALLOW_LIST), 'IMAGE/PNG', 'PHOTO.PNG').accepted).toBe(true);
+    });
+
+    it('rejects a file without an extension', () => {
+      expect(verdict(multerFileFilter(DOCUMENTS), 'text/plain', 'README').accepted).toBe(false);
+    });
+  });
+
+  describe('scriptable types are rejected on BOTH forms', () => {
+    // This is what makes an ALREADY EXISTING consumer expression safe.
+    const legacy = /jpeg|jpg|png|te?xt|csv/;
+
+    it('rejects text/html even when the expression matches it as a substring', () => {
+      const result = verdict(multerFileFilter(legacy), 'text/html', 'invoice.txt');
+      expect(result.accepted).toBe(false);
+      expect(result.error).toMatch(/may execute as script/);
+    });
+
+    it('rejects text/xml and application/xhtml+xml', () => {
+      expect(verdict(multerFileFilter(legacy), 'text/xml', 'notes.txt').accepted).toBe(false);
+      expect(verdict(multerFileFilter(legacy), 'application/xhtml+xml', 'notes.txt').accepted).toBe(false);
+    });
+
+    it('rejects SVG on the image default', () => {
+      expect(verdict(multerFileFilter(), 'image/svg+xml', 'logo.svg').accepted).toBe(false);
+    });
+
+    it('rejects a scriptable EXTENSION even under a harmless mimetype', () => {
+      expect(verdict(multerFileFilter(legacy), 'text/plain', 'payload.html').accepted).toBe(false);
+      expect(verdict(multerFileFilter(legacy), 'image/png', 'payload.svg').accepted).toBe(false);
+    });
+
+    it('allows them only when the caller opts in explicitly', () => {
+      const filter = multerFileFilter(
+        { extensions: ['.svg'], mimeTypes: ['image/svg+xml'] },
+        {
+          allowScriptableTypes: true,
+        },
+      );
+      expect(verdict(filter, 'image/svg+xml', 'logo.svg').accepted).toBe(true);
+    });
+  });
+
+  describe('legacy RegExp form stays usable', () => {
+    it('still accepts what it accepted before', () => {
+      const filter = multerFileFilter(/jpeg|jpg|png/);
+      expect(verdict(filter, 'image/jpeg', 'photo.jpg').accepted).toBe(true);
+      expect(verdict(filter, 'image/png', 'photo.png').accepted).toBe(true);
+      expect(verdict(filter, 'application/pdf', 'report.pdf').accepted).toBe(false);
+    });
+  });
+
+  describe('rejection reporting', () => {
+    it('reports a real Error, not a bare string', () => {
+      let received: unknown;
+      multerFileFilter(DOCUMENTS)({}, { mimetype: 'application/x-foo', originalname: 'x.foo' }, (err: unknown) => {
+        received = err;
+      });
+      // A bare string leaves multer with an "error" that has no `message`,
+      // which NestJS's transformException cannot map to a 4xx.
+      expect(received).toBeInstanceOf(Error);
+    });
+  });
+});
+
+describe('multerOptionsForImageUpload', () => {
+  it('applies the image allow-list by default', () => {
+    const filter = multerOptionsForImageUpload({}).fileFilter!;
+    expect(verdict(filter as any, 'image/png', 'a.png').accepted).toBe(true);
+    expect(verdict(filter as any, 'image/svg+xml', 'a.svg').accepted).toBe(false);
+  });
+
+  it('still installs a filter when fileTypeRegex is explicitly undefined', () => {
+    // Previously this disabled filtering entirely — on a helper named
+    // "ImageUpload". Safe-by-default instead; see the migration guide.
+    const filter = multerOptionsForImageUpload({ fileTypeRegex: undefined }).fileFilter;
+    expect(filter).toBeDefined();
+    expect(verdict(filter as any, 'text/html', 'a.txt').accepted).toBe(false);
+  });
+
+  it('honours an explicit allowList', () => {
+    const filter = multerOptionsForImageUpload({ allowList: DOCUMENTS }).fileFilter!;
+    expect(verdict(filter as any, 'application/pdf', 'report.pdf').accepted).toBe(true);
+  });
+});