@lenne.tech/nest-server 11.42.16 → 11.43.0

package/docs/REQUEST-LIFECYCLE.md

@@ -179,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

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.16",
+  "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",
@@ -204,7 +204,7 @@
     "@types/passport": "1.0.17",
     "@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",

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

@@ -60,8 +60,8 @@ import type { ISwaggerApiTokenViewOptions, ISwaggerSetupOptions } from '../inter
  * - With multi-tenancy on, every operation that reads the tenant header documents it as a parameter.
  * - The routes Better-Auth serves itself (two-factor, passkey, sessions, password change, … — whatever the
  *   configured plugins add) are documented from Better-Auth's own OpenAPI generator, under the project's
- *   Better-Auth controller (since 11.42.9); so are `/ai/mcp` and the MCP OAuth endpoints
- *   `mountAiMcpOAuth()` mounted.
+ *   Better-Auth controller (since 11.42.9); so are `/ai/mcp` and the MCP OAuth endpoints that are
+ *   actually mounted (by `CoreModule` when `ai.mcp.oauth` is enabled).
  * - Only what can succeed under the running configuration is documented (since 11.42.9): an `@All()`
  *   handler keeps the methods `@ApiMethods()` names; legacy `/auth/*` disappears while
  *   `auth.legacyEndpoints` keeps REST closed; Better-Auth routes disappear when the configuration or the
