@lenne.tech/nest-server 11.41.3 → 11.41.5

package/docs/REQUEST-LIFECYCLE.md

@@ -112,6 +112,7 @@ JWT-based authentication for existing projects:
 | **Tenant Isolation** | Header-based multi-tenant isolation with membership validation (opt-in) |
 | **Tenant Guard** | `CoreTenantGuard` validates tenant membership; system roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; hierarchy roles (`@Roles(DefaultHR.MEMBER)`), `@SkipTenantCheck()`, BetterAuth auto-skip (`betterAuth.skipTenantCheck`) |
 | **Tenant Plugin Safety Net** | Mongoose tenant plugin throws `ForbiddenException` when tenant-schema is accessed without valid tenant context |
+| **API Tokens** | `apiTokens` config (opt-in): USER tokens act as their user without global roles; TENANT tokens (multi-tenancy only) act with the lowest tenant role in their own tenant. `CoreApiTokenMiddleware` authenticates `Authorization: Bearer` / `x-api-key`; every guard denies a token unless the route declares `@ApiTokenScopes()`. Signed short-lived assertions for embedded pages. See `src/core/modules/api-token/README.md` |
 
 ### Data & CRUD
 
@@ -153,7 +154,8 @@ JWT-based authentication for existing projects:
 | `@ResponseModel(Model)` | REST response type hint for auto-conversion |
 | `@Translatable()` | Multi-language field metadata |
 | `@CommonError(code)` | Error code registration |
-| `@SkipTenantCheck()` | Opt out of CoreTenantGuard validation on a method |
+| `@SkipTenantCheck()` | Opt out of CoreTenantGuard validation on a method (not for tenant-restricted API tokens — they stay bound) |
+| `@ApiTokenScopes(...scopes)` | Open a route/class to API tokens holding one of the scopes; tokens are denied everywhere else |
 
 ### File Handling
 
@@ -335,11 +337,18 @@ The following diagram shows the exact order of execution from HTTP request to re
   |     - Accept-Language for translations                  |
   |                                                         |
   |  2. CoreBetterAuthMiddleware                            |
+  |     - Skips API-token credentials entirely              |
   |     - Strategy 1: Auth header (JWT/Session)             |
   |     - Strategy 2: JWT cookie                            |
   |     - Strategy 3: Session cookie                        |
   |     - Sets req.user                                     |
   |                                                         |
