@lenne.tech/nest-server 11.42.5 → 11.42.7

package/docs/REQUEST-LIFECYCLE.md

@@ -569,7 +569,7 @@ Both use body-parser's default limit of **100 kB** unless `bodyParser` says othe
 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.
+`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. Keep `server.useBodyParser('json')` (or `'urlencoded'`) in `main.ts` next to it: NestJS registers its global parser only when no layer with the same function name exists, so a path-scoped one registered before `app.init()` suppresses it, and every other path receives an empty body. Since 11.42.6 `CoreBodyParserInitializer` warns at boot in that case.
 
 The parser runs **before authentication and routing**. Over the limit, the whole request is refused:
 

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

@@ -63,6 +63,14 @@ server.useBodyParser('json', { limit: '2mb' });
 bodyParser: { json: { limit: '2mb' } },
 ```
 
+**Exception: keep `useBodyParser()` when `main.ts` also registers a path-scoped parser** such as
+`server.use('/upload', json({ limit: '20mb' }))`. NestJS registers its own global parser only if no
+layer with the same function name exists yet, and a path-scoped `json()` registered before
+`app.init()` counts as one. Removing `useBodyParser()` then leaves the app without a global JSON
+parser: every request outside that path reaches its handler with an empty body, and a sign-in fails
+with a validation error. Keep `server.useBodyParser('json')` (the configured limit is applied to it)
+and set the limit in the config as above. Since 11.42.6 the server warns at boot when it finds this.
+
 **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
@@ -75,7 +83,8 @@ The config is applied during module init, so it holds in every test that builds
 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
+still gives that one path its own limit, as long as the global parser stays registered next to it
+(see the exception above). 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:

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

