@lenne.tech/nest-server 11.33.0 → 11.34.0

package/docs/REQUEST-LIFECYCLE.md

@@ -162,7 +162,7 @@ JWT-based authentication for existing projects:
 | **File Module** | Upload/download with MongoDB GridFS storage |
 | **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 |
+| **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Cover BOTH the `id` and the `filename` branch — the filename route authorizes on the by-name lookup alone when presigned S3 downloads are on, and `deleteFileByName()` always does. Working reference: `src/server/modules/file/file.service.ts` (with `file.downloadRoles: [S_USER]` in `src/config.env.ts`, so the rule is actually reached). 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 |

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

@@ -207,18 +207,51 @@ export class FileService extends CoreFileService {
     input: any,
     options?: FileServiceOptions & { checkInputType: FileInputCheckType },
   ): Promise<boolean> {
-    if (options?.checkInputType !== 'id' || options.force) {
+    // Writes, list queries and forced (system) calls stay on the coarse role gate
+    if (options?.force || (options?.checkInputType !== 'filename' && options?.checkInputType !== 'id')) {
       return true;
     }
-    if (options.currentUser?.hasRole([RoleEnum.ADMIN])) {
+    if (options.currentUser?.hasRole?.([RoleEnum.ADMIN])) {
       return true;
     }
-    const raw = await this.getRawFileInfo(input);
-    return !!raw && String(raw.metadata?.ownerId) === String(options.currentUser?.id);
+    const raw = options.checkInputType === 'id'
+      ? await this.getRawFileInfo(input)
+      : await this.getRawFileInfoByName(input);
+    // Fails closed without a user, and on a file that records no owner.
+    return !!raw?.metadata?.ownerId && String(raw.metadata.ownerId) === String(options.currentUser?.id);
   }
 }
 ```
 
+**Cover the `filename` branch, not only `id`.** An id-only rule is enough while bytes are streamed —
+the filename route resolves an id and checks it again — but not once `s3.presignedDownloads` is on
+(the filename route then authorizes on the by-name lookup alone and redirects), and not for
+`deleteFileByName()`, which authorizes by name only. This is not hypothetical: 11.33.0 shipped a
+`deleteFileByName()` that authorized the caller and then re-resolved the file with an EMPTY context,
+so an overridden `checkRights()` was asked two different questions about one request and the owner
+got `File not found` for their own file. Both halves — the by-name branch and the forwarding — are
+covered by the reference server as of the next release.
+
+**Do not add an `if (!options.currentUser) return true` branch.** It reads as "system-internal call,
+the guard already decided", and that is not what it means: "no user in context" is also exactly what
+an ANONYMOUS request looks like. While `downloadRoles` is narrower than `S_EVERYONE` the coarse gate
+rejects those first and the branch looks harmless — widen the gate, which §A.2 explicitly offers, and
+the same branch hands every file to everyone. The ownership rule then evaporates precisely when it
+starts to matter. For the same reason the final comparison requires `metadata.ownerId` to be
+**present**: `String(undefined) === String(undefined)` would match an owner-less file against an
+absent user.
+
+Callers that genuinely are internal should say so, rather than relying on the omission:
+`{ force: true }` where a role decorator has already decided (an `@Roles(ADMIN)` admin endpoint), or
+the real `{ currentUser }` where the user is in scope (a controller cleaning up a file it just
+replaced — that delete should be COVERED by the ownership rule, not exempt from it). The reference
+server does both; see `src/server/modules/file/` and `src/server/modules/user/avatar.controller.ts`.
+
+The reference server also **runs** the rule above rather than documenting it: `src/config.env.ts`
+sets `file: { downloadRoles: [RoleEnum.S_USER] }` in every environment and
+`src/server/modules/file/file.service.ts` implements `checkRights()`. Copy from there — it is
+compiled and exercised by the test suite; this guide is not.
+
 Three new pieces make this possible, and all three were missing before: `createFile()` now forwards
 `serviceOptions.metadata` to storage; `getRawFileInfo()` / `getRawFileInfoByName()` read the raw
 document (the public `getFileInfo()` runs `prepareOutput` → `check()` and strips the very field the
@@ -1264,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.33.0",
+  "version": "11.34.0",
   "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",

package/src/config.env.ts

@@ -2,6 +2,7 @@ import { CronExpression } from '@nestjs/schedule';
 import * as dotenv from 'dotenv';
 import { join } from 'path';
 
+import { RoleEnum } from './core/common/enums/role.enum';
 import { getEnvironmentConfig } from './core/common/helpers/config.helper';
 import { IServerOptions } from './core/common/interfaces/server-options.interface';
 
@@ -100,6 +101,36 @@ const config: { [env: string]: IServerOptions } = {
       autoRegister: false,
     },
     execAfterInit: 'pnpm run docs:bootstrap',
+    // File access — the COARSE gate on the two inherited download routes
+    // (`GET /files/id/:id`, `GET /files/:filename`), which `FileController` inherits
+    // from `CoreFileController` unchanged so this config can reach them.
+    //
+    // Since 11.33.0 those routes are role-gated and default to `[ADMIN]`. That default
+    // is the safe one for a project that has not thought about file access yet, but it
+    // is the WRONG one for this reference server: it ships an avatar upload every
+    // signed-in user may use, so an admin-only download would make `user.avatar`
+    // unreadable by the very user it belongs to.
+    //
+    // So the gate is widened to "signed in" and the real decision is made per file in
+    // `FileService.checkRights()` (own file, or ADMIN). Roles can only answer "may this
+    // caller reach the route"; they can never answer "may this caller have THIS file".
+    // Widening here is therefore not a relaxation — it MOVES the decision to the layer
+    // that can actually make it. It is also what makes the pairing testable at all: under
+    // `[ADMIN]` the guard answers first and an ownership rule could never fire, which is
+    // how the two halves drifted apart and shipped a bug. See
+    // `migration-guides/11.32.x-to-11.33.x.md` § A.3.
+    //
+    // `uploadRoles` / `deleteRoles` stay at their `[ADMIN]` default. They govern
+    // `CoreFileResolver` members only, and this server registers its own `FileResolver`
+    // and `FileController` write endpoints, each carrying `@Roles(RoleEnum.ADMIN)`
+    // explicitly — so the two knobs are inert here, and leaving them unset keeps the
+    // framework default visible rather than restating it.
+    //
+    // NOTE for markup-driven downloads: anything stricter than `S_EVERYONE` only works
+    // from an `<img>` / `<a download>` when the session travels as a COOKIE on a
+    // same-site request. A Bearer-only frontend has to fetch such URLs programmatically
+    // and build an object URL.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },
@@ -224,6 +255,9 @@ const config: { [env: string]: IServerOptions } = {
     },
     env: 'development',
     execAfterInit: 'pnpm run docs:bootstrap',
+    // Coarse download gate widened to any signed-in user; the per-file rule lives in
+    // `FileService.checkRights()`. Full rationale in the `ci` block above.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },
@@ -376,6 +410,9 @@ const config: { [env: string]: IServerOptions } = {
       autoRegister: false,
     },
     execAfterInit: 'pnpm run docs:bootstrap',
+    // Coarse download gate widened to any signed-in user; the per-file rule lives in
+    // `FileService.checkRights()`. Full rationale in the `ci` block above.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },
@@ -534,6 +571,9 @@ const config: { [env: string]: IServerOptions } = {
       autoRegister: false,
     },
     execAfterInit: 'pnpm run docs:bootstrap',
+    // Coarse download gate widened to any signed-in user; the per-file rule lives in
+    // `FileService.checkRights()`. Full rationale in the `ci` block above.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },
@@ -670,6 +710,11 @@ const config: { [env: string]: IServerOptions } = {
     },
     env: 'production',
     execAfterInit: 'pnpm run docs:bootstrap',
+    // Coarse download gate widened to any signed-in user; the per-file rule lives in
+    // `FileService.checkRights()`. Full rationale in the `ci` block above. Deliberately the
+    // SAME value as every other environment: a per-file rule that only runs outside
+    // production is a rule nobody has actually tested where it matters.
+    file: { downloadRoles: [RoleEnum.S_USER] },
     filter: {
       maxLimit: null,
     },