@lenne.tech/nest-server 11.41.6 → 11.41.7

package/docs/REQUEST-LIFECYCLE.md

@@ -42,7 +42,7 @@ The `CoreModule` is a dynamic module that bootstraps the entire framework:
 | **Mongoose Plugins** | Auto-registration of ID, password, audit, and role guard plugins |
 | **GraphQL Subscriptions** | WebSocket support with JWT/session authentication (cluster-wide when `redis` is configured — see the Subscriptions row under GraphQL Features) |
 | **Central Redis (optional)** | `CoreRedisService` — globally provided **and exported** by `CoreModule`, always present but **inert unless `redis` is configured** ("presence implies enabled"). Injected with `@Optional()`; every consumer keeps a process-local fallback. One service serves all features: shared client (`getClient()`), one cached subscriber (`getSubscriber()` — a subscribing client cannot run commands), dedicated connections (`createClient(label)`); all tracked and quit on shutdown. Keys are namespaced by the framework per key via `key(...)`, **not** through ioredis's own `keyPrefix` (that would collide with BullMQ's prefix). Requires the OPTIONAL peer `ioredis` — configured but missing **fails the boot**. Switches on: exact cross-replica rate limits, cron deduplication, `CoreRedisPubSub` as `PUB_SUB`, tenant-cache invalidation broadcast, Hub collector mirroring, MCP session registry |
-| **Central S3 (optional)** | `CoreS3Service` — globally provided **and exported** by `CoreModule`, inert unless `s3` is configured *and* names a `bucket` (a bucket-less block is ignored with a warning). Backs `file.storage: 's3'` and TUS staging (`tus.s3Staging`). Requires the OPTIONAL peers `@aws-sdk/client-s3` (+ `@aws-sdk/s3-request-presigner` for `presignedDownloads`) — configured but missing **fails the boot** |
+| **Central S3 (optional)** | `CoreS3Service` — globally provided **and exported** by `CoreModule`, inert unless `s3` is configured *and* names a `bucket` (a bucket-less block is ignored with a warning). Backs `file.storage: 's3'` and TUS staging (`tus.s3Staging`). Requires the OPTIONAL peers `@aws-sdk/client-s3` (+ `@aws-sdk/s3-request-presigner` for `presignedDownloads`) — configured but missing **fails the boot**. `@aws-sdk/lib-storage` (optional) uploads streams of unknown length in parts; without it they are buffered in memory, with one boot warning |
 | **Configuration System** | `config.env.ts` with ENV variables, `NEST_SERVER_CONFIG` JSON, `NSC__*` prefixes |
 | **Cookie Handling** | Enabled by default (`cookies: true`), configurable via `ICookiesConfig` with `exposeTokenInBody` option |
 | **Unified CORS** | Single `cors` config propagates to GraphQL, REST, and BetterAuth layers |

package/docs/security-overrides.md