@@ -0,0 +1,113 @@
+# Migration Guide: 11.42.5 → 11.42.6
+
+## Overview
+
+| Category             | Details                                                                                                      |
+| -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **Correction**       | The 11.42.3 → 11.42.4 guide told every project to drop `useBodyParser()` from `main.ts`. With a path-scoped parser in `main.ts` that removes JSON parsing everywhere else (§1) |
+| **Improvement**      | The server warns at boot when NestJS skipped its global body parser because of such a path-scoped one (§1)   |
+| **Tooling**          | `check:overrides` no longer reports a failed audit as clean, and its probe follows `pnpm_config_registry` (§2) |
+| **Breaking Changes** | None                                                                                                         |
+| **Migration Effort** | None for most projects. Projects that removed `useBodyParser()` while registering a path-scoped parser in `main.ts` must add it back (§1) |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run update   # starter-based projects: raises every exact pin you share with the framework
+```
+
+Then check `main.ts` as described in §1. Vendor-mode projects pick up the core update and need the
+same check.
+
+**Exact pins below the framework's own split packages in two.** A project that pins `@nestjs/core`,
+`@nestjs/common`, `mongoose` or another package the framework also declares, at a LOWER exact version,
+gets two copies of it. The install only prints a peer warning. The failure appears in the tests, as a
+dependency-injection error that does not look like a version problem (see Troubleshooting).
+`pnpm run update` (`extras/sync-packages.mjs` in starter-based projects) raises those pins. Without
+that script, list the deviations and raise each one:
+
+```bash
+node -e "const f=require('@lenne.tech/nest-server/package.json'),p=require('./package.json');const want={...f.dependencies,...f.peerDependencies};for(const s of ['dependencies','devDependencies'])for(const[k,v]of Object.entries(p[s]||{}))if(want[k]&&/^\d/.test(want[k])&&want[k]!==v)console.log(s,k,v,'->',want[k])"
+```
+
+An `overrides:` entry in `pnpm-workspace.yaml` must not pin such a package below the framework's
+version either: it forces the framework onto the older version without anybody having tested it.
+
+## 1. Keep `useBodyParser()` next to a path-scoped parser
+
+§1 of the [11.42.3 → 11.42.4 guide](./11.42.3-to-11.42.4.md) recommended moving the body limit from
+`main.ts` into `bodyParser.json.limit` and deleting the `useBodyParser()` call. That is right, with one
+exception the guide did not name.
+
+NestJS registers its own global JSON and URL-encoded parsers inside `app.init()`, but only when no
+layer with the same function name exists yet. It compares the NAME and nothing else. A path-scoped
+parser registered in `main.ts` before `listen()` carries that name:
+
+```typescript
+// main.ts
+server.use('/diagnostics', json({ limit: '256kb' })); // a layer named `jsonParser`
+```
+
+With `useBodyParser()` removed, NestJS treats the JSON parser as already applied and registers none.
+Every request outside `/diagnostics` then reaches its handler with an empty body. A sign-in fails with
+a validation error such as "Missing input", and before this release nothing was logged.
+
+**Check `main.ts`.** If it registers `json(...)` or `urlencoded(...)` on a path, keep or restore the
+global parser next to it:
+
+```typescript
+// main.ts
+server.use('/diagnostics', json({ limit: '256kb' }));
+server.useBodyParser('json'); // the configured bodyParser.json.limit is applied to it
+```
+
+Keep the limit itself in the config (`bodyParser.json.limit`), where it also holds under
+`Test.createTestingModule()`. The e2e suite cannot catch the missing parser: the testing module never
+runs `main.ts`, so it never registers the path-scoped parser either.
+
+Since 11.42.6 the server logs a warning at boot in exactly this situation:
+
+```
+No global json body parser is registered: NestJS skips its own when a layer named `jsonParser`
+already exists, and a path-scoped `json()` parser registered before `app.init()` counts as one. …
+```
+
+The framework only reports it. It does not register the missing parser itself: NestJS would have put
+it after everything `main.ts` registered, and that position is no longer known during module init. A
+raw-body webhook or a proxy registered after the path-scoped parser must keep receiving the unread
+request stream.
+
+## 2. `check:overrides`: a failed audit is no longer reported as clean
+
+Two fixes in `scripts/check-overrides.mjs` (and the shared registry block in `scripts/check.mjs`):
+
+- When pnpm 11 cannot reach the registry, `pnpm audit --json` prints
+  `{"error": {"message": "fetch failed"}}` instead of a report. The guard read that as "0 advisories"
+  and printed `ok — N override(s) checked … none is failing`. It now prints
+  `could not obtain an audit report` (exit 0) on a live run, and fails (exit 1) when the failed report
+  was passed in with `--audit-file`, which is the CI path. The suppression checks still run in that
+  case, because they ask the GitHub Advisory API rather than the audit: a suppressed advisory that
+  gained a fix still fails with `FIX AVAILABLE`.
+- The clean-tree probe reads `pnpm_config_registry`, the variable pnpm 11 audits against. It used to
+  read `npm_config_registry`, which pnpm 11 ignores, and could then ask a registry the audit never used.
+
+`scripts/` is not part of the npm package. Projects created from nest-server-starter or lt-monorepo
+receive these fixes with their template update.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| Boot warning "No global json body parser is registered" | `main.ts` registers a path-scoped `json()` and no global parser | Add `server.useBodyParser('json')` to `main.ts` (§1) |
+| Requests arrive with an empty body outside one path; sign-in reports "Missing input" | Same cause, on a version before 11.42.6 | Same fix (§1) |
+| Tests fail with `Nest can't resolve dependencies of the MongooseCoreModule (MongooseConnectionName, ?)` (often hidden behind `Cannot read properties of undefined` from a `beforeAll` that swallows it) | Two copies of `@nestjs/core`: the project pins it below the framework's version | Raise the exact pins (Quick Migration), then check that `pnpm-lock.yaml` holds one copy of each |
+| `check:overrides` prints `could not obtain an audit report (fetch failed)` | The npm registry was not reachable during the audit | Re-run with network access, or pass a captured report with `--audit-file` |
+| `check:overrides` fails with `records a failed audit, not a result` | The report passed with `--audit-file` is a pnpm error, not an audit | Capture the report again once the registry answers |
+
+## Module Documentation
+
+- [REQUEST-LIFECYCLE.md — 0d. Body parsers](../docs/REQUEST-LIFECYCLE.md)
+- [11.42.3 → 11.42.4 guide §1](./11.42.3-to-11.42.4.md)
+- `.claude/rules/configurable-features.md` — Body Parser Limits row
+- `.claude/rules/package-management.md` — the `check:overrides` guard

package/migration-guides/11.42.6-to-11.42.7.md

