@lenne.tech/nest-server 11.32.3 → 11.32.4

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

@@ -2,6 +2,81 @@ import { MulterOptions } from '@nestjs/platform-express/multer/interfaces/multer
 import { diskStorage } from 'multer';
 import { extname } from 'path';
 
+/**
+ * What an upload endpoint accepts: exact mimetypes and exact file extensions.
+ *
+ * Prefer this over the legacy `RegExp` form. A single expression `.test()`ed
+ * against BOTH the mimetype and the extension searches for a SUBSTRING, so every
+ * alternative matches anywhere inside either value. An allow-list of `text` /
+ * `txt` therefore also accepts `text/html` and `text/xml`, and one containing
+ * `md` accepts every mimetype with "md" in it. Consumers hit this in practice:
+ * a filter documented as "no html" happily accepted a file named `x.txt` that
+ * was sent as `text/html`.
+ *
+ * Two separate sets also remove the reason the expression could not simply be
+ * anchored: it had to carry mimetype FRAGMENTS (`wordprocessingml`, `ms-excel`)
+ * next to bare extensions, and no anchoring satisfies both at once.
+ */
+export interface UploadAllowList {
+  /** Allowed file extensions, lowercase and WITH the leading dot. */
+  extensions: readonly string[];
+  /** Allowed mimetypes, lowercase and without parameters. */
+  mimeTypes: readonly string[];
+}
+
+/**
+ * Default for image uploads — the exact-matching equivalent of the legacy
+ * `/jpeg|jpg|png/`.
+ */
+export const IMAGE_UPLOAD_ALLOW_LIST: UploadAllowList = {
+  extensions: ['.jpeg', '.jpg', '.png'],
+  mimeTypes: ['image/jpeg', 'image/png'],
+};
+
+/**
+ * Types a browser may execute as script when it renders the stored file.
+ *
+ * These are rejected by {@link multerFileFilter} REGARDLESS of the allow-list,
+ * because the danger does not depend on what a given endpoint meant to accept:
+ * an upload served back from the API origin with one of these content types
+ * runs in that origin, with the victim's session. The check is what makes the
+ * legacy `RegExp` path safe for existing consumers without breaking their
+ * expressions — see `allowScriptableTypes` to opt out.
+ */
+export const SCRIPTABLE_UPLOAD_MIME_TYPES: readonly string[] = [
+  'application/javascript',
+  'application/xhtml+xml',
+  'application/xml',
+  'image/svg+xml',
+  'text/html',
+  'text/javascript',
+  'text/xml',
+];
+
+/** Extensions matching {@link SCRIPTABLE_UPLOAD_MIME_TYPES}. */
+export const SCRIPTABLE_UPLOAD_EXTENSIONS: readonly string[] = [
+  '.htm',
+  '.html',
+  '.js',
+  '.mjs',
+  '.svg',
+  '.xhtml',
+  '.xml',
+];
+
+/** Options for {@link multerFileFilter}. */
+export interface MulterFileFilterOptions {
+  /**
+   * Accept markup and script types too (`text/html`, `image/svg+xml`, …).
+   *
+   * Only set this when the stored 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`.
+   */
+  allowScriptableTypes?: boolean;
+}
+
 /**
  * Helper class for inputs
  * @deprecated use functions directly
@@ -18,14 +93,18 @@ export default class FileHelper {
   /**
    * Get function to filter files for multer with a certain mimetype & extname
    */