@@ -18,7 +18,7 @@ The framework pulls in three transitive packages that its `@nestjs/*` dependenci
 |---------|----------|------------------------------------------|
 | `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | Older `@nestjs/graphql` releases declare `"ws": "8.20.1"` — an **exact pin**, not a caret. 13.4.5, the version this framework declares, pins `8.21.3` |
 | `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS), patched `>=5.2.2`; [GHSA-r3ph-w7gj-g6xm](https://github.com/advisories/GHSA-r3ph-w7gj-g6xm) — moderate: `maxTotalMergeKeys` does not bound CPU use for empty merge sources, covers `<=5.4.0`, patched `>=5.4.1` (published 2026-09-29) | `@nestjs/swagger` declares js-yaml as an **exact pin**, the same shape as the `ws` case: older releases `5.2.1`, 11.4.7 — the version this framework declares, and the newest 11.x — `5.3.0`. No swagger update reaches the fix, so **this entry is load-bearing again** |
-| `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0` | `@nestjs/platform-express` up to 11.2.5 declares `"multer": "2.2.0"` — an **exact pin**. A direct `multer` dependency does not move it: you get both copies, and FileInterceptor uses the vulnerable one. 11.2.6, the version this framework declares since 11.41.4, pins `2.4.0` |
+| `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0` | `@nestjs/platform-express` up to 11.2.5 declares `"multer": "2.2.0"` — an **exact pin**. A direct `multer` dependency does not move it: you get both copies, and FileInterceptor uses the vulnerable one. 11.2.6, which this framework declared from 11.41.4, pins `2.4.0`, and so does 11.2.7, declared since 11.41.7 |
 
 **Status since 11.41.5:** `ws` and `multer` resolve to a patched version on their own with the
 `@nestjs/*` versions this framework declares; their entries below are insurance for a project whose

package/migration-guides/11.41.6-to-11.41.7.md

@@ -0,0 +1,192 @@
+# Migration Guide: 11.41.6 → 11.41.7
+
+## Overview
+
+| Category              | Details                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------- |
+| **Breaking Changes**  | None in npm mode. Vendor mode: one package to install (§1)                                  |
+| **Bugfixes**          | Uploads to S3 are no longer read into memory — a large upload could OOM-kill the container. A known length above 5 GiB (TUS) no longer fails on AWS S3. MCP clients reconnect on their own after a restart (§4) |
+| **New optional peer** | `@aws-sdk/lib-storage` — uploads of unknown length go to S3 in parts                        |
+| **New field**         | `FileUploadSource.size` — the exact file length, when the caller knows it                   |
+| **Migration Effort**  | `pnpm run update` (raises the `@nestjs/*` pins, §6). Projects using the S3 driver: install one package. Starter-based projects: assess two dev-only advisories (§5) |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run update            # starter-based projects: raises the @nestjs/* pins to 11.2.7 (§6)
+pnpm add @aws-sdk/lib-storage@<your @aws-sdk/client-s3 version>   # only with file.storage 's3'
+pnpm run build && pnpm test
+```
+
+**Vendor-mode projects must install it, whether they use S3 or not.** The vendored core is compiled
+as project code, and `core-s3.service.ts` now references the types of `@aws-sdk/lib-storage` — the
+same way it already references `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`. Without the
+package the typecheck fails with `Cannot find module '@aws-sdk/lib-storage'`. A project converted to
+vendor mode from now on gets it from the CLI's import scan; the core update of an EXISTING vendor
+project does not add packages, so add it there yourself, next to `@aws-sdk/client-s3`, at the same
+version.
+
+## What's New in 11.41.7
+
+### 1. Uploads reach S3 as a stream
+
+Until now the S3 driver read every upload into a Buffer before sending it: `createFile()` did so for
+every GraphQL and multer upload, and `CoreS3Service.putObject()` for every stream without a length.
+The memory cost of an upload was therefore its size. A multi-GB file threw
+`Array buffer allocation failed` or got the container OOM-killed at 100 % progress — taking every
+other request on that replica with it.
+
+Now nothing on that path buffers:
+
+| Length | Request | Memory |
+| ------ | ------- | ------ |
+| known, up to 5 GiB — `size` on the upload, a TUS upload, a buffer | one streamed `PutObject` | constant |
+| known, above 5 GiB | multipart upload via `@aws-sdk/lib-storage` | at most four parts |
+| unknown — every GraphQL and streamed REST upload | multipart upload via `@aws-sdk/lib-storage` | at most four 5 MiB parts |
+| `@aws-sdk/lib-storage` not installed | as before: an unknown length is read into memory, a known one is one `PutObject` | the file's size (unknown length) |
+
+The second row is a fix in its own right: AWS S3 refuses a single `PutObject` above 5 GiB
+(`EntityTooLarge`). A TUS upload that large — the default `tus.maxSize` is 50 GiB — used to fail at
+finalization, after the client had sent every byte, on every retry. MinIO and RustFS accept such a
+request, which is why test setups never showed it.
+
+The length recorded for an upload of unknown length is read back from the stored object.
+
+**What to do:** with `file.storage: 's3'` (or an `s3` config that makes it the derived driver),
+install `@aws-sdk/lib-storage` at the same version as your `@aws-sdk/client-s3`:
+
+```bash
+pnpm add @aws-sdk/lib-storage@3.1145.0   # match your @aws-sdk/client-s3
+```
+
+Without it nothing breaks — uploads keep the previous behaviour, and the boot log says once:
+
+```
+Streaming an S3 upload of unknown length falls back to buffering it in memory because the optional
+peer dependency "@aws-sdk/lib-storage" is not installed. Run: pnpm add @aws-sdk/lib-storage
+```
+
+Use an S3-compatible store that supports multipart uploads (AWS S3, MinIO and RustFS do). Give the
+bucket a lifecycle rule that aborts incomplete multipart uploads: a failed upload is aborted by the
+framework, but a process killed mid-upload leaves its parts behind, and S3 keeps them until something
+removes them.
+
+### 2. `FileUploadSource.size`
+
+A caller that knows the file's EXACT length can say so, and the S3 driver then uses one streamed
+request instead of a multipart upload (up to 5 GiB; above that it stays a multipart upload, with
+parts sized to the total):
+
+```typescript
+await fileService.createFile({
+  createReadStream: () => createReadStream(path),
+  filename,
+  mimetype,
+  size: (await stat(path)).size,
+});
+```
+
+Leaving it out is always safe — it only costs the multipart round trips — and for data that is
+already in memory it is the better choice: the multipart path sends Buffer parts, which the SDK
+retries after a transient S3 error, while one streamed request is attempted once.
+`multerFileToUpload()` therefore does not set it.
+
+**Never pass the `Content-Length` of a multipart/form-data request.** It counts the whole envelope
+(boundaries, part headers, other fields) and is always larger than the file, and a wrong length
+breaks the upload. Anything but a positive integer is treated as unknown.
+
+### 3. `CoreS3Service.statObject()`
+
+New: size and content type of an object, or `null` when it does not exist — one HEAD request.
+`objectExists()` now delegates to it.
+
+### 4. MCP clients recover from a restart
+
+`/ai/mcp` keeps its sessions in process memory, so every restart — every deploy — forgets the
+session ids its clients still hold. A request carrying such an id used to get a fresh transport,
+which answered the client's next call (a `tools/call`, never an `initialize`) with
+`400 Bad Request: Server not initialized`. Clients do not recover from a 400: every connected
+client stayed dead until somebody reconnected it by hand.
+
+Such a request now gets **404** `Unknown or expired MCP session` — the status the MCP specification
+tells clients to answer with a new `initialize`, and what the SDK's own server returns. An
+`initialize` carrying a stale id still starts a new session. With `redis` configured, a session
+that lives on another replica of the same user still answers **409**, as before.
+
+Nothing to do. A client or proxy that treated the old 400 as "session gone" sees 404 instead.
+
+### 5. Two advisories without a fix in the dev tooling
+
+Two HIGH advisories surfaced in the audit on 2026-10-03, and neither has a patched release
+anywhere yet:
+
+| Advisory | Package | Reaches a project through |
+| -------- | ------- | ------------------------- |
+| GHSA-ch52-4w7c-c8xp | `http-cache-semantics` <= 4.2.0 | `@swc/cli` (also via `@nestjs/cli`) — its binary downloader |
+| GHSA-vfj7-8cjw-p6xm | `braces` <= 3.0.3 | `nodemon` > `chokidar@3`; `cpy-cli` > `micromatch` |
+
+Both paths are dev tooling, and no override can help while no fixed version exists. So
+`pnpm audit` — and every `check` that runs it — is red in a starter-based project until you
+assess them.
+
+**What to do:** confirm neither package is in your production tree
+(`pnpm why http-cache-semantics --prod`, `pnpm why braces --prod` — both must print nothing),
+then suppress them in `pnpm-workspace.yaml` with the reasoning next to each entry. The starter's
+file shows the shape:
+
+```yaml
+auditConfig:
+  ignoreGhsas:
+    - GHSA-ch52-4w7c-c8xp   # http-cache-semantics, dev-only via @swc/cli
+    - GHSA-vfj7-8cjw-p6xm   # braces, dev-only via nodemon / cpy-cli
+```
+
+A suppression hides the advisory everywhere and for good, so nest-server-starter 11.41.7 also
+ships the two guards that keep one honest: `scripts/check-overrides.mjs` (wired into `check` as
+`check:overrides`; it fails once a patched version exists) and
+`tests/unit/audit-suppression-scope.spec.ts` (fails once a suppressed package reaches the
+production tree). Copy both along with the entries. A project generated as a monorepo already
+has the first one at its root, from lt-monorepo.
+
+### 6. Dependency updates
+
+| Package | 11.41.6 | 11.41.7 |
+| ------- | ------- | ------- |
+| `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-express` | 11.2.6 | **11.2.7** |
+| dev: `@nestjs/testing` | 11.2.6 | 11.2.7 |
+| dev / optional peers: `@aws-sdk/client-s3`, `@aws-sdk/lib-storage` (new), `@aws-sdk/s3-request-presigner` | 3.1143.0 | 3.1145.0 |
+| dev: `@swc/core`, `@types/node`, `bullmq`, `vite` | 1.16.12, 26.6.3, 6.3.10, 8.3.1 | 1.16.13, 26.6.4, 6.3.11, 8.3.2 |
+
+**Raise the `@nestjs/*` pins together with the framework.** Starter-based projects:
+`pnpm run update` does it. A project that pins them itself must move all four to 11.2.7 — a
+project still on 11.2.6 next to the framework's 11.2.7 gets two copies of `@nestjs/common`, and
+then `CronJobs extends CoreCronJobs` stops type-checking with an error that does not name the cause.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| GraphQL / multer uploads with the S3 driver | Streamed — multipart with `@aws-sdk/lib-storage`, buffered without it |
+| `CoreS3Service.putObject(key, stream)` without a length | Same as above |
+| `CoreS3Service.putObject(key, stream, type, length)` | Unchanged up to 5 GiB: one streamed `PutObject`. Above: multipart (with `@aws-sdk/lib-storage`) |
+| TUS uploads | Unchanged up to 5 GiB. Above, on AWS S3: fixed — they failed at finalization with `EntityTooLarge`, now multipart (with `@aws-sdk/lib-storage`) |
+| GridFS and filesystem drivers | Unchanged — they always streamed |
+| A subclass overriding `CoreS3Service.collect()` | Called only when `@aws-sdk/lib-storage` is missing |
+| `@nestjs/common` / `core` / `platform-express` / `testing` pinned at 11.2.6 | Raise to 11.2.7 with the framework (§6) |
+| An MCP request with a session id the process no longer knows | 404 instead of 400 — the client re-initializes (§4) |
+| `pnpm audit` red on GHSA-ch52-4w7c-c8xp / GHSA-vfj7-8cjw-p6xm | No fix exists yet; dev-only — suppress with the guards (§5) |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| Boot warning about `@aws-sdk/lib-storage` | The optional peer is not installed | `pnpm add @aws-sdk/lib-storage` |
+| Peer warning: `@aws-sdk/lib-storage` wants a newer `@aws-sdk/client-s3` | The two packages are on different AWS SDK releases | Install both at the same version |
+| S3 upload fails or never completes when `size` is passed | `size` is not the file's length — e.g. a request's `Content-Length` | Pass the file's own length, or leave `size` out |
+
+## Module Documentation
+
+- [File module README](../src/core/modules/file/README.md) — "How an upload reaches S3"
+- [File module INTEGRATION-CHECKLIST](../src/core/modules/file/INTEGRATION-CHECKLIST.md) — step 6, switching to the S3 driver
+- [AI module README](../src/core/modules/ai/README.md) — MCP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.41.6",
+  "version": "11.41.7",
   "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",
@@ -46,9 +46,8 @@
     "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",
+    "reinit:clean": "rimraf pnpm-lock.yaml && rimraf node_modules && pnpm install && pnpm run test:e2e && pnpm run build",
+    "reinit:legacy": "rimraf pnpm-lock.yaml && rimraf node_modules && pnpm install && pnpm run test:e2e",
     "spectaql:sync": "node extras/update-spectaql-version.mjs",
     "start": "pnpm run start:local",
     "start:debug": "nodemon --config nodemon-debug.json",
@@ -95,13 +94,13 @@
     "@getbrevo/brevo": "6.0.3",
     "@modelcontextprotocol/sdk": "1.31.0",
     "@nestjs/apollo": "13.4.5",
-    "@nestjs/common": "11.2.6",
-    "@nestjs/core": "11.2.6",
+    "@nestjs/common": "11.2.7",
+    "@nestjs/core": "11.2.7",
     "@nestjs/graphql": "13.4.5",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.2.6",
+    "@nestjs/platform-express": "11.2.7",
     "@nestjs/schedule": "6.1.3",
     "@nestjs/swagger": "11.4.7",
     "@nestjs/terminus": "11.1.1",
@@ -143,6 +142,7 @@
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3.1045.0 <4",
+    "@aws-sdk/lib-storage": ">=3.1045.0 <4",
     "@aws-sdk/s3-request-presigner": ">=3.1045.0 <4",
     "@better-auth/core": ">=1.7.1 <1.8.0",
     "@better-auth/passkey": ">=1.7.1 <1.8.0",
@@ -155,6 +155,9 @@
     "@aws-sdk/client-s3": {
       "optional": true
     },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
     "@aws-sdk/s3-request-presigner": {
       "optional": true
     },
@@ -178,16 +181,17 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1143.0",
-    "@aws-sdk/s3-request-presigner": "3.1143.0",
+    "@aws-sdk/client-s3": "3.1145.0",
+    "@aws-sdk/lib-storage": "3.1145.0",
+    "@aws-sdk/s3-request-presigner": "3.1145.0",
     "@better-auth/core": "1.7.1",
     "@better-auth/passkey": "1.7.1",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
-    "@nestjs/testing": "11.2.6",
+    "@nestjs/testing": "11.2.7",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.16.12",
+    "@swc/core": "1.16.13",
     "@tus/s3-store": "2.0.7",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
@@ -195,12 +199,12 @@
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.25",
     "@types/multer": "2.3.0",
-    "@types/node": "26.6.3",
+    "@types/node": "26.6.4",
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
     "ansi-colors": "4.1.3",
     "better-auth": "1.7.1",
-    "bullmq": "6.3.10",
+    "bullmq": "6.3.11",
     "cross-env": "10.1.0",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
@@ -218,7 +222,7 @@
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "2.0.0",
-    "vite": "8.3.1",
+    "vite": "8.3.2",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.11"
   },

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

@@ -272,6 +272,10 @@ export function multerFileToUpload(file: {
     encoding: '7bit',
     filename: file.originalname || randomBytes(16).toString('hex'),
     mimetype: file.mimetype || 'application/octet-stream',
+    // No `size`, although the buffer's length is exact: with a size, S3 receives one streamed
+    // PutObject, and the SDK does not retry a stream body after a transient error (503 SlowDown, a
+    // dropped socket). Without it the multipart path sends Buffer slices of this very buffer — no
+    // copy — which the SDK does retry.
   };
 }
 

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

@@ -80,7 +80,7 @@ export class GridFSHelper {
    * process down. That is reachable from ordinary traffic — a client that aborts a
    * GraphQL upload mid-body errors the capacitor stream — and it was
    * driver-conditional: the same abort is a rejected promise under the S3 driver
-   * (`streamToBuffer` throws) and under the filesystem driver (`pipeline()`
+   * (the multipart upload rejects) and under the filesystem driver (`pipeline()`
    * forwards both ends), and a process crash under GridFS, the pre-11.33 default.
    * The migration helper's `uploadFileToGridFS()` already carried this handler; the
    * one on the request path did not.

package/src/core/common/services/core-s3.service.ts

@@ -74,6 +74,16 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
    */
   protected presigner?: typeof import('@aws-sdk/s3-request-presigner');
 
+  /**
+   * Lazy-imported `@aws-sdk/lib-storage`, used to upload a stream whose length is unknown.
+   *
+   * Three states, and the third is the point: `undefined` means "not tried yet", a module means
+   * "available", and `null` means "tried and absent". Without the `null` the import would be
+   * retried on every single upload, and since the absence is permanent that is a resolver miss per
+   * request plus a repeated warning in the log.
+   */
+  protected multipartUploader?: null | typeof import('@aws-sdk/lib-storage');
+
   constructor(protected readonly configService: ConfigService) {
     const raw = this.configService.getFastButReadOnly<IS3Config | undefined>('s3');
     if (!raw || raw.enabled === false) {
@@ -189,6 +199,10 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
       ...(accessKeyId && secretAccessKey ? { credentials: { accessKeyId, secretAccessKey } } : {}),
     });
 
+    // Resolved at boot rather than on the first upload, so a missing optional peer is reported
+    // where operators look — the startup log — instead of during the first large upload.
+    await this.loadMultipartUploader();
+
     await this.verifyBuckets();
   }
 
@@ -263,10 +277,26 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
   /**
    * Upload an object to the main bucket.
    *
-   * A stream needs its length: without `Content-Length` the SDK switches to aws-chunked
-   * encoding and then fails on a missing `x-amz-decoded-content-length`, so a stream of
-   * unknown size is read into memory first. Pass `contentLength` whenever the size is
-   * known — that streams the body straight through instead of buffering it.
+   * A `PutObject` needs the body's length: without `Content-Length` the SDK switches to
+   * aws-chunked encoding and then fails on a missing `x-amz-decoded-content-length`. So pass
+   * `contentLength` whenever the size is known — that streams the body straight through as a
+   * single request.
+   *
+   * A stream of UNKNOWN length goes through a multipart upload instead (`@aws-sdk/lib-storage`),
+   * which is what that package exists for: it reads the stream in parts and needs no total up
+   * front. It used to be read into memory instead, which made the memory cost of an upload equal
+   * to its size — a multi-GB object then either threw "Array buffer allocation failed" or got the
+   * container OOM-killed at 100 % progress, taking every other in-flight request with it. That is
+   * not a hypothetical shape: any streamed HTTP upload has it, because a multipart request's
+   * `Content-Length` covers the whole envelope and therefore cannot be used as the object length.
+   *
+   * A KNOWN length above {@link CoreS3Service.MAX_SINGLE_PUT_BYTES} goes through the multipart
+   * upload as well: AWS S3 refuses a single PutObject that large with `EntityTooLarge`, which for a
+   * finished TUS upload means after the client has sent every byte.
+   *
+   * Without the optional peer dependency both cases behave exactly as before: an unknown length is
+   * read into memory, a known one goes up as one PutObject whatever its size (MinIO and RustFS
+   * accept that; AWS S3 does not above 5 GiB).
    */
   async putObject(
     key: string,
@@ -278,6 +308,15 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
 
     let payload: Buffer | Readable | string = body;
     let length = contentLength;
+    // Multipart for a stream of UNKNOWN length — nothing else carries it without buffering — and for
+    // one whose known length exceeds what S3 accepts in a single request.
+    if (this.isStream(body) && (length === undefined || length > CoreS3Service.MAX_SINGLE_PUT_BYTES)) {
+      const uploader = await this.loadMultipartUploader();
+      if (uploader) {
+        await this.putObjectMultipart(uploader, key, body, contentType, length);
+        return;
+      }
+    }
     if (this.isStream(body) && length === undefined) {
       payload = await this.collect(body);
       length = payload.length;
@@ -318,6 +357,69 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
     await send();
   }
 
+  /**
+   * The multipart uploader, or `undefined` when the optional peer dependency is absent.
+   *
+   * Absence is NOT an error here, unlike the missing `@aws-sdk/client-s3` in `onModuleInit`:
+   * multipart is an optimisation of a path that already works by buffering, so a project that
+   * never installs it keeps the previous behaviour instead of failing to boot. The cost of that
+   * choice is memory, which is why the caller's doc states it.
+   */
+  protected async loadMultipartUploader(): Promise<typeof import('@aws-sdk/lib-storage') | undefined> {
+    if (this.multipartUploader !== undefined) {
+      return this.multipartUploader ?? undefined;
+    }
+    try {
+      this.multipartUploader = await import('@aws-sdk/lib-storage');
+    } catch {
+      // `null`, not `undefined`: the field doubles as the "already tried" marker, and a failed
+      // import must not be retried on every upload.
+      this.multipartUploader = null;
+      this.logger.warn(
+        'Streaming an S3 upload of unknown length falls back to buffering it in memory because the ' +
+          'optional peer dependency "@aws-sdk/lib-storage" is not installed. Run: pnpm add @aws-sdk/lib-storage',
+      );
+    }
+    return this.multipartUploader ?? undefined;
+  }
+
+  /**
+   * Upload a stream of unknown length as a multipart upload.
+   *
+   * Memory stays bounded by the uploader's defaults — parts of 5 MiB, at most four in flight —
+   * whatever the object's size. A stream that ends within the first part is sent as one ordinary
+   * PutObject by `Upload` itself, so a small file costs no multipart round trips.
+   *
+   * No `guardBodyStream` here, and that is deliberate: the guard exists because the SDK pipes a
+   * `PutObject` body into its request without listening for the source's `error`, so a failed
+   * source surfaces as a successful upload of a truncated object. `Upload` does listen — a source
+   * error rejects `done()` and the already-uploaded parts are aborted — so wrapping it would add a
+   * second error path without adding a guarantee.
+   */
+  protected async putObjectMultipart(
+    uploader: typeof import('@aws-sdk/lib-storage'),
+    key: string,
+    body: Readable,
+    contentType?: string,
+    contentLength?: number,
+  ): Promise<void> {
+    const { client, config } = this.requireInit();
+    const upload = new uploader.Upload({
+      client,
+      params: {
+        Body: body,
+        Bucket: config.bucket,
+        // A known total lets `Upload` size its parts (`ceil(total / 10 000)`, at least 5 MiB) so the
+        // 10 000-part limit holds, and refuse a stream that yields a different NUMBER of parts than
+        // that total implies (it checks the part count, not the byte count). Not sent per part.
+        ...(contentLength === undefined ? {} : { ContentLength: contentLength }),
+        ...(contentType ? { ContentType: contentType } : {}),
+        Key: key,
+      },
+    });
+    await upload.done();
+  }
+
   /**
    * Shield the SDK from a REQUEST-BODY stream that can fail, and keep the cause.
    *
@@ -397,6 +499,12 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
    */
   static readonly MAX_COPY_OBJECT_BYTES = 5 * 1024 * 1024 * 1024;
 
+  /**
+   * Largest object a single `PutObject` can carry (AWS S3 hard limit). {@link CoreS3Service.putObject}
+   * sends a known length above it as a multipart upload instead.
+   */
+  static readonly MAX_SINGLE_PUT_BYTES = 5 * 1024 * 1024 * 1024;
+
   /**
    * Build the `CopySource` value for {@link CoreS3Service.copyObject}
    */
@@ -453,13 +561,23 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
    * Whether an object exists in the main bucket
    */
   async objectExists(key: string): Promise<boolean> {
+    return (await this.statObject(key)) !== null;
+  }
+
+  /**
+   * Size and content type of an object in the main bucket, or `null` when it does not exist.
+   *
+   * One HEAD request. This is how the length of an object uploaded WITHOUT a known length is
+   * learned afterwards: the stored object is the authority on its own size.
+   */
+  async statObject(key: string): Promise<null | { contentLength?: number; contentType?: string }> {
     const { client, config, sdk } = this.requireInit();
     try {
-      await client.send(new sdk.HeadObjectCommand({ Bucket: config.bucket, Key: key }));
-      return true;
+      const result = await client.send(new sdk.HeadObjectCommand({ Bucket: config.bucket, Key: key }));
+      return { contentLength: result.ContentLength, contentType: result.ContentType };
     } catch (error: any) {
       if (error?.$metadata?.httpStatusCode === 404 || error?.name === 'NotFound') {
-        return false;
+        return null;
       }
       throw error;
     }

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

@@ -621,6 +621,14 @@ the server log; the response carries only a stable `#LTNS_0901` code.
   framework's existing auth) — the MCP session is bound to that user, and
   `tools/list` / `tools/call` are filtered to and executed with their permissions.
 - Unauthenticated requests get `401` with a `WWW-Authenticate` header.
+- A session id the server does not know — which every restart produces, because the
+  transport map is process memory — gets **`404`**, and so does another user's id. 404
+  is the status the MCP spec has a client react to by sending a fresh `initialize`, so
+  clients recover from a deploy on their own rather than sitting dead until someone
+  reconnects by hand. A request with **no** session id and no `initialize` body still
+  gets `400`: there is nothing to recover, and a 404 would start a reconnect loop.
+- Answering a foreign id `404` rather than `403` is deliberate — a 403 would confirm
+  that the id exists, and the id travels in a response header and through client logs.
 
 ### Multi-replica / sticky sessions
 

package/src/core/modules/ai/core-ai-mcp.controller.ts

@@ -121,6 +121,27 @@ export class CoreAiMcpController implements OnModuleDestroy {
         this.foreignSession(res, owner);
         return;
       }
+
+      // A session id the client still holds that no replica knows — the state every restart
+      // produces, because the transport map is process memory. 404 is the only status a client
+      // reacts to by starting a fresh session itself (the spec requires it to), and it is what the
+      // SDK's own server returns for a mismatched id.
+      //
+      // Falling through to a new transport instead, as this did until now, looked like a silent
+      // recovery and was not one: after a restart the client's next request is a `tools/call` or
+      // `tools/list`, never an `initialize`, so the fresh transport's `validateSession()` answered
+      // `400 Bad Request: Server not initialized` — the same dead session, one layer down, and a
+      // 400 is a status no client recovers from. Found in a consumer project whose own older copy
+      // of this controller had the identical defect: after every deploy, every connected client
+      // stayed dead until somebody reconnected by hand.
+      //
+      // An `initialize` carrying a stale id still gets a new session rather than a 404: a client
+      // that keeps sending the old id would otherwise loop. No SDK client does that — it skips
+      // `initialize` entirely once its transport has an id — but the case costs one check.
+      if (!this.isInitializeRequest(req.body)) {
+        res.status(404).json({ error: 'Unknown or expired MCP session' });
+        return;
+      }
     }
 
     if (!entry) {
@@ -216,6 +237,18 @@ export class CoreAiMcpController implements OnModuleDestroy {
     return null;
   }
 
+  /**
+   * Whether the body is an `initialize` — the one request that legitimately starts a session.
+   *
+   * A batch counts when any member is an initialize, matching how the SDK transport reads it.
+   */
+  protected isInitializeRequest(body: any): boolean {
+    if (Array.isArray(body)) {
+      return body.some((message: any) => message?.method === 'initialize');
+    }
+    return body?.method === 'initialize';
+  }
+
   /**
    * Whether the OAuth 2.1 layer is enabled via `ai.mcp.oauth`.
    */