@lenne.tech/nest-server 11.42.15 → 11.43.0

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 |
@@ -178,7 +179,7 @@ JWT-based authentication for existing projects:
 | **AI Module** | Prompt orchestrator (auto + plan mode), DB-backed LLM connections, tool registry |
 | **REST Endpoints** | `POST /ai/prompt`, `POST /ai/stream` (SSE); `GET/POST/PUT/DELETE /ai/connections*`, `/ai/connections/available`, `/ai/connections/select`, `/ai/connections/preferences*`, `/ai/conversations*`, `/ai/interactions*`, `/ai/budget-limits*`, `GET /ai/usage` |
 | **GraphQL Endpoints** | `aiPrompt`, `aiAvailableConnections`, `aiSetUserConnection`, connection/preference/conversation/interaction/budget queries + mutations, `aiUsage` |
-| **MCP Server** | Streamable HTTP at `POST/GET/DELETE /ai/mcp` (Bearer auth); optional OAuth 2.1 router mounted in `main.ts` via `mountAiMcpOAuth(app)` (`/.well-known/*`, `/authorize`, `/token`, `/register`) |
+| **MCP Server** | Streamable HTTP at `POST/GET/DELETE /ai/mcp` (Bearer auth); with `ai.mcp.oauth` an OAuth 2.1 router (`/.well-known/*`, `/authorize`, `/token`, `/register`) that `CoreAiMcpOAuthInitializer` mounts during `app.init()` — an Express router behind the Nest middleware and routes, ahead of Nest's not-found handler, so guards and interceptors do not run for it; `/authorize` answers with a built-in consent page (the Better-Auth session from the middleware is the user; Allow is a CSRF-bound POST) |
 | **Permission Model** | `S_USER` for prompt/conversations/available/usage; `ADMIN` for connections/preferences/interactions/budgets; encrypted API keys never leave the server (`securityCheck` + `secretFields`) |
 
 ### Email & Templates
@@ -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.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/migration-guides/11.42.x-to-11.43.x.md

