@lenne.tech/nest-server 12.2.0 → 12.3.0

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/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;
 
@@ -975,6 +981,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 +2021,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 +2084,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 +2114,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 +2176,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 +2219,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 +4453,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 +5072,7 @@ export interface ICoreModuleOverrides {
    * - `slotService` must extend `CoreAiSlotService`
    * - `toolGrantService` must extend `CoreAiToolGrantService`
    * - `toolPolicyService` must extend `CoreAiToolPolicyService`
+   * - `userSettingService` must extend `CoreAiUserSettingService`
    *
    * @example
    * ```typescript
@@ -5035,6 +5106,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