@lenne.tech/nest-server 11.41.3 → 11.41.4

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,20 @@ 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` | Older `@nestjs/swagger` releases declare `"js-yaml": "5.2.1"` — an **exact pin**, the same shape as the `ws` case. 11.4.7, the version this framework declares, pins `5.3.0` |
+| `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0` | `@nestjs/platform-express` up to 11.2.5 declares `"multer": "2.2.0"` — an **exact pin**. A direct `multer` dependency does not move it: you get both copies, and FileInterceptor uses the vulnerable one. 11.2.6, the version this framework declares since 11.41.4, pins `2.4.0` |
+
+**Status since 11.41.4:** with the `@nestjs/*` versions this framework declares, all three resolve to
+a patched version on their own. The entries below are insurance for a project whose own
+`package.json` pins an older `@nestjs/graphql`, `@nestjs/swagger` or `@nestjs/platform-express` —
+duplicates of those are exactly how an old exact pin comes back. Keep them; they cost nothing while
+inert, and keep the `multer` target in lockstep (now `2.4.0`).
 
 `@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 +43,15 @@ 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).
+  # Older @nestjs/swagger releases exact-pin 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.41.3",
+  "version": "11.41.4",
   "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",
@@ -16,8 +16,8 @@
   "scripts": {
     "build": "rimraf dist && nest build && pnpm run build:copy-types && pnpm run build:copy-templates && pnpm run build:add-type-references && pnpm run build:framework-api",
     "build:add-type-references": "node scripts/add-type-references.js",
-    "build:copy-templates": "mkdir -p dist/core/modules/migrate/templates && cp src/core/modules/migrate/templates/migration-project.template.ts dist/core/modules/migrate/templates/",
-    "build:copy-types": "mkdir -p dist/types && cp src/types/*.d.ts dist/types/",
+    "build:copy-templates": "node scripts/copy-build-assets.mjs templates",
+    "build:copy-types": "node scripts/copy-build-assets.mjs types",
     "build:dev": "pnpm run build",
     "build:framework-api": "tsx scripts/generate-framework-api.ts",
     "build:pack": "pnpm pack && echo \"use file:/ROOT_PATH_TO_TGZ_FILE to integrate the package\"",
@@ -92,42 +92,42 @@
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.0.3",
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/sdk": "1.30.1",
     "@nestjs/apollo": "13.4.5",
-    "@nestjs/common": "11.2.1",
-    "@nestjs/core": "11.2.1",
+    "@nestjs/common": "11.2.6",
+    "@nestjs/core": "11.2.6",
     "@nestjs/graphql": "13.4.5",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.2.1",
+    "@nestjs/platform-express": "11.2.6",
     "@nestjs/schedule": "6.1.3",
     "@nestjs/swagger": "11.4.7",
     "@nestjs/terminus": "11.1.1",
     "@tus/file-store": "2.1.1",
-    "@tus/server": "2.4.4",
+    "@tus/server": "2.4.5",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
-    "compression": "1.8.1",
+    "compression": "1.8.2",
     "cookie-parser": "1.4.7",
     "cron": "4.4.0",
     "dotenv": "17.4.2",
     "ejs": "6.0.1",
     "express": "5.2.1",
-    "graphql": "16.14.0",
+    "graphql": "16.14.2",
     "graphql-query-complexity": "2.0.0",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
     "graphql-ws": "6.2.1",
-    "jose": "6.2.9",
+    "jose": "6.2.12",
     "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
-    "mongodb": "7.5.0",
-    "mongoose": "9.9.3",
-    "multer": "2.3.0",
+    "mongodb": "7.6.0",
+    "mongoose": "9.10.2",
+    "multer": "2.4.0",
     "node-mailjet": "6.0.11",
     "nodemailer": "9.1.1",
     "passport": "0.7.0",
@@ -135,7 +135,7 @@
     "reflect-metadata": "0.2.2",
     "rfdc": "1.4.1",
     "rxjs": "7.8.2",
-    "supertest": "7.2.2",
+    "supertest": "7.3.0",
     "ts-morph": "28.0.0",
     "ws": "8.21.3",
     "yuml-diagram": "1.2.0"
@@ -177,47 +177,47 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1115.0",
-    "@aws-sdk/s3-request-presigner": "3.1115.0",
+    "@aws-sdk/client-s3": "3.1140.0",
+    "@aws-sdk/s3-request-presigner": "3.1140.0",
     "@better-auth/core": "1.7.1",
     "@better-auth/passkey": "1.7.1",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
-    "@nestjs/testing": "11.2.1",
+    "@nestjs/testing": "11.2.6",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.16.1",
-    "@tus/s3-store": "2.0.6",
+    "@swc/core": "1.16.2",
+    "@tus/s3-store": "2.0.7",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.25",
     "@types/multer": "2.2.0",
-    "@types/node": "26.2.0",
-    "@types/nodemailer": "8.0.1",
+    "@types/node": "26.6.2",
+    "@types/nodemailer": "8.0.2",
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
     "ansi-colors": "4.1.3",
     "better-auth": "1.7.1",
-    "bullmq": "6.2.0",
+    "bullmq": "6.3.8",
     "cross-env": "10.1.0",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
     "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
-    "otpauth": "9.5.1",
-    "oxfmt": "0.64.0",
-    "oxlint": "1.79.0",
+    "otpauth": "9.5.2",
+    "oxfmt": "0.70.0",
+    "oxlint": "1.85.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
-    "tsx": "4.23.12",
+    "tsx": "4.23.15",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
-    "unplugin-swc": "1.5.11",
-    "vite": "8.2.2",
+    "unplugin-swc": "2.0.0",
+    "vite": "8.3.1",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.11"
   },

package/src/core/common/helpers/graceful-shutdown.helper.ts

@@ -47,6 +47,15 @@ const SHUTDOWN_DELAY_ADVISORY_MS = 10_000;
  * Without a configured delay this is exactly `app.enableShutdownHooks()`, which is what the
  * framework did before.
  *
+ * **Windows: a termination from outside runs none of this.** Windows has no SIGTERM to deliver.
+ * Ending a process from outside, whether by `child.kill()`, `taskkill /F` (what `lt dev down` and
+ * the `check` watchdog use) or the Task Manager, terminates it at once. Measured on the Windows CI
+ * runner (`tests/unit/process-diagnostics-signal.spec.ts`): the process exits and the handler
+ * never runs. So on Windows neither `shutdownDelayMs` nor any `onModuleDestroy` /
+ * `onApplicationShutdown` hook runs on such a termination. Ctrl+C in a console window reaches Node
+ * as SIGINT and SHOULD reach this handler — that path is **unmeasured**. Do not rely on a graceful
+ * drain there; production targets Linux containers, where all of the above holds.
+ *
  * @param app the Nest application to shut down
  * @returns the same app, so it can be chained
  */

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

