@lenne.tech/nest-server 11.42.14 → 11.42.16

package/docs/REQUEST-LIFECYCLE.md

@@ -107,6 +107,7 @@ JWT-based authentication for existing projects:
 | **Security Check Interceptor** | Calls `securityCheck()` + removes secret fields |
 | **Response Filter Interceptor** | Enforces `@Restricted()` field-level access |
 | **Translation Interceptor** | Applies `_translations` based on `Accept-Language` |
+| **CastError Filter** | `MongooseCastErrorFilter` (`APP_FILTER`, 11.42.16): a malformed id from a route parameter answers 404, one from the query string or an update/filter body 400, instead of an unhandled 500 (a create body raises `ValidationError` and stays a 500); a cast failure on a value the request does not contain stays a 500. See "Malformed ids: 404 / 400, not 500" below |
 | **Secret Fields Removal** | Configurable fallback removal of password, tokens, etc. |
 | **RequestContext** | `AsyncLocalStorage`-based context for current user in Mongoose hooks. `fromRequest` (11.42.0) marks a context created for a CLIENT operation (HTTP middleware, GraphQL WebSocket), so service-level checks such as `assertTenantRole()` tell an anonymous request apart from system work |
 | **Query Complexity** | GraphQL query complexity analysis to prevent DoS |
@@ -1215,6 +1216,33 @@ throw accessDeniedException(currentUser);
 See `src/core/common/exceptions/access-denied.exception.ts` and
 `migration-guides/11.27.7-to-11.28.0.md`.
 
+### Malformed ids: 404 / 400, not 500 (v11.42.16+)
+
+A malformed id reaches Mongoose, which throws `mongoose.Error.CastError`. That is not an
+`HttpException`, so it escapes `HttpExceptionLogFilter` (`@Catch(HttpException)`), and Nest used to
+answer **500** for what is simply "this resource does not exist". `CoreModule` registers
+`MongooseCastErrorFilter` as `APP_FILTER`; it decides by where the failing value came from:
+
+| Value of the failed cast | REST | GraphQL |
+|--------------------------|------|---------|
+| a route parameter (`GET /users/not-an-id`) / a top-level argument (`getUser(id: …)`) | **404** `ErrorCode.RESOURCE_NOT_FOUND` | same |
+| the query string or the body / nested in an input object | **400** `ErrorCode.INVALID_FIELD_FORMAT [<path>]` | same |
+| not in the request — a broken stored id, a value computed by server code | **500**, Nest's own body and log line | unchanged (Nest rethrows) |
+
+The third row is deliberate: that cast failure is a data or code defect, and answering it as a client
+error would hide it from monitoring. The Mongoose message never reaches the client — it names the
+model. Opt out with `security.mongooseCastErrorFilter: false`.
+
+Mongoose throws `CastError` only while casting a **query or an update** — `findById`, filters,
+`findByIdAndUpdate` / `updateOne` (the path `CrudService.update()` takes). Two neighbours are not
+covered and stay a 500:
+
+- a malformed id in a document being **created or saved** (`save()`, `Model.create()`, `insertMany()`
+  — the path `CrudService.create()` takes) arrives as a `ValidationError` wrapping the CastError;
+  validate reference ids in the input (`validator: () => [IsMongoId()]` on the `@UnifiedField`);
+- a `BSONError` from `new Types.ObjectId(bad)` in service code carries no value to classify; validate
+  such ids in the service, as `CoreFileService.isMalformedFileId()` does.
+
 ### Depth-Based Optimization (v11.23.0+)
 
 When `process()` is called from within another `process()` call (service cascades like A.create → B.create → C.create), steps 4–6 are **conditionally skipped** on inner calls to avoid redundant work:
@@ -1643,6 +1671,7 @@ All security features are configured in `config.env.ts` under the `security` key
 | `security.checkSecurityInterceptor` | `boolean \| object` | `true` | Enable securityCheck() calls |
 | `security.mapAndValidatePipe` | `boolean \| object` | `true` | Enable input validation |
 | `security.mapAndValidatePipe.nonWhitelistedFields` | `'strip' \| 'error' \| false` | `'strip'` | Whitelist behavior |
+| `security.mongooseCastErrorFilter` | `boolean` | `true` | Malformed request ids answer 404 / 400 instead of 500 |
 
 ### Safety Net — Mongoose Plugins
 

package/docs/security-overrides.md

