@lenne.tech/nest-server 12.2.0 → 12.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "12.2.0",
+  "version": "12.3.1",
   "type": "module",
   "description": "Server framework in TypeScript on top of NestJS: GraphQL and REST APIs on MongoDB, PostgreSQL, MySQL or MariaDB, with authentication, field-level permissions, multi-tenancy, offline sync and an AI assistant.",
   "keywords": [
@@ -104,18 +104,18 @@
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.2.0",
     "@modelcontextprotocol/sdk": "1.32.2",
-    "@nestjs/apollo": "14.1.1",
+    "@nestjs/apollo": "14.1.2",
     "@nestjs/common": "12.3.2",
     "@nestjs/core": "12.3.2",
-    "@nestjs/graphql": "14.1.0",
+    "@nestjs/graphql": "14.1.2",
     "@nestjs/jwt": "12.0.3",
     "@nestjs/passport": "12.0.0",
     "@nestjs/platform-express": "12.3.2",
     "@nestjs/schedule": "12.0.2",
-    "@nestjs/swagger": "12.0.5",
+    "@nestjs/swagger": "12.1.0",
     "@nestjs/terminus": "12.1.0",
-    "@tus/file-store": "2.1.1",
-    "@tus/server": "2.4.6",
+    "@tus/file-store": "2.1.2",
+    "@tus/server": "2.4.7",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "class-transformer": "0.5.1",
@@ -131,13 +131,13 @@
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "17.1.0",
     "graphql-ws": "6.3.0",
-    "jose": "6.2.13",
+    "jose": "6.2.15",
     "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "multer": "2.5.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "10.3.0",
+    "nodemailer": "10.3.1",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -153,12 +153,12 @@
     "@aws-sdk/client-s3": ">=3.1045.0 <4",
     "@aws-sdk/lib-storage": ">=3.1045.0 <4",
     "@aws-sdk/s3-request-presigner": ">=3.1045.0 <4",
-    "@better-auth/core": ">=1.7.12 <1.8.0",
-    "@better-auth/passkey": ">=1.7.12 <1.8.0",
+    "@better-auth/core": ">=1.7.16 <1.8.0",
+    "@better-auth/passkey": ">=1.7.16 <1.8.0",
     "@nestjs/mongoose": ">=12.0.0 <13",
     "@swc/core": ">=1.10.0 <2",
     "@tus/s3-store": ">=2.0.5 <3",
-    "better-auth": ">=1.7.12 <1.8.0",
+    "better-auth": ">=1.7.16 <1.8.0",
     "bullmq": ">=5.16.0 <7",
     "drizzle-orm": "1.0.0-rc.5",
     "ioredis": ">=5.0.0 <7",
@@ -226,19 +226,19 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1159.0",
-    "@aws-sdk/lib-storage": "3.1159.0",
-    "@aws-sdk/s3-request-presigner": "3.1159.0",
-    "@better-auth/core": "1.7.14",
-    "@better-auth/passkey": "1.7.14",
+    "@aws-sdk/client-s3": "3.1161.0",
+    "@aws-sdk/lib-storage": "3.1161.0",
+    "@aws-sdk/s3-request-presigner": "3.1161.0",
+    "@better-auth/core": "1.7.16",
+    "@better-auth/passkey": "1.7.16",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "12.0.11",
     "@nestjs/mongoose": "12.0.0",
     "@nestjs/schematics": "12.0.12",
     "@nestjs/testing": "12.3.2",
     "@swc/cli": "0.8.2",
-    "@swc/core": "1.16.20",
-    "@tus/s3-store": "2.0.9",
+    "@swc/core": "1.16.21",
+    "@tus/s3-store": "2.1.0",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
@@ -248,32 +248,32 @@
     "@types/node": "26.6.6",
     "@types/passport": "1.0.17",
     "@types/pg": "8.23.1",
-    "@vitest/coverage-v8": "5.0.5",
-    "better-auth": "1.7.14",
-    "bullmq": "6.5.1",
+    "@vitest/coverage-v8": "5.1.0",
+    "better-auth": "1.7.16",
+    "bullmq": "6.5.4",
     "cross-env": "10.1.0",
     "drizzle-orm": "1.0.0-rc.5",
     "ioredis": "6.0.0",
-    "kysely": "0.29.7",
+    "kysely": "0.29.8",
     "mongodb": "7.7.0",
     "mongoose": "9.11.4",
     "mysql2": "3.24.6",
     "nodemon": "3.1.14",
-    "otpauth": "9.5.2",
+    "otpauth": "9.6.0",
     "oxfmt": "0.75.0",
     "oxlint": "1.90.0",
     "oxlint-tsgolint": "7.0.2005",
     "pg": "8.23.1",
     "playwright-core": "1.64.1",
     "rimraf": "6.1.3",
-    "smtp-server": "3.21.1",
+    "smtp-server": "3.21.3",
     "tsx": "4.23.15",
     "tus-js-client": "4.3.1",
     "typeorm": "1.1.2",
     "typescript": "6.0.3",
     "unplugin-swc": "2.0.0",
-    "vite": "8.3.4",
-    "vitest": "5.0.5"
+    "vite": "8.3.5",
+    "vitest": "5.1.0"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/config.env.ts

@@ -59,7 +59,9 @@ const config: { [env: string]: IServerOptions } = {
         rpId: 'localhost',
         rpName: 'Nest Server Local',
       },
-      rateLimit: { enabled: true, max: 100, windowSeconds: 60 },
+      // 200: sign-in and sign-up get the strict half (100), the headroom the suites had while the limiter
+      // counted every IAM request of a client on one shared counter of 100
+      rateLimit: { enabled: true, max: 200, windowSeconds: 60 },
       secret: process.env.BETTER_AUTH_SECRET || 'BETTER_AUTH_SECRET_LOCAL_32_CHARS_M',
       // Social providers disabled in local environment (no credentials)
       socialProviders: {
@@ -367,7 +369,9 @@ const config: { [env: string]: IServerOptions } = {
         rpId: 'localhost',
         rpName: 'Nest Server Local',
       },
-      rateLimit: { enabled: true, max: 100, windowSeconds: 60 },
+      // 200: sign-in and sign-up get the strict half (100), the headroom the suites had while the limiter
+      // counted every IAM request of a client on one shared counter of 100
+      rateLimit: { enabled: true, max: 200, windowSeconds: 60 },
       secret: process.env.BETTER_AUTH_SECRET || 'BETTER_AUTH_SECRET_LOCAL_32_CHARS_M',
       // Social providers disabled in local environment (no credentials)
       socialProviders: {

package/src/core/common/helpers/graphql-ws-connection.helper.ts

@@ -82,6 +82,17 @@ export interface IWsConnectionRegistration {
    */
   carrier: object;
 
+  /** How the log names the connection when it is closed. Default `GraphQL WebSocket`. */
+  channel?: string;
+
+  /**
+   * The connection cannot be re-checked in place — an HTTP stream has no handshake to repeat — so every re-check ends
+   * it, and the client's reconnect passes the guards again. The end the re-check interval brings is planned and logged
+   * at debug; one an invalidation brings (sign-out, role or tenant change) is logged like every withdrawn
+   * authorization. `reauthenticate` is not called.
+   */
+  endsOnRecheck?: boolean;
+
   /**
    * Re-run the handshake's authentication. Resolves to the user the credential authenticates as NOW,
    * or to a falsy value when it no longer does. A rejection counts as falsy. Without it only the
@@ -105,7 +116,9 @@ export interface IWsConnectionIdentity {
 
 /** @internal The registered state of one connection. */
 export interface WsConnection {
+  readonly channel: string;
   readonly email?: string;
+  readonly endsOnRecheck: boolean;
   readonly iamId?: string;
   readonly reauthenticate?: () => any;
   readonly socket?: IWsConnectionSocket;
@@ -206,13 +219,15 @@ export function readWsTenantHeader(contextValue: any): string | undefined {
  * the handshake recorded on the carrier.
  */
 export function registerWsConnection(registration: IWsConnectionRegistration): void {
-  const { carrier, reauthenticate, socket, user } = registration;
+  const { carrier, channel, endsOnRecheck, reauthenticate, socket, user } = registration;
   if (!carrier || typeof carrier !== 'object') {
     return;
   }
   const userId = user?.id ?? user?._id;
   const connection: WsConnection = {
+    channel: channel || 'GraphQL WebSocket',
     email: typeof user?.email === 'string' ? user.email.toLowerCase() : undefined,
+    endsOnRecheck: endsOnRecheck === true,
     iamId: typeof user?.iamId === 'string' ? user.iamId : undefined,
     reauthenticate,
     socket,
@@ -246,15 +261,20 @@ export function getWsConnection(contextValue: any): undefined | WsConnection {
 
 /**
  * Close a connection whose authorization no longer holds. Idempotent; always answers `false` so a
- * caller can `return terminate(...)`.
+ * caller can `return terminate(...)`. `debug` is for a planned end, which says nothing about the user.
  */
-function terminate(connection: WsConnection, reason: string): false {
+function terminate(connection: WsConnection, reason: string, level: 'debug' | 'log' = 'log'): false {
   if (connection.terminated) {
     return false;
   }
   connection.terminated = true;
   liveConnections.delete(connection);
-  logger.log(`Closing GraphQL WebSocket of user ${connection.userId ?? '(unknown)'}: ${reason}`);
+  const message = `Closing ${connection.channel} of user ${connection.userId ?? '(unknown)'}: ${reason}`;
+  if (level === 'debug') {
+    logger.debug(message);
+  } else {
+    logger.log(message);
+  }
   try {
     // A close reason is limited to 123 bytes on the wire; these are short and ASCII.
     connection.socket?.close(WS_AUTHORIZATION_CHANGED_CLOSE_CODE, reason);
@@ -265,7 +285,15 @@ function terminate(connection: WsConnection, reason: string): false {
 }
 
 async function revalidate(connection: WsConnection): Promise<boolean> {
+  const invalidated = connection.stale;
   connection.stale = false;
+  if (connection.endsOnRecheck) {
+    // Nothing to check in place: the end IS the re-check, and the reconnect is authorized afresh. Only an invalidation
+    // says that the rights may have changed; the interval is the planned beat and must not read like a lost session.
+    return invalidated
+      ? terminate(connection, 'authorization invalidated, client reconnects')
+      : terminate(connection, 're-check interval reached, client reconnects', 'debug');
+  }
   try {
     let user = connection.user;
     if (connection.reauthenticate) {

package/src/core/common/interceptors/check-security.interceptor.ts

@@ -6,8 +6,31 @@ import { getContextData } from '../helpers/context.helper.js';
 import { hasRestrictionsCheckedMarker } from '../decorators/restrictions-checked.marker.js';
 import { getStringIds } from '../helpers/db.helper.js';
 import { processDeep } from '../helpers/input.helper.js';
+import { columnName } from '../persistence/sql/sql-naming.js';
 import { ConfigService } from '../services/config.service.js';
 
+/**
+ * The keys a secret field can arrive under: its own name and its SQL column (12.3.1). A row read through
+ * `store.native()` / `store.raw()` carries snake_case columns (`password_reset_token`), and a route returning it
+ * unchanged handed every secret but `password` — the one spelled alike — to the client. `id` / `_id` keep their own
+ * spelling only (their column is `id`), and a name that is no identifier has no column.
+ */
+function secretFieldKeys(fields: string[]): Set<string> {
+  const keys = new Set<string>();
+  for (const field of fields) {
+    keys.add(field);
+    if (field === 'id' || field === '_id') {
+      continue;
+    }
+    try {
+      keys.add(columnName(field));
+    } catch {
+      // Not an identifier, so no column carries it
+    }
+  }
+  return keys;
+}
+
 /**
  * Verification of all outgoing data via securityCheck
  */
@@ -137,6 +160,7 @@ export class CheckSecurityInterceptor implements NestInterceptor {
       return proto === null || proto === Object.prototype;
     };
     const visited = new WeakSet();
+    const secretKeys = secretFieldKeys(this.config.secretFields);
     const removeSecrets = (data: any) => {
       if (!this.config.removeSecretFields || !data || typeof data !== 'object') {
         return data;
@@ -155,7 +179,7 @@ export class CheckSecurityInterceptor implements NestInterceptor {
         return data;
       }
       visited.add(data);
-      for (const field of this.config.secretFields) {
+      for (const field of secretKeys) {
         if (field in data && data[field] !== undefined) {
           data[field] = undefined;
         }
@@ -163,7 +187,7 @@ export class CheckSecurityInterceptor implements NestInterceptor {
       // Recurse into nested plain objects
       for (const key of Object.keys(data)) {
         const value = data[key];
-        if (value && typeof value === 'object' && !this.config.secretFields.includes(key)) {
+        if (value && typeof value === 'object' && !secretKeys.has(key)) {
           removeSecrets(value);
         }
       }

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

@@ -510,8 +510,14 @@ export type IBetterAuth = IBetterAuthWithoutPasskey | IBetterAuthWithPasskey;
  */
 export interface IBetterAuthEmailVerificationConfig {
   /**
-   * Whether to automatically sign in the user after email verification.
-   * @default true
+   * Whether `GET /iam/verify-email` signs in the browser that opens the verification link.
+   *
+   * Off by default, as in Better-Auth (12.3.0+; before, the framework defaulted to `true`). Switching it on signs in
+   * WHOEVER opens the link, to the account the link belongs to: someone who signs up with their own address and
+   * forwards the unopened link has the recipient's browser signed in to their account, and what the recipient then
+   * enters lands there (login CSRF). Only switch it on where verification links reach nobody but their owner.
+   *
+   * @default false
    */
   autoSignInAfterVerification?: boolean;
 
@@ -795,6 +801,10 @@ export interface IBetterAuthPasskeyConfig {
    * - 'required': Always require biometric/PIN verification (most secure)
    * - 'preferred': Request verification if available (default)
    * - 'discouraged': Skip verification for faster auth (least secure)
+   *
+   * With 'required', a passkey response without user verification is refused at registration and sign-in. Takes effect
+   * since 12.3.1, as do `authenticatorAttachment` and `residentKey`: before, the three reached the passkey plugin where
+   * it never reads them.
    * @default 'preferred'
    */
   userVerification?: 'discouraged' | 'preferred' | 'required';
@@ -975,6 +985,17 @@ export interface IBetterAuthSocialProvider {
    */
   clientSecret: string;
 
+  /**
+   * Whether a first sign-in through this provider may create an account.
+   *
+   * Unset, the provider follows `betterAuth.emailAndPassword.disableSignUp`: with that set to `true` (since 12.3.0)
+   * nobody gets a new account through any provider, while existing users keep signing in. `false` opens sign-up
+   * through this provider although `disableSignUp` closes it otherwise; `true` closes it for this provider alone.
+   * Only a boolean counts: any other value follows `emailAndPassword.disableSignUp`.
+   * @default emailAndPassword.disableSignUp
+   */
+  disableSignUp?: boolean;
+
   /**
    * Whether this provider is enabled.
    * Defaults to true when clientId and clientSecret are provided.
@@ -2004,7 +2025,13 @@ export interface IAi {
    * Fallback total context window (input + output tokens) used to budget the
    * assembled session messages when a connection has no `contextWindow` set. When the
    * conversation (per user/session) would overflow, the oldest history turns are
-   * dropped and oversized payloads truncated before the LLM call.
+   * dropped and oversized payloads truncated before the LLM call. Native tool
+   * definitions count against that budget too (12.3.0+), and when the system prompt and
+   * tools take more than half of it, a warning names the connection once per process.
+   *
+   * A test that guards the prompt size against this value guards the connections WITHOUT
+   * a window of their own — the worst case — not the window a pinned or detected
+   * connection actually has. Name it that way; raising its limit removes that guard.
    * @default 8192
    */
   contextWindow?: number;
@@ -2061,14 +2088,14 @@ export interface IAi {
    * a caller sees and may run is decided server-side by the registry's role filter
    * (`AiToolRegistry.forUser()`), re-checked at execution time, and the
    * confirmation gate reads the `mutating`/`destructive` FLAGS, never the
-   * description text. (`AiTool.authorize()` runs in plan mode only — in auto mode
-   * and over MCP, data-level checks belong inside `execute()`.)
+   * description text. (`AiTool.authorize()` runs before every execution — auto
+   * mode, plan mode and MCP — on the call's arguments, never its description.)
    *
    * Applies to the EMULATED tool protocol, not to a provider as such. In auto mode
    * a connection with native tool calling receives every full description and schema
-   * through `buildToolSchemas()` regardless, so no truncation is applied there and no
-   * `search_tools` banner is emitted — capping would otherwise assert a truncation
-   * that the tool payload right next to it contradicts.
+   * through `buildToolSchemas()` regardless, and its catalog lists names only since
+   * 12.3.0 (`nativeToolCatalog`), so this cap has no effect there and no `search_tools`
+   * banner is emitted.
    *
    * **Plan mode always uses the emulated protocol** (it sends no native schemas), so a
    * native connection IS truncated there. Because plan mode returns a complete plan in
@@ -2091,6 +2118,17 @@ export interface IAi {
    */
   deferToolSummaryChars?: number;
 
+  /**
+   * What the system prompt's tool catalog holds for a connection with NATIVE tool calling in auto mode (12.3.0+).
+   * Such a connection receives every description and parameter schema in the tool payload, so by default the catalog
+   * lists names only — repeating the descriptions (and, without `deferToolSchemas`, the schemas) paid for every tool
+   * twice. `'full'` restores the full catalog, for a model that picks tools better with the descriptions in the prompt.
+   *
+   * Emulated connections and plan mode always get the full catalog: there it is the model's only source.
+   * @default 'names'
+   */
+  nativeToolCatalog?: 'full' | 'names';
+
   /** Maximum number of agent-loop iterations (tool round-trips). @default 5 */
   maxIterations?: number;
 
@@ -2142,11 +2180,32 @@ export interface IAi {
    * 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.
+   *
+   * `tools/call` applies the admin's tool policies and a tool's `authorize()`, and asks the user before a
+   * tool that needs confirmation (`destructive`, or `mutating` under `ai.confirmation.mutating`) — see
+   * `confirmation`.
    * @default false
    */
   mcp?:
     | boolean
     | {
+        /**
+         * Whether MCP asks the user — through MCP elicitation, a yes/no form the client shows — before a
+         * `destructive` tool, or a `mutating` one under `ai.confirmation.mutating` (12.3.0+). The tool runs only
+         * on an explicit yes; a client without the `elicitation` capability gets a refusal. `authorize()` runs
+         * either way, and an admin's `ask` tool policy always asks.
+         *
+         * - `true` / `{}` / unset: MCP asks, unless a user switched it off for themselves
+         *   (`PUT /ai/settings`, `updateAiSettings` — like a "bypass permissions" mode).
+         * - `false`: MCP asks nobody, unless a user switched it on for themselves.
+         * - `{ default, enforced }`: `default` as above; `enforced: true` ignores every user's choice and
+         *   refuses a change with 403.
+         *
+         * Only `false` / `default: false` switch the default off and only `enforced: true` enforces, so a
+         * misspelt value never relaxes the gate.
+         * @default { default: true, enforced: false }
+         */
+        confirmation?: boolean | { default?: boolean; enforced?: boolean };
         enabled?: boolean;
         oauth?: boolean;
         /**
@@ -2164,6 +2223,17 @@ export interface IAi {
          */
         oauthLoginUrl?: string;
         oauthSecret?: string;
+        /**
+         * Serve `/ai/mcp` without sessions: every POST builds its own server and transport for the
+         * authenticated user and ends with the response, no `mcp-session-id` is issued, and GET /
+         * DELETE answer 405. Any replica can answer any request, so no sticky sessions are needed
+         * behind a load balancer. The price is what a session carries: server-initiated messages
+         * (notifications, SSE streams) and server-initiated requests — MCP elicitation among them, so a
+         * tool that needs confirmation (`confirmation`) is refused unless the user or `confirmation`
+         * switched the question off. A server that only offers read tools uses none of it (12.3.0+).
+         * @default false
+         */
+        stateless?: boolean;
       };
 
   /** Rate limiting for prompts. */
@@ -4387,6 +4457,10 @@ interface IBetterAuthBase {
      * Disable user registration (sign-up) via BetterAuth.
      * Passed through to better-auth's native emailAndPassword.disableSignUp.
      * Custom endpoints (GraphQL + REST) also check this flag early.
+     * Since 12.3.0 it closes social sign-up too: every configured social provider receives it as its own
+     * `disableSignUp`, so a first sign-in through Google, GitHub etc. creates no account, while existing users keep
+     * signing in. `socialProviders.<name>.disableSignUp: false` opens one provider deliberately. Plugins a project
+     * registers itself through `options.plugins` are not covered.
      * The Swagger document built by `setupSwagger()` then leaves out `POST /iam/sign-up/email`,
      * which would answer `SIGNUP_DISABLED` to every caller.
      * @default false
@@ -5002,6 +5076,7 @@ export interface ICoreModuleOverrides {
    * - `slotService` must extend `CoreAiSlotService`
    * - `toolGrantService` must extend `CoreAiToolGrantService`
    * - `toolPolicyService` must extend `CoreAiToolPolicyService`
+   * - `userSettingService` must extend `CoreAiUserSettingService`
    *
    * @example
    * ```typescript
@@ -5035,6 +5110,7 @@ export interface ICoreModuleOverrides {
     slotService?: Type<any>;
     toolGrantService?: Type<any>;
     toolPolicyService?: Type<any>;
+    userSettingService?: Type<any>;
   };
 
   /**

package/src/core/common/persistence/sync-model.ts

@@ -9,7 +9,7 @@ import type {
 export type { SyncDescriptor, SyncIdFormat } from './model-descriptor.interface.js';
 
 /**
- * Synchronized models (offline sync, `docs/offline-sync-protocol.md`, plan `.claude/plans/offline-sync/PLAN.md` §3.2).
+ * Synchronized models (offline sync, `docs/offline-sync-protocol.md`, offline-sync plan §3.2).
  *
  * A model declared with `@PersistedModel({ sync })` carries three system fields every store maintains and no caller
  * writes — `version`, `deletedAt` and its position in the change order — and its delete leaves a tombstone instead of

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

@@ -146,9 +146,10 @@ ai: {
 }
 ```
 
-- **Plan mode / pre-flight permissions:** give data-mutating tools an `authorize()` that
-  checks permission WITHOUT mutating (e.g. load the record + verify ownership). Plan mode
-  runs it for every step before executing anything.
+- **Data-level permissions:** give data-mutating tools an `authorize()` that checks
+  permission WITHOUT mutating (e.g. load the record + verify ownership). It runs before every
+  execution — auto mode, plan mode (for every step before anything runs) and MCP (12.3.0+);
+  return `data` to hand the loaded record to `execute()` (`context.authorization.data`).
 - **Confirmation:** mark create/update/delete tools `mutating: true` and irreversible ones
   `destructive: true`.
 - **Self-optimizing prompts:** the system prompt is built from editable, keyed slots —
@@ -174,8 +175,9 @@ ai: {
   `deferToolSummaryChars` (~200–400) ALONGSIDE it — otherwise the descriptions alone
   re-inflate the prompt you just shrank. Both are scoped to the **emulated tool protocol**:
   in auto mode a connection with `supportsNativeTools: true` gets every full description and
-  schema in the native `tools` payload regardless, so truncation and the banner are skipped
-  there. **Plan mode always uses the emulated protocol**, so a native connection IS truncated
+  schema in the native `tools` payload regardless, and its prompt catalog lists names only
+  (12.3.0+, `ai.nativeToolCatalog: 'full'` restores it), so truncation and the banner are
+  skipped there. **Plan mode always uses the emulated protocol**, so a native connection IS truncated
   there — and since plan mode plans in one call without executing, it cannot follow the
   `search_tools` hint. Keep the cap generous if you use plan mode.
   The truncated tail is typically where a tool's preconditions and role limits are written;
@@ -183,10 +185,16 @@ ai: {
   stays with the registry's role filter, the execution-time re-check, and the
   `mutating`/`destructive` flags behind the confirmation gate, none of which read the
   description.
-- **Where data-level checks belong:** `authorize()` runs in **plan mode only**. In auto mode
-  (the default) and over MCP, the orchestrator calls `execute()` directly. Put ownership and
-  tenant checks INSIDE `execute()` (via `CrudService` + `context.serviceOptions`) — a check
-  that lives only in `authorize()` will not run for most callers.
+- **Guarding the prompt size in a test?** Measure against `ai.contextWindow`, the fallback for
+  connections without a window of their own, and name the test that way: it guards the worst
+  case, not the window a pinned or detected connection has. Raising its limit removes the guard;
+  shrink the catalog instead. At runtime the framework warns once per connection when the system
+  prompt and tool definitions take more than half of the real input budget.
+- **Where data-level checks belong:** `authorize()` decides whether a call may be tried;
+  `execute()` still routes every read and write through `CrudService` +
+  `context.serviceOptions`, so `@Restricted`, `securityCheck()` and tenant scoping apply.
+  Until 12.2 `authorize()` ran in plan mode only — a project that moved its checks into
+  `execute()` for that reason keeps working unchanged.
 
 ### MCP server (only when `ai.mcp.enabled` or `ai.mcp` is truthy)
 
@@ -200,10 +208,14 @@ A **503 Service Unavailable** from `/ai/mcp` therefore means the module could no
 _resolved_, not that it is missing — check the server log for the underlying error.
 The response body carries the stable `#LTNS_0901` code, never the raw error.
 
-> **No confirmation gate over MCP.** `mcpCallTool` does not consult the
-> `mutating`/`destructive` flags, and `authorize()` does not run there either. A
-> destructive tool invoked through `/ai/mcp` executes immediately. Only expose MCP to
-> clients you trust, and put every permission check inside `execute()`.
+> **Confirmation over MCP (12.3.0+).** `tools/call` applies the admin's tool policies and
+> `authorize()`, and asks the user through MCP elicitation before a `destructive` tool (or a
+> `mutating` one under `ai.confirmation.mutating`) runs. A client without elicitation gets an
+> error result. Each user may switch the question off (and on) for themselves via
+> `PUT /ai/settings` / `updateAiSettings`; `ai.mcp.confirmation` sets the default
+> (`false` = off) and `{ enforced: true }` takes the switch away. **Check your MCP clients**
+> and offer users the switch in your UI (`GET /ai/settings` says whether it is enforced).
+> See the module README, "Authorization and confirmation over MCP".
 
 ### MCP OAuth 2.1 (only when `ai.mcp.oauth` is enabled)
 
@@ -229,9 +241,15 @@ Put `{returnTo}` into it only if that login page can send the user back to the A
 (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
+`renderConsentPage(view)` (restyle — `renderMcpOAuthConsentPage(view, { texts, styles })` changes wording and
+CSS without copying markup, scripts or headers; fill both from code or configuration only) or
+`authorizeConsent(client, params, res)` (replace), registered via
 `CoreModule.forRoot(envConfig, { ai: { mcpOAuthService: McpOAuthService } })`.
 
+**Optional — no sticky sessions:** `ai: { mcp: { stateless: true } }` serves `/ai/mcp` without sessions, so any
+replica answers any request. Without a session the server cannot ask the user (no MCP elicitation): tools that
+need confirmation are refused there unless the user or `ai.mcp.confirmation` switched the question off.
+
 **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
@@ -242,7 +260,10 @@ with a CSRF token.
 **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.
+a server error. Check the CSRF token on Deny as on Allow (12.3.0): the refusal redirects the browser to
+the client's registered URI, so an unprotected Deny lets a cross-site POST send a signed-in user there.
+An error before your method runs (a malformed request) is answered with 400 by the framework and never
+redirected.
 
 ## Verification Checklist