@@ -171,6 +171,13 @@ export function redactSensitiveText(text: string): string {
         /(\/(?:request-password-reset|reset-password|forget-password|forgot-password|set-password|change-email|magic-?link|verify|reset|confirm|activate|invite)\/)([A-Za-z0-9._~-]{16,})/gi,
         (_m, prefix, token) => `${prefix}${maskToken(token)}`,
       )
+      // tenant API tokens (`<prefix>_<24 hex>_<64 hex>`) and their signed assertions
+      // (`<prefix>s_<payload>.<43-char HMAC>`) anywhere in the line — they are long-lived bearer
+      // credentials, and a line that quotes one outside an Authorization header would pass the rule below
+      .replace(/\b[a-z][a-z0-9]{1,15}_[0-9a-f]{24}_[0-9a-f]{64}\b/g, (match) => maskToken(match))
+      .replace(/\b[a-z][a-z0-9]{1,15}s_[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-])/g, (match) =>
+        maskToken(match),
+      )
       // authorization: Bearer xyz / Authorization=xyz
       .replace(
         /(authorization["']?\s*[:=]\s*["']?)(?:Bearer\s+)?([^\s"',;]+)/gi,

package/src/core/common/helpers/process-diagnostics.helper.ts

@@ -208,6 +208,10 @@ function describeError(value: unknown): string {
  * Call this as the first statement of `bootstrap()`, before `NestFactory.create()`. See the module
  * docblock for why it must not live inside `CoreModule.forRoot()`.
  *
+ * On Windows the signal labels are not written when the process is ended from outside: there is
+ * no signal to deliver, the process is terminated at once and no handler runs (measured on the
+ * Windows CI runner, see `installGracefulShutdown()`). Ctrl+C in a console is unmeasured.
+ *
  * @param options - Injectable dependencies; defaults target the real `process`
  *
  * @example