@lenne.tech/nest-server 11.32.4 → 11.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.32.4",
+  "version": "11.33.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",
@@ -15,21 +15,20 @@
   "license": "MIT",
   "scripts": {
     "build": "rimraf dist && nest build && pnpm run build:copy-types && pnpm run build:copy-templates && pnpm run build:add-type-references && pnpm run build:framework-api",
-    "build:framework-api": "tsx scripts/generate-framework-api.ts",
-    "build:copy-types": "mkdir -p dist/types && cp src/types/*.d.ts dist/types/",
-    "build:copy-templates": "mkdir -p dist/core/modules/migrate/templates && cp src/core/modules/migrate/templates/migration-project.template.ts dist/core/modules/migrate/templates/",
     "build:add-type-references": "node scripts/add-type-references.js",
-    "build:pack": "pnpm pack && echo 'use file:/ROOT_PATH_TO_TGZ_FILE to integrate the package'",
+    "build:copy-templates": "mkdir -p dist/core/modules/migrate/templates && cp src/core/modules/migrate/templates/migration-project.template.ts dist/core/modules/migrate/templates/",
+    "build:copy-types": "mkdir -p dist/types && cp src/types/*.d.ts dist/types/",
     "build:dev": "pnpm run build",
+    "build:framework-api": "tsx scripts/generate-framework-api.ts",
+    "build:pack": "pnpm pack && echo 'use file:/ROOT_PATH_TO_TGZ_FILE to integrate the package'",
     "c": "pnpm run check",
+    "cf": "pnpm run check:fix",
     "check": "node scripts/check.mjs",
-    "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: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: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:manifest": "node scripts/check-package-manifest.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",
-    "spectaql:sync": "node extras/update-spectaql-version.mjs",
-    "cf": "pnpm run check:fix",
     "cnaf": "pnpm run check:naf",
     "docs": "pnpm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",
     "docs:bootstrap": "node extras/update-spectaql-version.mjs && node scripts/run-spectaql.mjs",
@@ -38,36 +37,40 @@
     "format:check": "oxfmt --check src/ scripts/",
     "lint": "oxlint --ignore-path .oxlintignore src/ tests/ scripts/",
     "lint:fix": "oxlint --fix --fix-suggestions --ignore-path .oxlintignore src/ tests/ scripts/",
+    "prepack": "pnpm run prestart:prod",
+    "prepublishOnly": "pnpm run lint && pnpm run test:ci",
     "prestart:prod": "pnpm run build",
+    "preversion": "pnpm run lint",
     "reinit": "rimraf pnpm-lock.yaml && rimraf node_modules && pnpm install && pnpm run lint && pnpm run test:e2e && pnpm run test:ci && pnpm run build",
     "reinit:clean": "rimraf pnpm-lock.yaml && rimraf node_modules && pnpm store prune && pnpm install && pnpm run test:e2e && pnpm run build",
     "reinit:force": "rimraf pnpm-lock.yaml && rimraf node_modules && pnpm store prune && pnpm install --force && pnpm run test:e2e",
     "reinit:legacy": "rimraf pnpm-lock.yaml && rimraf node_modules && pnpm store prune && pnpm install && pnpm run test:e2e",
+    "spectaql:sync": "node extras/update-spectaql-version.mjs",
     "start": "pnpm run start:local",
-    "start:prod": "NODE_ENV=production node dist/main.js",
-    "start:nodemon": "ts-node -r tsconfig-paths/register src/main.ts",
     "start:debug": "nodemon --config nodemon-debug.json",
     "start:dev": "nodemon",
     "start:dev:swc": "nest start -b swc -w --type-check",
     "start:local": "NODE_ENV=local nodemon",
     "start:local:swc": "NODE_ENV=local nest start -b swc -w --type-check",
+    "start:nodemon": "ts-node -r tsconfig-paths/register src/main.ts",
+    "start:prod": "NODE_ENV=production node dist/main.js",
     "test": "pnpm run vitest:unit && pnpm run vitest",
     "test:ci": "pnpm run vitest:unit && pnpm run vitest:ci",
+    "test:cleanup": "find tests -type f \\( -name '*.txt' -o -name '*.bin' -o -name '*.png' \\) -not -name '.gitkeep' -delete && echo 'Test artifacts cleaned up'",
     "test:cov": "pnpm run vitest:unit:cov && pnpm run vitest:cov",
     "test:e2e": "pnpm run vitest",
-    "prepack": "pnpm run prestart:prod",
-    "prepublishOnly": "pnpm run lint && pnpm run test:ci",
-    "preversion": "pnpm run lint",
+    "test:infra": "node scripts/test-infra.mjs up",
+    "test:infra:down": "node scripts/test-infra.mjs down",
+    "test:infra:status": "node scripts/test-infra.mjs status",
+    "test:types": "tsc --noEmit --skipLibCheck -p tests/types/tsconfig.json",
+    "test:unit:watch": "vitest --config vitest.config.ts",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
     "vitest": "NODE_ENV=e2e vitest run --config vitest-e2e.config.ts",
     "vitest:ci": "NODE_ENV=ci vitest run --config vitest-e2e.config.ts",
     "vitest:cov": "NODE_ENV=e2e vitest run --coverage --config vitest-e2e.config.ts",
-    "vitest:watch": "NODE_ENV=e2e vitest --config vitest-e2e.config.ts",
     "vitest:unit": "vitest run --config vitest.config.ts",
     "vitest:unit:cov": "vitest run --coverage --config vitest.config.ts",
-    "test:unit:watch": "vitest --config vitest.config.ts",
-    "test:types": "tsc --noEmit --skipLibCheck -p tests/types/tsconfig.json",
-    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
-    "test:cleanup": "find tests -type f \\( -name '*.txt' -o -name '*.bin' \\) -not -name '.gitkeep' -delete && echo 'Test artifacts cleaned up'",
+    "vitest:watch": "NODE_ENV=e2e vitest --config vitest-e2e.config.ts",
     "watch": "npm-watch"
   },
   "repository": {
@@ -85,25 +88,25 @@
   "dependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
-    "@better-auth/passkey": "1.6.23",
+    "@better-auth/passkey": "1.6.26",
     "@getbrevo/brevo": "6.0.2",
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@nestjs/apollo": "13.4.2",
-    "@nestjs/common": "11.1.28",
-    "@nestjs/core": "11.1.28",
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
     "@nestjs/graphql": "13.4.2",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.1.28",
+    "@nestjs/platform-express": "11.1.29",
     "@nestjs/schedule": "6.1.3",
     "@nestjs/swagger": "11.4.6",
     "@nestjs/terminus": "11.1.1",
-    "@tus/file-store": "2.1.0",
-    "@tus/server": "2.4.2",
+    "@tus/file-store": "2.1.1",
+    "@tus/server": "2.4.3",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
-    "better-auth": "1.6.23",
+    "better-auth": "1.6.26",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
     "compression": "1.8.1",
@@ -113,19 +116,19 @@
     "ejs": "6.0.1",
     "express": "5.2.1",
     "graphql": "16.14.0",
-    "graphql-query-complexity": "1.1.1",
+    "graphql-query-complexity": "2.0.0",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
-    "graphql-ws": "6.1.0",
-    "jose": "6.2.3",
-    "js-sha256": "0.12.0",
+    "graphql-ws": "6.2.1",
+    "jose": "6.2.8",
+    "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "mongodb": "7.5.0",
-    "mongoose": "9.8.0",
+    "mongoose": "9.9.1",
     "multer": "2.2.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "9.0.3",
+    "nodemailer": "9.0.5",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -133,43 +136,72 @@
     "rxjs": "7.8.2",
     "supertest": "7.2.2",
     "ts-morph": "28.0.0",
-    "ws": "8.21.1",
+    "ws": "8.21.3",
     "yuml-diagram": "1.2.0"
   },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3.1045.0 <4",