@@ -0,0 +1,115 @@
+# Migration Guide: 11.42.6 → 11.42.7
+
+## Overview
+
+| Category             | Details                                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **New Feature**      | `setupSwagger()` — a Swagger document that says how each route is reached: security, API-token scopes, tenant header (§1) |
+| **New Feature**      | Optional second document with only the routes an API token may call (§2)                                        |
+| **Dependencies**     | `nodemailer` 10.0.15, `@modelcontextprotocol/sdk` 1.32.1, dev: `oxlint` 1.87.0 (§3)                             |
+| **Breaking Changes** | None                                                                                                            |
+| **Migration Effort** | Optional. Switching `main.ts` to the helper replaces the hand-built `DocumentBuilder` block with one call        |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Nothing changes until `main.ts` calls the new helper. Vendor-mode projects pick it up with the core
+update.
+
+## 1. `setupSwagger()` instead of a hand-built `DocumentBuilder`
+
+The starters built the document like this:
+
+```typescript
+const config = new DocumentBuilder().setTitle('…').addBearerAuth().build();
+SwaggerModule.setup('swagger', server, () => SwaggerModule.createDocument(server, config, { … }), {
+  jsonDocumentUrl: '/api-docs-json',
+});
+```
+
+`addBearerAuth()` registers a scheme but attaches it to no route. A token entered under "Authorize" is
+therefore sent with almost no request: in one project 10 of 158 operations carried a security entry.
+And what a caller needs to know — is the route public, which API-token scope does it release, does it
+read the tenant header — lived only in decorators.
+
+```typescript
+import { setupSwagger } from '@lenne.tech/nest-server';
+
+setupSwagger(server, {
+  description: 'API of my project',
+  documentOptions: {
+    extraModels: [CoreUserModel, CoreAuthModel, User, PersistenceModel, CorePersistenceModel, FilterArgs],
+  },
+  title: 'My Project API',
+  version: packageJson.version,
+});
+```
+
+Paths stay as before (`/swagger`, `/api-docs-json`) unless `path` / `jsonDocumentUrl` say otherwise.
+What the document now contains, read from the same metadata the guards read:
+
+| Feature in the config | In the document |
+| --- | --- |
+| always | `bearer` as a global security requirement — "Authorize" applies to every route. Public routes (no `@Roles`, or `S_EVERYONE`) carry `security: []` |
+| `betterAuth` + `cookies` on | the session cookie (`iam.session_token`, or the name `COOKIE_PREFIX` / `basePath` produce) as a second, alternative requirement |
+| `apiTokens` on | per operation `x-api-token-scopes` and a description line: "allowed with scope `read`" or "not allowed on this route". `@ApiTokenScopes()` on the method replaces the class declaration, exactly as in `assertApiTokenScopes()` |
+| `multiTenancy` on | a reusable `TenantHeader` parameter (`X-Tenant-Id`, or `multiTenancy.headerName`) on every operation except public ones and `@SkipTenantCheck()`; its description says which callers need it (sessions and personal tokens) and which may omit it (company tokens) |
+
+Optional:
+
+- `operationTags: (operation) => string[] | undefined` regroups operations by use case instead of by
+  controller; `tags: [{ name, description }]` orders and describes them.
+- `configureBuilder: (builder) => builder` adds servers, contact or further schemes.
+- `customOptions` is passed to `SwaggerModule.setup()` for both documents.
+
+Each operation is mapped to its handler through the default operation id (`<Controller>_<method>`, with
+`[<n>]` for a handler serving several paths). An own `operationIdFactory` is therefore refused. Two different controller classes with the same name
+cannot be told apart; their operations are left as Swagger built them, with a warning.
+
+## 2. A document for API-token callers
+
+```typescript
+setupSwagger(server, { …, apiTokenView: true });
+// or: apiTokenView: { path: 'swagger-partner', title: 'Partner API' }
+```
+
+Serves a second document (default: UI `swagger-api-tokens`, JSON `/api-docs-api-tokens-json`) with only
+the operations that release a scope, the bearer scheme as the only requirement and without the schemas
+nothing refers to any more. Keep its path outside the path of the full UI, which serves its assets below
+its own path.
+
+The tenant header stays in this view while personal (user) tokens are enabled (`apiTokens.userTokens`,
+the default): such a token without a company restriction chooses the company like a session does, and
+without the header it is checked against its global roles and refused on company routes. With company
+tokens only (`userTokens: false`) the header is dropped — a company token carries its company.
+
+## 3. Dependency updates
+
+Patch-level maintenance, no code changes required:
+
+| Package | Old | New | Section |
+| --- | --- | --- | --- |
+| `nodemailer` | 10.0.14 | 10.0.15 | dependencies |
+| `@modelcontextprotocol/sdk` | 1.32.0 | 1.32.1 | dependencies |
+| `oxlint` | 1.86.0 | 1.87.0 | devDependencies |
+
+A project that pins `oxlint` itself should raise it to 1.87.0 alongside the framework —
+`pnpm run update` in starter-based projects does this. A project that carries a `nodemailer`
+override matching the framework's version (the starter does) should raise it to `10.0.15`.
+
+## Compatibility Notes
+
+- The helper is additive. `DocumentBuilder` + `SwaggerModule.setup()` keep working unchanged.
+- The document is built on the first request, as before.
+- `buildSwaggerDocument()` and `buildApiTokenSwaggerDocument()` are exported for tests: a project can
+  assert in its e2e suite that a route documents the scope it enforces.
+
+## References
+
+- Helper: `src/core/common/helpers/swagger.helper.ts`
+- Options: `src/core/common/interfaces/swagger-setup-options.interface.ts`
+- Tests: `tests/unit/swagger-helper.spec.ts`
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) `src/main.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.5",
+  "version": "11.42.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",
@@ -92,7 +92,7 @@
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.0.3",
-    "@modelcontextprotocol/sdk": "1.32.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@nestjs/apollo": "13.4.5",
     "@nestjs/common": "11.2.7",
     "@nestjs/core": "11.2.7",
@@ -129,7 +129,7 @@
     "mongoose": "9.10.4",
     "multer": "2.4.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "10.0.14",
+    "nodemailer": "10.0.15",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -212,7 +212,7 @@
     "npm-watch": "0.13.0",
     "otpauth": "9.5.2",
     "oxfmt": "0.71.0",
-    "oxlint": "1.86.0",
+    "oxlint": "1.87.0",
     "rimraf": "6.1.3",
     "smtp-server": "3.19.17",
     "ts-node": "10.9.2",