@lenne.tech/nest-server 11.42.15 → 11.43.0

package/src/core/common/filters/mongoose-cast-error.filter.ts

@@ -0,0 +1,310 @@
+import {
+  ArgumentsHost,
+  BadRequestException,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { Error as MongooseError } from 'mongoose';
+
+import { ErrorCode } from '../../modules/error-code/error-codes';
+
+import type { GqlContextType } from '@nestjs/graphql';
+import type { Request, Response } from 'express';
+
+/**
+ * Where the value of a failed Mongoose cast came from — and therefore who is at fault.
+ *
+ * - `identifier`: it names the resource the request addresses — a route parameter, or a top-level
+ *   GraphQL argument. A malformed identifier names nothing, so it is answered like an unknown one: 404.
+ * - `input`: the client sent it as data — query string, body, or nested inside a GraphQL input: 400.
+ * - `server`: the request does not contain it. It came from stored data or from server code, which is
+ *   a data or code defect and stays a 500, so monitoring keeps seeing it.
+ */
+export type CastErrorOrigin = 'identifier' | 'input' | 'server';
+
+/**
+ * Bounds for walking request data. They keep error handling cheap and terminating for a deeply nested,
+ * very wide or self-referencing structure — the body parser's size limit alone does not: a project may
+ * raise it, and a few megabytes of `[0,0,0,…]` are a million nodes. What the budget cannot reach is not
+ * matched, which answers `server` (a 500), the status quo — never a client error.
+ */
+const MAX_WALK_DEPTH = 32;
+const MAX_WALK_NODES = 10_000;
+
+type Primitive = bigint | boolean | number | string;
+
+function isPrimitive(value: unknown): value is Primitive {
+  return (
+    typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint'
+  );
+}
+
+/**
+ * The strings a CastError's `value` stands for.
+ *
+ * A primitive stands for itself, an array (the `$in` shape) for each of its primitive elements.
+ * Anything else yields nothing: the strings inside an object cast as a whole (a subdocument, a whole
+ * array of them) are not what failed, and matching them against the request would relabel a server
+ * defect as a client error whenever one of them happens to appear in the body.
+ */
+export function castErrorCandidates(value: unknown): string[] {
+  if (isPrimitive(value)) {
+    return [String(value)];
+  }
+  if (Array.isArray(value)) {
+    return value.filter(isPrimitive).map((item) => String(item));
+  }
+  return [];
+}
+
+/**
+ * The children of an array or object, or `undefined` when there are more than `room` of them.
+ *
+ * Never collects more than `room` entries: an object is read key by key rather than through
+ * `Object.values()`, which would first copy every value of a million-key object.
+ */
+function boundedChildren(value: object, room: number): readonly unknown[] | undefined {
+  if (Array.isArray(value)) {
+    return value.length > room ? undefined : value;
+  }
+  const children: unknown[] = [];
+  // Own enumerable keys only, as Object.values — also for the null-prototype objects Express's query
+  // parser and graphql-js produce, which is why hasOwnProperty is borrowed rather than called
+  for (const key in value) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      continue;
+    }
+    if (children.length >= room) {
+      return undefined;
+    }
+    children.push((value as Record<string, unknown>)[key]);
+  }
+  return children;
+}
+
+/**
+ * Whether one of `candidates` occurs as a primitive anywhere in `source` (compared as strings, so a
+ * number in a JSON body matches the number Mongoose failed to cast). Depth- and size-bounded, and
+ * safe against cycles.
+ *
+ * The node budget is checked BEFORE a container's children are queued, not when they are visited: a
+ * container the remaining budget cannot hold is skipped as a whole. Queuing first and counting later
+ * let `{ ids: ['bad'], pad: [<a million zeros>] }` allocate a million stack entries and then give up
+ * before reaching `ids` — a 400 answered as a 500 after half a second of blocked event loop. Skipping
+ * (rather than queuing the first few) also leaves the budget to the oversized container's siblings.
+ */
+export function containsCastValue(source: unknown, candidates: readonly string[]): boolean {
+  if (!candidates.length) {
+    return false;
+  }
+  const wanted = new Set(candidates);
+  const seen = new Set<object>();
+  const stack: { depth: number; value: unknown }[] = [{ depth: 0, value: source }];
+  let nodes = 0;
+  for (let item = stack.pop(); item; item = stack.pop()) {
+    const { depth, value } = item;
+    // Unreachable while boundedChildren() keeps the invariant below; kept so that a regression there
+    // degrades to a 500 instead of an unbounded walk
+    if (++nodes > MAX_WALK_NODES) {
+      return false;
+    }
+    if (isPrimitive(value)) {
+      if (wanted.has(String(value))) {
+        return true;
+      }
+      continue;
+    }
+    if (!value || typeof value !== 'object' || depth >= MAX_WALK_DEPTH || ArrayBuffer.isView(value)) {
+      continue;
+    }
+    if (seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    // nodes + stack.length never exceeds MAX_WALK_NODES: only what the budget can still hold is queued
+    const children = boundedChildren(value, MAX_WALK_NODES - nodes - stack.length);
+    for (const child of children ?? []) {
+      stack.push({ depth: depth + 1, value: child });
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether one of `candidates` is one of `values` itself, or an element of an array among them — the
+ * shape of route parameters (Express 5 wildcards are arrays) and of top-level GraphQL arguments.
+ */
+function isDirectValue(values: readonly unknown[], candidates: readonly string[]): boolean {
+  const wanted = new Set(candidates);
+  const matches = (value: unknown) => isPrimitive(value) && wanted.has(String(value));
+  // A list beyond the walk budget is not scanned here either — a GraphQL list argument is client-sized
+  return values.some((value) =>
+    Array.isArray(value) ? value.length <= MAX_WALK_NODES && value.some(matches) : matches(value),
+  );
+}
+
+/**
+ * Classify a CastError raised while handling a REST request.
+ *
+ * A value that is a route parameter is an `identifier`; one found anywhere in the query string or the
+ * body is `input`; anything else is `server`. The parameter check runs first, so `PATCH /x/:id` with the
+ * same malformed id in its body is still a 404.
+ */
+export function classifyHttpCastError(
+  value: unknown,
+  request: Partial<Pick<Request, 'body' | 'params' | 'query'>> | undefined,
+): CastErrorOrigin {
+  const candidates = castErrorCandidates(value);
+  if (!candidates.length || !request) {
+    return 'server';
+  }
+  if (isDirectValue(Object.values(request.params ?? {}), candidates)) {
+    return 'identifier';
+  }
+  if (containsCastValue(request.query, candidates) || containsCastValue(request.body, candidates)) {
+    return 'input';
+  }
+  return 'server';
+}
+
+/**
+ * Classify a CastError raised while executing a GraphQL field.
+ *
+ * The GraphQL counterpart of a route parameter is a top-level scalar argument (`getUser(id: …)`), and
+ * of a body a value nested inside an input object (`findUsers(filter: …)`, `updateUser(input: …)`).
+ */
+export function classifyGraphQlCastError(value: unknown, args: unknown): CastErrorOrigin {
+  const candidates = castErrorCandidates(value);
+  if (!candidates.length || !args || typeof args !== 'object') {
+    return 'server';
+  }
+  if (isDirectValue(Object.values(args), candidates)) {
+    return 'identifier';
+  }
+  if (containsCastValue(args, candidates)) {
+    return 'input';
+  }
+  return 'server';
+}
+
+/**
+ * Answers a Mongoose `CastError` caused by the CLIENT as a client error instead of a 500.
+ *
+ * A malformed id in a route parameter (`GET /users/not-an-id`) reaches Mongoose, which throws
+ * `CastError`. That is not an `HttpException`, so it escaped every `@Catch(HttpException)` filter and Nest
+ * answered **500 Internal server error** for what is simply "this resource does not exist".
+ *
+ * | Value of the failed cast | REST | GraphQL |
+ * |--------------------------|------|---------|
+ * | a route parameter / a top-level argument | 404 `ErrorCode.RESOURCE_NOT_FOUND` | same |
+ * | in the query string or the body / nested in an input | 400 `ErrorCode.INVALID_FIELD_FORMAT [path]` | same |
+ * | not in the request (stored data, server code) | 500, exactly as before, logged as an error | unchanged |
+ *
+ * The third row is deliberate: a broken id in stored data or a cast on a server-computed value is a
+ * defect, and relabelling it as a client error would hide it from monitoring.
+ *
+ * The Mongoose message is never sent: it names the model. Registered by `CoreModule` as `APP_FILTER`
+ * (opt out with `security.mongooseCastErrorFilter: false`), so `main.ts` and test setups need no change.
+ * A project's own catch-all filter registered via `app.useGlobalFilters()` is consulted first and wins.
+ *
+ * Only `CastError` is handled, and Mongoose raises it only while casting a QUERY or an UPDATE
+ * (filters, `findById`, `findByIdAndUpdate` / `updateOne` — the path `CrudService.update()` takes). Two
+ * neighbours stay a 500:
+ * - a malformed id in a document being CREATED or SAVED (`new Model().save()`, `Model.create()`,
+ *   `insertMany()` — the path `CrudService.create()` takes) arrives as a `ValidationError` wrapping the
+ *   CastError. Validate reference ids in the input instead (`validator: () => [IsMongoId()]` on the
+ *   `@UnifiedField`);
+ * - a `BSONError` from `new Types.ObjectId(bad)` in service code carries no value to classify; such code
+ *   should check the id itself (see `CoreFileService.isMalformedFileId()`).
+ */
+@Catch(MongooseError.CastError)
+export class MongooseCastErrorFilter implements ExceptionFilter {
+  protected static readonly logger = new Logger('MongooseCastErrorFilter');
+
+  /**
+   * The context Nest's own handler logs an unknown error under — so a cast failure that stays a 500 is
+   * logged exactly as before this filter existed, and monitoring matching that line keeps matching.
+   */
+  protected static readonly unknownErrorLogger = new Logger('ExceptionsHandler');
+
+  catch(exception: MongooseError.CastError, host: ArgumentsHost): HttpException | undefined {
+    const type = host.getType<GqlContextType>();
+    if (type === 'graphql') {
+      return this.catchGraphQl(exception, host);
+    }
+    if (type === 'http') {
+      this.catchHttp(exception, host);
+    }
+    // Any other transport: returning nothing hands the error back to its own exception handler
+    return undefined;
+  }
+
+  /**
+   * GraphQL: the returned exception becomes the field error. Returning nothing hands the error back to
+   * Nest's external exception handler, which logs and rethrows it — what happened before this filter.
+   */
+  protected catchGraphQl(exception: MongooseError.CastError, host: ArgumentsHost): HttpException | undefined {
+    const origin = classifyGraphQlCastError(exception.value, host.getArgByIndex(1));
+    if (origin === 'server') {
+      return undefined;
+    }
+    return this.toHttpException(exception, origin);
+  }
+
+  /**
+   * REST: a filter that matched must answer the request itself — Nest does not fall back to its own
+   * handler afterwards.
+   */
+  protected catchHttp(exception: MongooseError.CastError, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const origin = classifyHttpCastError(exception.value, ctx.getRequest<Request>());
+    if (origin === 'server') {
+      this.replyAsUnknownError(exception, response);
+      return;
+    }
+    const httpException = this.toHttpException(exception, origin);
+    if (response.headersSent) {
+      response.end();
+      return;
+    }
+    // Same wire shape as HttpExceptionLogFilter, so a client sees one error format for every 4xx
+    response.status(httpException.getStatus()).json({ ...httpException });
+  }
+
+  /**
+   * The client error a request-supplied cast failure is answered with. The Mongoose message stays in
+   * the server log (debug level): it names the model, which is none of the client's business.
+   */
+  protected toHttpException(exception: MongooseError.CastError, origin: 'identifier' | 'input'): HttpException {
+    MongooseCastErrorFilter.logger.debug(
+      `Cast failed on a value from the request (${origin === 'identifier' ? 404 : 400}): ${exception.message}`,
+    );
+    if (origin === 'identifier') {
+      return new NotFoundException(ErrorCode.RESOURCE_NOT_FOUND);
+    }
+    return new BadRequestException(
+      exception.path ? `${ErrorCode.INVALID_FIELD_FORMAT} [${exception.path}]` : ErrorCode.INVALID_FIELD_FORMAT,
+    );
+  }
+
+  /**
+   * What Nest's `BaseExceptionFilter` does with an error it does not know: the generic 500 body, and
+   * the error object itself in the log — `logger.error(exception)`, the same call Nest 11 makes, so the
+   * line (and its JSON form under a JSON logger) is the one monitoring already sees.
+   */
+  protected replyAsUnknownError(exception: Error, response: Response): void {
+    if (response.headersSent) {
+      response.end();
+    } else {
+      response
+        .status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .json({ statusCode: HttpStatus.INTERNAL_SERVER_ERROR, message: 'Internal server error' });
+    }
+    MongooseCastErrorFilter.unknownErrorLogger.error(exception);
+  }
+}

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;
@@ -3154,6 +3178,28 @@ export interface IServerOptions {
           nonWhitelistedFields?: 'strip' | 'error' | false;
         };
 
+    /**
+     * Answer a Mongoose `CastError` caused by the client as a client error instead of a 500.
+     * See @lenne.tech/nest-server/src/core/common/filters/mongoose-cast-error.filter.ts
+     *
+     * A malformed id in a route parameter (`GET /users/not-an-id`) answers 404
+     * (`ErrorCode.RESOURCE_NOT_FOUND`), one in the query string or the body 400
+     * (`ErrorCode.INVALID_FIELD_FORMAT`); GraphQL likewise for a top-level argument and a nested input.
+     * A failed cast on a value the request does not contain (stored data, server code) stays a 500.
+     *
+     * Covers casts Mongoose performs while running a query or an update (`findById`, filters,
+     * `findByIdAndUpdate`). A malformed id in a document being created (`save()`, `create()`,
+     * `insertMany()`) is a Mongoose `ValidationError` instead and stays a 500 — validate such ids in the
+     * input (`validator: () => [IsMongoId()]`).
+     *
+     * Registered by `CoreModule` as `APP_FILTER`. `false` restores the previous behaviour, in which every
+     * `CastError` answered 500.
+     *
+     * @default true
+     * @since 11.42.16
+     */
+    mongooseCastErrorFilter?: boolean;
+
     /**
      * Mongoose password hashing plugin - automatically hashes passwords on save/update
      * (save, findOneAndUpdate, updateOne, updateMany).
@@ -4537,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
@@ -4599,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
@@ -4681,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`
@@ -4713,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()`                     |