+    "@aws-sdk/s3-request-presigner": ">=3.1045.0 <4",
+    "@tus/s3-store": ">=2.0.5 <3",
+    "bullmq": ">=5.16.0 <7",
+    "ioredis": ">=5.0.0 <7"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@tus/s3-store": {
+      "optional": true
+    },
+    "bullmq": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@aws-sdk/client-s3": "3.1106.0",
+    "@aws-sdk/s3-request-presigner": "3.1106.0",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.1.28",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.15.46",
+    "@swc/core": "1.15.47",
+    "@tus/s3-store": "2.0.5",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "5.0.6",
-    "@types/lodash": "4.17.24",
+    "@types/lodash": "4.17.25",
     "@types/multer": "2.2.0",
-    "@types/node": "26.1.1",
+    "@types/node": "26.2.0",
     "@types/nodemailer": "8.0.1",
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.10",
     "@vitest/ui": "4.1.10",
     "ansi-colors": "4.1.3",
+    "bullmq": "6.0.9",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
+    "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.1",
-    "oxfmt": "0.59.0",
-    "oxlint": "1.74.0",
+    "oxfmt": "0.62.0",
+    "oxlint": "1.77.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
-    "tsx": "4.23.1",
+    "tsx": "4.23.11",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
-    "unplugin-swc": "1.5.9",
-    "vite": "8.1.5",
+    "unplugin-swc": "1.5.10",
+    "vite": "8.2.1",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.10"
   },

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,
     },