-  public static multerFileFilter(fileTypeRegex = /jpeg|jpg|png/) {
-    return multerFileFilter(fileTypeRegex);
+  public static multerFileFilter(
+    accept: RegExp | UploadAllowList = IMAGE_UPLOAD_ALLOW_LIST,
+    options?: MulterFileFilterOptions,
+  ) {
+    return multerFileFilter(accept, options);
   }
 
   /**
    * Get multer options for image upload
    */
   public static multerOptionsForImageUpload(options: {
+    allowList?: UploadAllowList;
     destination?: string;
     fileSize?: number;
     fileTypeRegex?: RegExp;
@@ -35,24 +114,80 @@ export default class FileHelper {
 }
 
 /**
- * Get function to filter files for multer with a certain mimetype & extname
+ * Reduce a reported mimetype to the bare type: lowercase, trimmed, without the
+ * `; charset=…` parameters a user agent may append.
+ */
+function normalizeMimeType(value: string): string {
+  return String(value || '')
+    .split(';')[0]
+    .trim()
+    .toLowerCase();
+}
+
+/**
+ * Get a multer `fileFilter` that accepts only the given mimetypes / extensions.
+ *
+ * Pass an {@link UploadAllowList} — both the mimetype and the extension must
+ * appear in it, each compared as a WHOLE value. The two conditions are
+ * independent: either one alone rejects the file, while 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.
+ *
+ * A `RegExp` is still accepted for backwards compatibility but is
+ * **deprecated**: it is `.test()`ed against both values and therefore matches
+ * SUBSTRINGS, which is how `te?xt` ends up accepting `text/html`. Whichever form
+ * is used, the types in {@link SCRIPTABLE_UPLOAD_MIME_TYPES} /
+ * {@link SCRIPTABLE_UPLOAD_EXTENSIONS} are rejected first unless
+ * `options.allowScriptableTypes` is set — that is what closes the hole for
+ * expressions that already exist in consumer projects.
+ *
+ * Rejections are reported as a real `Error`. Passing a bare string (as this
+ * helper did before) leaves multer with an "error" that has no `message`, which
+ * NestJS's `transformException` cannot map to a 4xx.
  */
-export function multerFileFilter(fileTypeRegex = /jpeg|jpg|png/) {
+export function multerFileFilter(
+  accept: RegExp | UploadAllowList = IMAGE_UPLOAD_ALLOW_LIST,
+  options?: MulterFileFilterOptions,
+) {
   return (req, file, cb) => {
-    const mimetype = fileTypeRegex.test(file.mimetype);
-    const extName = fileTypeRegex.test(extname(file.originalname).toLowerCase());
+    const mimeType = normalizeMimeType(file?.mimetype);
+    const extension = extname(String(file?.originalname || '')).toLowerCase();
 
-    if (mimetype && extName) {
+    if (
+      !options?.allowScriptableTypes &&
+      (SCRIPTABLE_UPLOAD_MIME_TYPES.includes(mimeType) || SCRIPTABLE_UPLOAD_EXTENSIONS.includes(extension))
+    ) {
+      return cb(new Error(`File upload rejected: ${mimeType || 'unknown type'} may execute as script`));
+    }
+
+    const accepted =
+      accept instanceof RegExp
+        ? accept.test(mimeType) && accept.test(extension)
+        : accept.mimeTypes.includes(mimeType) && accept.extensions.includes(extension);
+
+    if (accepted) {
       return cb(null, true);
     }
-    cb(`Error: File upload only supports the following filetypes - ${fileTypeRegex}`);
+    cb(new Error(`File upload only supports the following filetypes - ${describeAccept(accept)}`));
   };
 }
 
+/** Render the accepted types for the rejection message. */
+function describeAccept(accept: RegExp | UploadAllowList): string {
+  return accept instanceof RegExp ? String(accept) : accept.extensions.join(', ');
+}
+
 /**
  * Get multer options for image upload
+ *
+ * Pass `allowList` for exact matching; `fileTypeRegex` is deprecated (see
+ * {@link multerFileFilter}). When neither is set, {@link IMAGE_UPLOAD_ALLOW_LIST}
+ * applies.
  */
 export function multerOptionsForImageUpload(options: {
+  allowList?: UploadAllowList;
   destination?: string;
   fileSize?: number;
   fileTypeRegex?: RegExp;
@@ -60,13 +195,16 @@ export function multerOptionsForImageUpload(options: {
   // Set config
   const config = {
     fileSize: 1024 * 1024, // 1MB
-    fileTypeRegex: /jpeg|jpg|png/, // Images only
     ...options,
   };
 
+  // An explicit regex keeps precedence so existing callers behave as before
+  // (minus the scriptable types); otherwise the exact-matching default applies.
+  const accept: RegExp | UploadAllowList = config.fileTypeRegex ?? config.allowList ?? IMAGE_UPLOAD_ALLOW_LIST;
+
   return {
     // File filter
-    fileFilter: config.fileTypeRegex ? multerFileFilter(config.fileTypeRegex) : undefined,
+    fileFilter: multerFileFilter(accept),
 
     // Limits
     limits: {

package/src/core/modules/file/README.md

@@ -74,6 +74,65 @@ export class FileController extends CoreFileController {
 }
 ```
 
+Access can also be restricted per file by overriding `CoreFileService.checkRights()`. When it
+refuses, `getFileStream()` returns `null` and the controller answers **404** — deliberately the same
+answer as an unknown id, so the endpoint cannot be used to probe which files exist. Do not change
+this to a 403 in an override without accepting that trade-off.
+
+### Error responses
+
+| Situation                                                                              | Status | Body                                                                                                  |
+| -------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
+| Unknown id / filename, or `checkRights()` refused                                      | `404`  | `NotFoundException` with `ErrorCode.FILE_NOT_FOUND`                                                   |
+| Missing id / filename in the route                                                     | `400`  | `BadRequestException` with `ErrorCode.REQUIRED_FIELD_MISSING`                                         |
+| GridFS read fails **before** any byte was sent (file document exists, chunks are gone) | `404`  | `{ "error": "Not Found", "message": "<FILE_NOT_FOUND>", "statusCode": 404 }`                          |
+| GridFS read fails **after** streaming started                                          | —      | The connection is closed; a truncated transfer is the only signal left once the status is on the wire |
+
+The mid-stream failure case is handled by `pipeFileToResponse()`. Without it the stream error would
+go unhandled, Node would destroy the socket, and a reverse proxy would report **502 Bad Gateway** —
+i.e. "the server is down", while every other route keeps answering. On the error path the headers
+describing the file (`Content-Type`, `Content-Disposition`, `Cache-Control`, `ETag`) are removed, so
+the JSON body is not labelled as the image it failed to deliver. The error itself is logged
+server-side even though the client answer stays deliberately generic.
+
+To change the status, the body or the logging, override the `protected pipeFileToResponse()` method
+on the controller rather than the exported function of the same name.
+
+### Upload filtering
+
+Upload endpoints are project-specific, but the filter they install comes from the framework
+(`multerOptionsForImageUpload()` / `multerFileFilter()` in `common/helpers/file.helper.ts`). Name what
+the endpoint accepts as an `UploadAllowList` — both the mimetype and the extension are compared as
+WHOLE values:
+
+```typescript
+@UseInterceptors(FileInterceptor('file', multerOptionsForImageUpload({
+  allowList: {
+    extensions: ['.jpeg', '.jpg', '.pdf', '.png'],
+    mimeTypes: ['application/pdf', 'image/jpeg', 'image/png'],
+  },
+})))
+```
+
+The two conditions are **independent**: either one alone rejects the file, while a pair that is odd
+yet individually allowed (`report.txt` announced as `application/pdf`) passes. An extension→mimetype
+MAPPING is deliberately not enforced, because user agents genuinely disagree about office and audio
+types (macOS reports `.csv` as `text/plain`) and a mapping would reject legitimate uploads.
+
+The legacy `fileTypeRegex` option still works and keeps precedence, but is **deprecated**: one
+expression is `.test()`ed against both the mimetype and the extension, so every alternative matches
+as a SUBSTRING — an allow-list containing `te?xt` also accepts `text/html`.
+
+Types a browser may execute as script (`text/html`, `image/svg+xml`, `application/xhtml+xml`, XML and
+JavaScript types, plus the matching extensions) are rejected **before** the allow-list is consulted,
+on both forms. A stored upload served back from the API origin with one of these content types runs
+in that origin, with the victim's session. Opt out only when the file never reaches an origin that
+carries a session:
+
+```typescript
+multerFileFilter({ extensions: ['.svg'], mimeTypes: ['image/svg+xml'] }, { allowScriptableTypes: true });
+```
+
 ---
 
 ## GraphQL Support

package/src/core/modules/file/core-file.controller.spec.ts

@@ -0,0 +1,164 @@
+import { NotFoundException } from '@nestjs/common';
+import type { Response } from 'express';
+import { PassThrough, Readable } from 'stream';
+import { describe, expect, it } from 'vitest';
+
+import type { CoreFileService } from './core-file.service';
+import { CoreFileController, pipeFileToResponse } from './core-file.controller';
+
+/**
+ * Build a response stub that records what the handler did to it.
+ *
+ * A real `Response` is not needed here — what is under test is the decision
+ * (status vs. destroy), not Express. Writing it out as a stub also makes the
+ * "headers already sent" case reachable, which is awkward to force otherwise.
+ *
+ * What this stub CANNOT show is how Express itself treats headers: `res.json()`
+ * only defaults `Content-Type` when none is set, so a stub whose `json()` merely
+ * records a body can never reveal a stale one. That property is pinned at the
+ * HTTP level in `tests/file.e2e-spec.ts`; here we assert the removal list.
+ */
+function responseStub(headersSent = false) {
+  const sink = new PassThrough();
+  const calls = {
+    destroyed: false,
+    json: undefined as unknown,
+    removed: [] as string[],
+    set: {} as Record<string, string>,
+    status: 0,
+  };
+
+  const res = Object.assign(sink, {
+    destroy: () => {
+      calls.destroyed = true;
+      return res;
+    },
+    headersSent,
+    json: (body: unknown) => {
+      calls.json = body;
+      return res;
+    },
+    removeHeader: (name: string) => {
+      calls.removed.push(name);
+    },
+    setHeader: (name: string, value: string) => {
+      calls.set[name] = value;
+      return res;
+    },
+    status: (code: number) => {
+      calls.status = code;
+      return res;
+    },
+  }) as unknown as Response;
+
+  return { calls, res };
+}
+
+describe('pipeFileToResponse', () => {
+  it('turns a read error into 404 while nothing has been written yet', async () => {
+    // A GridFS record and its bytes are two separate writes, so the record can
+    // outlive the chunks. GridFS reports that on the stream, asynchronously.
+    // A bare `stream.pipe(res)` installs no error handler, so the error goes
+    // unhandled, Node destroys the socket mid-response, and any reverse proxy
+    // in front reports 502 Bad Gateway — "the server is down", which is the one
+    // diagnosis that is wrong while every other route answers normally.
+    const stream = new Readable({ read() {} });
+    const { calls, res } = responseStub(false);
+
+    pipeFileToResponse(stream, res);
+    stream.emit('error', new Error('FileNotFound: file 0123456789ab was not found'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(calls.status).toBe(404);
+    expect(calls.json).toMatchObject({ statusCode: 404 });
+    expect(calls.destroyed).toBe(false);
+  });
+
+  it('drops every header that describes the file, not just the download one', async () => {
+    // Each of these would otherwise survive onto the error response:
+    // `Content-Disposition` offers a JSON error body as a file to save, a long
+    // `Cache-Control` lets the client cache the failure, `ETag` describes bytes
+    // that were never sent — and `Content-Type` makes an ofetch/`$fetch` client
+    // parse the JSON as an image and lose the message entirely.
+    const stream = new Readable({ read() {} });
+    const { calls, res } = responseStub(false);
+
+    pipeFileToResponse(stream, res);
+    stream.emit('error', new Error('chunks missing'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(calls.removed).toEqual(
+      expect.arrayContaining(['Cache-Control', 'Content-Disposition', 'Content-Type', 'ETag']),
+    );
+    expect(calls.set['X-Content-Type-Options']).toBe('nosniff');
+  });
+
+  it('closes the connection once bytes are already on the wire', async () => {
+    // Past the first byte there is no status left to send. Dropping the
+    // connection is the only remaining signal — and it is the correct one: it
+    // is what a truncated transfer looks like, so the client does not cache a
+    // half file as if it were complete.
+    const stream = new Readable({ read() {} });
+    const { calls, res } = responseStub(true);
+
+    pipeFileToResponse(stream, res);
+    stream.emit('error', new Error('connection lost mid-stream'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(calls.destroyed).toBe(true);
+    expect(calls.status).toBe(0);
+  });
+
+  it('answers a refused download exactly like an unknown id', async () => {
+    // `getFileStream()` returns null when the service's own `checkRights()`
+    // refuses — a branch only a CONSUMER project can reach, since the framework's
+    // base implementation always returns true. That is precisely why the
+    // framework has to pin it: consumers cannot, and if the two answers ever
+    // diverge (403 here, 404 there, or different messages) the endpoint becomes
+    // an existence oracle for files the caller may not read.
+    // Invoked through the prototype rather than a subclass: `CoreFileController`
+    // has a protected constructor (it is abstract by design), and a subclass added
+    // only to widen that visibility is exactly what `no-useless-constructor`
+    // strips — leaving code that no longer compiles.
+    const download = (service: Partial<CoreFileService>, res: Response) =>
+      (CoreFileController.prototype.getFileById as (this: unknown, id: string, res: Response) => Promise<unknown>).call(
+        { fileService: service },
+        'abc',
+        res,
+      );
+
+    const file = { contentType: 'image/png', filename: 'secret.png', id: 'abc' };
+    const { res } = responseStub(false);
+
+    const refusedErr = await download(
+      { getFileInfo: async () => file, getFileStream: async () => null } as unknown as Partial<CoreFileService>,
+      res,
+    ).catch((e: unknown) => e);
+    const unknownErr = await download(
+      { getFileInfo: async () => null, getFileStream: async () => null } as unknown as Partial<CoreFileService>,
+      res,
+    ).catch((e: unknown) => e);
+
+    expect(refusedErr).toBeInstanceOf(NotFoundException);
+    expect(unknownErr).toBeInstanceOf(NotFoundException);
+    // Byte-identical answers: same status, same message.
+    expect((refusedErr as NotFoundException).getStatus()).toBe((unknownErr as NotFoundException).getStatus());
+    expect((refusedErr as NotFoundException).getResponse()).toEqual((unknownErr as NotFoundException).getResponse());
+  });
+
+  it('destroys the source stream when the client goes away', async () => {
+    // `pipe()` only ever unpipes the DESTINATION; it never destroys the source.
+    // On a public download route an aborted request would therefore leak the
+    // GridFS read stream and its server-side cursor until the cursor timeout.
+    const stream = new Readable({ read() {} });
+    const { res } = responseStub(false);
+
+    pipeFileToResponse(stream, res);
+    expect(stream.destroyed).toBe(false);
+
+    res.emit('close');
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(stream.destroyed).toBe(true);
+  });
+});

package/src/core/modules/file/core-file.controller.ts

@@ -1,10 +1,82 @@
-import { BadRequestException, Controller, Get, NotFoundException, Param, Res } from '@nestjs/common';
-import { Response } from 'express';
+import { BadRequestException, Controller, Get, Logger, NotFoundException, Param, Res } from '@nestjs/common';
+import type { Response } from 'express';
+import type { Readable } from 'stream';
 
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { ErrorCode } from '../error-code/error-codes';
 import { CoreFileService } from './core-file.service';
 
+const fileStreamLogger = new Logger('CoreFileController');
+
+/**
+ * Headers that describe the FILE and must not survive onto an error response.
+ *
+ * Deliberately not the whole set: CORS headers are already on the response at
+ * this point, and removing those would turn a readable 404 into an opaque CORS
+ * failure in the browser — hiding the very answer this handler exists to give.
+ *
+ * `Content-Type` is the one most easily missed. Express only defaults it in
+ * `res.json()` when nothing is set yet (`if (!this.get('Content-Type'))`), so the
+ * file's own type would otherwise label a JSON body as `image/png` — and an
+ * ofetch/`$fetch` client picks its parser from that header and hands the caller a
+ * Blob instead of the error message.
+ */
+const FILE_DELIVERY_HEADERS = ['Cache-Control', 'Content-Disposition', 'Content-Type', 'ETag'];
+
+/**
+ * Pipe a GridFS download to the response without letting a read error kill the socket.
+ *
+ * A GridFS record and its chunks are two separate writes, so a file document can
+ * outlive its bytes — an interrupted upload, a restored backup, a manual cleanup.
+ * GridFS reports that asynchronously, on the stream, and `stream.pipe(res)` alone
+ * installs no error handler: the error goes unhandled, Node destroys the socket
+ * mid-response, and any reverse proxy in front turns that into **502 Bad Gateway**.
+ * That reads as "the server is down" — the one diagnosis that is wrong here, while
+ * every other route keeps answering normally.
+ *
+ * Nothing has been written when GridFS reports a missing file, so the status is
+ * still ours to set and the answer becomes an honest 404. Once bytes are on the
+ * wire there is no status left to send and closing the connection is all that
+ * remains — but at that point it genuinely is a truncated transfer, which is
+ * exactly what a dropped connection means to the client.
+ *
+ * Note on `pipe()` vs `stream.pipeline()`: pipeline would destroy BOTH streams on
+ * error, including the response — which is precisely the object still needed to
+ * send the 404. So the source is cleaned up explicitly on `res` close instead;
+ * `pipe()` only ever unpipes the destination and would otherwise leave the
+ * GridFS read stream and its server-side cursor open on every aborted download.
+ */
+export function pipeFileToResponse(stream: Readable, res: Response): Response {
+  res.on('close', () => {
+    if (!stream.destroyed) {
+      stream.destroy();
+    }
+  });
+
+  stream.on('error', (err: Error) => {
+    // The answer to the CLIENT stays deliberately indistinguishable from an
+    // unknown id, but the server must not lose the event: a files document
+    // without its chunks is data corruption, and an error silently converted
+    // into a 404 is one nobody will ever notice.
+    fileStreamLogger.error(`GridFS download failed: ${err.message}`, err.stack);
+
+    if (res.headersSent) {
+      res.destroy();
+      return;
+    }
+    for (const header of FILE_DELIVERY_HEADERS) {
+      res.removeHeader(header);
+    }
+    // No global nosniff on this route, and the body is now correctly typed —
+    // set it anyway so a mislabelled response can never be sniffed into markup.
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.status(404).json({ error: 'Not Found', message: ErrorCode.FILE_NOT_FOUND, statusCode: 404 });
+  });
+
+  return stream.pipe(res);
+}
+
 /**
  * File controller
  */
@@ -16,6 +88,18 @@ export abstract class CoreFileController {
    */
   protected constructor(protected fileService: CoreFileService) {}
 
+  /**
+   * Stream a file to the response.
+   *
+   * Delegates to the module-level {@link pipeFileToResponse} (which stays exported
+   * so it can be unit-tested without a Nest context). Override this to change the
+   * error status, the body shape or the logging for a project — the free function
+   * alone would not be reachable from a subclass.
+   */
+  protected pipeFileToResponse(stream: Readable, res: Response): Response {
+    return pipeFileToResponse(stream, res);
+  }
+
   /**
    * Download file by ID
    *
@@ -26,17 +110,22 @@ export abstract class CoreFileController {
   @Roles(RoleEnum.S_EVERYONE)
   async getFileById(@Param('id') id: string, @Res() res: Response) {
     if (!id) {
-      throw new BadRequestException('Missing file ID for download');
+      throw new BadRequestException(ErrorCode.REQUIRED_FIELD_MISSING);
     }
 
     const file = await this.fileService.getFileInfo(id);
     if (!file) {
-      throw new NotFoundException('File not found');
+      throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
     }
     const filestream = await this.fileService.getFileStream(id);
+    // `getFileStream` answers null when the service's own rights check refuses.
+    // Same answer as an unknown id: never confirm that the file exists.
+    if (!filestream) {
+      throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
+    }
     res.header('Content-Type', file.contentType || 'application/octet-stream');
     res.header('Content-Disposition', `attachment; filename=${file.filename}`);
-    return filestream.pipe(res);
+    return this.pipeFileToResponse(filestream, res);
   }
 
   /**
@@ -49,16 +138,19 @@ export abstract class CoreFileController {
   @Roles(RoleEnum.S_EVERYONE)
   async getFile(@Param('filename') filename: string, @Res() res: Response) {
     if (!filename) {
-      throw new BadRequestException('Missing filename for download');
+      throw new BadRequestException(ErrorCode.REQUIRED_FIELD_MISSING);
     }
 
     const file = await this.fileService.getFileInfoByName(filename);
     if (!file) {
-      throw new NotFoundException('File not found');
+      throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
     }
     const filestream = await this.fileService.getFileStream(file.id);
+    if (!filestream) {
+      throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
+    }
     res.header('Content-Type', file.contentType || 'application/octet-stream');
     res.header('Content-Disposition', `attachment; filename=${file.filename}`);
-    return filestream.pipe(res);
+    return this.pipeFileToResponse(filestream, res);
   }
 }

package/src/core/modules/migrate/README.md

@@ -387,6 +387,41 @@ const fileId = await uploadFileToGridFS('mongodb://localhost/mydb', '../assets/i
 });
 ```
 
+`relativePath` is resolved against the **helper module's** directory, not the migration file's — the
+paths in this example and in the migration template are written accordingly.
+
+The returned promise settles only after three guarantees hold:
+
+| Guarantee                       | Behaviour                                                                                                                                                                                                         |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The bytes are stored            | Chunk completeness is verified before resolving (see `assertGridFsFileComplete()` below). An incomplete upload **rejects** and the incomplete file is removed, rather than returning an id that points at nothing |
+| An unreadable source fails fast | A missing or unreadable file **rejects** with the underlying `ENOENT`. It used to hang forever, because `pipe()` does not forward read-stream errors                                                              |
+| The connection is released      | The MongoClient it opens is always closed, on the success and the failure path alike. A leaked connection keeps the Node event loop alive and `migrate up` never exits                                            |
+
+Since these are hard failures, a seed migration whose asset is missing or only partially stored now
+fails the migration — and with the default `MIGRATE_FAILURE_POLICY=abort` in `docker-entrypoint.sh`,
+the container refuses to start rather than booting with broken data. That is intentional: the point
+of running migrations before the server is to find exactly this.
+
+### assertGridFsFileComplete()
+
+Verifies that every chunk of an already-stored GridFS file is present. `uploadFileToGridFS()` calls
+it for you; call it directly to check files written by something else (a restored dump, another
+service, a manual upload):
+
+```typescript
+import { assertGridFsFileComplete, getDb } from '@lenne.tech/nest-server';
+
+const db = await getDb('mongodb://localhost/mydb');
+await assertGridFsFileComplete(db, 'images', fileId, 'logo.png'); // throws if incomplete
+```
+
+Throws when the files document is missing entirely, or when fewer chunks are stored than its
+`length` implies. It counts chunk documents rather than reading bytes back, so a chunk that was
+written but truncated is **not** detected — the check targets the failure that actually occurs, a
+connection lost mid-upload. Empty files are valid and pass: GridFS stores a zero-byte file with no
+chunk documents at all.
+
 ### Migration Templates
 
 Ready-to-use template for nest-server projects: