@lenne.tech/nest-server 11.42.3 → 11.42.5

package/docs/REQUEST-LIFECYCLE.md

@@ -45,6 +45,7 @@ The `CoreModule` is a dynamic module that bootstraps the entire framework:
 | **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 |
+| **Body Parser Limits** | `bodyParser.json.limit` / `bodyParser.urlencoded.limit` (default 100 kB each, body-parser's own). Applied in place to the parsers NestJS registers, so they hold under `Test.createTestingModule()` too. Every 413 is answered with `#LTNS_0304` plus size and limit, and logged with the route and the config key — see [0d. Body parsers](#0d-body-parsers) |
 | **Unified CORS** | Single `cors` config propagates to GraphQL, REST, and BetterAuth layers |
 | **Dual Auth Modes** | IAM-Only (BetterAuth) or Legacy+IAM for migration periods |
 
@@ -326,6 +327,12 @@ The following diagram shows the exact order of execution from HTTP request to re
   |      - credentials: true when cookies enabled           |
   |      - Origins from appUrl/baseUrl/cors.allowedOrigins  |
   |      - Propagated to BetterAuth trustedOrigins          |
+  |                                                         |
+  |  0d. Body parsers: json + urlencoded  [always]          |
+  |      - Registered by NestJS in app.init(), limits from  |
+  |        bodyParser.*.limit (default 100 kB each)         |
+  |      - Over the limit: 413 #LTNS_0304 BEFORE auth and   |
+  |        routing, REST and GraphQL alike                  |
   +----------------------------+----------------------------+
                                |
   +----------------------------v----------------------------+
@@ -551,6 +558,27 @@ if (!isCorsDisabled(envConfig.cors)) {
 
 > **Security:** steps 2 and 4 grant the derived origin credentialed CORS. If the apex domain is not trusted (e.g. a third-party-hosted marketing site whose XSS surface you do not control), set `cors.deriveAppUrl: false` and list the frontend origin explicitly via `appUrl` or `cors.allowedOrigins`. The derivation never yields a bare TLD (`https://api.dev` stays unchanged) and never emits the opaque `null` origin. With `cors.deriveAppUrl: false`, a host-split localhost `baseUrl` falls back to the `http://localhost:3001` default.
 
+#### 0d. Body parsers
+
+NestJS registers two global body parsers on every Express application — `application/json` and `application/x-www-form-urlencoded` (`extended: true`) — inside `app.init()`, i.e. after everything `main.ts` registers and before the NestJS middleware chain. GraphQL has no parser of its own: Apollo reads the body the global JSON parser produced, so one limit governs REST and GraphQL.
+
+Both use body-parser's default limit of **100 kB** unless `bodyParser` says otherwise (since 11.42.4):
+
+```typescript
+// config.env.ts — documents carry HTML: allow 2 MB of JSON, keep form posts at the default
+bodyParser: { json: { limit: '2mb' } },
+```
+
+`CoreBodyParserInitializer` applies it during module init by replacing the handle of the global parser layers NestJS created — in place, because NestJS registers them before any init hook runs and a parser appended later would sit behind the routes. Running during module init is what makes the limit hold under `Test.createTestingModule()`, which never runs `main.ts`. A path-scoped parser (`server.use('/upload', json({ limit }))` in `main.ts`) runs before the global one and is left untouched — that remains the way to give one path a different limit.
+
+The parser runs **before authentication and routing**. Over the limit, the whole request is refused:
+
+```json
+{ "statusCode": 413, "message": "#LTNS_0304: Request body too large [137270 bytes, limit 102400 bytes]", "error": "Payload Too Large" }
+```
+
+and the server logs a warning with method, path (query string stripped) and the config key to raise. Other parser errors (malformed JSON → 400) pass through unchanged. The default is deliberately not raised for everybody: `JSON.parse` is synchronous, and a larger pre-auth limit is a larger pre-auth event-loop block for every route, including unauthenticated ones.
+
 ### NestJS Middleware Chain (CoreModule)
 
 NestJS middleware runs for every request after Express-level middleware. Registration happens in `CoreModule.configure()`:

package/docs/error-codes.md

@@ -262,6 +262,22 @@ All error codes follow the format: `#PREFIX_XXXX: Description`
 
 ---
 
+### LTNS_0304: requestBodyTooLarge
+
+**Message:** Request body too large
+
+**Description:** Answered with HTTP 413 when a JSON or URL-encoded request body exceeds the body parser's limit. The parser runs before authentication and routing, so the whole request is rejected. The message carries the size and the limit in brackets, e.g. `#LTNS_0304: Request body too large [137270 bytes, limit 102400 bytes]` (the size is missing when the client sent no `Content-Length`). The server logs a warning with the route and the config key.
+
+**Solution:** Send a smaller body (split the operation, or upload large content through the file endpoints). If payloads of this size are legitimate for the route, raise the limit via `bodyParser.json.limit` / `bodyParser.urlencoded.limit` in the server options.
+
+**Parameters:** none (the size details are part of the developer message, not of the translation)
+
+**Translations:**
+- DE: Die gesendeten Daten sind zu groß und wurden nicht verarbeitet.
+- EN: The submitted data is too large and was not processed.
+
+---
+
 ## Resource Errors (LTNS_0400-LTNS_0499)
 
 ### LTNS_0400: resourceNotFound

package/docs/security-overrides.md

@@ -11,15 +11,23 @@ A green `pnpm audit` inside the framework repo says nothing about your tree.
 
 ## What this concretely means for you
 
-The framework pulls in three transitive packages that its `@nestjs/*` dependencies used to
-**exact-pin** to a vulnerable version:
+The framework pulls in four transitive packages that its `@nestjs/*` dependencies exact-pin, or
+used to **exact-pin**, to a vulnerable version:
 
 | Package | Advisory | Why it cannot resolve forward on its own |
 |---------|----------|------------------------------------------|
 | `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** |
+| `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep`, which runs while the GraphQL schema is assembled. Covers `<=12.0.0`, patched `>=12.0.1` (added 2026-10-06) | `@nestjs/graphql` 13.4.5 — the version this framework declares, and the newest 13.x — declares `"@graphql-tools/utils": "12.0.0"`, an **exact pin**. Only `@nestjs/graphql` 14.x moves it, so **this entry is load-bearing**. `@apollo/server` reaches it too, through `@graphql-tools/schema` / `merge` — and in a lockfile that still holds schema 10.0.x (resolved before 2026-08-12), as **utils 11.x**: vulnerable too, with no 11.x fix, and outside the override key. Lift it with `pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge`; the current releases request utils `^12.0.3`, which needs Node >=22.15 |
 | `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.42.4:** `@graphql-tools/utils` joins `js-yaml` as load-bearing — no `@nestjs/graphql`
+13.x resolves past the exact pin. The 11.42.4 release also covers `proxy-addr` (GHSA-jqcg-44mw-7w3h,
+critical: IP spoofing through an IPv4-mapped IPv6 address in a trusted subnet — it is what
+`trustProxy` hands to Express). That one needs **no override**: `express` requests `^2.0.7` and the
+fix `2.0.8` is in range, but an existing lockfile keeps `2.0.7` until you refresh it:
+`pnpm update --depth Infinity proxy-addr`.
+
 **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
 own `package.json` pins an older `@nestjs/graphql` or `@nestjs/platform-express`. **`js-yaml` does
@@ -54,6 +62,14 @@ overrides:
   # Keep the target in LOCKSTEP with the multer version @lenne.tech/nest-server declares (2.4.0 since 11.41.4).
   # Inert on @nestjs/platform-express 11.2.6+, which pins 2.4.0 itself.
   'multer@>=2.0.0 <2.4.0': '2.4.0'
+
+  # @nestjs/graphql 13.4.5 exact-pins @graphql-tools/utils@12.0.0 — GHSA-7mx3-vvmw-hjmv (high, patched >=12.0.1).
+  # Target 12.0.1 rather than the newest 12.x: 12.0.2+ requires Node >=22.15 via @whatwg-node/promise-helpers@2.
+  # If your engines floor is already >=22.15, prefer the newest 12.x, so the caret requesters are not held back.
+  # Does NOT reach a utils 11.x pulled in by an older @graphql-tools/schema 10.0.x — refresh that one instead:
+  #   pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge   (current releases need Node >=22.15)
+  # Remove once @nestjs/graphql pins >=12.0.1 in the major you use.
+  '@graphql-tools/utils@>=12.0.0 <12.0.1': '12.0.1'
 ```
 
 ### Retired: `@hono/node-server` (removed 2026-08-22, nest-server 11.36.1)

package/migration-guides/11.42.3-to-11.42.4.md

@@ -0,0 +1,199 @@
+# Migration Guide: 11.42.3 → 11.42.4
+
+## Overview
+
+| Category             | Details                                                                                                          |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **New option**       | `bodyParser.json.limit` / `bodyParser.urlencoded.limit` — the request body limit, configurable for the first time (§1) |
+| **Improvement**      | A request over the body limit is answered with `#LTNS_0304` plus size and limit, and logged with the route (§2) |
+| **Security**         | `proxy-addr` 2.0.8 (critical) and `@graphql-tools/utils` 12.0.1 (high) — your project needs a lockfile refresh and one override (§3) |
+| **Bugfix**           | Without `betterAuth.secret` and with JWT secrets shorter than 32 characters, native Better-Auth endpoints rejected the session right after sign-in (§4) |
+| **Dependencies**     | `nodemailer` 10.0.14 (patch: address-parser and DKIM header fixes) — no action needed |
+| **Migration Effort** | Small — `pnpm update` plus one override in `pnpm-workspace.yaml` (§3). Projects that raise the body limit in `main.ts` can move it into the config (§1) |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm update --depth Infinity proxy-addr
+```
+
+Then add the `@graphql-tools/utils` override from §3 to `pnpm-workspace.yaml`, run `pnpm install`,
+refresh `source-map-js` (§3), check §3 for an older `@graphql-tools/utils` 11.x copy, which the
+override does not reach, and commit `pnpm-workspace.yaml` together with `pnpm-lock.yaml`.
+Vendor-mode projects pick up the core update and need the same two dependency steps. The body limit
+needs no configuration: unset, both parsers keep the 100 kB they had.
+
+## 1. The request body limit is configurable
+
+NestJS registers a JSON and a URL-encoded body parser on every application, and until now neither had
+a limit anybody chose: body-parser's default of **100 kB** applied, and nothing in the framework or the
+starter could change it. A request over it is refused in middleware — before authentication, before
+routing, GraphQL included — so a document that grew past 100 kB could no longer be saved, and every
+retry failed the same way.
+
+```typescript
+// config.env.ts — documents carry HTML: allow 2 MB of JSON, keep form posts at the default
+bodyParser: {
+  json: { limit: '2mb' },
+},
+```
+
+| Value                  | Meaning                                                              |
+| ---------------------- | -------------------------------------------------------------------- |
+| unset                  | 100 kB, exactly as before                                            |
+| `2097152`              | bytes                                                                |
+| `'500kb'`, `'2mb'`     | 1024-based size; units `b` / `kb` / `mb` / `gb`, case-insensitive    |
+| `0`, negative, `'lots'` | refused with an error log at boot; the parser keeps its limit       |
+
+The JSON and URL-encoded limits are separate on purpose: raising one does not raise the other.
+
+**Raise it only where the data model needs it, and only as far.** The parser runs before
+authentication, and `JSON.parse` blocks the event loop for the whole body — measured on a realistic
+document shape, about 0.5 ms for 100 kB, 16 ms for 1 MB and 55 ms for 2 MB per request. That is why
+the default stays at 100 kB.
+
+**If you raise the limit in `main.ts` today**, move it into the config:
+
+```typescript
+// main.ts — before: not applied in the e2e suite
+server.useBodyParser('json', { limit: '2mb' });
+
+// config.env.ts — after: applied in production AND under Test.createTestingModule()
+bodyParser: { json: { limit: '2mb' } },
+```
+
+**Starter-based projects:** `config.env.ts` builds `local` / `e2e` / `ci` from `localConfig()` and the
+deployed environments from `deployedConfig()`. Put the limit where BOTH see it — the starter ships a
+shared `PROJECT_BODY_PARSER` constant for this since its 11.42.4 update — or set
+`NSC__BODY_PARSER__JSON__LIMIT` in the environment. A value only in the deployed block leaves the e2e
+suite and `lt dev up` at 100 kB.
+
+The config is applied during module init, so it holds in every test that builds the app with
+`Test.createTestingModule(...).createNestApplication()` — which never runs `main.ts`, so a
+`useBodyParser()` call there never reached the e2e suite. Once configured, the value also replaces a
+global parser your `main.ts` registered; keeping both is harmless, but the config wins.
+
+A **path-scoped** parser is left alone: `server.use('/upload', json({ limit: '20mb' }))` in `main.ts`
+still gives that one path its own limit. The parser runs before routing, so a per-route limit can only
+key on the path — and all GraphQL operations share one.
+
+**`rawBody: true`:** `req.rawBody` is kept for apps created with `NestFactory.create(…, { rawBody:
+true })`. Under `Test.createTestingModule()` the options passed to `createNestApplication()` are not
+visible to providers, so a test app created with `{ rawBody: true }` gets no `req.rawBody` once a limit
+is configured.
+
+## 2. An oversized request says what happened
+
+Before, the caller received:
+
+```json
+{ "statusCode": 413, "message": "request entity too large" }
+```
+
+and the server logged the same text as an error with a stack trace. Now, configured or not:
+
+```json
+{ "statusCode": 413, "message": "#LTNS_0304: Request body too large [137270 bytes, limit 102400 bytes]", "error": "Payload Too Large" }
+```
+
+The size is present when the client sent a `Content-Length`. Frontends using the error translation of
+`@lenne.tech/nuxt-extensions` show the translated `LTNS_0304` text. The server logs one warning per
+refused request, with method, path (without query string) and the config key to raise:
+
+```
+413 PATCH /offers/6650…: json body of 137270 bytes exceeds the limit of 102400 bytes. If payloads of this size are legitimate here, raise `bodyParser.json.limit` in the server options.
+```
+
+The status code is unchanged. Only clients that compare the message text against
+`'request entity too large'` need adjusting — branch on the status or on `LTNS_0304` instead.
+
+## 3. Dependency advisories your project must fix itself
+
+`pnpm` overrides apply only to the project that runs the install, so the framework's own fixes do not
+reach your tree — see [docs/security-overrides.md](../docs/security-overrides.md).
+
+| Package | Advisory | What your project needs |
+| ------- | -------- | ----------------------- |
+| `proxy-addr` | [GHSA-jqcg-44mw-7w3h](https://github.com/advisories/GHSA-jqcg-44mw-7w3h) — **critical**: IP spoofing through an IPv4-mapped IPv6 address in a trusted subnet. Patched `>=2.0.8` | A lockfile refresh. `express` requests `^2.0.7`, so `2.0.8` is in range, but an existing lockfile stays on `2.0.7` |
+| `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep` (schema assembly). Covers `<=12.0.0` — **11.x included, with no 11.x fix**. Patched `>=12.0.1` | An override for the copy `@nestjs/graphql` 13.4.5 exact-pins (`12.0.0`), and — in an older lockfile — a refresh of `@graphql-tools/schema` / `merge`, which can still pull in 11.x (see below) |
+| `source-map-js` | [GHSA-68fv-2mgg-jv7q](https://github.com/advisories/GHSA-68fv-2mgg-jv7q) — high: event-loop DoS through indexed source-map section offsets. Patched `>=1.2.2`. **Dev tooling only** (vitest > vite > postcss), but `pnpm audit` — and therefore `check` — reports it | A lockfile refresh: `pnpm update --depth Infinity source-map-js`. If `postcss` keeps a `1.2.1` copy, re-resolve it the same way rather than with `pnpm dedupe`, which moves unrelated peers too |
+
+`proxy-addr` is what Express uses to compute `request.ip` from `X-Forwarded-For` as far as
+`trustProxy` allows. With `trustProxy` set, every IP-keyed rate limit — the framework's own and any of
+yours — depends on it.
+
+```bash
+pnpm update --depth Infinity proxy-addr
+```
+
+```yaml
+# pnpm-workspace.yaml
+overrides:
+  # @nestjs/graphql 13.4.5 exact-pins @graphql-tools/utils@12.0.0 — GHSA-7mx3-vvmw-hjmv (high, patched >=12.0.1).
+  # 12.0.2+ requires Node >=22.15; take the newest 12.x instead if your engines floor allows it.
+  '@graphql-tools/utils@>=12.0.0 <12.0.1': '12.0.1'
+```
+
+**Check for a second, older copy.** `@apollo/server` 5.x requests `@graphql-tools/schema` `^10.0.0`. A
+lockfile resolved before schema 10.1.0 (published 2026-08-12) holds a 10.0.x, which requests utils
+`^11.1.0` — vulnerable, outside the override key above, and with no fix in the 11.x line. Look for it:
+
+```bash
+grep -n "'@graphql-tools/utils@11" pnpm-lock.yaml
+```
+
+If it is there, lift the requesters into their current lines, which ask for utils 12:
+
+```bash
+pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge
+```
+
+The current releases (schema 10.1.3, merge 9.2.6) request utils `^12.0.3`, which depends on
+`@whatwg-node/promise-helpers` 2 and therefore needs **Node >=22.15**. Current Node 22 LTS images
+(22.22) and Node 24 satisfy that; if your `engines.node` still declares a lower floor, raise it — the
+override above cannot hold this copy back, because `^12.0.3` does not intersect its key.
+
+Then `pnpm install` and `pnpm audit` — the advisories must be gone.
+
+**Commit `pnpm-workspace.yaml` and `pnpm-lock.yaml` together.** Every step above leaves a consistent
+lockfile once it has run to the end, but the override only reaches the lockfile through the
+`pnpm install` that follows it. A `pnpm-workspace.yaml` committed with the override and without the
+re-installed lockfile fails every `pnpm install --frozen-lockfile` — typically the Docker image build.
+Check with `pnpm install --frozen-lockfile` locally before you push.
+
+## 4. Native Better-Auth endpoints accept the session when the secret is auto-generated
+
+**Affects only** projects that configure no `betterAuth.secret` and whose fallback secrets
+(`jwt.secret`, `jwt.refresh.secret`) are shorter than 32 characters — typically a local `.env`.
+Better-Auth then generates a secret at startup and signs with it, while the NestJS layer (cookie
+helper, API middleware, `CoreBetterAuthService`) still signed with the configured value or none. The
+session cookie went out unsigned, so every endpoint Better-Auth serves itself and that reads the
+cookie — `/iam/token`, the MCP `/iam/mcp/authorize`, passkey, 2FA — answered **401 right after a
+successful sign-in**, and an MCP OAuth login looped back to the login page.
+
+Since 11.42.4 the NestJS layer signs with exactly the secret Better-Auth uses. No action is needed.
+It is still the wrong setup for anything but local development: a generated secret changes on every
+restart and differs per replica, so sessions do not survive either — set `betterAuth.secret` (at
+least 32 characters), as the boot warning says.
+
+## Troubleshooting
+
+| Symptom                                                          | Cause                                                        | Fix                                                        |
+| ---------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
+| `413 … exceeds the limit` warnings for a route that should accept it | The 100 kB default is too small for that data              | Set `bodyParser.json.limit` (§1)                           |
+| `bodyParser.json.limit … is not a positive size` at boot         | A typo or unit the parser does not know (`'2 megabytes'`)    | Use bytes or `'2mb'`                                       |
+| `no global json body parser is registered` at boot               | The app was created with `bodyParser: false`                 | Remove the option, or register your own parser             |
+| A webhook test loses `req.rawBody` after configuring a limit     | Test app created via the testing module with `rawBody: true` | See the `rawBody` note in §1                               |
+| A path still answers a bare `request entity too large`           | A path-scoped parser of your own refused it                  | Raise that parser's limit in `main.ts`                     |
+| `pnpm audit` still reports `@graphql-tools/utils` 12.0.0          | The override is missing, or its key was copied without the range | Add the entry from §3 verbatim                              |
+| `pnpm audit` still reports `@graphql-tools/utils` 11.x            | An older `@graphql-tools/schema` 10.0.x requests `^11.1.0`, outside the override key | `pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge` (§3) — needs Node >=22.15 |
+| `pnpm audit` still reports `proxy-addr` 2.0.7                     | The lockfile was not refreshed                              | `pnpm update --depth Infinity proxy-addr` (§3)              |
+| `/iam/token` or MCP authorize answers 401 right after sign-in   | 11.42.3 or older without `betterAuth.secret` and with short JWT secrets | Update to 11.42.4 (§4); for anything beyond local development set `betterAuth.secret` |
+
+## Module Documentation
+
+- [Request lifecycle — 0d. Body parsers](../docs/REQUEST-LIFECYCLE.md#0d-body-parsers)
+- [Error codes — LTNS_0304](../docs/error-codes.md#ltns_0304-requestbodytoolarge)
+- [Security overrides — why yours are not inherited](../docs/security-overrides.md)
+- [Better-Auth README](../src/core/modules/better-auth/README.md) — secret resolution and fallback chain

package/migration-guides/11.42.4-to-11.42.5.md

@@ -0,0 +1,104 @@
+# Migration Guide: 11.42.4 → 11.42.5
+
+## Overview
+
+| Category             | Details                                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **New feature**      | `TestHelper.mcpSession()` / `TestHelper.mcp()` — MCP tests without hand-written SSE parsing (§1)            |
+| **Tooling**          | `check:overrides` accepts a declared "fix exists, but this consumer cannot use it" suppression that expires by itself (§2) |
+| **Docs**             | The 11.42.3 → 11.42.4 guide gained three steps; check them if you already applied it (§3)                   |
+| **Breaking Changes** | None                                                                                                        |
+| **Migration Effort** | None required — `pnpm update`. Adopting the helpers is optional                                             |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick up the core update; the new helpers arrive with `src/test/`. No configuration
+change is required.
+
+## 1. TestHelper: MCP tests without SSE parsing
+
+Projects that enable the AI module's MCP server (`ai.mcp` in `config.env.ts`) should test their tools over
+MCP as well as over REST/GraphQL: MCP has its own role filter and sessions, and a refused tool comes back as
+a result with `isError: true`, not as an HTTP error. Until now such a test had to set the right `Accept`
+header, carry the `mcp-session-id` header, and parse the SSE stream by hand. `TestHelper` now does that:
+
+```typescript
+const session = await testHelper.mcpSession({ token: userToken });
+
+expect((await session.listTools()).map((tool) => tool.name)).not.toContain('delete_user');
+
+const refused = await session.callTool('delete_user', { id });
+expect(refused.isError).toBe(true);
+
+const result = await session.callTool('find_users', { query: '@test.com' });
+expect(result.json.data.length).toBeGreaterThan(0);
+
+await session.close();
+```
+
+`testHelper.mcp(message, { statusCode, sessionId, token })` sends a single JSON-RPC message for the
+HTTP-level cases (401 without a token, 404 for another user's session). Full reference: `src/test/README.md`
+→ "MCP Testing".
+
+The helpers are additive and build on `testHelper.rest()`, so `token` and `cookies` behave as there. They add
+no dependency, so vendor-mode projects receive them with `src/test/`. A project with its own MCP module (not
+the AI module's `/ai/mcp`) passes its endpoint as `path`.
+
+## 2. `check:overrides`: a suppression for a fix the consumer cannot use
+
+`auditConfig.ignoreGhsas` used to be usable only for advisories with no fix at all — the moment any fix
+appeared, `check:overrides` failed with `FIX AVAILABLE`. That is right in the common case and a dead end in
+one: the fix exists, but the package that pulls in the vulnerable version cannot use it (for example, a
+patched major removed an export the consumer imports).
+
+That case can now be declared next to the suppression:
+
+```yaml
+auditConfig:
+  ignoreGhsas:
+    - GHSA-x6jw-m9v5-85vh
+  unusableFixConsumers:
+    GHSA-x6jw-m9v5-85vh: '@nuxt/devtools@3.4.1 cannot use 4.0.1'
+```
+
+The declaration expires by itself: `check:overrides` fails with `RE-TEST` as soon as the consumer leaves the
+tree or changes version, the advisory offers a patched version nobody assessed (a backport), or anything other
+than exactly that consumer version pulls the vulnerable package — including a direct dependency of your own
+project. An undeclared suppression of a fixed advisory still fails on sight.
+
+This is a change to the guard script, not to the published runtime: projects created from
+nest-server-starter or lt-monorepo receive it with their template update. Exhaust the remedies first (raise
+the vulnerable package, raise or patch the consumer); the rules and the reasoning are in
+`.claude/rules/package-management.md` → "When the fix exists and the consumer cannot use it".
+
+## 3. Three steps added to the 11.42.3 → 11.42.4 guide
+
+If you already applied [11.42.3 → 11.42.4](./11.42.3-to-11.42.4.md), check these — they were added after its
+release:
+
+1. **`source-map-js` < 1.2.2** ([GHSA-68fv-2mgg-jv7q](https://github.com/advisories/GHSA-68fv-2mgg-jv7q),
+   high, dev tooling only) is also reported by `pnpm audit`: `pnpm update --depth Infinity source-map-js`.
+2. **Commit `pnpm-workspace.yaml` and `pnpm-lock.yaml` together.** An override only reaches the lockfile through
+   the `pnpm install` that follows it; a workspace file committed without the re-installed lockfile fails every
+   `pnpm install --frozen-lockfile`, typically the Docker image build.
+3. **Starter-based projects:** set `bodyParser` where both `localConfig()` and `deployedConfig()` see it (the
+   starter ships a shared `PROJECT_BODY_PARSER` constant), or via `NSC__BODY_PARSER__JSON__LIMIT`. A value only
+   in the deployed block leaves the e2e suite and `lt dev up` at 100 kB.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| `check:overrides` fails with `RE-TEST` on a declared suppression | The consumer moved, a new patched version appeared, or another package (or your project directly) now pulls the vulnerable package | Re-assess: take the fix if it is now usable, otherwise update the declaration with what you re-checked (§2) |
+| `check:overrides` fails with `FIX AVAILABLE` | A suppressed advisory gained a fix, and no declaration explains why it cannot be used | Take the fix; declare only after the remedies are exhausted (§2) |
+| `session.callTool()` throws instead of returning `isError` | The JSON-RPC call itself failed (protocol error), not the tool | Assert on `session.request(...)` for protocol-level errors (§1) |
+
+## Module Documentation
+
+- [TestHelper README — MCP Testing](../src/test/README.md)
+- [AI module README](../src/core/modules/ai/README.md)
+- `.claude/rules/package-management.md` — suppressions, overrides and the `check:overrides` guard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.3",
+  "version": "11.42.5",
   "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",
@@ -129,7 +129,7 @@
     "mongoose": "9.10.4",
     "multer": "2.4.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "10.0.13",
+    "nodemailer": "10.0.14",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -214,7 +214,7 @@
     "oxfmt": "0.71.0",
     "oxlint": "1.86.0",
     "rimraf": "6.1.3",
-    "smtp-server": "3.19.16",
+    "smtp-server": "3.19.17",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
     "tsx": "4.23.15",

package/src/core/common/interfaces/server-options.interface.ts

@@ -1051,6 +1051,53 @@ export interface IBetterAuthUserField {
   type: BetterAuthFieldType;
 }
 
+/**
+ * Size limits for the two body parsers NestJS registers globally (`application/json` and
+ * `application/x-www-form-urlencoded`).
+ *
+ * @see IServerOptions.bodyParser
+ * @since 11.42.4
+ */
+export interface IBodyParserConfig {
+  /**
+   * Limit for `application/json` bodies — REST and GraphQL alike, since Apollo reads the body the
+   * global parser produced.
+   *
+   * A number is bytes; a string is a size such as `'500kb'` or `'2mb'` (1024-based, units
+   * `b` / `kb` / `mb` / `gb`, case-insensitive).
+   *
+   * @default '100kb' (body-parser's own default — unset leaves the parser untouched)
+   */
+  json?: IBodyParserTypeConfig;
+
+  /**
+   * Limit for `application/x-www-form-urlencoded` bodies. Same value format as `json`.
+   *
+   * Configured separately on purpose: form posts rarely need more, and raising one limit should not
+   * silently raise the other.
+   *
+   * @default '100kb' (body-parser's own default — unset leaves the parser untouched)
+   */
+  urlencoded?: IBodyParserTypeConfig;
+}
+
+/**
+ * Settings for one body parser.
+ *
+ * @see IBodyParserConfig
+ * @since 11.42.4
+ */
+export interface IBodyParserTypeConfig {
+  /**
+   * Maximum body size: bytes as a number, or a size string such as `'2mb'`.
+   *
+   * A value that is not a positive size (`0`, negative, `NaN`, `'lots'`) is REJECTED with an error
+   * log and the parser keeps its default — it never becomes "no limit". The parser runs before
+   * authentication, so an unbounded limit would be an unbounded pre-auth allocation.
+   */
+  limit?: number | string;
+}
+
 /**
  * Interface for Error Code module configuration
  *
@@ -2264,6 +2311,48 @@ export interface IServerOptions {
    */
   betterAuth?: boolean | IBetterAuth;
 
+  /**
+   * Size limits for request bodies.
+   *
+   * NestJS registers a JSON and a URL-encoded body parser on every application, and neither has a
+   * limit anybody chose: body-parser's default of **100 kB** applies. A request over it is answered
+   * with 413 in middleware — before authentication, before routing — so the whole request fails,
+   * every retry fails identically, and a document that grew past the limit can no longer be saved.
+   *
+   * Unset, both parsers stay exactly as NestJS registered them. Set a limit only where the data
+   * model needs it, and keep it as small as that need allows: the parser runs before
+   * authentication, and `JSON.parse` blocks the event loop for the whole body — measured on a
+   * realistic document shape, about 0.5 ms for 100 kB, 16 ms for 1 MB and 55 ms for 2 MB per
+   * request. That is why the default is not raised for everybody.
+   *
+   * Applied by `CoreModule` during module init, which replaces the global parsers NestJS registered
+   * IN PLACE — same position in the middleware chain, same options otherwise (`extended: true` for
+   * URL-encoded bodies, `req.rawBody` when the app was created with `NestFactory.create(…, {
+   * rawBody: true })`). Because this happens in `app.init()`, it holds under
+   * `Test.createTestingModule(...).createNestApplication()` too, which never runs `main.ts` — a
+   * `useBodyParser()` call in `main.ts` does not reach the e2e suite, this does. A configured value
+   * also replaces a global parser registered in `main.ts`; a path-scoped one
+   * (`server.use('/upload', json({ limit }))`) is left alone, and stays the way to give ONE path a
+   * different limit, since the parser runs before routing and GraphQL shares a single path anyway.
+   *
+   * One caveat: under the testing module the options passed to `createNestApplication()` are not
+   * visible to providers, so a test app created with `{ rawBody: true }` gets no `req.rawBody` from
+   * a CONFIGURED parser. Applications created with `NestFactory.create()` are not affected.
+   *
+   * Independent of this setting, a 413 from either parser is answered with
+   * `#LTNS_0304: Request body too large [<size>, limit <limit>]` instead of a bare
+   * "request entity too large", and logged as a warning naming the route and the config key.
+   *
+   * @since 11.42.4
+   *
+   * @example
+   * ```typescript
+   * // Documents carry HTML: allow 2 MB of JSON, keep form posts at the default
+   * bodyParser: { json: { limit: '2mb' } },
+   * ```
+   */
+  bodyParser?: IBodyParserConfig;
+
   /**
    * Configuration for Brevo
    * See: https://developers.brevo.com/