package/src/core/common/helpers/content-disposition.helper.ts

@@ -0,0 +1,90 @@
+/**
+ * `Content-Disposition` rendering for a client-supplied filename.
+ *
+ * An import-free LEAF on purpose. Two call sites in different layers need the identical value —
+ * the file controller's streaming branch (`src/core/modules/file/`) and the S3 presigned-URL
+ * branch (`src/core/common/services/`) — and `src/core/common/**` must not depend on
+ * `src/core/modules/**`. A leaf serves both without an import edge in the wrong direction, and
+ * without a cycle to reason about (see `.claude/rules/architecture.md` → "DI Token Placement
+ * (SWC-Safe)").
+ *
+ * Sharing it is the point, not just tidiness: while the logic was duplicated, the SAME file
+ * downloaded under a DIFFERENT name depending on whether `s3.presignedDownloads` was enabled.
+ */
+
+/**
+ * Characters an RFC 8187 ext-value may carry unescaped (`attr-char`).
+ *
+ * `encodeURIComponent` is close but not equal: it leaves `'`, `(`, `)` and `*`
+ * unescaped, and none of those is an `attr-char`. A filename like
+ * `O'Brien (final)*.pdf` therefore produced a MALFORMED `filename*` parameter,
+ * which a strict parser is entitled to drop — falling back to the ASCII
+ * `filename` and losing the very name the ext-value exists to preserve.
+ * Over-escaping is always allowed (`value-chars = *( pct-encoded / attr-char )`),
+ * so escaping these four extra is the whole fix.
+ */
+const NON_ATTR_CHAR = /['()*]/g;
+
+/**
+ * Everything that may NOT stand in the quoted `filename` fallback.
+ *
+ * The complement is printable US-ASCII (0x20–0x7E) minus `"` (0x22) and `\`
+ * (0x5C) — the two characters that would end the quoted-string early or start a
+ * quoted-pair. So the allowed ranges are 0x20–0x21, 0x23–0x5B and 0x5D–0x7E, and
+ * everything else (non-ASCII, CR/LF, other control characters, DEL) is replaced
+ * with `_`.
+ *
+ * Replacing rather than deleting is deliberate: it keeps the name's shape
+ * recognisable (`Übersicht.pdf` → `_bersicht.pdf`) instead of silently welding
+ * neighbouring words together, and it can never produce an empty parameter.
+ */
+const NON_QUOTABLE_ASCII = /[^\x20-\x21\x23-\x5B\x5D-\x7E]/g;
+
+/**
+ * Percent-encode a filename as an RFC 8187 ext-value (the `filename*` parameter).
+ */
+function toExtValue(filename: string): string {
+  return encodeURIComponent(filename).replace(
+    NON_ATTR_CHAR,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * Build the `Content-Disposition` value for a client-supplied filename.
+ *
+ * Used for BOTH file delivery paths — the streamed response and the S3 presigned URL's
+ * `response-content-disposition` — so a file keeps its name whichever one serves it.
+ *
+ * Exported so the rendering can be unit-tested without a Nest context, and so a
+ * project overriding `CoreFileController.setFileHeaders` can reuse it.
+ *
+ * Filenames are client-supplied on both the multer path (`multerFileToUpload()`
+ * keeps `originalname`, where the old diskStorage path generated the name
+ * server-side) and the tus path (`Upload-Metadata`), so this value has to hold
+ * up against a hostile name as well as merely an awkward one.
+ *
+ * Two parameters, because they answer to two different specs and one client set
+ * each:
+ *
+ *  - `filename` is an RFC 6266 quoted-string, and NOTHING percent-decodes it.
+ *    Percent-encoding it protects nothing the quotes do not already handle — it
+ *    only makes a client without `filename*` support save
+ *    `Jahresbericht%202024.pdf`. So it is sanitised to quotable ASCII and left
+ *    literal.
+ *  - `filename*` is the RFC 8187 ext-value that carries the real, non-ASCII name
+ *    for every client that understands it, and it wins over `filename` per RFC
+ *    6266 §4.3 when both are present.
+ *
+ * Injection is closed by the quoting plus the sanitiser, not by the encoding.
+ * Before 11.33.0 this header was emitted bare (`filename=${file.filename}`), so a
+ * `"` or a `; ` let the caller append or replace parameters outright — and an
+ * appended `filename*` WINS over the one meant here. A CR/LF is worse than that:
+ * it makes Node's `setHeader` throw `ERR_INVALID_CHAR`, turning that one file's
+ * download into a permanent 500.
+ */
+export function buildContentDisposition(filename?: string): string {
+  const name = filename || 'download';
+  const quotable = name.replace(NON_QUOTABLE_ASCII, '_');
+  return `attachment; filename="${quotable}"; filename*=UTF-8''${toExtValue(name)}`;
+}

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

@@ -1,6 +1,10 @@
 import { MulterOptions } from '@nestjs/platform-express/multer/interfaces/multer-options.interface';
-import { diskStorage } from 'multer';
+import { randomBytes } from 'crypto';
+import { diskStorage, memoryStorage } from 'multer';
 import { extname } from 'path';
+import { Readable } from 'stream';
+
+import type { FileUploadSource } from '../../modules/file/interfaces/file-upload.interface';
 
 /**
  * What an upload endpoint accepts: exact mimetypes and exact file extensions.
@@ -191,6 +195,7 @@ export function multerOptionsForImageUpload(options: {
   destination?: string;
   fileSize?: number;
   fileTypeRegex?: RegExp;
+  memory?: boolean;
 }): MulterOptions {
   // Set config
   const config = {
@@ -214,15 +219,53 @@ export function multerOptionsForImageUpload(options: {
 
     // Automatic storage handling
     // For configuration see https://github.com/expressjs/multer#storage
-    storage: diskStorage({
-      // Destination for uploaded file
-      // If destination is not set file will be buffered and can be processed
-      // in the method
-      destination: config.destination ? config.destination : undefined,
-
-      // Generated random file name
-      filename: multerRandomFileName(),
-    }),
+    //
+    // `memory: true` keeps the upload in RAM so the handler can hand it straight
+    // to a central store (GridFS/S3) via `multerFileToUpload()`. Disk storage
+    // writes to the POD's filesystem, which another replica cannot read and a
+    // restart discards — see `memoryStorage()` below.
+    storage: config.memory
+      ? memoryStorage()
+      : diskStorage({
+          // Destination for uploaded file
+          // If destination is not set file will be buffered and can be processed
+          // in the method
+          destination: config.destination ? config.destination : undefined,
+
+          // Generated random file name
+          filename: multerRandomFileName(),
+        }),
+  };
+}
+
+/**
+ * Adapt a multer upload to the shape `CoreFileService` consumes.
+ *
+ * Lets a REST/multer endpoint write to the same central storage (GridFS or S3)
+ * as the GraphQL upload path, instead of the pod-local disk that multer's
+ * `diskStorage` produces. Requires `memory: true` on the multer options — a
+ * disk-stored file has no `buffer`, and this throws rather than silently
+ * storing an empty file.
+ *
+ * The returned `createReadStream` is callable more than once: it builds a fresh
+ * stream over the same buffer each time, matching graphql-upload's contract.
+ */
+export function multerFileToUpload(file: {
+  buffer?: Buffer;
+  mimetype?: string;
+  originalname?: string;
+}): FileUploadSource {
+  if (!file?.buffer) {
+    throw new Error(
+      'multerFileToUpload() needs an in-memory upload: pass `memory: true` to the multer options ' +
+        '(a disk-stored file has no buffer).',
+    );
+  }
+  return {
+    createReadStream: () => Readable.from(file.buffer),
+    encoding: '7bit',
+    filename: file.originalname || randomBytes(16).toString('hex'),
+    mimetype: file.mimetype || 'application/octet-stream',
   };
 }
 

package/src/core/common/helpers/graceful-shutdown.helper.ts

@@ -0,0 +1,116 @@
+import { INestApplication, Logger } from '@nestjs/common';
+
+import { ConfigService } from '../services/config.service';
+
+/** Signals an orchestrator uses to ask a container to stop */
+const SHUTDOWN_SIGNALS: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];
+
+/**
+ * A delay this long is almost certainly a typo (seconds written as milliseconds, or the other way
+ * round). Orchestrators SIGKILL after their grace period anyway — typically 10-30s — so a longer
+ * wait cannot be honored, it only guarantees the ungraceful ending it was meant to avoid.
+ */
+const MAX_SHUTDOWN_DELAY_MS = 60_000;
+
+/**
+ * Above this, the delay is very likely longer than what actually gets to run.
+ *
+ * The cap above catches typos; it does NOT describe the real ceiling, and the gap between the two
+ * is where this silently breaks. Three separate limits sit BELOW the 60s cap:
+ * Docker/Compose `stop_grace_period` defaults to 10s, Kubernetes `terminationGracePeriodSeconds`
+ * to 30s, and this framework's own `installProcessDiagnostics()` arms a 30s watchdog that calls
+ * `exit(1)`. A delay of, say, 45s passes the cap without a word and is then force-killed mid-wait:
+ * no drain, and not one `onModuleDestroy` / `onApplicationShutdown` hook runs — precisely the
+ * ending the delay exists to prevent. Warning here means the dangerous band is no longer silent.
+ *
+ * The delay is only part of the budget: whatever `app.close()` needs to drain comes after it.
+ */
+const SHUTDOWN_DELAY_ADVISORY_MS = 10_000;
+
+/**
+ * Install signal handling that keeps the app healthy for `IServerOptions.shutdownDelayMs`
+ * before shutting it down, then closes it cleanly.
+ *
+ * **Why this is not a NestJS lifecycle hook.** The obvious place looks like
+ * `beforeApplicationShutdown`, but Nest's `close()` runs
+ * `onModuleDestroy` → `beforeApplicationShutdown` → dispose (close the HTTP server) →
+ * `onApplicationShutdown`. A delay in that hook therefore waits AFTER every module has been
+ * destroyed while the socket is still accepting — so the instance keeps taking traffic with its
+ * services already torn down. That is worse than not waiting at all, which is why the wait has to
+ * happen before `close()` is entered, i.e. in the signal handler.
+ *
+ * **What the delay is for.** An orchestrator sends SIGTERM and deregisters the instance from the
+ * load balancer at the same moment, but deregistration propagates asynchronously — for a beat,
+ * requests still arrive. Staying fully healthy through that beat is what lets them be answered
+ * instead of dropped.
+ *
+ * Without a configured delay this is exactly `app.enableShutdownHooks()`, which is what the
+ * framework did before.
+ *
+ * @param app the Nest application to shut down
+ * @returns the same app, so it can be chained
+ */
+export function installGracefulShutdown<T extends INestApplication>(app: T): T {
+  const logger = new Logger('GracefulShutdown');
+  const configured = ConfigService.getFastButReadOnly<number | undefined>('shutdownDelayMs');
+  const delayMs = typeof configured === 'number' && configured > 0 ? configured : 0;
+
+  if (!delayMs) {
+    // Nest's own handling: close immediately on a signal, running every lifecycle hook.
+    app.enableShutdownHooks();
+    return app;
+  }
+
+  if (delayMs > MAX_SHUTDOWN_DELAY_MS) {
+    logger.warn(
+      `shutdownDelayMs is ${delayMs}ms, which exceeds the ${MAX_SHUTDOWN_DELAY_MS}ms cap and is longer than a typical ` +
+        `orchestrator grace period — capping it, since a longer wait only ends in SIGKILL.`,
+    );
+  } else if (delayMs > SHUTDOWN_DELAY_ADVISORY_MS) {
+    logger.warn(
+      `shutdownDelayMs is ${delayMs}ms. Keep it well below your orchestrator's grace period AND leave room for the ` +
+        'drain that follows it — Docker/Compose stop_grace_period defaults to 10s, Kubernetes ' +
+        'terminationGracePeriodSeconds to 30s, and installProcessDiagnostics() force-exits after 30s. Exceeding any ' +
+        'of them means the process is killed mid-wait and no shutdown hook runs at all.',
+    );
+  }
+  const effectiveDelayMs = Math.min(delayMs, MAX_SHUTDOWN_DELAY_MS);
+
+  // Deliberately NOT enableShutdownHooks(): Nest would install its own listener for the same
+  // signals and close the app immediately, in parallel with the wait below.
+  let shuttingDown = false;
+  // Hoisted out of the handler so a second signal can CANCEL the pending wait. Left inside, the
+  // timer stayed armed and fired after the impatient close had already run, calling app.close()
+  // a second time and re-running every onApplicationShutdown hook against a closed app.
+  let timer: NodeJS.Timeout | undefined;
+
+  const handle = (signal: NodeJS.Signals): void => {
+    if (shuttingDown) {
+      // A second signal means someone is impatient. Stop waiting and close now.
+      logger.warn(`${signal} received again — closing immediately`);
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      void app.close();
+      return;
+    }
+    shuttingDown = true;
+    logger.log(`${signal} received — staying healthy for ${effectiveDelayMs}ms so the load balancer can deregister`);
+
+    timer = setTimeout(() => {
+      app
+        .close()
+        .then(() => logger.log('Shutdown complete'))
+        .catch((error) => logger.error(`Shutdown failed: ${error instanceof Error ? error.message : 'Unknown error'}`));
+    }, effectiveDelayMs);
+    // The listening server keeps the loop alive on its own; this timer must not be what holds it.
+    timer.unref?.();
+  };
+
+  for (const signal of SHUTDOWN_SIGNALS) {
+    process.on(signal, handle);
+  }
+
+  return app;
+}