@@ -0,0 +1,195 @@
+# Migration Guide: 11.42.x → 11.43.x
+
+## Why this is a MINOR
+
+Per `.claude/rules/versioning.md` the MAJOR mirrors NestJS, so **MINOR is where breaking changes
+live**. Two behaviour changes can turn a call that used to succeed into a refusal: a browser sign-in
+or sign-up from an origin Better-Auth does not trust now answers **403** in every project (§5), and
+with `ai.mcp.oauth` enabled a deployed environment without a signing secret or without `baseUrl`
+now fails the boot instead of signing tokens with the public development key (§1, §4). So this is
+`11.43.0` rather than a patch.
+
+**Projects whose frontends sign in from `appUrl` or an origin in `cors.allowedOrigins`, and that do
+not use `ai.mcp.oauth`, see no behaviour change.** Server-side clients (scripts, seeders, SSR
+routes, API tests) are not affected either (§5).
+
+## Overview
+
+| Category             | Details |
+| -------------------- | ------- |
+| **Bugfixes**         | MCP OAuth endpoints were unreachable in every Nest application (404) — `CoreModule` now mounts them itself (§1). A refused refresh token or authorization code answers **400 `invalid_grant`** instead of **500** (§2). The MCP endpoint's 401 names the protected resource metadata, not the endpoint (§3) |
+| **New Features**     | Built-in consent page with sign-in for `/authorize` (§4); override `ai: { mcpOAuthService }` (§4); config `ai.mcp.oauthBaseUrl` (§1) and `ai.mcp.oauthLoginUrl` (§4) |
+| **Security**         | A code issued while answering a GET to `/authorize` is refused — consent must be a POST (§4). Without a signing secret, every environment except `local` / `ci` / `e2e` refuses to sign MCP tokens instead of using the public development key (§4). IAM sign-in / sign-up run Better-Auth's login-CSRF protection again (§5) |
+| **Framework API**    | New: `CoreAiMcpOAuthInitializer`, `mountAiMcpOAuthRouter()`, `renderMcpOAuthConsentPage()` + `IMcpOAuthConsentView`, `IAiMcpOAuthMountTarget`, `IAiMcpOAuthRouterOptions`, `IAiMcpOAuthConsentBinding`; on `CoreAiMcpOAuthService`: `isOAuthEnabled()`, `usesBuiltInConsent()`, protected `loadOAuthErrors()`, `renderConsentPage()`, `buildConsentView()`, `consentUser()`, `consentLoginUrl()`, `signConsentToken()`, `verifyConsentToken()`; `consumeAuthorizationCode(code, clientId?)`. `mountAiMcpOAuth()` is deprecated (a no-op once `CoreModule` mounted the router). No changed signatures |
+| **Dependencies**     | `@tus/server` 2.4.5 → 2.4.6 (typings fix). Lockfile: `follow-redirects` 1.16.0 → 1.16.1 (via `node-mailjet` → `axios`; GHSA-8r9p-f939-6h3c / GHSA-q3jh-wrc6-jgq8 — `Authorization` / `Cookie` forwarded on a cross-origin redirect). Run `pnpm update --depth Infinity follow-redirects` if your lockfile still holds 1.16.0 |
+| **Breaking Changes** | With `ai.mcp.oauth`: see "What to check" in §1 — notably a deployed environment without `baseUrl` or without a signing secret (`develop` / `test` stages included) now fails the boot. For every project: a browser sign-in from an origin not in `trustedOrigins` now answers 403 (§5) |
+| **Migration Effort** | Check that every browser origin that signs in is in `trustedOrigins` (§5). With `ai.mcp.oauth`: remove the `mountAiMcpOAuth()` call, check `NSC__BASE_URL`; the consent page comes built in (§4) |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update. **Every project:** check that each browser origin that signs in is
+trusted (§5). **With `ai.mcp.oauth: true`:** also §1 and §4.
+
+## 1. The MCP OAuth endpoints are mounted by `CoreModule`
+
+The OAuth 2.1 endpoints for MCP clients (`/.well-known/oauth-authorization-server`,
+`/.well-known/oauth-protected-resource/ai/mcp`, `/authorize`, `/token`, `/register`) are an Express router. The
+documentation said to mount it in `main.ts` **after** `app.init()`:
+
+```typescript
+// main.ts — what the documentation prescribed until 11.42.16
+await app.init();
+await mountAiMcpOAuth(app);
+```
+
+That never worked in a Nest application. Nest registers its not-found handler inside `app.init()`; a router added
+afterwards sits behind it and is never reached. Every OAuth endpoint answered Nest's 404, so no MCP client could
+discover the server, register or get a token.
+
+Since 11.43.0 `CoreAiMcpOAuthInitializer` (registered by `CoreAiModule` together with the MCP endpoint) mounts the
+router during `app.init()` whenever `ai.mcp.oauth` is `true`: behind every Nest middleware (security headers, request
+context, CORS) and the Nest routes, ahead of the not-found handler. It needs no `main.ts` code and works the same
+under `Test.createTestingModule()`. Guards and interceptors do not run for it — the SDK's handlers authenticate the
+client and rate-limit per IP themselves.
+
+```typescript
+// main.ts — remove the call; it is a no-op now and logs that it can go
+await mountAiMcpOAuth(app);
+```
+
+The protected MCP resource is described at the path Nest registered `/ai/mcp` at — global prefix and its exclusions,
+URI versioning and a `RouterModule` path included. The issuer is the server's `baseUrl`, or the new
+`ai.mcp.oauthBaseUrl` when MCP clients reach the server under another URL (its origin is added to Better-Auth's
+trusted origins automatically, so the consent page can sign users in there; it replaces the `baseUrl` option of
+`mountAiMcpOAuth()`, which is ignored with a warning once the router is mounted).
+
+**What to check:**
+
+- **A deployed environment without `baseUrl` now fails the boot** when `ai.mcp.oauth` is `true` — before, only the
+  `mountAiMcpOAuth()` call failed. Set `NSC__BASE_URL` (or `ai.mcp.oauthBaseUrl`). `local` / `ci` / `e2e` keep the
+  `http://localhost:3000` default.
+- **The endpoints now exist.** With `ai.mcp.oauth: true`, dynamic client registration (`/register`) is reachable,
+  rate-limited per IP by the SDK — configure `trustProxy` behind a proxy, or all clients share one bucket — and so is
+  the consent page (§4): users can now authorize MCP clients.
+- **CORS.** A project's `enableCors()` runs before the router, so a browser-based MCP client on an origin it does not
+  allow is refused at the preflight. Native clients (Claude Code, Claude Desktop) are unaffected.
+- **Express only.** `ai.mcp.oauth` on another HTTP adapter fails the boot with a named error.
+- **A route of your own at `/token`, `/register` or `/authorize`** now wins over the OAuth router, which comes after
+  the Nest routes.
+
+## 2. Refusals answer `400 invalid_grant`, not `500`
+
+The SDK's handlers answer an error with its OAuth code only when it is one of the SDK's own `OAuthError` classes;
+anything else becomes `500 server_error`. The provider refused with plain `Error('invalid_grant')`, so an unknown,
+rotated or foreign refresh token, or a code issued to another client, was answered with a 500. MCP clients discard
+their stored tokens only on `invalid_grant`: on a 500, Claude Code kept the dead token, retried the refresh on every
+start and never asked the user to sign in again.
+
+Now: `invalid_grant` (400) for refresh tokens and codes, `invalid_client` for a missing client, `invalid_token` from
+`verifyAccessToken`, and `access_denied` when an API token tries to approve a consent (the client is redirected back
+with `error=access_denied` instead of `server_error`). `verifyAccessToken` also returns `expiresAt`, which the SDK's
+bearer middleware requires. A code presented by another client is no longer deleted on the way to the refusal: the
+exchange consumes only a code issued to the presenting client (`consumeAuthorizationCode(code, clientId)`), so the
+owner can still redeem it.
+
+**What to check:** code that matched the error MESSAGE (`/invalid_grant/`) — the code is in `error.errorCode` now, the
+message is a description. An `authorizeConsent()` of your own must refuse the same way:
+
+```typescript
+const { AccessDeniedError } = await this.loadOAuthErrors();
+throw new AccessDeniedError('The user declined');
+```
+
+## 3. The MCP 401 points at the metadata document
+
+`POST /ai/mcp` without credentials answered `WWW-Authenticate: Bearer resource_metadata="<request host>/ai/mcp"` — the
+endpoint itself, built from the caller-controlled `Host` header. RFC 9728 §5.1 wants the URL of the protected resource
+METADATA. It is now exactly the document the mounted router serves
+(`https://api.example.com/.well-known/oauth-protected-resource/ai/mcp`), and a plain `Bearer` without OAuth, where no
+such document exists.
+
+**What to check:** a test or client that parsed the old header value.
+
+## 4. A built-in consent page
+
+`/authorize` needs a consent step: the page on which a user decides whether an MCP client may act for them. The
+documentation told projects to override `authorizeConsent()` for it, but `CoreAiModule` offered no way to register a
+subclass, so no project had one and no authorization could ever complete. The framework now brings the page itself:
+
+- **Nobody signed in** → e-mail + password and the two-factor step (TOTP or backup code), against Better-Auth's own
+  endpoints on the API origin, then a reload of the pending request. Passkey and social login through the app's login
+  page: `ai.mcp.oauthLoginUrl`, default `<appUrl>/auth/login`, opened next to the consent page. A user already signed in
+  to the API origin skips this.
+- **Signed in** → the account first (with "use another account"), which client asks, where the code goes; Allow /
+  Deny as a form POST. Allow counts only after intent on the page (visible, focused, a pointer move / key / touch at
+  least 600 ms later), against double-clickjacking; without JavaScript nothing can be approved.
+- **Allow** issues the code only with the page's CSRF token, signed and bound to user, client, redirect URI and PKCE
+  challenge (10 minutes). **Deny** → `access_denied`.
+
+The page sets its own CSP (nonces, `frame-ancestors 'none'`), `X-Frame-Options: DENY` and `Cache-Control: no-store`,
+escapes every value from outside (the client's name comes from whoever registered it), and speaks German to a German
+browser. It needs Better-Auth active; without it the boot warns.
+
+**A signed-in session is not consent.** Dynamic registration is open, so anybody can register a client with their own
+redirect URI and start the flow — PKCE is then theirs too. A GET to `/authorize` is what any link produces, and it
+carries the SameSite=Lax session cookie. The framework therefore refuses a code saved while answering a GET to
+`/authorize`: the client is sent back with `error=server_error`, and the server log names the refusal. That applies to
+a consent page of your own as well.
+
+**Your own page** (optional): override `renderConsentPage(view)` to restyle, or `authorizeConsent(client, params, res)`
+to replace it, and register the subclass:
+
+```typescript
+CoreModule.forRoot(envConfig, { ai: { mcpOAuthService: McpOAuthService } })
+```
+
+Two checks stay outside the overridable methods: an API token can never approve a consent, and the production secret
+check runs again before the endpoints are mounted. Without a signing secret, every environment except `local`, `ci` and
+`e2e` now refuses to boot with `ai.mcp.oauth` — and refuses to sign or verify tokens at all — instead of falling back
+to the public development key. That includes the DEPLOYED `develop` and `test` stages of a starter-based project:
+before, anybody who knew a user id could forge that user's MCP access token there.
+
+## 5. IAM sign-in and sign-up run Better-Auth's login-CSRF protection
+
+Better-Auth protects `sign-in/email` and `sign-up/email` itself (`formCsrfMiddleware`): it refuses a cross-site
+navigation (`Sec-Fetch-Site: cross-site` + `Sec-Fetch-Mode: navigate`, i.e. a form a hostile page submits) and checks
+a present `Origin` / `Referer` against `trustedOrigins`. It reads both from the request — and
+`CoreBetterAuthController` called `api.signInEmail()` / `api.signUpEmail()` without one, so the check never ran. A
+hostile page could sign a visitor in to an account of the attacker's choosing (login CSRF); whatever the visitor did
+next, approving an MCP client on the consent page included, happened in the attacker's account.
+
+The controller now hands Better-Auth those headers (`Origin`, `Referer`, `Sec-Fetch-*` — not the cookie, see below). A
+refused request answers **403** (`#LTNS_0101`, `ErrorCode.ACCESS_DENIED`) instead of a session, and the server logs the reason.
+
+**What to check:**
+
+- **Every origin that signs in from a browser must be trusted.** Trusted by default: the API's own origin, `appUrl`,
+  every origin in `cors.allowedOrigins` (merged with `appUrl` and `baseUrl`) and, with `ai.mcp.oauth`, the origin of
+  `ai.mcp.oauthBaseUrl`. A frontend on any other origin — a second web app, a native app's web view
+  (`capacitor://localhost`, `http://localhost`), a preview deployment — now answers 403 where it used to succeed.
+  Add it to **`cors.allowedOrigins`**; it needs that entry for credentialed CORS anyway. `cors.allowAll: true` does not
+  trust arbitrary origins for sign-in — an origin check has no "allow everything" mode.
+- **Do not reach for `betterAuth.trustedOrigins` for this unless you list everything.** An explicit list REPLACES the
+  derived one: `['capacitor://localhost']` alone stops trusting `appUrl` and `cors.allowedOrigins`, and every sign-in from
+  the main web app then answers 403 — with the project's test suite still green (see "Test runners" below). If you set
+  it, include `appUrl` and every other frontend origin.
+- **Non-browser clients are unaffected:** a request without `Origin`, `Referer` and `Sec-Fetch-Site` (server-to-server,
+  API tests, mobile HTTP clients, scripts and SSR routes using Node's built-in `fetch`) is not checked. Node's `fetch`
+  sends a lone `Sec-Fetch-Mode: cors`; that is not a browser signal and is not forwarded, because Better-Auth would read
+  it as a browser request missing its origin. The cookie is deliberately not forwarded either: its presence alone makes
+  Better-Auth demand an `Origin`, which would refuse such clients when they keep a cookie jar.
+- **Test runners:** Better-Auth skips this check under a test runner by default (`isTest()`), so project test suites
+  behave as before; set `betterAuth.options.advanced.disableOriginCheck: false` in a spec that must see production
+  behaviour.
+- A subclass overriding `signIn()` / `signUp()` that calls `super` keeps the protection; one that calls
+  `api.signInEmail()` itself should pass `request: this.csrfCheckedRequest(req, '/sign-in/email')` and
+  `asResponse: false` the same way.
+
+## Module Documentation
+
+- [AI module README — OAuth 2.1](../src/core/modules/ai/README.md)
+- [AI module integration checklist — MCP OAuth 2.1](../src/core/modules/ai/INTEGRATION-CHECKLIST.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.15",
+  "version": "11.43.0",
   "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",
@@ -105,7 +105,7 @@
     "@nestjs/swagger": "11.4.7",
     "@nestjs/terminus": "11.1.1",
     "@tus/file-store": "2.1.1",
-    "@tus/server": "2.4.5",
+    "@tus/server": "2.4.6",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "class-transformer": "0.5.1",
@@ -193,7 +193,7 @@
     "@nestjs/testing": "11.2.7",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.16.18",
-    "@tus/s3-store": "2.0.7",
+    "@tus/s3-store": "2.0.8",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
@@ -202,15 +202,15 @@
     "@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.15",
+    "bullmq": "6.3.16",
     "cross-env": "10.1.0",
     "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.2",
-    "oxfmt": "0.72.0",
+    "oxfmt": "0.73.0",
     "oxlint": "1.88.0",
     "rimraf": "6.1.3",
     "smtp-server": "3.19.23",
@@ -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",