@lenne.tech/nest-server 11.42.6 → 11.42.8

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

@@ -14,11 +14,26 @@
 
 ```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
@@ -86,6 +101,7 @@ receive these fixes with their template update.
 | ------- | ----- | --- |
 | 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 |
 

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/migration-guides/11.42.7-to-11.42.8.md

@@ -0,0 +1,74 @@
+# Migration Guide: 11.42.7 → 11.42.8
+
+## Overview
+
+| Category             | Details                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Bugfix**           | `setupSwagger()` enriches every operation an `@All()` route produces, including `SEARCH` (§1)        |
+| **Bugfix**           | The Better-Auth pass-through route no longer appears as `/iam/{path}` in the Swagger document (§2)   |
+| **Dependencies**     | dev: `vite` 8.3.3; override `js-yaml` 5.4.3 (§3)                                                     |
+| **Breaking Changes** | None                                                                                                 |
+| **Migration Effort** | None for most projects. Regenerate a client built from `/api-docs-json` if you keep one (§2)         |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update.
+
+## 1. `SEARCH` operations of `@All()` routes are enriched
+
+For an `@All()` route, `@nestjs/swagger` documents one operation per HTTP method — including
+`SEARCH`, which no OpenAPI version lists as a path-item method. 11.42.7 walked a fixed list of
+methods and skipped it, so that one operation stayed as Swagger built it: no API-token scope line,
+no `security: []` on a public route, no tenant header, and `operationTags` did not reach it — it
+landed in its own tag group next to the regrouped siblings.
+
+The helper now reads the operations from the path item itself, so `SEARCH` (and any other method
+`@nestjs/swagger` emits) is treated like every other operation — in the full document and in the
+API-token view.
+
+Nothing to change in your code. If you assert on the document in tests, a `search` operation of an
+`@All()` route now carries the same `x-api-token-scopes`, description line and tags as its siblings.
+
+## 2. `/iam/{path}` is gone from the document
+
+`CoreBetterAuthController.handlePluginRoutes` (`@All('*path')`) forwards every other `/iam/*` request
+to Better-Auth's own handler. It appeared in Swagger as eight `/iam/{path}` operations without
+parameters or description. It is now `@ApiExcludeEndpoint()`; the route itself is unchanged.
+
+- **Generated clients:** a client generated from `/api-docs-json` (hey-api, openapi-generator, …)
+  loses its `coreBetterAuthControllerHandlePluginRoutes*` functions on the next generation. They
+  could not express any real Better-Auth call, so nothing should depend on them — but regenerate and
+  let the compiler confirm it.
+- **Own controller:** a project controller that **overrides** `handlePluginRoutes` (re-declaring
+  `@All('*path')`) must also re-declare `@ApiExcludeEndpoint()` to keep it out of the document.
+  Decorator metadata belongs to the method, so an override starts without it. A controller that
+  only inherits the method is covered automatically.
+
+## 3. Dependency updates
+
+Maintenance only, nothing to change in your project:
+
+| Package | Old | New | Where |
+| --- | --- | --- | --- |
+| `vite` | 8.3.2 | 8.3.3 | devDependencies (test tooling) |
+| `js-yaml` 5.x | 5.4.2 | 5.4.3 | override target in `pnpm-workspace.yaml` (parser bug fix) |
+
+`mongoose` 9.11.0 / `mongodb` 7.7.0 are deliberately not part of this release: the framework and the
+starter have to raise `mongodb` together, because two driver copies make Better-Auth's Mongo adapter
+reject each other's ids.
+
+## Compatibility Notes
+
+- Both changes only affect the generated Swagger/OpenAPI document. Routing, guards and API-token
+  enforcement are unchanged.
+- The document gets smaller: the framework's own test server goes from 142 to 134 operations.
+
+## References
+
+- Helper: `src/core/common/helpers/swagger.helper.ts` (`operationsOf()`)
+- Controller: `src/core/modules/better-auth/core-better-auth.controller.ts` (`handlePluginRoutes`)
+- Tests: `tests/unit/swagger-helper.spec.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.6",
+  "version": "11.42.8",
   "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",
@@ -221,7 +221,7 @@
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "2.0.0",
-    "vite": "8.3.2",
+    "vite": "8.3.3",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.11"
   },