@lenne.tech/nest-server 11.42.8 → 11.42.10

package/docs/REQUEST-LIFECYCLE.md

@@ -157,6 +157,7 @@ JWT-based authentication for existing projects:
 | `@CommonError(code)` | Error code registration |
 | `@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 |
+| `@ApiMethods(...methods)` | Swagger only (11.42.9): the HTTP methods an `@All()` handler actually serves — `setupSwagger()` documents those instead of all eight. No runtime effect |
 
 ### File Handling
 
@@ -166,7 +167,7 @@ JWT-based authentication for existing projects:
 | **REST Endpoints** | `GET /files/id/:id`, `GET /files/:filename` (core, gated by `file.downloadRoles`, default ADMIN); `POST /files/upload`, `DELETE /files/:id` (project-specific) |
 | **GraphQL Endpoints** | `getFileInfo` (`file.downloadRoles`), `uploadFile` / `uploadFiles` (`file.uploadRoles`), `deleteFile` (`file.deleteRoles`) — all default ADMIN |
 | **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Cover BOTH the `id` and the `filename` branch — the filename route authorizes on the by-name lookup alone when presigned S3 downloads are on, and `deleteFileByName()` always does. Working reference: `src/server/modules/file/file.service.ts` (with `file.downloadRoles: [S_USER]` in `src/config.env.ts`, so the rule is actually reached). Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
-| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })` |
+| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })`. Configured by `TusModule.forRoot({ config })`, else the server config's `tus` key (11.42.9+). Switched-off `creation` / `termination` answer 501 (enforced by `CoreTusService`, not `@tus/server`); upload URLs follow the path the upload was created at |
 | **GridFS Migration** | Completed TUS uploads auto-migrate to GridFS |
 | **CORS Support** | Automatic CORS headers for browser uploads |
 
@@ -636,6 +637,13 @@ If authentication succeeds, `req.user` is set with the authenticated user (inclu
 > raw-forwarded routes. A forged `POST /iam/update-user {"roles":["admin"]}` is rejected with
 > `FIELD_NOT_ALLOWED` (HTTP 400) at the input-parse stage, before any persistence.
 
+> **Never routed: `/iam/open-api/*` (11.42.9).** nest-server registers Better-Auth's `openAPI()` plugin
+> only so `setupSwagger()` can document Better-Auth's own routes, and marks its endpoints `SERVER_ONLY`:
+> better-call leaves them out of the router, so a forwarded request answers 404 however its path is
+> spelled, while the generator still runs in-process. Deliberately not a path check in the middleware —
+> it would see the path as sent, Better-Auth the one `new URL()` produced (`/iam/./open-api/…`). Only a
+> project that registered `openAPI()` itself in `betterAuth.plugins` gets the routes.
+
 > **"Raw" has one exception since 11.38.0: the password-setting reset routes.**
 > `CoreBetterAuthApiMiddleware.normalizeResetPassword()` rewrites the password field of
 > `/reset-password`, `/email-otp/reset-password` and `/phone-number/reset-password` to its

package/docs/security-overrides.md

@@ -18,7 +18,7 @@ used to **exact-pin**, to a vulnerable version:
 |---------|----------|------------------------------------------|
 | `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | Older `@nestjs/graphql` releases declare `"ws": "8.20.1"` — an **exact pin**, not a caret. 13.4.5, the version this framework declares, pins `8.21.3` |
 | `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS), patched `>=5.2.2`; [GHSA-r3ph-w7gj-g6xm](https://github.com/advisories/GHSA-r3ph-w7gj-g6xm) — moderate: `maxTotalMergeKeys` does not bound CPU use for empty merge sources, covers `<=5.4.0`, patched `>=5.4.1` (published 2026-09-29) | `@nestjs/swagger` declares js-yaml as an **exact pin**, the same shape as the `ws` case: older releases `5.2.1`, 11.4.7 — the version this framework declares, and the newest 11.x — `5.3.0`. No swagger update reaches the fix, so **this entry is load-bearing again** |
-| `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep`, which runs while the GraphQL schema is assembled. Covers `<=12.0.0`, patched `>=12.0.1` (added 2026-10-06) | `@nestjs/graphql` 13.4.5 — the version this framework declares, and the newest 13.x — declares `"@graphql-tools/utils": "12.0.0"`, an **exact pin**. Only `@nestjs/graphql` 14.x moves it, so **this entry is load-bearing**. `@apollo/server` reaches it too, through `@graphql-tools/schema` / `merge` — and in a lockfile that still holds schema 10.0.x (resolved before 2026-08-12), as **utils 11.x**: vulnerable too, with no 11.x fix, and outside the override key. Lift it with `pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge`; the current releases request utils `^12.0.3`, which needs Node >=22.15 |
+| `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep`, which runs while the GraphQL schema is assembled. Covers `<=12.0.0`, patched `>=12.0.1` (added 2026-10-06) | `@nestjs/graphql` 13.4.5 — the version this framework declares, and the newest 13.x — declares `"@graphql-tools/utils": "12.0.0"`, an **exact pin**. Only `@nestjs/graphql` 14.x moves it, so **this entry is load-bearing**. `@apollo/server` reaches it too, through `@graphql-tools/schema` / `merge` — and in a lockfile that still holds schema 10.0.x (resolved before 2026-08-12), as **utils 11.x**: vulnerable too, with no 11.x fix, and outside the override key. Lift it with `pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge`; the current releases request utils `^12.0.3`, which needs Node >=22.15 — the framework's own floor since 11.42.10, which is why the snippet below targets 12.0.3 |
 | `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0` | `@nestjs/platform-express` up to 11.2.5 declares `"multer": "2.2.0"` — an **exact pin**. A direct `multer` dependency does not move it: you get both copies, and FileInterceptor uses the vulnerable one. 11.2.6, which this framework declared from 11.41.4, pins `2.4.0`, and so does 11.2.7, declared since 11.41.7 |
 
 **Status since 11.42.4:** `@graphql-tools/utils` joins `js-yaml` as load-bearing — no `@nestjs/graphql`
@@ -64,12 +64,13 @@ overrides:
   'multer@>=2.0.0 <2.4.0': '2.4.0'
 
   # @nestjs/graphql 13.4.5 exact-pins @graphql-tools/utils@12.0.0 — GHSA-7mx3-vvmw-hjmv (high, patched >=12.0.1).
-  # Target 12.0.1 rather than the newest 12.x: 12.0.2+ requires Node >=22.15 via @whatwg-node/promise-helpers@2.
-  # If your engines floor is already >=22.15, prefer the newest 12.x, so the caret requesters are not held back.
+  # Target the newest 12.x, so the caret requesters (@graphql-tools/schema / merge) are not held back.
+  # 12.0.2+ requires Node >=22.15 via @whatwg-node/promise-helpers@2 — the floor this framework declares
+  # since 11.42.10. On an older Node, take 12.0.1 instead.
   # Does NOT reach a utils 11.x pulled in by an older @graphql-tools/schema 10.0.x — refresh that one instead:
-  #   pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge   (current releases need Node >=22.15)
+  #   pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge
   # Remove once @nestjs/graphql pins >=12.0.1 in the major you use.
-  '@graphql-tools/utils@>=12.0.0 <12.0.1': '12.0.1'
+  '@graphql-tools/utils@>=12.0.0 <12.0.3': '12.0.3'
 ```
 
 ### Retired: `@hono/node-server` (removed 2026-08-22, nest-server 11.36.1)

package/migration-guides/11.42.8-to-11.42.9.md

@@ -0,0 +1,186 @@
+# Migration Guide: 11.42.8 → 11.42.9
+
+## Overview
+
+| Category             | Details                                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **New Feature**      | `setupSwagger()` documents every HTTP interface the server makes usable — Better-Auth's own routes, `/ai/mcp`, the MCP OAuth endpoints (§1) |
+| **Bugfix**           | …and only those: routes the running configuration makes fail for every caller leave the document (§2)          |
+| **New Feature**      | `@ApiMethods()` — the HTTP methods an `@All()` handler actually serves (§3)                                     |
+| **Bugfix**           | The `tus` key in the server configuration takes effect — it was never read (§5). **Check your `tus` block**     |
+| **Bugfix**           | TUS: upload URLs work below a global prefix and a project route, a `path` naming a new route moves the endpoint, `termination: false` / `creation: false` are enforced, new `relativeLocation` (§5) |
+| **Bugfix**           | `healthCheck.enabled: false` leaves the health check endpoints out (§6)                                         |
+| **Breaking Changes** | None in the API. A `tus` block in `config.env.ts` that did nothing before now applies (§5)                      |
+| **Migration Effort** | Review a `tus` block in `config.env.ts` if you have one (§5.1); a proxy that renames the tus route or relative upload URLs need a look (§5.2). Regenerate a client built from `/api-docs-json` if you keep one (§4) |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update.
+
+## 1. Everything usable is documented
+
+The document is built from the running application, so it follows the server configuration and every
+project module automatically: a module that is registered appears, one that is not stays out. Three
+kinds of interface used to be invisible to `@nestjs/swagger` because they have no Nest handler:
+
+| Interface | Documented since 11.42.9 |
+| --- | --- |
+| Routes Better-Auth serves itself under `/iam` — whatever the configured plugins add (two-factor, passkey, sessions, password change, …), including plugins a project adds via `betterAuth.plugins` | from Better-Auth's own OpenAPI generator, under your Better-Auth controller (§1.1) |
+| `/ai/mcp` (MCP server, `ai.mcp`) | POST/GET/DELETE, with the bearer requirement the endpoint enforces itself |
+| MCP OAuth endpoints (`mountAiMcpOAuth()` in `main.ts`) | exactly the endpoints the call mounted (`/.well-known/…`, `/authorize`, `/token`, `/register`) |
+
+### 1.1 Better-Auth routes
+
+- Documented under your Better-Auth controller: same tags, and `operationTags` receives them with
+  `controller` set to that controller's class name (`handler` is Better-Auth's operation id).
+- Operation ids: `<Controller>_betterAuth_<betterAuthOperationId>`, e.g.
+  `BetterAuthController_betterAuth_changePassword`. Unique and stable across builds.
+- Schemas Better-Auth refers to are added as `BetterAuthUser`, `BetterAuthSession`, … so they cannot
+  collide with your own `User` model; Better-Auth's OpenAPI 3.1 constructs are converted to 3.0.
+- Security: what Better-Auth enforces. A route behind one of its session middlewares (or one of the
+  social-account routes that check the session in their handler) carries the global requirement —
+  bearer or the session cookie; every other route is public (`security: []`): sign-in, password reset,
+  get-session, the two-factor verification steps of a sign-in. Better-Auth's own generator marks every
+  route bearer-only, so this is read from the live instance, not from the generator. Routes of plugins
+  you add yourself (`admin()`, `organization()`, …) always carry the global requirement.
+- With API tokens configured they carry "API tokens: not allowed on this route" and never appear in the
+  API-token view.
+- Under a global prefix or URI versioning Better-Auth's own routes are not reachable (the API
+  middleware does not forward them); they are then not documented, and a warning says why.
+
+**Behind it:** Better-Auth exposes its generator only through its `openAPI()` plugin, so nest-server
+registers that plugin itself (`disableDefaultReference: true`). Its own route,
+`/iam/open-api/generate-schema`, is not part of your API: its endpoints are marked server-only, so
+Better-Auth never routes them and they answer 404, as before this release. If you registered `openAPI()`
+in `betterAuth.plugins` yourself, nothing changes — your registration replaces the internal one.
+
+## 2. Only what can succeed is documented
+
+A route that answers an error to every caller under the running configuration is left out. Each rule
+reads the switch the handler itself reads:
+
+| Configuration | Left out |
+| --- | --- |
+| `auth.legacyEndpoints` keeps REST closed (the default since 11.38.0) | legacy `/auth/signin`, `/auth/signup`, `/auth/logout`, `/auth/refresh-token` (they answer 410) |
+| `betterAuth.emailAndPassword.enabled: false` | `/iam/sign-in/email`, `/iam/sign-up/email` |
+| `betterAuth.emailAndPassword.disableSignUp: true` | `/iam/sign-up/email` |
+| `betterAuth.emailAndPassword.passwordReset: false` | `/iam/request-password-reset`, `/iam/reset-password`, `/iam/reset-password/{token}` |
+| Better-Auth's own options, read from the live instance — so `betterAuth.options` counts too | e.g. POST `/iam/get-session` without `session.deferSessionRefresh`, social routes without a provider, two-factor OTP routes without `otpOptions.sendOTP`, `/iam/delete-user` without `user.deleteUser.enabled`, `/iam/change-email` without `user.changeEmail.enabled`, `/iam/update-session` without session fields that accept input |
+| A Hub panel switched off (`hub.collectors.*`, `hub.mailbox`, `hub.emailPreview`, `hub.db`, `hub.migrations`) | its `*.json` endpoint and actions, which would only answer `{ available: false }` or 400 |
+
+A project controller extending a core controller is covered too — the rules go by the handler, not by
+the class name.
+
+## 3. `@ApiMethods()` for `@All()` handlers
+
+`@nestjs/swagger` documents an `@All()` handler as eight operations (GET … SEARCH), whatever it serves.
+The TUS handlers now declare theirs, so `/tus` shows POST and `/tus/{id}` HEAD/PATCH/DELETE. Use the
+decorator on your own catch-all handlers:
+
+```typescript
+import { ApiMethods } from '@lenne.tech/nest-server';
+
+@All(':id')
+@ApiMethods('get', 'delete')
+async handle(@Req() req: Request, @Res() res: Response) { … }
+```
+
+It affects the document only, never routing.
+
+## 4. Generated clients
+
+A client generated from `/api-docs-json` (hey-api, openapi-generator, …) gains functions for the newly
+documented routes and loses those for routes your configuration switches off (and the eight
+`/iam/{path}` catch-all functions since 11.42.8). Regenerate and let the compiler point at anything that
+used a removed function.
+
+## 5. TUS: the configuration takes effect
+
+### 5.1 The server configuration's `tus` key is read
+
+`TusModule.forRoot()` without a `config` of its own now reads the `tus` key of the server configuration
+(`config.env.ts`, `NSC__TUS__*`) — the zero-config rule `BetterAuthModule.forRoot()` already follows. An
+explicit `TusModule.forRoot({ config })` still wins. **Before this release that key was never read**:
+TUS ran with the defaults whatever it said.
+
+What that means for you, if `config.env.ts` has a `tus` block:
+
+| You set | Before | Now |
+| --- | --- | --- |
+| `tus: false` | TUS enabled anyway | `/tus` is not registered |
+| `allowedTypes` | every type accepted | other types answer 415 at creation |
+| `maxSize` | 50 GB | your limit (413 above it) |
+| `roles` | `[S_USER]` | your roles |
+| `termination`, `creation`, `path`, `expiration`, … | defaults | your values (see 5.2 / 5.3) |
+
+These are the values the block was written to enforce, so this is the behaviour you asked for — but it
+starts on this upgrade. Check that the allowed types cover what your clients upload before you deploy.
+
+### 5.2 `path` and upload URLs
+
+Before this release `path` only changed the URL handed to a client for a new upload (`Location`); the
+endpoint itself always stayed where the controller declared it. Every setup that works today keeps
+working:
+
+| `path` | Since 11.42.9 |
+| --- | --- |
+| unset | The upload URL is built from the path the upload was created at — so resuming now also works below a global prefix, a URI version or a project controller's own route, where it answered 404 before |
+| ends with the controller's route — `'/api/tus'` (global prefix) or `'/files/tus'` (a proxy that strips `/files`) | Unchanged: the controller stays, upload URLs use this path. This was the workaround for the old behaviour and needs no change |
+| a new route — `'/uploads'` | The controller is now mounted there (a project controller too, as `roles` already did). Before, the endpoint stayed at `/tus` while clients were sent to `/uploads/…`, so no upload could ever be resumed |
+
+Like any controller route, a new route sits below the global prefix and the URI version.
+
+Two cases need a look:
+
+- **A proxy that renames the route** (public `/files/upload` forwarded as `/tus`): `path: '/files/upload'`
+  now moves the endpoint. Remove `path` and override `uploadCollectionPath(req)` in your
+  `CoreTusService` subclass to return the public path.
+- **Relative upload URLs.** The framework now builds the upload URL itself, which takes precedence over
+  `@tus/server`'s `relativeLocation`. Use `tus.relativeLocation: true` (new); a `relativeLocation` you
+  pass to the tus server yourself — in a vendored core, for example — is honoured as well.
+
+### 5.3 Switched-off extensions are enforced
+
+`@tus/server` itself ignores the extension flags. Since this release:
+
+| Setting | Effect |
+| --- | --- |
+| `termination: false` | DELETE answers 501, OPTIONS no longer advertises `termination` |
+| `creation: false` | POST answers 501, OPTIONS no longer advertises the creation extensions |
+| `creationWithUpload: false` | a POST carrying data answers 501 |
+
+`checksum` and `concatenation` have no effect: neither built-in store supports them. The boot log now
+lists the extensions the server actually offers.
+
+## 6. `healthCheck.enabled: false`
+
+The flag was declared and ignored: any `healthCheck` object registered `GET /health-check` and the
+`healthCheck` query. `enabled: false` now leaves both out (and out of the Swagger document).
+
+## Compatibility Notes
+
+- The Swagger work changes nothing at runtime. Better-Auth's `openAPI()` plugin is now registered, but
+  kept off the router, so `/iam/open-api/*` answers 404 exactly as before. The runtime changes of this
+  release are the ones in §5 and §6.
+- A `CoreTusService` subclass that overrides `onUploadCreate()` keeps the extension checks of §5.3: they
+  run before the hook, whether or not the override calls `super`.
+- The description of Better-Auth's routes is prepared once at application bootstrap
+  (`CoreBetterAuthService.onApplicationBootstrap()`). A project service extending
+  `CoreBetterAuthService` that overrides `onApplicationBootstrap()` must call `super` to keep it.
+- An explicit `@ApiBearerAuth()` / `@ApiSecurity()` on a route the guards admit to everybody now keeps
+  its security requirement instead of being documented as public.
+
+## References
+
+- Swagger helper: `src/core/common/helpers/swagger.helper.ts`
+- Better-Auth rules: `src/core/modules/better-auth/core-better-auth-openapi.helper.ts`
+- Decorator: `src/core/common/decorators/api-methods.decorator.ts`
+- TUS: `src/core/modules/tus/tus.module.ts`, `src/core/modules/tus/core-tus.service.ts`, `src/core/modules/tus/README.md`
+- Tests: `tests/unit/swagger-helper.spec.ts`, `tests/unit/swagger-availability.spec.ts`,
+  `tests/unit/better-auth-openapi-availability.spec.ts`, `tests/better-auth-openapi.e2e-spec.ts`,
+  `tests/unit/tus-module-config.spec.ts`, `tests/tus-protocol-config.e2e-spec.ts`,
+  `tests/unit/core-module-signatures.spec.ts`

package/migration-guides/11.42.9-to-11.42.10.md

@@ -0,0 +1,111 @@
+# Migration Guide: 11.42.9 → 11.42.10
+
+## Overview
+
+| Category             | Details                                                                                                   |
+| -------------------- | --------------------------------------------------------------------------------------------------------- |
+| **Requirement**      | `engines.node` is now `>= 22.15` (was `>= 22.12`). In practice the floor already applied — see §1        |
+| **Security**         | Recommended `@graphql-tools/utils` override target moves from 12.0.1 to 12.0.3 (§2)                       |
+| **Dependencies**     | `nodemailer` 10.0.16 (bug fixes only). Dev tooling: transitive `handlebars` 4.7.10 (§3)                   |
+| **Breaking Changes** | None in the API                                                                                           |
+| **Migration Effort** | None for projects on Node ≥ 22.15. Projects that carry their own `@graphql-tools/utils` override should raise it (§2) |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update. No code or configuration change is required.
+
+## 1. Node ≥ 22.15
+
+The declared minimum Node version rises from 22.12 to 22.15. This changes the declaration, not the reality:
+`@apollo/server` resolves `@graphql-tools/schema` 10.1.3, which requests `@graphql-tools/utils ^12.0.3`, and
+that in turn requires `@whatwg-node/promise-helpers` 2 — whose own `engines` field demands Node `>=22.15.0`.
+Every fresh install of a GraphQL-enabled project has carried that requirement since those releases came out.
+The framework's `engines` field now says so instead of promising a floor its own dependency tree does not
+honour.
+
+Check the Node version wherever the server runs:
+
+```bash
+node --version   # must print v22.15.0 or newer (any Node 24 qualifies)
+```
+
+The places to look: the Docker base image (`FROM node:…`), the CI runner's Node version, and the version a
+host or PaaS pins. The starter's Dockerfile and the framework's own CI already run Node 24.
+
+## 2. `@graphql-tools/utils` override: target 12.0.3
+
+Overrides in this package's `pnpm-workspace.yaml` do not reach your project (see
+[security-overrides.md](../docs/security-overrides.md)), so a project that copied the
+`@graphql-tools/utils` entry for GHSA-7mx3-vvmw-hjmv holds its own. Until now the recommended target was
+12.0.1, because 12.0.2+ needs Node ≥ 22.15. With the framework's floor at 22.15, take the newest 12.x:
+
+```yaml
+# Before
+overrides:
+  '@graphql-tools/utils@>=12.0.0 <12.0.1': '12.0.1'
+
+# After
+overrides:
+  '@graphql-tools/utils@>=12.0.0 <12.0.3': '12.0.3'
+```
+
+```bash
+pnpm install
+pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge
+```
+
+Why it matters beyond tidiness: the key intersects the `^12.0.0` range that `@graphql-tools/schema` and
+`@graphql-tools/merge` request, so a target behind the newest 12.x holds them back too. Commit
+`pnpm-workspace.yaml` and `pnpm-lock.yaml` together — a workspace file without the re-installed lockfile fails
+every `pnpm install --frozen-lockfile`, typically in the Docker build.
+
+Afterwards `@nestjs/graphql` 13.4.5 still brings its own exact-pinned `@graphql-tools/schema` 10.1.0 /
+`merge` 9.2.3 next to the 10.1.3 / 9.2.6 that `@apollo/server` uses. That is expected: both copies share the
+single overridden `@graphql-tools/utils` 12.0.3 and the single `graphql`.
+
+Projects still on Node < 22.15 keep the 12.0.1 target until they upgrade Node.
+
+## 3. Dependency updates
+
+- **`nodemailer` 10.0.15 → 10.0.16** — bug fixes in the address parser and cookie handling, no API change.
+  A project that carries a lock-step `nodemailer` override (nest-server-starter does) should raise it to
+  `'nodemailer@<10.0.16': '10.0.16'`.
+- **`handlebars` 4.7.10 (dev tooling only)** — three advisories (GHSA-8r5x-fm3f-whwj, GHSA-p8wg-vrv2-v86f,
+  GHSA-xw65-4hp5-5hc7) reach projects through `@compodoc/compodoc`, which already allows the fixed version.
+  If `pnpm audit` reports them in your project, refresh the stale lockfile entry instead of adding an override:
+
+  ```bash
+  pnpm update --depth Infinity handlebars
+  ```
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| Projects on Node 24 (starter Dockerfile, CI) | Unaffected |
+| Projects on Node 22.12 – 22.14 | Already outside what `@graphql-tools/utils` 12.0.3 declares; upgrade Node |
+| Vendor-mode projects | The core carries no `engines` field — check the Node version of your own runtime (§1) |
+| `engine-strict=true` in `.npmrc` | Installs now fail on Node < 22.15 instead of warning |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| `pnpm install` warns `Unsupported engine` for `@whatwg-node/promise-helpers` | Node older than 22.15 | Upgrade Node (§1) |
+| `ERR_PNPM_UNSUPPORTED_ENGINE` for `@lenne.tech/nest-server` | `engine-strict` with Node < 22.15 | Upgrade Node (§1) |
+| `pnpm audit` reports `@graphql-tools/utils` after updating | Your own override still targets an older version, or an old `@graphql-tools/schema` 10.0.x pulls utils 11.x | Raise the override and refresh schema / merge (§2) |
+| `pnpm audit` reports `handlebars` via `@compodoc/compodoc` | Stale lockfile entry | `pnpm update --depth Infinity handlebars` (§3) |
+
+## Module Documentation
+
+- [Security overrides](../docs/security-overrides.md) — which overrides are load-bearing and how to write your own
+- `.claude/rules/package-management.md` — override and suppression rules
+
+## References
+
+- [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — `@graphql-tools/utils` prototype pollution
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — reference project

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.8",
+  "version": "11.42.10",
   "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",
@@ -84,10 +84,10 @@
     "url": "https://github.com/lenneTech/nest-server/issues"
   },
   "engines": {
-    "node": ">= 22.12",
+    "node": ">= 22.15",
     "pnpm": "^11.0.0"
   },
-  "packageManager": "pnpm@11.13.1+sha512.b2fc7683b8a6525414e7d13e1ba28caaddde96bf66ec540bfaeb7e702b81f3e0be4d1f295edf7f9fe0396740a8dce4509c582ddf79891f4543fea32d37645f25",
+  "packageManager": "pnpm@11.28.5+sha512.484563d30b4c2ad27cb48aa94ff2b302dbcebc8ff6bf28816c2589886e146ce7f76f354f3bc1a438e6f5e9768c302aa0a6f7add8232903cd4cf81426cbc14d9e",
   "dependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
@@ -129,7 +129,7 @@
     "mongoose": "9.10.4",
     "multer": "2.4.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "10.0.15",
+    "nodemailer": "10.0.16",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -182,9 +182,9 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1146.0",
-    "@aws-sdk/lib-storage": "3.1146.0",
-    "@aws-sdk/s3-request-presigner": "3.1146.0",
+    "@aws-sdk/client-s3": "3.1147.0",
+    "@aws-sdk/lib-storage": "3.1147.0",
+    "@aws-sdk/s3-request-presigner": "3.1147.0",
     "@better-auth/core": "1.7.7",
     "@better-auth/passkey": "1.7.7",
     "@compodoc/compodoc": "2.0.0",
@@ -203,7 +203,6 @@
     "@types/node": "26.6.4",
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
-    "ansi-colors": "4.1.3",
     "better-auth": "1.7.7",
     "bullmq": "6.3.11",
     "cross-env": "10.1.0",

package/src/core/common/decorators/api-methods.decorator.ts

@@ -0,0 +1,25 @@
+import { SetMetadata } from '@nestjs/common';
+
+/** Metadata key of {@link ApiMethods} */
+export const API_METHODS_KEY = 'lt:apiMethods';
+
+/**
+ * Lists the HTTP methods an `@All()` handler actually serves.
+ *
+ * `@nestjs/swagger` documents an `@All()` handler as eight operations (GET, POST, PUT, DELETE, PATCH,
+ * OPTIONS, HEAD, SEARCH), whatever the handler does with them. `setupSwagger()` keeps only the methods
+ * named here, so a catch-all that serves three of them is documented with three.
+ *
+ * @example
+ * ```typescript
+ * @All(':id')
+ * @ApiMethods('head', 'patch', 'delete')
+ * async handleUpload(@Req() req: Request, @Res() res: Response) { … }
+ * ```
+ * @since 11.42.9
+ */
+export const ApiMethods = (...methods: string[]) =>
+  SetMetadata(
+    API_METHODS_KEY,
+    methods.map((method) => method.toLowerCase()),
+  );