@@ -437,8 +437,8 @@ function declaresSecurity(reference: IHandlerReference): boolean {
 }
 
 /**
- * Documents the MCP OAuth 2.1 endpoints `mountAiMcpOAuth()` mounted on Express — the ones it mounted,
- * nothing else. They authenticate the client themselves, so they carry no security requirement.
+ * Documents the MCP OAuth 2.1 endpoints mounted on Express (`CoreAiMcpOAuthInitializer`, or a manual
+ * `mountAiMcpOAuth()`) — the ones mounted, nothing else. They authenticate the client themselves, so they carry no security requirement.
  */
 function addMcpOAuthRoutes(
   document: OpenAPIObject,

package/src/core/common/interfaces/server-options.interface.ts

@@ -2114,12 +2114,36 @@ export interface IAi {
    * external MCP clients. Requires `@modelcontextprotocol/sdk`. Boolean shorthand.
    *
    * `oauth: true` additionally enables the OAuth 2.1 layer (dynamic client
-   * registration + PKCE) so generic MCP clients can authenticate; mount the OAuth
-   * router in `main.ts` via `mountAiMcpOAuth(app)` (see INTEGRATION-CHECKLIST).
-   * Without it, MCP authenticates via the existing Bearer/session token.
+   * registration + PKCE) so generic MCP clients can authenticate. `CoreModule` mounts
+   * its endpoints (`/.well-known/oauth-*`, `/authorize`, `/token`, `/register`) during
+   * `app.init()` — no `main.ts` code (11.43.0+). The issuer is `oauthBaseUrl`, else
+   * the server's `baseUrl`; a deployed environment with neither fails the boot. `/authorize`
+   * answers with a built-in consent page: sign-in through Better-Auth (password + 2FA),
+   * then Allow / Deny. Replace it via `CoreModule.forRoot(env, { ai: { mcpOAuthService } })`.
+   * Without `oauth`, MCP authenticates via the existing Bearer/session token.
    * @default false
    */
-  mcp?: boolean | { enabled?: boolean; oauth?: boolean; oauthSecret?: string };
+  mcp?:
+    | boolean
+    | {
+        enabled?: boolean;
+        oauth?: boolean;
+        /**
+         * Public base URL of this server for the OAuth issuer and the MCP resource, when MCP
+         * clients reach it under a different URL than `baseUrl`. Blank counts as unset.
+         * @default the server's `baseUrl` (`http://localhost:3000` in local / ci / e2e)
+         */
+        oauthBaseUrl?: string;
+        /**
+         * The app's login page, linked from the consent page for sign-in methods it does not
+         * offer itself (passkey, social login). A `{returnTo}` in it is replaced by the URL of the
+         * pending `/authorize` request, for a login page that sends the user back by itself;
+         * without it the link opens next to the consent page, which then offers "continue".
+         * @default `<appUrl>/auth/login` when an app URL can be resolved
+         */
+        oauthLoginUrl?: string;
+        oauthSecret?: string;
+      };
 
   /** Rate limiting for prompts. */
   rateLimit?: IAiRateLimit;
@@ -4559,10 +4583,11 @@ interface IBetterAuthWithoutPasskey extends IBetterAuthBase {
    * Trusted origins for CORS configuration.
    *
    * Optional when Passkey is disabled.
-   * If not set, all origins are allowed (CORS `*`).
+   * If not set, it is derived (see below) — never "all origins": an origin check has no such mode.
    *
-   * Auto-derived from `baseUrl` and `appUrl` when these are configured.
-   * Explicitly listed origins are merged with the auto-derived ones.
+   * Auto-derived when not set: `appUrl`, `baseUrl` and `cors.allowedOrigins` (plus the passkey
+   * origins and, with `ai.mcp.oauth`, the origin of `ai.mcp.oauthBaseUrl`). An explicit list
+   * REPLACES the derived one — include `appUrl` and every frontend origin, or their sign-ins answer 403.
    *
    * **Important for cross-subdomain setups:** When using `crossSubDomainCookies`,
    * cookies are shared across subdomains, but the server also needs to accept requests
@@ -4621,8 +4646,9 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
    * Passkey uses `credentials: 'include'` which requires explicit CORS origins.
    * Browsers don't allow wildcard `*` with credentials.
    *
-   * Auto-derived from `baseUrl` and `appUrl` when these are configured.
-   * Explicitly listed origins are merged with the auto-derived ones.
+   * Auto-derived when not set: `appUrl`, `baseUrl` and `cors.allowedOrigins` (plus the passkey
+   * origins and, with `ai.mcp.oauth`, the origin of `ai.mcp.oauthBaseUrl`). An explicit list
+   * REPLACES the derived one — include `appUrl` and every frontend origin, or their sign-ins answer 403.
    *
    * **Important for cross-subdomain setups:** When using `crossSubDomainCookies`,
    * cookies are shared across subdomains, but the server also needs to accept requests
@@ -4703,6 +4729,7 @@ export interface ICoreModuleOverrides {
    * - `conversationService` must extend `CoreAiConversationService`
    * - `interactionService` must extend `CoreAiInteractionService`
    * - `mcpClientService` must extend `CoreAiMcpClientService`
+   * - `mcpOAuthService` must extend `CoreAiMcpOAuthService` (implements `authorizeConsent()`)
    * - `modeService` must extend `CoreAiModeService`
    * - `placeholderRegistry` must extend `CoreAiPlaceholderRegistry`
    * - `preferenceService` must extend `CoreAiConnectionPreferenceService`
@@ -4735,6 +4762,7 @@ export interface ICoreModuleOverrides {
     conversationService?: Type<any>;
     interactionService?: Type<any>;
     mcpClientService?: Type<any>;
+    mcpOAuthService?: Type<any>;
     modeService?: Type<any>;
     placeholderRegistry?: Type<any>;
     preferenceService?: Type<any>;

package/src/core/modules/ai/INTEGRATION-CHECKLIST.md

@@ -44,8 +44,10 @@ rest. Without `ai.encryptionSecret` / `NSC__AI__ENCRYPTION_SECRET` /
 `SECRETS_ENCRYPTION_KEY`, an insecure development default is used (logged as a
 warning) in non-production environments. In **production/staging the app refuses to
 boot** when AI is enabled but no secret is set (mirrors the email/cookie production
-guards) — so a missing secret can never silently ship. The same applies to the MCP
-OAuth signing secret when `ai.mcp.oauth` is enabled.
+guards) — so a missing secret can never silently ship. The MCP OAuth signing secret
+(`ai.mcp.oauth`) is stricter: it is required everywhere except `local`, `ci` and `e2e`,
+deployed `develop` / `test` stages included — a public key there would let anybody forge
+an MCP access token for any user id.
 
 ### 2. Set the LLM API key (environment)
 
@@ -205,21 +207,42 @@ The response body carries the stable `#LTNS_0901` code, never the raw error.
 
 ### MCP OAuth 2.1 (only when `ai.mcp.oauth` is enabled)
 
-**Edit `main.ts`** (after `app.init()`):
+**No `main.ts` step.** `CoreModule` mounts the OAuth endpoints itself during `app.init()`
+(11.43.0+). Remove a `mountAiMcpOAuth(app)` call from `main.ts` — it is a no-op now.
 
-```typescript
-import { mountAiMcpOAuth } from '@lenne.tech/nest-server';
-await mountAiMcpOAuth(app);
-```
+**WHY not in `main.ts` any more:** the endpoints are an Express router, and Nest registers its
+not-found handler inside `app.init()`. Mounted after `app.init()`, as this checklist used to say,
+the router sat behind that handler and every OAuth endpoint answered 404.
+
+**Check `NSC__BASE_URL` in every deployed environment.** The issuer is every URL in the discovery
+metadata, and MCP clients follow them. It is the server's `baseUrl`, and a deployed environment
+without one fails the boot rather than advertising `localhost` — which sends clients to the user's
+own machine. Set `ai.mcp.oauthBaseUrl` only when MCP clients reach the server under another URL;
+never add a `localhost` fallback of your own.
+
+**Nothing to create for consent.** `/authorize` answers with a built-in consent page: sign-in through
+Better-Auth (password + TOTP / backup code), then Allow / Deny with a CSRF token bound to user, client,
+redirect URI and PKCE challenge. It needs Better-Auth active (the boot warns otherwise).
+
+**Optional — `ai.mcp.oauthLoginUrl`:** the link for passkey / social login, default `<appUrl>/auth/login`.
+Put `{returnTo}` into it only if that login page can send the user back to the API's `/authorize` URL
+(the nuxt-base-starter login accepts same-origin targets only, so leave it out there).
+
+**Optional — your own consent UI:** a subclass of `CoreAiMcpOAuthService` overriding
+`renderConsentPage(view)` (restyle) or `authorizeConsent(client, params, res)` (replace), registered via
+`CoreModule.forRoot(envConfig, { ai: { mcpOAuthService: McpOAuthService } })`.
 
-**WHY no `baseUrl` argument:** the issuer is every URL in the discovery metadata, and MCP clients
-follow them. The helper takes it from the server's `baseUrl` (`NSC__BASE_URL` when deployed) and
-fails the boot in a deployed environment that has none, rather than advertising `localhost` —
-which sends clients to the user's own machine. Pass `{ baseUrl }` only for an issuer that must
-differ from the server's `baseUrl`; never add a `localhost` fallback of your own.
+**WHY a POST, never "signed in, so issue":** 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 session cookie, so issuing on GET hands a code for whoever clicks to the
+attacker. The framework refuses a code saved while answering a GET to `/authorize` (the client gets
+`error=server_error`); an own consent UI must show WHICH client is approved and protect the POST
+with a CSRF token.
 
-Override `CoreAiMcpOAuthService.authorizeConsent()` with your login/consent UI (the only
-browser-interactive step). All other OAuth pieces (tokens, PKCE, stores) are built in.
+**WHY refuse with `this.loadOAuthErrors()`:** the SDK maps an error to its OAuth code only when it
+is one of its own `OAuthError` classes, and turns anything else into `server_error`. A user who
+declines consent should send the client back with `access_denied` (`AccessDeniedError`), not with
+a server error.
 
 ## Verification Checklist
 
@@ -237,13 +260,16 @@ browser-interactive step). All other OAuth pieces (tokens, PKCE, stores) are bui
 
 ## Common Mistakes
 
-| Mistake                                          | Symptom                                                                                | Fix                                                                |
-| ------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| No `ai` config block                             | Module not loaded, `aiPrompt` missing from schema                                      | Add an `ai` block (presence implies enabled)                       |
-| No encryption secret in prod                     | **App refuses to boot** (throws); dev/local only warns                                 | Set `NSC__AI__ENCRYPTION_SECRET` (32+ chars)                       |
-| Encryption secret changed after keys stored      | Boot logs "key(s) could not be decrypted"; those prompts fail                          | Re-enter the API key for the listed connections                    |
-| Tool returns `.lean()`/aggregate data            | `@Restricted` fields leak into the LLM context                                         | Route through `CrudService` with `context.serviceOptions`          |
-| Tool not registered                              | Tool never offered to the LLM                                                          | Declare it as a provider in a module (extends `AiTool`)            |
-| Overridden resolver method missing decorators    | Method absent from GraphQL schema                                                      | Re-declare `@Mutation`/`@Query`/`@Roles` in the override           |
-| Storing a real API key in `config.env.ts`        | Secret committed to the repo                                                           | Use `apiKeyEnv` or the runtime connection CRUD                     |
-| `localhost` fallback for the MCP OAuth `baseUrl` | MCP client fails to register with `ECONNREFUSED`; discovery metadata names `localhost` | Call `mountAiMcpOAuth(app)` without `baseUrl`, set `NSC__BASE_URL` |
+| Mistake                                                    | Symptom                                                                                | Fix                                                                              |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| No `ai` config block                                       | Module not loaded, `aiPrompt` missing from schema                                      | Add an `ai` block (presence implies enabled)                                     |
+| No encryption secret in prod                               | **App refuses to boot** (throws); dev/local only warns                                 | Set `NSC__AI__ENCRYPTION_SECRET` (32+ chars)                                     |
+| Encryption secret changed after keys stored                | Boot logs "key(s) could not be decrypted"; those prompts fail                          | Re-enter the API key for the listed connections                                  |
+| Tool returns `.lean()`/aggregate data                      | `@Restricted` fields leak into the LLM context                                         | Route through `CrudService` with `context.serviceOptions`                        |
+| Tool not registered                                        | Tool never offered to the LLM                                                          | Declare it as a provider in a module (extends `AiTool`)                          |
+| Overridden resolver method missing decorators              | Method absent from GraphQL schema                                                      | Re-declare `@Mutation`/`@Query`/`@Roles` in the override                         |
+| Storing a real API key in `config.env.ts`                  | Secret committed to the repo                                                           | Use `apiKeyEnv` or the runtime connection CRUD                                   |
+| `localhost` fallback for the MCP OAuth `baseUrl`           | MCP client fails to register with `ECONNREFUSED`; discovery metadata names `localhost` | Set `NSC__BASE_URL`; no `ai.mcp.oauthBaseUrl` pointing at `localhost`            |
+| `mountAiMcpOAuth(app)` after `app.init()` (pre-11.43.0)    | `/.well-known/oauth-*`, `/token`, `/register` answer Nest's 404                        | Upgrade; remove the call — `CoreModule` mounts the endpoints during `app.init()` |
+| Own consent issues the code on GET ("signed in = consent") | `/authorize` redirects back with `error=server_error`; the refusal is logged           | Show the consent page on GET, issue only on the approving POST with a CSRF token |
+| `ai.mcp.oauth` without Better-Auth                         | Boot warning; the consent page offers no sign-in                                       | Enable `betterAuth`, or register an own `authorizeConsent()`                     |

package/src/core/modules/ai/README.md

@@ -685,32 +685,117 @@ Without Redis nothing changes: unknown ids answer `404` exactly as before.
 For generic MCP clients that auto-discover + register:
 `CoreAiMcpOAuthService` provides HMAC-signed access tokens (constant-time verify),
 PKCE S256, and MongoDB-backed client/code/refresh stores; the MCP controller then
-also accepts OAuth access tokens. Mount the discovery/token endpoints in `main.ts`:
+also accepts OAuth access tokens.
 
 ```typescript
-// main.ts, after app.init()
-import { mountAiMcpOAuth } from '@lenne.tech/nest-server';
-await mountAiMcpOAuth(app);
+// config.env.ts — that is all: endpoints, consent page and sign-in come with it
+ai: { mcp: { oauth: true, oauthSecret: process.env.NSC__AI__ENCRYPTION_SECRET } }
 ```
 
+**Mounted by `CoreModule` (11.43.0).** `CoreAiMcpOAuthInitializer` mounts the discovery and token
+endpoints (`/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource<mcp path>`,
+`/authorize`, `/token`, `/register`) during `app.init()` — no `main.ts` code, and the same under
+`Test.createTestingModule()`. The position is the point: the endpoints are an Express router, and Nest
+registers its not-found handler inside `app.init()`. The call this replaces — `mountAiMcpOAuth(app)` after
+`app.init()`, as this README used to say — sat behind that handler, so every OAuth endpoint answered 404.
+Mounted during init, the router sits behind every Nest middleware (security headers, request context,
+CORS) and the Nest routes, and ahead of the not-found handler. Guards and interceptors do not run for it;
+the SDK's handlers authenticate the client and rate-limit per IP themselves (so `trustProxy` matters
+behind a proxy). A `mountAiMcpOAuth()` call left in `main.ts` is a no-op and logs that it can go; options
+it passes that differ from the mount (`baseUrl`, `mcpPath`) are named in a warning.
+
+The protected MCP resource is described at the path Nest registered the endpoint at — global prefix and
+its exclusions, URI versioning and a `RouterModule` path included — and the endpoint's `401` names that
+metadata document in `WWW-Authenticate: Bearer resource_metadata="…"` (RFC 9728 §5.1). Without OAuth the
+challenge is a plain `Bearer`: there is no metadata to point at. CORS: a project's `enableCors()` runs
+first, so a browser-based MCP client on an origin it does not allow is refused at the preflight; native
+clients (Claude Code, Claude Desktop) send none.
+
 **Swagger (11.42.9):** `setupSwagger()` documents `/ai/mcp` (POST/GET/DELETE, with the bearer
 requirement the endpoint enforces itself) whenever the MCP server is registered, and — because the
-OAuth endpoints are an Express router, invisible to `@nestjs/swagger` — exactly the OAuth endpoints
-`mountAiMcpOAuth()` mounted (`/.well-known/oauth-authorization-server`,
-`/.well-known/oauth-protected-resource/ai/mcp`, `/authorize`, `/token`, `/register`; `/revoke` only for a
-provider with `revokeToken`). Without the call they are not documented, because they do not exist.
+OAuth endpoints are an Express router, invisible to `@nestjs/swagger` — exactly the OAuth endpoints that
+are mounted (`/revoke` only for a provider with `revokeToken`). Without `ai.mcp.oauth` they are not
+documented, because they do not exist.
 
 The issuer — and with it every endpoint URL in the discovery metadata, which MCP clients follow —
 is the server's `baseUrl` (`NSC__BASE_URL` when deployed), resolved the same way 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 guessing, because a deployed API that advertised
+without a `baseUrl` fails the boot instead of guessing, because a deployed API that advertised
 `http://localhost:3000` sent Claude Code off to register the client on the user's own machine.
-Pass `{ baseUrl }` only when the issuer must differ from the server's `baseUrl`, and do not add a
-`localhost` fallback of your own. The resolved issuer is logged once at boot.
-
-Override `CoreAiMcpOAuthService.authorizeConsent()` to wire your login/consent UI.
+Set `ai.mcp.oauthBaseUrl` only when MCP clients reach the server under another URL than `baseUrl` (its
+origin is then trusted by Better-Auth automatically, because the consent page signs users in there),
+and do not add a `localhost` fallback of your own. Issuer and resource are logged once at boot.
 Set `ai.mcp.oauthSecret` (or reuse `ai.encryptionSecret`) to a random 32+ char value.
 
+**Consent page (11.43.0).** `/authorize` answers with a built-in, build-free page — the step where the
+user decides whether an MCP client may act for them:
+
+- **Nobody signed in** → the sign-in view: e-mail + password and the two-factor step (TOTP or backup
+  code) against Better-Auth's own endpoints on this origin (`<basePath>/sign-in/email`,
+  `/two-factor/verify-totp`, `/two-factor/verify-backup-code`), then a reload of the same `/authorize`
+  request. Passkey and social login go through the app's login page: `ai.mcp.oauthLoginUrl`, else
+  `<appUrl>/auth/login`, opened next to the consent page, which then offers "continue". A `{returnTo}`
+  in `oauthLoginUrl` is replaced by the pending request's URL, for a login page that sends the user
+  back by itself. A user already signed in to the API origin (session cookie) skips this view.
+- **Signed in** → the consent view: the signed-in account first (with "use another account", which signs
+  out and shows the sign-in view), the client's name, the host the code goes to (a loopback host is
+  named "an application on this computer"), Allow / Deny as a form POST. Allow is rendered `disabled`;
+  a nonce'd script enables it, and a click counts only after intent on this page — visible, focused,
+  and a pointer move / key / touch at least 600 ms after it got there. That defeats
+  double-clickjacking (a hostile page sends this window to `/authorize` behind a popup and lets the
+  second click of a "double-click" land on Allow). Without JavaScript nothing can be approved, and the
+  sign-in forms are hidden and `method="post"`, so a password never lands in a URL.
+- **Allow** issues the code only with the page's CSRF token, signed with the OAuth secret and bound to
+  the user, the client, the redirect URI and the PKCE challenge (10 minutes); a stale token shows the
+  form again, a forged or tampered one too, and nothing is issued. **Deny** sends the client back with
+  `access_denied`.
+
+The page carries its own `Content-Security-Policy` (script and style by nonce, `frame-ancestors 'none'`,
+no `form-action`, which browsers would apply to the redirect to the client), `X-Frame-Options: DENY`,
+`Cache-Control: no-store` and `Referrer-Policy: no-referrer`, independent of `security.headers`. Every
+value from outside is escaped — the client's name is chosen by whoever registered the client. German
+for a German `Accept-Language`, English otherwise.
+
+Why Allow is a deliberate step: dynamic registration is open by design, 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 session cookie, so a page that issued on GET would let any
+link a signed-in user opens authorize an attacker's client. The framework refuses a code saved while
+answering a GET to `/authorize` (logged; the client gets `error=server_error`) — for the built-in page
+and for one of your own alike.
+
+**Global prefix.** Nest registers the Better-Auth middleware below a global prefix while the OAuth router sits at the
+root, so the page resolves the session itself when the middleware did not run, and signs in at the prefixed IAM path
+(`/api/iam/sign-in/email`). Better-Auth's own routes are not forwarded below a global prefix (see `setupSwagger()`), so
+the two-factor step does not work there; users with 2FA sign in through the app.
+
+**Needs Better-Auth.** The page signs users in through it; without Better-Auth active the boot warns and
+the page offers no sign-in. Its sign-in goes through the IAM sign-in controller, which (since 11.43.0)
+hands Better-Auth the request so Better-Auth's own login-CSRF protection runs — otherwise a hostile page
+could sign the visitor in to the attacker's account before they approve a client.
+
+**Your own page.** Override `renderConsentPage(view)` in a subclass to restyle it (keep every value
+escaped), or `authorizeConsent(client, params, res)` for a consent UI of your own — same shape: no session
+→ sign in, GET → show which client, POST with a CSRF token → `saveAuthorizationCode()` and redirect;
+refuse with `AccessDeniedError` from `this.loadOAuthErrors()`. Register the subclass via
+`CoreModule.forRoot(env, { ai: { mcpOAuthService } })`, so the MCP controller and the endpoints share it.
+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, a
+environment outside `local` / `ci` / `e2e` refuses to boot and to sign tokens at all — deployed `develop` and `test`
+stages included).
+
+Known property of the SDK: `/authorize` redirects its error answers to the client's registered
+redirect URI, and any client may register any https URI — an open redirect in the sense of RFC 9700
+§4.11.2, carrying only an OAuth error code.
+
+**Refusals are OAuth errors (11.43.0).** 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
+built-in provider refuses an unknown, rotated or foreign refresh token or authorization code with
+`400 invalid_grant` (until 11.43.0 these were plain `Error`s and answered 500). That matters beyond the
+status: an MCP client discards its stored tokens only on `invalid_grant`, so on a 500 it kept a dead
+token, retried, and never asked the user to sign in again. A refusal in your own `authorizeConsent()`
+needs the same: take the class from `this.loadOAuthErrors()` (e.g. `AccessDeniedError` when the user
+declines), never a plain `Error`.
+
 ## Tests
 
 - `tests/unit/ai.spec.ts` — crypto, registry role filtering, orchestrator loop,