+  |  2c. CoreApiTokenMiddleware  [if apiTokens enabled]     |
+  |     - Bearer / x-api-key with the token prefix only     |
+  |     - Invalid token or assertion -> 401 on every route  |
+  |     - Per-token rate limit -> 429 + Retry-After         |
+  |     - Sets req.user (tenant principal / token's user)   |
+  |                                                         |
   |  3. graphqlUploadExpress()  [GraphQL only]              |
   |     - Handles multipart file uploads                    |
   +----------------------------+----------------------------+
@@ -348,6 +357,8 @@ The following diagram shows the exact order of execution from HTTP request to re
   |                      GUARDS                             |
   |                                                         |
   |  4. RolesGuard / BetterAuthRolesGuard                   |
+  |     - API token: @ApiTokenScopes() required, else 403   |
+  |       (checked BEFORE the public-route shortcut)        |
   |     - Reads @Roles() metadata                           |
   |     - Validates JWT / session token                     |
   |     - Checks real roles (ADMIN)                         |
@@ -355,6 +366,8 @@ The following diagram shows the exact order of execution from HTTP request to re
   |     - Throws 401 (Unauthorized) or 403 (Forbidden)     |
   |                                                         |
   |  4b. CoreTenantGuard  [if multiTenancy enabled]          |
+  |     - Tenant API token: bound to its tenant, lowest role|
+  |     - User API token: tenant restriction + role cap     |
   |     - Reads X-Tenant-Id header                          |
   |     - Validates membership via hierarchy roles (level comparison)  |
   |     - Non-admin + header + no membership = always 403   |
@@ -640,6 +653,22 @@ makes every project on that host unreachable over http for up to a year, with no
 Behind a TLS-terminating proxy the inward connection is plain http, which makes `trustProxy`
 load-bearing for this header too.
 
+#### 2c. CoreApiTokenMiddleware
+
+Registered by `CoreApiTokenModule` (auto-imported by `CoreModule` when `apiTokens` is configured).
+Claims only credentials carrying the configured prefix — `Authorization: Bearer <prefix>_…` /
+`<prefix>s_…`, or the same value in `x-api-key` — so sessions, JWTs and legacy tokens pass untouched;
+`CoreBetterAuthMiddleware` in turn skips prefixed credentials, including its cookie fallback, so a
+session cookie riding along can never turn a token request into a session request.
+
+- A token resolves to a TENANT principal (no global roles, bound to its tenant) or to the owning USER,
+  loaded from the `users` collection with global roles removed. Both carry a token context
+  (`getApiTokenContext(user)`), recognised by a module-private symbol — never by a data field.
+- A prefixed credential that does not authenticate (unknown, revoked, expired, tampered, bad
+  signature, deleted owner, two different credentials in the two headers) answers **401 on every
+  route**, public ones included — unlike an invalid session, which degrades to anonymous.
+- A per-token fixed-window rate limit (`RateLimitStore`, Redis-shared when configured) answers 429.
+
 #### 3. graphqlUploadExpress
 
 Only for GraphQL routes. Handles multipart file upload requests according to the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec).
@@ -694,6 +723,25 @@ Two consequences worth knowing when you own a public endpoint:
 
 **Important:** `@Roles()` already handles JWT authentication internally. Do NOT add `@UseGuards(AuthGuard(JWT))` — it is redundant.
 
