@lenne.tech/nest-server 11.33.1 → 11.34.1

package/migration-guides/11.23.x-to-11.24.0.md

@@ -267,6 +267,6 @@ If your code accessed `result.author.password` after a CrudService call (within
 
 ## References
 
-- [SubDocument Array Optimization](../docs/subdocument-array-optimization-plan.md) — Detailed OOM analysis and implementation notes
+- SubDocument array handling (`pushToArray()` / `pullFromArray()`, and why a subdoc array must never pass through `CrudService.update()`) — see `CLAUDE.md` § High-Frequency Path Design Rules, rule 6. The former `docs/subdocument-array-optimization-plan.md` was a working document and no longer exists
 - [process() Performance Optimization](../docs/process-performance-optimization.md) — Pipeline optimization details
 - [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — Reference implementation

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

@@ -1297,6 +1297,8 @@ re-resolve. Update the lockfile and re-run `pnpm audit` rather than assuming the
 | 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 `duplicateByName()` / `duplicateById()` | **Action required in 11.34.0** | They take an optional `serviceOptions` and are authorized now, and `duplicateByName()` resolves a `CoreFileInfo` instead of a write stream — [11.33.x → 11.34.x](./11.33.x-to-11.34.x.md) §1 |
+| Test asserting on the error of `deleteFile(<unknown id>)` | **Action required in 11.34.0** | `NotFoundException` (404) instead of `MongoRuntimeError` (500) — [11.33.x → 11.34.x](./11.33.x-to-11.34.x.md) §3 |
 | 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) |

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

@@ -0,0 +1,394 @@
+# Migration Guide: 11.33.x → 11.34.x
+
+## Why this is a MINOR
+
+Per `.claude/rules/versioning.md` the MAJOR mirrors NestJS, so **MINOR is where breaking changes
+live**. This release changes the declared return type of a public method (§1), so it is `11.34.0`
+rather than a `11.33.2` patch — even though the change set is small and every other entry is a fix
+you simply inherit.
+
+## Upgrade urgency
+
+Three of the eight defects fixed here are severe. If you are on 11.33.x, these are the reason to
+move now rather than at the next convenient moment:
+
+| # | Defect | Exposure | Section |
+|---|--------|----------|---------|
+| 1 | **Duplication bypassed `checkRights()` entirely** on the GridFS driver — a per-file ownership rule did not apply to `duplicateByName()` at all | Any project with an overridden `checkRights()` that exposes duplication. The copy was made with **no** authorization | [§1](#1-security-duplication-bypassed-checkrights-on-gridfs) |
+| 2 | **An aborted upload crashed the process** — an unhandled stream `'error'` is an uncaught exception in Node | Every GridFS upload; and every tus finalization into S3. A client that hangs up mid-upload takes the API down | [§2](#2-crash-an-aborted-upload-no-longer-takes-the-process-down-gridfs-and-s3) |
+| 3 | Same crash on the **S3** streaming write path | `tus` + `file.storage: 's3'` | [§2](#2-crash-an-aborted-upload-no-longer-takes-the-process-down-gridfs-and-s3) |
+
+Both crash paths are reachable from unauthenticated-adjacent traffic (an upload that is simply cut
+off), and neither leaves a stack trace pointing at the file module — they surface as an unexplained
+pod restart. If you have been seeing those on a replica that accepts uploads, §2 is a strong
+candidate.
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Security** | `duplicateByName()` no longer copies a file without a rights check on the GridFS driver (§1) |
+| **Stability** | An upload whose SOURCE stream fails no longer crashes the process — on GridFS, and on the S3 driver's streaming (tus finalization) path (§2) |
+| **Breaking Changes** | `duplicateByName()` resolves the COPY's `CoreFileInfo` instead of a raw `GridFSBucketWriteStream` (§1). `duplicateByName()` / `duplicateById()` now run `checkRights()` — a project with a fail-closed `checkRights()` that duplicated files without passing a context gets a refusal where the GridFS driver previously copied unchecked (§1). `deleteFile()` answers `NotFoundException` (404) for an unknown id instead of the driver's `MongoRuntimeError` (500) (§3) |
+| **New Features** | `duplicateByName()` / `duplicateById()` accept an optional `serviceOptions` (§1). `CoreFileService.duplicateFile()` as the shared, driver-agnostic write half. The Hub's **Files panel covers all three storage drivers** (§6) |
+| **Bugfixes** | `findFileInfo()` sorts correctly on a DOTTED path (`metadata.ownerId`) across merged stores — a wrong order there returned the wrong ROWS, not merely the wrong order (§4). `findFileInfo()` can filter and sort on `contentType` across all three drivers (§5). `duplicateByName()` keeps the source's content type on the GridFS driver |
+| **Migration Effort** | Nothing to configure. Read §1 if you call `duplicateByName()` / `duplicateById()` anywhere, §3 if any test asserts on the error a delete-by-unknown-id produces. Everything else is a fix you inherit |
+
+All of it lives in the file module, the GridFS helper, `CoreS3Service`'s upload path and the Hub's DB
+service. If your project never calls the duplicate methods, the only changes you can observe are the
+fixes — all of which turn a wrong answer into a right one.
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.34.0
+pnpm run build
+pnpm test
+```
+
+**Vendor-mode projects:** eight modified files under `src/core/`, in two independent groups. No
+moved files and no new files, so a partial sync has no atomic file-set hazard — but the Hub group
+must land together, because the panel, its data contract and its action message changed as one.
+
+| Group | Files |
+|-------|-------|
+| File module (§1–§5) | `common/helpers/gridfs.helper.ts`, `common/services/core-s3.service.ts`, `modules/file/core-file.service.ts` |
+| Hub Files panel (§6) | `modules/hub/services/core-hub-db.service.ts`, `modules/hub/services/core-hub-actions.service.ts`, `modules/hub/interfaces/hub-panels.interface.ts`, `modules/hub/hub-action-messages.ts`, `modules/hub/helpers/hub-client-js.helper.ts` |
+
+The reference implementation in `src/server/modules/file/file.service.ts` also changed (§1), but
+vendor projects do not receive `src/server/` — if you copied its old `duplicate()` body, see §1.
+
+---
+
+## 1. Security: duplication bypassed `checkRights()` on GridFS
+
+### What was wrong
+
+Neither `duplicateByName()` nor `duplicateById()` accepted `serviceOptions` at all. They still called
+`getFileInfo()`, `getFileStream()` and `createFile()` — all of which run `checkRights()` — but with an
+**empty context**. Under the fail-closed `checkRights()` that this framework's README, its reference
+server and `nest-server-starter` all teach, that produced three different wrong answers depending on
+the storage driver:
+
+| Call | `gridfs` | `filesystem` | `s3` |
+|------|----------|--------------|------|
+| `duplicateById(id)` | `TypeError: Cannot read properties of null (reading 'filename')` | same `TypeError` | same `TypeError` |
+| `duplicateByName(a, b)` | **succeeded — the file was copied with no rights check at all** | `Error: FilesystemFileHelper.writeFile requires either 'buffer' or 'body'` | `TypeError: … (reading 'Symbol(Symbol.asyncIterator)')` |
+
+The GridFS cell is the severe one, and it is the reason this release exists: that branch went
+straight to the bucket and never consulted `checkRights()`, so a per-file ownership rule simply did
+not apply to duplication. On the default storage driver, any caller who could reach a duplicate
+endpoint could copy **any** file — and the copy, being a new file, was then reachable under whatever
+rule the copy itself satisfied.
+
+The other two cells are the same defect failing loudly instead of silently. That asymmetry is why it
+survived: the drivers that would have made the bug obvious were the ones nobody ran.
+
+### What it does now
+
+A duplicate is treated as what it is — a **READ of the source plus a WRITE of the copy** — and each
+half is authorized through the ordinary public method:
+
+| Half | Method | `checkInputType` |
+|------|--------|------------------|
+| read the source | `getFileInfoByName()` / `getFileInfo()` + `getFileStreamByName()` / `getFileStream()` | `'filename'` / `'id'` |
+| write the copy | `createFile()` | `'file'` |
+
+```typescript
+// Forward the caller's context, so the duplicate is COVERED by your rule
+await this.fileService.duplicateById(id, { currentUser });
+await this.fileService.duplicateByName(name, newName, { currentUser });
+
+// …or say explicitly that a role decorator already decided
+await this.fileService.duplicateById(id, { force: true });
+
+// …and give the COPY its own metadata (see below)
+await this.fileService.duplicateById(id, { currentUser, metadata: { ownerId: currentUser.id } });
+```
+
+A missing source, or a refused read, now answers `NotFoundException` — the same 404 the download
+routes answer, so a refusal never confirms that an id or a filename is real. A refused **write**
+answers through `accessDeniedException()` (403 authenticated / 401 anonymous), because at that point
+the caller has already been shown the source and the question is no longer whether the file exists.
+
+### Break 1 — a fail-closed `checkRights()` now applies to duplication
+
+This is the security fix seen from the consumer's side: if your project overrides `checkRights()` and
+duplicates files **without** passing a context, the GridFS driver used to copy anyway. It now refuses.
+
+**Symptom:** `NotFoundException: File not found with filename …` (or `… with id …`) from a code path
+that worked before, and no copy in the bucket.
+
+**Fix:** pass `{ currentUser }` where a user is in scope, or `{ force: true }` where a role decorator
+has already decided. Do **not** add `if (!options.currentUser) return true` to `checkRights()` — that
+reads "system-internal call", but it is also exactly what an anonymous request looks like.
+
+### Break 2 — the return value of `duplicateByName()`
+
+```typescript
+// 11.33.x and earlier, GridFS driver: the raw write stream
+const stream = await fileService.duplicateByName('a.txt', 'b.txt');
+stream.id; // ObjectId
+
+// 11.34.0: the copy's file info, under every driver
+const copy = await fileService.duplicateByName('a.txt', 'b.txt');
+copy.id;       // string
+copy.filename; // 'b.txt'
+```
+
+`.id` and `.filename` still answer (as a string and the new name), so the common uses keep working —
+`String(result.id)` and `getStringIds(result.id)` are unaffected. Anything that treated the result as
+a **stream** has to change. The declared return type moved from `Promise<any>` to
+`Promise<CoreFileInfo>`, so TypeScript points at the sites for you. **This is the change that makes
+the release a MINOR.**
+
+This break is not avoidable: the GridFS branch could only be authorized by routing it through
+`createFile()` like the other two drivers, and that is what produces a file info. The S3 and
+filesystem branches already returned a `CoreFileInfo`, so this also removes a driver-conditional
+return type that was never documented as one.
+
+`duplicateById()` still returns the copy's id as a `string`. Unchanged.
+
+### The copy does not inherit the source's metadata
+
+It never did, and it deliberately still does not: silently copying `metadata` would hand the
+duplicate the **source's owner**, which is the one thing an ownership rule must not do behind the
+caller's back. State the copy's own metadata instead:
+
+```typescript
+await this.fileService.duplicateById(id, { currentUser, metadata: { copiedFrom: id, ownerId: currentUser.id } });
+```
+
+Under a fail-closed rule a copy made without metadata is reachable by ADMIN only — that is
+fail-closed, not lost data, and `getFileInfo(copyId, { force: true })` still finds it.
+
+### If you copied `FileService.duplicate()` out of `src/server`
+
+The reference implementation was a direct GridFS pipe — and because it is a reference
+implementation, this defect was **designed to be copied**:
+
+```typescript
+// WRONG — and it was in the reference implementation until 11.34.0
+async duplicate(fileName: string, newName: string): Promise<any> {
+  return this.files.openDownloadStreamByName(fileName).pipe(this.files.openUploadStream(newName));
+}
+```
+
+It only worked on the GridFS driver, bypassed `checkRights()` entirely, returned before the copy was
+written, and carried no error handler on either stream (an unhandled stream `'error'` takes the
+process down — the same defect as §2). It now delegates:
+
+```typescript
+async duplicate(fileName: string, newName: string, serviceOptions?: FileServiceOptions): Promise<CoreFileInfo> {
+  return this.duplicateByName(fileName, newName, serviceOptions);
+}
+```
+
+**If you copied the old body into your own `FileService`, replace it with the delegation above.** The
+framework fix does not reach a copy living in your project.
+
+---
+
+## 2. Crash: an aborted upload no longer takes the process down (GridFS **and** S3)
+
+Two write paths handed a body stream to something that did not listen on the SOURCE. `pipe()` does
+not forward source errors, and an unhandled `'error'` event is an uncaught exception in Node — which
+ends the process. An aborted upload could take the API down.
+
+| Write path | Reached by | Before | After |
+|------------|-----------|--------|-------|
+| `GridFSHelper.writeFileFromStream()` | every GridFS upload | **process crash** | rejects, partial upload aborted |
+| `CoreS3Service.putObject()` with a body stream + `contentLength` | **tus finalization into S3** | **process crash** | rejects with the real cause |
+| `CoreS3Service.putObject()` without a length | `createFile()` on the S3 driver | rejects (`streamToBuffer` throws) | unchanged |
+| `FilesystemFileHelper.writeFile()` | every filesystem upload | rejects (`pipeline()` forwards both ends) | unchanged |
+
+So the same aborted upload behaved in three different ways depending on `file.storage` — which is
+the driver asymmetry this release keeps finding, in its most expensive form.
+
+**GridFS.** The failed write is now aborted as well, so its chunks do not linger in `fs.chunks` with
+no `fs.files` document naming them.
+
+**S3.** The AWS SDK pipes the request body into its HTTP request without a source listener. Adding a
+listener alone is *not* enough: the SDK's own pipeline still observes a stream that errored and
+rejects a promise nothing awaits — an unhandled rejection, which Node also treats as fatal by
+default. The body is therefore relayed through a `PassThrough` that simply **ends early** on source
+failure, which the SDK reports as an ordinary short-body request error; the captured source error
+then replaces the SDK's `socket hang up`, so the log names the cause rather than the symptom.
+
+Nothing to do — but if you have been seeing unexplained restarts on a pod that accepts uploads (or
+finalizes tus uploads into S3), this is the fix.
+
+---
+
+## 3. `deleteFile()` answers 404 for an unknown id, not 500
+
+`deleteFileByName()` threw `NotFoundException` for a filename that does not exist. `deleteFile()` fell
+through to the GridFS driver, which threw its own `MongoRuntimeError: File not found for id …` — an
+HTTP **500** for the very same condition, under all three storage drivers.
+
+```typescript
+await fileService.deleteFile(unknownId);
+// 11.33.x: MongoRuntimeError → 500
+// 11.34.0: NotFoundException → 404
+```
+
+A **refusal** still answers `null` rather than throwing, which is unchanged and is the module-wide
+contract: a refusal must be indistinguishable from a file that is not there.
+
+**What to check:** any test or client code that asserts on the error of a delete-by-unknown-id. If
+you catch `MongoRuntimeError` there, catch `NotFoundException` instead — or, better, treat 404 as the
+idempotent-delete case.
+
+---
+
+## 4. `findFileInfo()` sorts correctly on a dotted path across stores
+
+`SortInput.field` is a free string, and MongoDB reads `metadata.ownerId` as a path into the document.
+Each store therefore returned its own page correctly ordered — and the merge that follows compared
+`doc['metadata.ownerId']`, which is `undefined` for every row. Every comparison tied, and the merged
+page came back **grouped by store**.
+
+That is not a cosmetic ordering bug: `skip` / `limit` applied to a wrongly ordered merge returns
+**different rows**, so a paginated listing sorted on a nested field silently showed some files twice
+and others never.
+
+Only the multi-store read path was affected — i.e. any `file.storage` other than `gridfs`, or a
+GridFS deployment that also has files in `s3-files` / `filesystem-files` from a previous driver.
+
+---
+
+## 5. `findFileInfo()` can filter and sort on `contentType` under every driver
+
+`s3-files` and `filesystem-files` carry `contentType` at the root of the metadata document. GridFS
+keeps it inside `metadata` (the MongoDB driver dropped the top-level option in v7). So a filter on
+`contentType` matched every S3 / filesystem file and **no** GridFS file:
+
+| Driver | `findFileInfo({ filter: contentType == 'application/pdf' })` before | after |
+|--------|--------------------------------------------------------------------|-------|
+| `gridfs` | always `[]` | matches |
+| `filesystem` / `s3` | matches new files, **silently drops every pre-switch GridFS file** | matches both |
+
+`GridFSHelper.findFiles()` now rewrites a `contentType` key to `metadata.contentType` in both the
+filter and the sort — the mirror image of the normalisation it already did on the way out. The
+rewrite is deliberately narrow: only that one key, only where it names a field, recursing only
+through `$and` / `$or` / `$nor`, and an already-qualified `metadata.contentType` is left alone.
+
+**What you may notice:** a listing filtered on `contentType` that used to return nothing now returns
+rows. If you depended on the empty result, filter on something else.
+
+---
+
+## 6. The Hub's Files panel covers all three storage drivers
+
+`CoreHubDbService.getFiles()` / `deleteFile()` read GridFS directly, so under `file.storage: 's3'` or
+`'filesystem'` the Hub's Files panel reported **0 files** and could not delete anything.
+
+"0 files" is not "this panel does not cover your driver" — in an operator cockpit a confidently wrong
+answer is worse than an honest gap, because it is the answer an operator acts on. Somebody checking
+whether an upload landed would have concluded it had not.
+
+The panel now reads the same three metadata sources `CoreFileService.findFileInfo()` does
+(`fs.files`, `s3-files`, `filesystem-files`), merges them newest-first, and dispatches a delete to
+whichever store actually holds the file. Each row carries a **Store** column, and the panel's tiles
+name the stores consulted with a per-store count.
+
+| Behaviour | Before | After |
+|-----------|--------|-------|
+| Listing under `file.storage: 'gridfs'` | GridFS files | unchanged, plus any files left in the other stores by a previous driver |
+| Listing under `'s3'` / `'filesystem'` | **always empty** | the files that are actually there |
+| Deleting an S3- or filesystem-backed file | **impossible** (`File not found`) | deletes the bytes AND the metadata document |
+| Deleting a GridFS file | GridFS delete | unchanged |
+
+Nothing to configure. Two operational notes:
+
+- **S3 deletion needs `CoreS3Service` to be usable.** When `s3` is not configured, the Hub refuses an
+  S3-backed delete with `S3 storage is not available.` rather than deleting the metadata document and
+  orphaning the object in the bucket. A half-delete is unrecoverable in a way a refusal is not.
+- **Reading never creates a collection.** A GridFS-only deployment does not grow an empty `s3-files`
+  / `filesystem-files` from the Hub looking at them — the same rule
+  `ensureFilenameIndex()` follows on the write path.
+
+`HubFilesData` gained a `stores` summary and a `store` field per file. If you override
+`CoreHubDbService` or consume `files.json` directly, both are additive.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| Project that never calls `duplicateByName()` / `duplicateById()` | **Unchanged** | |
+| `duplicateById(id)` with the framework's default `checkRights()` | **Unchanged** | The default returns `true`, so an omitted context behaves exactly as before |
+| `duplicateByName(a, b)` reading `.id` / `.filename` off the result | **Compatible** | `.id` is a `string` now instead of an `ObjectId`; `String(...)` / `getStringIds(...)` are unaffected |
+| `duplicateByName(a, b)` treating the result as a stream | **Action required** | §1 — it is a `CoreFileInfo` now |
+| Overridden fail-closed `checkRights()` + duplication without a context | **Action required** | §1 — pass `{ currentUser }` or `{ force: true }` |
+| `FileService.duplicate()` copied out of `src/server` before 11.34.0 | **Action required** | §1 — the copy still bypasses `checkRights()`; replace the body with the delegation |
+| Test asserting `MongoRuntimeError` on delete-by-unknown-id | **Action required** | §3 — it is `NotFoundException` now |
+| `findFileInfo()` sorted on a nested field, `file.storage` other than `gridfs` | **Rows changed (fixed)** | §4 |
+| `findFileInfo()` filtered on `contentType` | **Rows changed (fixed)** | §5 |
+| Hub Files panel under `file.storage: 's3'` / `'filesystem'` | **Rows changed (fixed)** | §6 — it showed nothing before |
+| Project overriding `CoreFileService.deleteFile()` | **Review** | If you call `super.deleteFile()`, it may now throw where it previously returned |
+| Project overriding `GridFSHelper` behaviour | **Review** | `findFiles()` rewrites one filter key; `writeFileFromStream()` gained source-error handling |
+| Project overriding `CoreS3Service.putObject()` | **Review** | A body STREAM is now relayed through a `PassThrough` before it reaches the SDK (§2); Buffer and string bodies are untouched |
+| Project overriding `CoreHubDbService.getFiles()` / `deleteFile()` | **Review** | Both are multi-store now; `HubFilesData` gained `stores` + per-file `store` (§6) |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `NotFoundException: File not found with filename …` from a duplicate that used to work | Fail-closed `checkRights()` now applies to duplication (§1) | Pass `{ currentUser }` or `{ force: true }` |
+| `Property 'pipe' does not exist on type 'CoreFileInfo'` | §1 — the return type changed | Use `copy.id` / `copy.filename`, or `getFileStream(copy.id)` if you really need bytes |
+| A delete that returned 500 now returns 404 | §3 — that is the fix | Treat 404 as the idempotent-delete case |
+| A copied file is suddenly invisible to its owner | The copy records no owner unless you say so (§1) | `duplicateById(id, { currentUser, metadata: { ownerId: currentUser.id } })` |
+| Hub Files panel says `S3 storage is not available.` on delete | §6 — the file's bytes are in S3, but `s3` is not configured in this process | Configure `s3` (and install `@aws-sdk/client-s3`), or delete through the file API |
+
+---
+
+## Verification
+
+```bash
+pnpm run build
+pnpm test
+```
+
+Framework suites covering this release:
+
+| Suite | Covers |
+|-------|--------|
+| `tests/file-duplicate.e2e-spec.ts` | Duplication under all three drivers: default context, owner context, stranger, missing context, content type, copy metadata (§1) |
+| `tests/file-upload-stream-error.e2e-spec.ts` | An aborted upload rejects instead of crashing, on GridFS and on the S3 streaming path (§2) |
+| `tests/file-missing-answers.e2e-spec.ts` | By-id vs by-name answers for a file that is not there (§3) |
+| `tests/file-find-info.e2e-spec.ts` | Merged multi-store ordering, dotted sort paths, paging, `contentType` filtering, and that unused metadata collections stay absent (§4, §5) |
+| `tests/tus-finalization.e2e-spec.ts` | A finished tus upload lands in the active driver, takes the S3→S3 copy path, and clears the staging bucket |
+| `tests/unit/core-hub-db.service.spec.ts` | The Hub Files panel across all three metadata stores, and its delete dispatch (§6) |
+
+Every defect above is additionally backed by a **registered mutation** in
+`tests/regression-mutations.json`: `pnpm run check:mutations` restores each bug on purpose and
+requires the suites that claim to catch it to go red. A regression test that was never seen failing
+is a claim, not a check — this release is the one that stopped taking those on trust.
+
+---
+
+## Module Documentation
+
+### File
+
+- [README](../src/core/modules/file/README.md) — § Access control, § Storage drivers
+- [`CoreFileService`](../src/core/modules/file/core-file.service.ts)
+- Reference implementation: `src/server/modules/file/`
+
+### Hub
+
+- [README](../src/core/modules/hub/README.md) — § Files panel
+- [`CoreHubDbService`](../src/core/modules/hub/services/core-hub-db.service.ts)
+
+---
+
+## References
+
+- [11.32.x → 11.33.x](./11.32.x-to-11.33.x.md) — the release that introduced the three storage drivers and closed the file endpoints
+- [11.32.3 → 11.32.4](./11.32.3-to-11.32.4.md) — the earlier round of GridFS upload/download hardening

package/migration-guides/11.34.0-to-11.34.1.md

@@ -0,0 +1,132 @@
+# Migration Guide: 11.34.0 → 11.34.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None in signatures. One **client-visible text** change: validation error messages are now rendered the way class-validator itself renders them (§1, §2) |
+| **Bugfixes** | A custom `message` in `ValidationOptions` is no longer ignored (§1). Default messages no longer reach API clients with raw placeholders such as `$constraint1` (§2) |
+| **Migration Effort** | Nothing to configure. Read §1 and §2 if any test — or any frontend — asserts on exact validation error strings. Read §3 before you put `$value` in a custom message |
+
+`MapAndValidatePipe` re-implements class-validator's validation executor, so it also has to render
+error messages the way that executor does. It did neither: it built every message from the
+constraint's `defaultMessage()` alone, and substituted only `$property`.
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.34.1
+pnpm run build
+pnpm test
+```
+
+No configuration change is required, and no source change is required in a typical project.
+
+**Vendor-mode projects: this release ADDS a file, so the sync is atomic.**
+`src/core/common/pipes/map-and-validate.pipe.ts` now imports the new
+`src/core/common/helpers/validation-message.helper.ts`. Taking the pipe without the helper does not
+fail a rights check or a test — it fails the build. Sync both files together.
+
+---
+
+## 1. A custom `message` in `ValidationOptions` is now honored
+
+Previously the pipe built the message from the constraint's own `defaultMessage()` and never looked
+at `metadata.message`, so the message you wrote was silently discarded and the client received the
+generic default instead.
+
+```typescript
+class UpdateUserInput {
+  @IsIn(['admin'], { each: true, message: 'roles may only contain assignable roles (admin)' })
+  @IsOptional()
+  roles?: string[];
+}
+```
+
+| | Before | After |
+|---|---|---|
+| Response | `each value in roles must be one of the following values: $constraint1` | `roles may only contain assignable roles (admin)` |
+
+Custom messages now take precedence over the constraint's default — the same order class-validator's
+own executor uses. The function form (`message: (args) => string`) works too, and its result is
+interpolated afterwards.
+
+**What you may notice:** a custom message that was written but never delivered starts being
+delivered. If a frontend or a test was written against the *default* text your project was
+accidentally serving, it now sees the text the decorator actually asks for.
+
+---
+
+## 2. Default messages no longer leak raw placeholders
+
+Only `$property` was substituted, so every other token reached the client verbatim:
+
+| | Before | After |
+|---|---|---|
+| Response | `each value in roles must be one of the following values: $constraint1` | `each value in roles must be one of the following values: alpha, beta` |
+
+All four special tokens are now interpolated — `$constraint1..N`, `$value`, `$property` and
+`$target` — rendered exactly as class-validator renders them (arrays joined with `, `, symbols by
+their description).
+
+**Scope of the text change:** 44 of class-validator's built-in messages carry a `$constraint` token,
+so those 44 change text. None of the built-ins uses `$value` or `$target`, so no built-in message
+changes *shape* — they stop showing a placeholder and start showing the value it stood for.
+
+**What to check:** any test or frontend string comparison that asserts on a full validation message.
+A test that was pinned to the broken output (`…: $constraint1`) fails and should be updated to the
+interpolated text.
+
+This also applies to `@IsDefined`, which since class-validator 0.13 is the one built-in that does not
+register through `ValidateBy` and therefore took a separate code path with the same two gaps.
+
+---
+
+## 3. Security: `$value` echoes the submitted value, and validation errors are not scrubbed
+
+`$value` now works — which means a custom message containing it renders the value the client
+submitted, straight back into the error response.
+
+**Validation errors bypass the secret-field filtering you may be assuming.**
+`security.secretFields` is applied by `CheckSecurityInterceptor` on the **response** path, whereas
+the `BadRequestException` raised by the pipe goes to the exception filter and is forwarded verbatim.
+The guard inside the renderer is a **type** guard (`boolean | number | string`), not a secrecy guard
+— it will happily echo a password or a token.
+
+```typescript
+// DANGEROUS — the rejected password is echoed back in the error response
+@MinLength(12, { message: 'password "$value" is too short' })
+password: string;
+
+// SAFE — describe the rule, never the submitted value
+@MinLength(12, { message: 'password must be at least $constraint1 characters' })
+password: string;
+```
+
+No built-in message uses `$value`, so reaching this is opt-in: it requires a custom message that
+names the token. Note that class-validator's own `validate()` behaves identically — this is not a
+new exposure introduced by the framework, but it becomes reachable in projects where `$value`
+previously did nothing.
+
+**Action:** grep your input classes for `$value` in custom messages and confirm none of them sits on
+a credential, token, or otherwise sensitive field.
+
+---
+
+## Under the hood
+
+The token renderer is a port of class-validator internals
+(`ValidationUtils.replaceMessageSpecialTokens`, `constraintToString`), which are not part of its
+public API. Because vendor-mode projects resolve their own class-validator, that port can meet a
+version this framework never installed. It is therefore pinned by an invariant test that compares it
+against the installed implementation over a fixture table, so a divergence surfaces as a failing
+test rather than as two renderers disagreeing about one decorator.
+
+---
+
+## Module Documentation
+
+- Request lifecycle and the validation pipe: [`docs/REQUEST-LIFECYCLE.md`](../docs/REQUEST-LIFECYCLE.md)
+- Field decorators and validation: `src/core/common/decorators/unified-field.decorator.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.33.1",
+  "version": "11.34.1",
   "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",
@@ -24,8 +24,10 @@
     "c": "pnpm run check",
     "cf": "pnpm run check:fix",
     "check": "node scripts/check.mjs",
+    "check:consumer": "node scripts/check-consumer.mjs",
     "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:manifest": "node scripts/check-package-manifest.mjs",
+    "check:mutations": "node scripts/check-mutations.mjs",
     "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",