@@ -64,13 +64,14 @@ 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 the newest 12.x, so the caret requesters (@graphql-tools/schema / merge) are not held back.
+  # Target the newest 12.x, so the caret requesters (@graphql-tools/schema / merge) are not held back —
+  # @graphql-tools/schema 10.1.5 requests ^12.1.0, so a lower target leaves a second copy in the tree.
   # 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
   # Remove once @nestjs/graphql pins >=12.0.1 in the major you use.
-  '@graphql-tools/utils@>=12.0.0 <12.0.3': '12.0.3'
+  '@graphql-tools/utils@>=12.0.0 <12.1.0': '12.1.0'
 ```
 
 ### Retired: `@hono/node-server` (removed 2026-08-22, nest-server 11.36.1)

package/migration-guides/11.42.14-to-11.42.15.md

@@ -0,0 +1,117 @@
+# Migration Guide: 11.42.14 → 11.42.15
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | No framework code changes; security release of the runtime dependency `undici` (§3)                     |
+| **New Features**     | None                                                                                                     |
+| **Framework API**    | Unchanged — no new exports, no changed signatures                                                        |
+| **Dependencies**     | `mongoose` 9.10.4 → 9.11.2 and `mongodb` 7.6.0 → 7.7.0 (both `dependencies`, raised together, §1); **`undici` 7.30.0 → 7.30.1 (security release, §3)**; `nodemailer` 10.1.0 → 10.1.2; `@getbrevo/brevo` 6.0.3 → 6.2.0; overrides `@graphql-tools/utils` → 12.0.4, `undici` → 7.30.1, `qs` → 6.16.1 |
+| **Breaking Changes** | None                                                                                                     |
+| **Migration Effort** | Low, but **one step is required**: a project that keeps `mongodb` in `devDependencies` (the starter default) MUST raise it to 7.7.0 — by hand, or with the starter's new update script — or sign-in fails with 401 (§1). Typed `lean()` / `bulkWrite()` code may need a type adjustment (§2) |
+
+## Quick Migration
+
+```bash
+pnpm run update            # starter-based projects: raises every pin the framework raised
+pnpm why mongodb           # must show ONE version: 7.7.0
+```
+
+If `pnpm why mongodb` lists 7.6.0 next to 7.7.0, raise the project's own `mongodb` entry to `7.7.0` (§1). If your
+project has its own `undici` override, raise it to 7.30.1 (§3) — `pnpm audit` does not flag this one yet.
+
+Vendor-mode projects pick up the core with `/lt-dev:backend:update-nest-server-core`; raise `mongoose` and `mongodb`
+in the project's `package.json` to the versions above in the same step.
+
+## 1. mongoose 9.11 and mongodb 7.7 move together
+
+mongoose 9.11.x requires `mongodb ~7.7`, so both are raised in this release. nest-server declares `mongodb` under
+`dependencies`. nest-server-starter keeps it under `devDependencies` — and that pin is **not test-only**: Better-Auth's
+MongoDB adapter (`@better-auth/mongo-adapter`, used by nest-server's IAM module) resolves its `mongodb` peer from the
+project's own `mongodb` entry, in the production image too.
+
+Until this release, `pnpm run update` (the starter's `extras/sync-packages.mjs`) raised a pin only when the framework
+declared it **in the same section**. A project with `mongodb` in `devDependencies` therefore stayed on 7.6.0 while the
+framework's mongoose brought 7.7.0: two driver copies. Where the project's lockfile still holds the older `bson` for
+the old driver (any lockfile not refreshed since bson 7.3), there are two `bson` copies as well. The adapter checks ids
+with `instanceof ObjectId` against ITS driver's bson, the ids come from the framework's — so the check fails, the
+adapter throws `MongoAdapterError: Invalid id value`, and authenticated requests answer **401**. With a single shared
+bson it stays a typing problem in tests (`Db` / `MongoClient` from the test helpers no longer match the project's own
+import). Neither is acceptable, and which one a project gets depends on its lockfile history, so raise the pin.
+
+The starter's update script now raises a package the framework **ships** (`dependencies`) in whichever section the
+project keeps it. A package the framework only develops and tests with (`devDependencies`) still raises only the
+project's own `devDependencies` — never a runtime pin. That keeps the better-auth trio where it belongs: the framework
+holds it as devDependencies (its test versions, with a peer range as the contract), the project holds it as
+dependencies and owns that version, because its api and app must resolve the same better-auth. The rule lives in
+`extras/align-package-versions.mjs`, and nest-server's consumer gate (`pnpm run check:consumer`) applies the identical
+rule before every release.
+
+**What to do:**
+
+- **Your project still has the old `extras/sync-packages.mjs`:** raise `mongodb` to `7.7.0` by hand (also
+  `json-to-graphql-query`, if you keep it in `devDependencies` and it lags), or copy `extras/sync-packages.mjs` and
+  `extras/align-package-versions.mjs` from nest-server-starter. **This step is required** — skipping it breaks sign-in.
+- **Your project has `mongodb` in `dependencies`:** `pnpm run update` already raised it; nothing to do.
+- **Check either way:** `pnpm why mongodb` must list exactly one version.
+
+## 2. mongoose 9.11 type changes
+
+No runtime behaviour your code relies on changed, but two typing changes can surface in a project's own code:
+
+- `lean()` now passes its result type into the query, so a `lean<T>()` result is narrowed to `T`. Code that assigned
+  the result to an incompatible type now gets a compile error instead of a silent mismatch.
+- `UpdateOneModel` / `UpdateManyModel` (`bulkWrite()` operations) are typed like `UpdateQuery`. An update document that
+  was accepted by the looser type may now need its operators spelled out (`$set`, `$push`, …).
+
+Runtime fixes that come along (no action needed): validators on document arrays under nested paths no longer run
+twice, `bulkWrite()` casts array filter values, cursors await driver cleanup on destroy. The mongodb 7.7 driver
+recovers from a failed OIDC token fetch instead of failing every later operation on that client.
+
+## 3. undici 7.30.1 is a security release
+
+undici 7.30.1 fixes four high and four medium advisories (GHSA-qrxm-fqhp-jwvm, GHSA-2m5v-pch6-74hx,
+GHSA-4w7w-5xrc-9h26, GHSA-xjj6-f33q-929c high; GHSA-55wc-3pg8-jfw6, GHSA-f72v-6w45-q472, GHSA-4qv8-2p9j-2685,
+GHSA-9fm3-97px-rjf6 medium). They were published as repository advisories, so **`pnpm audit` does not report them
+yet** — a green audit says nothing about this release. nest-server uses undici at runtime for `outboundFetch()` (the
+SSRF-guarded fetch for user-entered URLs), and one of the fixes concerns function-valued Agent options, which that
+helper's guarded connector is.
+
+**What to do:**
+
+- **Nothing for nest-server's own dependency** — `pnpm run update` raises it.
+- **Your project carries its own `undici` override** (starter-derived projects do, for the
+  `@compodoc/compodoc > cheerio > undici` path): raise key and target together, e.g.
+  `'undici@>=7.0.0 <7.30.0': 7.30.0` → `'undici@>=7.0.0 <7.30.1': 7.30.1`. The old entry would otherwise keep that path
+  on the vulnerable 7.30.0, because cheerio's `^7.19.0` intersects the old key.
+- **Check:** `pnpm why undici` lists only 7.30.1.
+
+Also raised in the same way (no advisory, removes a hold-back): `qs` override `<6.16.0` → `<6.16.1` (6.16.1), and
+`nodemailer` 10.1.2, which strips credentials on a cross-origin redirect.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| `mongodb` in `dependencies` of the project | Raised by `pnpm run update` as before |
+| `mongodb` in `devDependencies` of the project (starter default) | Raised only by the new update script — otherwise raise by hand, **required** (§1) |
+| better-auth / `@better-auth/*` in the project's `dependencies` | Never raised from the framework's devDependencies — the project owns that version, as before |
+| `lean<T>()` with an explicit result type | May need a type adjustment (§2) |
+| `bulkWrite()` with typed `updateOne` / `updateMany` operations | May need operators spelled out (§2) |
+| Routes with `@Roles()` + `@UseGuards(AuthGuard(BETTER_AUTH))` | Unchanged. nest-server-starter dropped these redundant guards from its `UserController`; removing them in your project is optional |
+
+## Troubleshooting
+
+**Sign-in or every authenticated request answers 401, the log shows `MongoAdapterError: Invalid id value`**
+Two mongodb (and bson) versions are installed, and Better-Auth's MongoDB adapter uses the project's older one.
+`pnpm why mongodb` shows both; raise the project's own `mongodb` entry to 7.7.0, run `pnpm install`, and rebuild the
+image (§1).
+
+**Type errors around `Db`, `MongoClient` or `Collection` in tests after the update**
+Same cause, same fix: two mongodb versions are installed. Raise the project's own entry to 7.7.0 and run
+`pnpm install`.
+
+## Module Documentation
+
+- [nest-server-starter `extras/align-package-versions.mjs`](https://github.com/lenneTech/nest-server-starter/blob/main/extras/align-package-versions.mjs)

package/migration-guides/11.42.15-to-11.42.16.md

@@ -0,0 +1,114 @@
+# Migration Guide: 11.42.15 → 11.42.16
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | A malformed id in a route parameter answers **404** instead of **500**; one in the query string or an update body **400** (§1) |
+| **New Features**     | `MongooseCastErrorFilter`, registered automatically; opt-out `security.mongooseCastErrorFilter: false` (§1) |
+| **Framework API**    | New exports: `MongooseCastErrorFilter`, `classifyHttpCastError()`, `classifyGraphQlCastError()`, `castErrorCandidates()`, `containsCastValue()`, type `CastErrorOrigin`. No changed signatures |
+| **Dependencies**     | Development tooling only: `vitest` / `@vitest/coverage-v8` 4.1.11 → 4.1.12 (security, §2), `oxfmt` 0.72.0 → 0.73.0; override `@graphql-tools/utils` → 12.1.0 (§2). Runtime dependencies and peer ranges unchanged |
+| **Breaking Changes** | None. Status codes change from 500 to 404 / 400 for requests that were already failing (§1)              |
+| **Migration Effort** | None for most projects. Check tests or clients that expected a 500 for a malformed id (§1)               |
+
+## 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 — the filter is
+registered by `CoreModule`, so neither `main.ts` nor test setups built with `Test.createTestingModule()` need a new
+line.
+
+## 1. Malformed ids answer 404 / 400 instead of 500
+
+A malformed id in a route parameter (`GET /users/not-an-id`, `/ai/connections/abc`) reached Mongoose, which throws
+`mongoose.Error.CastError`. That is not an `HttpException`, so it escaped `HttpExceptionLogFilter`
+(`@Catch(HttpException)`) and Nest answered **500 Internal server error** for what is simply "this resource does not
+exist". In a typical project that affected every `:id` route, including the framework's own `/users/:id` and the AI
+module's routes.
+
+`CoreModule` now registers `MongooseCastErrorFilter` as `APP_FILTER`. It decides by where the value that failed to
+cast came from:
+
+| Value of the failed cast | REST | GraphQL |
+| ------------------------ | ---- | ------- |
+| a route parameter / a top-level argument (`getUser(id: …)`) | **404** `#LTNS_0400: Resource not found` | same |
+| the query string or an update / filter body / a value nested in an input | **400** `#LTNS_0302: Invalid field format [<path>]` | same |
+| not in the request (a broken stored id, a value computed by server code) | **500**, unchanged — Nest's body, logged as an error | unchanged |
+
+The third row is deliberate: a cast failure on a value the request does not contain is a data or code defect, and
+answering it as a client error would hide it from monitoring. The Mongoose message is never sent to the client — it
+names the model. REST bodies have the same shape as every other error `HttpExceptionLogFilter` answers.
+
+**What to check:**
+
+- **A test or client expected 500 for a malformed id:** it now gets 404 (route parameter) or 400 (query / body).
+  A well-formed id that matches nothing keeps answering 404 as before, so 404 now means the same for both.
+- **A project filter already handled `CastError`:** a catch-all filter registered with `app.useGlobalFilters()` is
+  consulted before this one and keeps winning. One registered as `APP_FILTER` in the project's root module is
+  consulted after it — set `security.mongooseCastErrorFilter: false` if your own filter must see every `CastError`
+  (for example a Sentry filter that reports them).
+- **You want the previous behaviour:** `security.mongooseCastErrorFilter: false` restores the 500.
+
+**Not covered — both stay a 500:**
+
+- A malformed id in a document being **created** (`save()`, `Model.create()`, `insertMany()` — the path
+  `CrudService.create()` takes). Mongoose reports that as a `ValidationError` wrapping the `CastError`. Validate
+  reference ids in the input instead:
+
+  ```typescript
+  import { IsMongoId } from 'class-validator';
+
+  @UnifiedField({ isOptional: true, type: () => String, validator: () => [IsMongoId()] })
+  owner?: string = undefined;
+  ```
+
+- A `BSONError` from `new Types.ObjectId(bad)` in service code. It carries no value to classify; check the id
+  before converting it, as `CoreFileService.isMalformedFileId()` does.
+
+## 2. Development tooling and the `@graphql-tools/utils` override
+
+Nothing here reaches the published package's runtime dependencies. Worth mirroring in your own project:
+
+- **`vitest` and `@vitest/coverage-v8` 4.1.12** fix two `@vitest/mocker` advisories published on 2026-10-16
+  (GHSA-qxg6-89mg-rqv8, GHSA-xp26-3454-mjgp, both medium). Development tooling only. `pnpm audit` may not list them
+  yet, so raise both together without waiting for it: `@vitest/coverage-v8` peer-requires the exact vitest version.
+- **`@graphql-tools/utils` override:** if your project carries its own entry for GHSA-7mx3-vvmw-hjmv (overrides do
+  not reach consumers, so many do), raise it:
+
+  ```yaml
+  # pnpm-workspace.yaml
+  overrides:
+    '@graphql-tools/utils@>=12.0.0 <12.1.0': '12.1.0'   # was: '<12.0.3': '12.0.3' / '<12.0.4': '12.0.4'
+  ```
+
+  The old target still clears the advisory, but `@graphql-tools/schema` 10.1.5 (pulled in by `@apollo/server`)
+  requests `^12.1.0`, so a lower target leaves two copies of `@graphql-tools/utils` in the tree.
+  See [`docs/security-overrides.md`](../docs/security-overrides.md).
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| `main.ts` with `app.useGlobalFilters(new HttpExceptionLogFilter())` | Unchanged; both filters coexist (they catch different classes) |
+| A project catch-all filter via `app.useGlobalFilters()` | Unchanged; it still sees every `CastError` |
+| A project catch-all filter as `APP_FILTER` in the root module | No longer sees `CastError` — opt out if it must (§1) |
+| Tests built with `Test.createTestingModule({ imports: [ServerModule] })` | Get the filter automatically |
+| `security.mongooseCastErrorFilter: false` | Previous behaviour (500) |
+
+## Troubleshooting
+
+**A malformed id still answers 500**
+Check where it fails. A create path raises `ValidationError` (see "Not covered" above); a `new Types.ObjectId(bad)` in
+service code raises `BSONError`; a value from a header or from stored data is not in the request and stays a 500 on
+purpose. The server log names the cast at debug level (`MongooseCastErrorFilter`) when the filter answered 404 / 400.
+
+**A 400 names a field the client did not send**
+The path in brackets is the schema path Mongoose failed to cast. For a filter on `id` it reads `[_id]`.
+
+## Module Documentation
+
+- [Request lifecycle](../docs/REQUEST-LIFECYCLE.md) — "Malformed ids: 404 / 400, not 500"
+- Implementation: `src/core/common/filters/mongoose-cast-error.filter.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.14",
+  "version": "11.42.16",
   "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",
@@ -91,7 +91,7 @@
   "dependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
-    "@getbrevo/brevo": "6.0.3",
+    "@getbrevo/brevo": "6.2.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@nestjs/apollo": "13.4.5",
     "@nestjs/common": "11.2.7",
@@ -125,11 +125,11 @@
     "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
-    "mongodb": "7.6.0",
-    "mongoose": "9.10.4",
+    "mongodb": "7.7.0",
+    "mongoose": "9.11.2",
     "multer": "2.4.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "10.1.0",
+    "nodemailer": "10.1.2",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -137,7 +137,7 @@
     "rxjs": "7.8.2",
     "supertest": "7.3.1",
     "ts-morph": "28.0.0",
-    "undici": "7.30.0",
+    "undici": "7.30.1",
     "ws": "8.21.3",
     "yuml-diagram": "1.2.0"
   },
@@ -182,9 +182,9 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1149.0",
-    "@aws-sdk/lib-storage": "3.1149.0",
-    "@aws-sdk/s3-request-presigner": "3.1149.0",
+    "@aws-sdk/client-s3": "3.1152.0",
+    "@aws-sdk/lib-storage": "3.1152.0",
+    "@aws-sdk/s3-request-presigner": "3.1152.0",
     "@better-auth/core": "1.7.7",
     "@better-auth/passkey": "1.7.7",
     "@compodoc/compodoc": "2.0.0",
@@ -202,18 +202,18 @@
     "@types/multer": "2.3.0",
     "@types/node": "26.6.5",
     "@types/passport": "1.0.17",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/coverage-v8": "4.1.12",
     "better-auth": "1.7.7",
-    "bullmq": "6.3.12",
+    "bullmq": "6.3.15",
     "cross-env": "10.1.0",
     "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.2",
-    "oxfmt": "0.71.0",
-    "oxlint": "1.87.0",
+    "oxfmt": "0.73.0",
+    "oxlint": "1.88.0",
     "rimraf": "6.1.3",
-    "smtp-server": "3.19.21",
+    "smtp-server": "3.19.23",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
     "tsx": "4.23.15",
@@ -222,7 +222,7 @@
     "unplugin-swc": "2.0.0",
     "vite": "8.3.4",
     "vite-plugin-node": "8.0.0",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",