+#### API tokens (`@ApiTokenScopes`)
+
+All three guards call ONE function, `enforceApiTokenRoute()` (`core-api-token.helpers.ts`), before
+their public-route shortcut, so the policy holds whichever guard runs first or alone:
+
+1. A token is refused (403) on every route that does not declare `@ApiTokenScopes()` — public ones
+   included — and on a route whose scopes it does not hold (method-level replaces class-level).
+2. A **TENANT** token is then decided completely: `S_NO_ONE` refuses; `S_EVERYONE` / `S_USER` /
+   `S_VERIFIED` count as satisfied; other roles resolve against the LOWEST tenant role, global roles
+   never; a route guarded only by `S_SELF` / `S_CREATOR` refuses (a tenant token is nobody's self);
+   an `X-Tenant-Id` naming another tenant refuses. The request gets `tenantId` / `tenantRole`
+   like a membership.
+3. A **USER** token continues through the ordinary checks as its user (global roles removed, so no
+   admin bypass). `CoreTenantGuard` adds its restrictions: a token restricted to one tenant is bound
+   to it (a foreign header refuses, `@SkipTenantCheck()` does not unbind it), and `maxTenantRole`
+   caps the membership role wherever it is used — including the no-header `tenantIds` resolution.
+4. A request that carries a token credential but reaches a guard without a token context (the
+   middleware did not run) is refused with 401 rather than treated as anonymous.
+
 #### System Roles (S_ prefix)
 
 System roles are evaluated at runtime and must **never** be stored in `user.roles`.

package/docs/security-overrides.md

@@ -11,14 +11,21 @@ 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 resolve to a **vulnerable** version unless you
-override them yourself:
+The framework pulls in three transitive packages that its `@nestjs/*` dependencies 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` | `@nestjs/graphql` declares `"ws": "8.20.1"` — an **exact pin**, not a caret. No amount of updating moves it |
-| `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` | `@nestjs/swagger` declares `"js-yaml": "5.2.1"` — an **exact pin**, the same shape as the `ws` case. It cannot resolve forward |
-| `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` declares `"multer": "2.2.0"` — an **exact pin** in every 11.2.x. The framework's own `multer: 2.3.0` dependency does not move it: you get both copies, and FileInterceptor uses the vulnerable one |
+| `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` |
+
+**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
+not**: GHSA-r3ph-w7gj-g6xm covers the `5.3.0` that `@nestjs/swagger` 11.4.7 pins, so without the
+entry your `pnpm audit` reports it. Its key and target were raised in 11.41.5 — an entry copied
+before that (`<5.2.2`) no longer reaches swagger's pin.
 
 `@nestjs/graphql` is a plain `dependencies` entry, so `ws` is installed even when you run with
 `graphQl: false`. `@nestjs/swagger` and `@nestjs/platform-express` are likewise plain `dependencies`
@@ -37,15 +44,16 @@ overrides:
   # Remove once @nestjs/graphql stops pinning it.
   'ws@>=8.0.0 <8.21.0': '8.21.3'
 
-  # @nestjs/swagger exact-pins js-yaml@5.2.1 (GHSA-pm4m-ph32-ghv5, high, patched >=5.2.2).
-  # Same shape as the ws entry: an exact pin cannot resolve forward.
-  # Remove once @nestjs/swagger stops pinning it.
-  'js-yaml@>=5.0.0 <5.2.2': '5.2.2'
+  # @nestjs/swagger exact-pins js-yaml (11.4.7: 5.3.0) — GHSA-r3ph-w7gj-g6xm (moderate, patched >=5.4.1)
+  # and, for older swagger releases, GHSA-pm4m-ph32-ghv5 (high, patched >=5.2.2).
+  # Same shape as the ws entry: an exact pin cannot resolve forward. LOAD-BEARING since 11.41.5.
+  # Remove once @nestjs/swagger pins >=5.4.1 itself.
+  'js-yaml@>=5.0.0 <5.4.2': '5.4.2'
 
-  # @nestjs/platform-express exact-pins multer@2.2.0 (GHSA-wc9g-mqfw-jrwm and three more, patched >=2.3.0).
-  # Keep the target in LOCKSTEP with the multer version @lenne.tech/nest-server declares.
-  # Remove once @nestjs/platform-express requests >=2.3.0 itself.
-  'multer@>=2.0.0 <2.3.0': '2.3.0'
+  # @nestjs/platform-express <=11.2.5 exact-pins multer@2.2.0 (GHSA-wc9g-mqfw-jrwm and three more, patched >=2.3.0).
+  # 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'
 ```
 
 ### Retired: `@hono/node-server` (removed 2026-08-22, nest-server 11.36.1)

package/migration-guides/11.41.3-to-11.41.4.md

@@ -0,0 +1,172 @@
+# Migration Guide: 11.41.3 → 11.41.4
+
+## Overview
+
+| Category                 | Effort                  | Applies to                                                                                             |
+| ------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| **New feature (opt-in)** | config + a thin controller | API tokens: USER tokens and — with multi-tenancy — TENANT tokens, signed assertions for embedded pages |
+| Improvement              | none, optional clean-up | `mountAiMcpOAuth(app)` takes the OAuth issuer from the server config                                   |
+| **Security fix**         | none, verify once       | Role guards hand non-system roles to the tenant guard only while one is REGISTERED                     |
+| Dependencies             | `pnpm run update`       | `@nestjs/*` 11.2.6, mongoose 9.10.2 / mongodb 7.6.0, multer 2.4.0 — align your own pins (§4)           |
+
+No breaking change for a standard setup. Without an `apiTokens` block the token feature does nothing; the security fix only changes behaviour where `multiTenancy` is configured but no tenant guard is registered (see §3).
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run update            # starter-based projects: aligns the framework's ecosystem (see §4)
+pnpm run build && pnpm test
+```
+
+Vendor-mode projects adopt the new `src/core/modules/api-token/` directory and the touched guards
+through the core update.
+
+## What's New in 11.41.4
+
+### 1. API tokens
+
+Bearer credentials for machine clients, scripts and embedded pages that cannot carry a session cookie.
+
+|                     | USER token                                          | TENANT token           |
+| ------------------- | --------------------------------------------------- | ---------------------- |
+| Belongs to          | one user                                            | one tenant             |
+| Acts with           | the user's current rights, **without** global roles | the lowest tenant role |
+| Optional limits     | scopes, one tenant, `maxTenantRole`, expiry         | scopes, expiry         |
+| Needs multi-tenancy | no                                                  | yes                    |
+
+```typescript
+// config.env.ts
+apiTokens: {
+  scopes: ['upload', 'read', 'export'],
+  encryptionKey: process.env.API_TOKEN_ENCRYPTION_KEY, // required in production/staging
+},
+
+// a route a token may call — tokens are denied on every other route, public ones included
+@ApiTokenScopes('upload')
+@Roles(RoleEnum.S_USER)
+@Post('documents')
+```
+
+Management goes through `CoreApiTokenService` (`createUserToken`, `createTenantToken`, …); the project
+writes a thin controller. Full integration: `src/core/modules/api-token/INTEGRATION-CHECKLIST.md`.
+
+Security properties worth knowing before you open a route:
+
+- A token only reaches routes that declare `@ApiTokenScopes()`; every guard enforces that.
+- A prefixed credential that fails answers **401 on every route** — it is never silently anonymous.
+- Tenant boundaries hold for both kinds: a tenant token only in its tenant, a user token only in its
+  user's active memberships (and in one of them, if restricted).
+- A tenant token is no person: a route guarded only by `S_SELF` / `S_CREATOR` refuses it, and
+  `@CurrentUser()` carries no `email` / `verified`.
+- Tokens never manage tokens — `CoreApiTokenService` refuses a token caller even on a route you
+  released; a platform admin's user token is not a platform admin. Protected fields (`tenant`, `user`,
+  `kind`, `revokedAt`, …) cannot be set through a management input, dotted paths included.
+- The MCP OAuth consent step (`mountAiMcpOAuth`) refuses token-authenticated requests: a consent
+  mints an access token with the user's full rights. An override of `authorizeConsent()` keeps this check.
+- A password reset that ends the user's sessions ends their user tokens too: the legacy reset always,
+  the IAM reset while `betterAuth.emailAndPassword.revokeSessionsOnPasswordReset` is on (recommended).
+  Tenant tokens are not affected — they belong to the tenant.
+
+What your project has to take care of itself:
+
+| Topic                               | What to do                                                                                                                                                                                                        |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Deleting or off-boarding a tenant   | Call `CoreApiTokenService.deleteAllForTenant(tenantId)`. The core has no tenant model to notice the deletion, and a tenant token depends on no member — until you call it, the tenant's tokens keep authenticating                         |
+| Account compromise without a reset  | Call `CoreApiTokenService.revokeAllForUser(userId)`. With `revokeSessionsOnPasswordReset` off, an IAM reset leaves user tokens alive, like personal access tokens elsewhere; a password CHANGE never revokes them |
+| Routes mounted with `app.use()`     | They run outside the Nest guards, so `@ApiTokenScopes()` does not protect them and `req.user` may be a token. Check `getApiTokenContext(req.user)` there                                                          |
+| `@CurrentUser()` on an opened route | For a tenant token it is not a person: no `email`, no `verified`. Code that mails or notifies "the current user" must check `getApiTokenContext()` first                                                          |
+| Better-Auth admin plugin (`banned`) | Not used by the framework. If you add it, override `CoreApiTokenService.loadTokenUser()` so a banned user's tokens are refused too                                                                                |
+| Brute force against tokens          | Tokens carry 256 bits of secret, so guessing is not the risk — but failed attempts are not rate-limited per IP. Put an IP limit in front (reverse proxy / WAF) if the API is exposed                              |
+| Secret scanning                     | Register the shape `<prefix>_<24 hex>_<64 hex>` as a custom pattern                                                                                                                                               |
+
+### 2. `mountAiMcpOAuth(app)` without `baseUrl`
+
+The OAuth issuer — and with it every URL in the discovery metadata that MCP clients follow — now
+defaults to the server's `baseUrl` (`NSC__BASE_URL`), resolved like BetterAuth and CORS resolve it.
+`local` / `ci` / `e2e` fall back to `http://localhost:3000`; any other environment without a
+`baseUrl` fails the call instead of advertising a guessed localhost URL. The resolved issuer is logged
+once at boot.
+
+```typescript
+// Before
+await mountAiMcpOAuth(app, { baseUrl: envConfig.baseUrl || `http://localhost:${envConfig.port}` });
+
+// After
+await mountAiMcpOAuth(app);
+```
+
+An explicit `baseUrl` still wins. Remove a hand-written `localhost` fallback: it is exactly what made a
+deployed API advertise `http://localhost:3000` and send MCP clients to the user's own machine.
+
+### 3. Role guards delegate only to a registered tenant guard (security fix)
+
+`RolesGuard` and `BetterAuthRolesGuard` hand every non-system role to `CoreTenantGuard`, which
+resolves it against the membership. They used to decide that from CONFIGURATION alone: with
+`multiTenancy` set but no tenant guard actually registered, a role such as `RoleEnum.ADMIN` went to
+a guard that never ran, and every authenticated caller passed. They now delegate only while a tenant
+guard is registered, and otherwise check the roles against `user.roles` themselves (with a one-time
+warning).
+
+A project that lets `CoreModule` register the tenant module — the normal setup — sees no difference.
+If your project replaces the tenant module with its own registration, make sure a tenant guard is
+still registered, either through `CoreTenantModule.forRoot({ guard })` or as `CoreTenantGuard`
+itself.
+
+### 4. Dependency updates
+
+A maintenance pass ships with this release. No major version moved in `dependencies` or
+`peerDependencies`; `better-auth` stays on its `>=1.7.1 <1.8.0` peer range.
+
+| Package | 11.41.3 | 11.41.4 |
+| ------- | ------- | ------- |
+| `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-express` | 11.2.1 | 11.2.6 |
+| `mongoose` / `mongodb` | 9.9.3 / 7.5.0 | 9.10.2 / 7.6.0 |
+| `multer` | 2.3.0 | 2.4.0 |
+| `graphql` | 16.14.0 | 16.14.2 |
+| `jose` | 6.2.9 | 6.2.12 |
+| `@modelcontextprotocol/sdk` | 1.30.0 | 1.30.1 |
+| `@tus/server` | 2.4.4 | 2.4.5 |
+| `compression` | 1.8.1 | 1.8.2 |
+| `supertest` | 7.2.2 | 7.3.0 |
+
+**What to do:** if your project pins any of these itself — most do for `@nestjs/common`,
+`@nestjs/core`, `@nestjs/platform-express` and `mongoose` — raise the pins to the versions above.
+A pin that lags behind the framework puts a second copy into the tree, and with `@nestjs/*` that
+surfaces as type errors about classes that "incorrectly extend" their base class. Starter-based
+projects get this from `pnpm run update`, which also raises the tooling devDependencies a project
+shares with the framework: `@nestjs/testing` 11.2.6, `@swc/core` 1.16.2, `@types/node` 26.6.2,
+`oxfmt` 0.70.0, `oxlint` 1.85.0 and `unplugin-swc` 2.0.0 (a major, whose only breaking change is
+dropping Node 18).
+
+**Security overrides:** `@nestjs/platform-express` 11.2.6 pins `multer` 2.4.0 itself, so the
+`multer` override from `docs/security-overrides.md` is inert on this version. Keep it as insurance
+and raise its target in lockstep: `'multer@>=2.0.0 <2.4.0': '2.4.0'`. The `ws` and `js-yaml`
+entries are likewise inert on the `@nestjs/graphql` / `@nestjs/swagger` versions this framework
+declares; they only matter where your own `package.json` pins older ones.
+
+## Compatibility Notes
+
+| Pattern                                                                           | Status                                                                                                                                                                                                                                                                                                               |
+| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Projects without `apiTokens`                                                      | Unchanged                                                                                                                                                                                                                                                                                                            |
+| Custom guards extending `RolesGuard` / `BetterAuthRolesGuard` / `CoreTenantGuard` | Unchanged as long as they call `super.canActivate()`. A guard that replaces the logic entirely skips the token rules in THAT guard: route release and scopes are still enforced by the role guard, but a user token's tenant restriction and `maxTenantRole` are applied only by `CoreTenantGuard` — keep calling it |
+| A project using the `x-api-key` header for its own keys                           | Only values carrying the token prefix are claimed; everything else passes through                                                                                                                                                                                                                                    |
+| `mountAiMcpOAuth(app, { baseUrl })`                                               | Unchanged; the argument is optional now                                                                                                                                                                                                                                                                              |
+| `multiTenancy` configured without any registered tenant guard                     | Non-system roles are now checked against `user.roles` instead of being waved through — a route that relied on the gap starts answering 403                                                                                                                                                                           |
+
+## Troubleshooting
+
+| Symptom                                                        | Cause                                                                              | Fix                                                           |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Boot error mentioning `apiTokens.manageRole` or "a role below" | The manage role is not a declared tenant role, or the hierarchy has a single level | Declare the role / add a lower role, or `tenantTokens: false` |
+| Boot error "encryptionKey … required in production/staging"    | No key configured                                                                  | Set `apiTokens.encryptionKey` or `SECRETS_ENCRYPTION_KEY`     |
+| A token gets 403 on a route                                    | Route not opened, scope missing, role too high, foreign tenant                     | `@ApiTokenScopes()`, token scopes, `X-Tenant-Id`              |
+| `mountAiMcpOAuth: no public server URL` at boot                | Deployed without `baseUrl`                                                         | Set `NSC__BASE_URL`                                           |
+
+## Module Documentation
+
+- [API tokens README](../src/core/modules/api-token/README.md)
+- [API tokens Integration Checklist](../src/core/modules/api-token/INTEGRATION-CHECKLIST.md)
+- [AI module README → OAuth 2.1](../src/core/modules/ai/README.md)
+- [Request lifecycle → API tokens](../docs/REQUEST-LIFECYCLE.md)

package/migration-guides/11.41.4-to-11.41.5.md

@@ -0,0 +1,144 @@
+# Migration Guide: 11.41.4 → 11.41.5
+
+## Overview
+
+| Category              | Details                                                                                                          |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Breaking Changes**  | None in the package                                                                                              |
+| **Bugfix**            | `migrate down` now holds the migration lock, like `migrate up` already did                                       |
+| **Template change**   | nest-server-starter's `docker-entrypoint.sh` now aborts the start when a migration RAN AND FAILED (§2)           |
+| **New option**        | `MIGRATIONS_ALLOW_FAILURE=true` — start anyway for one deploy (starter and this repo's entrypoint)               |
+| **Dependencies**      | nodemailer 9 → 10 (security; the only break is Node >= 20), js-yaml override now needed in your project (§3)     |
+| **Migration Effort**  | Raise two overrides in your `pnpm-workspace.yaml` (§3); decide once whether to adopt the strict entrypoint (§2)  |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run update            # starter-based projects: aligns the framework's ecosystem (see §3)
+pnpm run build && pnpm test
+```
+
+Vendor-mode projects pick up `migration-runner.ts` through the core update.
+
+## What's New in 11.41.5
+
+### 1. `migrate down` holds the migration lock
+
+Since 11.33.0, `migrate up` (`MigrationRunner.up()`) runs under the lock of the state store's lock
+collection — `migrations_lock` by default for stores built by `createMigrationStore()` — so replicas
+booting together serialize instead of each applying the same pending migration. `migrate down`
+did not. A rollback is typically run while a deploy is failing, i.e. exactly while replicas restart
+and each boots into `migrate up`; outside the lock the two read and rewrote the migration state
+concurrently. `MigrationRunner.down()` now takes the same lock. `migrate list` only reads and stays
+unlocked.
+
+Nothing to do: projects using `createMigrationStore()` get it automatically. A store built with an
+empty lock collection name (`createMigrationStore(uri, 'migrations', '')`) still runs unlocked, as
+before.
+
+### 2. The starter's entrypoint aborts on a migration that ran and failed
+
+This concerns `docker-entrypoint.sh` in **nest-server-starter** (and therefore in projects created
+from it), not the npm package. Until now the starter's entrypoint logged a failed migration and
+started the server anyway. A failed schema migration is then indistinguishable from a good deploy
+on every level anyone watches — health check 200, the right commit on `/meta`, drift detection
+green, `turbo deploy --wait` converging — over an app that works against the empty collections
+Mongoose created at boot while the data still sits under the old names.
+
+| Situation | Before | Now |
+| --------- | ------ | --- |
+| A migration ran and threw | warning, server starts | **start aborted** (exit 1); the container runtime retries |
+| `MIGRATIONS_ALLOW_FAILURE=true` | — | warning, server starts — a deliberate exception for ONE deploy |
+| `MIGRATE_FAILURE_POLICY=warn` / `abort` | `warn` was the default | still honoured; wins over `MIGRATIONS_ALLOW_FAILURE` |
+| Unknown value in either variable | fell back to `warn` | falls back to `abort`, with a warning |
+| A recorded migration whose FILE is gone | warning, server starts | unchanged: warning, server starts |
+| No migrations bundled / no CLI in the image | skipped | unchanged: skipped |
+
+The last-but-one row is deliberate: migrations that ran everywhere may simply be deleted once a new
+instance no longer needs them (git history restores them). The migrate CLI reports such a file as a
+warning, and the entrypoint passes no `--strict`. A project that wants the opposite sets
+`NSC__MIGRATE__STRICT=true` explicitly — that stays available, it is just not the default.
+
+**What to do in an existing project:** your `docker-entrypoint.sh` is your own file, so nothing
+changes until you adopt the new one. To adopt it, copy `docker-entrypoint.sh` from
+nest-server-starter 11.41.5. If a deploy must go out with a migration known to fail, set
+`MIGRATIONS_ALLOW_FAILURE=true` for that deploy and unset it again once the migration is fixed.
+
+This repository's own `docker-entrypoint.sh` already defaulted to `abort`; it gained the
+`MIGRATIONS_ALLOW_FAILURE` alias.
+
+### 3. Dependency updates
+
+| Package | 11.41.4 | 11.41.5 |
+| ------- | ------- | ------- |
+| `nodemailer` | 9.1.1 | **10.0.13** |
+| `mongoose` | 9.10.2 | 9.10.3 |
+| `@modelcontextprotocol/sdk` | 1.30.1 | 1.31.0 |
+| dev: `@swc/core`, `@types/multer`, `@types/node`, `oxfmt`, `oxlint` | 1.16.2, 2.2.0, 26.6.2, 0.70.0, 1.85.0 | 1.16.12, 2.3.0, 26.6.3, 0.71.0, 1.86.0 |
+
+**nodemailer 10 is a major, and it ships in a patch on purpose.** Five advisories cover 9.1.1 — two
+of them high (GHSA-v53p-9fqp-m79j, GHSA-prgh-xp8r-p3m5), three moderate — and they are fixed only in
+10.x; there is no 9.x backport. The single breaking change of 10.0.0 is "Node.js 20 or newer is
+required", and this package already requires Node >= 22.12. 10.x is a TypeScript rewrite that ships
+its own declarations; `@types/nodemailer` is no longer read. Only one thing changes for code that
+uses nodemailer's types directly:
+
+```typescript
+import type * as SMTPTransport from 'nodemailer/lib/smtp-transport';
+
+let transport: SMTPTransport;          // before: the namespace WAS the class
+let transport: SMTPTransport.default;  // nodemailer 10: the class is the default export
+let options: SMTPTransport.Options;    // unchanged
+```
+
+`MailTransportOptions` in `IServerOptions` was adjusted the same way; a project that only passes a
+plain options object (`email.smtp`) is unaffected.
+
+**What to do:**
+
+1. Starter-based projects: `pnpm run update` raises `mongoose` and the dev tooling to the versions above.
+2. Two overrides `pnpm run update` does NOT touch — edit `overrides:` in your `pnpm-workspace.yaml`:
+
+   ```yaml
+   # The lockstep entry from nest-server-starter. Left at 9.1.1 it forces the framework's
+   # nodemailer back DOWN to 9.1.1 — and keeps all five advisories.
+   nodemailer: 10.0.13
+
+   # @nestjs/swagger 11.4.7 (the newest 11.x) exact-pins js-yaml 5.3.0, covered by
+   # GHSA-r3ph-w7gj-g6xm (moderate, patched >=5.4.1). Replaces an older `<5.2.2` entry, which no
+   # longer reaches that pin. Background: docs/security-overrides.md.
+   'js-yaml@>=5.0.0 <5.4.2': '5.4.2'
+   ```
+
+3. Run `pnpm install` and `pnpm audit` — both advisories must be gone.
+
+Overrides in this repository never reach your project (pnpm applies them only to the root of an
+install), which is why the js-yaml entry has to be repeated there.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| `createMigrationStore(uri)` / `createMigrationStore(uri, 'migrations')` | Lock active for `up` and now `down` |
+| A custom `MongoStateStore` without `lockCollectionName` | Unchanged: runs unlocked |
+| `NSC__MIGRATE__STRICT=true` | Unchanged: a missing recorded migration file fails the run |
+| A `nodemailer: 9.1.1` override (starter-derived projects) | Pins nodemailer 9.1.1 under the framework — raise it to `10.0.13` (§3) |
+| Code typing `import * as X from 'nodemailer/lib/…'` as `X` | Use `X.default` (§3) |
+| Your own `docker-entrypoint.sh` | Unchanged until you adopt the starter's (§2) |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| Container restarts in a loop, log: `refusing to start against a possibly half-applied schema` | A migration ran and failed (new entrypoint) | Fix the migration; for one deploy, `MIGRATIONS_ALLOW_FAILURE=true` |
+| `migrate down` waits with `Waiting for migration lock release …` | Another replica is running `migrate up` | Wait; a lock whose holder died is broken after 60 s without heartbeat |
+| `Strict mode: N recorded migration file(s) missing` | `NSC__MIGRATE__STRICT=true` and a migration file was deleted | Restore the file from git, or unset `NSC__MIGRATE__STRICT` |
+| `pnpm audit` still reports nodemailer advisories after the update | A `nodemailer: 9.1.1` override pins the old version | Raise it to `10.0.13` |
+| `pnpm audit` reports GHSA-r3ph-w7gj-g6xm (js-yaml) | No (or an old `<5.2.2`) js-yaml override | Add `'js-yaml@>=5.0.0 <5.4.2': '5.4.2'` |
+| `TS2709` / `Cannot use namespace 'SMTPTransport' as a type` | nodemailer 10 types | Use `SMTPTransport.default` |
+
+## Module Documentation
+
+- [Migrate module README](../src/core/modules/migrate/README.md) — locking, strict mode, CLI
+- nest-server-starter `README.md` → Environment — `MIGRATE_FAILURE_POLICY` / `MIGRATIONS_ALLOW_FAILURE`