@lenne.tech/nest-server 11.41.8 → 11.42.0

package/src/core/common/helpers/outbound-url.helper.ts

@@ -0,0 +1,310 @@
+import { lookup as dnsLookup, type LookupAddress } from 'node:dns';
+import { BlockList, isIP } from 'node:net';
+import { Agent, buildConnector, fetch as undiciFetch } from 'undici';
+
+import { ConfigService } from '../services/config.service';
+
+/**
+ * Requests to a URL a USER entered — a webhook, an export target, an ERP address.
+ *
+ * The server calls such a URL from inside its own network. Without a check, a user points it at the
+ * neighbourhood — the database, other containers, the cloud metadata service at 169.254.169.254 — and,
+ * wherever the response is stored or shown, reads the answer back (SSRF).
+ *
+ * **Only for user-entered URLs.** Targets the operator configured (AI providers, SMTP, S3, Redis,
+ * Brevo) do not go through this; nothing here is applied globally.
+ *
+ * The check runs twice on purpose:
+ * 1. {@link assertOutboundUrlAllowed} on the URL before anything is sent — a readable error, and
+ * 2. on every connection through {@link createOutboundDispatcher} — the only place that sees a
+ *    redirect's next hop and the address a DNS name resolves to at connect time (rebinding).
+ *
+ * {@link outboundFetch} does both.
+ *
+ * Internal targets are refused on deployed stages (including `test`) and allowed locally, in e2e and CI,
+ * where the counterpart often runs in the same network. `security.allowPrivateOutboundTargets`
+ * (`NSC__SECURITY__ALLOW_PRIVATE_OUTBOUND_TARGETS=true|false`) decides it explicitly either way;
+ * `allowedHosts` frees individual internal hosts without opening all of them.
+ */
+
+const blocked = new BlockList();
+for (const [network, prefix] of [
+  ['0.0.0.0', 8], // "this network"
+  ['10.0.0.0', 8], // RFC 1918
+  ['100.64.0.0', 10], // carrier-grade NAT
+  ['127.0.0.0', 8], // loopback
+  ['169.254.0.0', 16], // link-local, incl. the cloud metadata service
+  ['172.16.0.0', 12], // RFC 1918
+  ['192.0.0.0', 24], // IETF protocol assignments
+  ['192.168.0.0', 16], // RFC 1918
+  ['198.18.0.0', 15], // benchmarking
+  ['224.0.0.0', 4], // multicast
+  ['240.0.0.0', 4], // reserved, incl. broadcast
+] as const) {
+  blocked.addSubnet(network, prefix, 'ipv4');
+}
+for (const [network, prefix] of [
+  ['::', 96], // unspecified, loopback and IPv4-compatible (::a.b.c.d)
+  ['64:ff9b::', 96], // NAT64 — embeds an IPv4 address
+  ['fc00::', 7], // unique local
+  ['fe80::', 10], // link-local
+  ['ff00::', 8], // multicast
+] as const) {
+  blocked.addSubnet(network, prefix, 'ipv6');
+}
+
+/**
+ * Environments in which internal targets are allowed unless configured otherwise. Deliberately NOT
+ * `test`: in projects built from nest-server-starter that is a DEPLOYED stage.
+ */
+const LOCAL_ENVIRONMENTS = new Set(['ci', 'e2e', 'local']);
+
+/** Thrown for a target that is, or resolves to, an internal address. */
+export class OutboundUrlBlockedError extends Error {
+  constructor(
+    readonly host: string,
+    readonly address: string,
+  ) {
+    super(
+      `Outbound target not allowed: "${host}" points to the internal address ${address}. ` +
+        'Use a public address, list the host in allowedHosts, or set security.allowPrivateOutboundTargets.',
+    );
+    this.name = 'OutboundUrlBlockedError';
+  }
+}
+
+export interface IOutboundUrlOptions {
+  /**
+   * Internal hosts that may be reached anyway, e.g. an ERP in the same network. `'erp.local:8443'`
+   * matches that port only, `'erp.local'` and `'10.0.0.5'` any port. Matched against the host as
+   * written in the URL — and on every connection, so a redirect does not inherit the exemption.
+   */
+  allowedHosts?: string[];
+}
+
+/** Whether internal targets are allowed at all — explicit config first, then the environment. */
+export function privateOutboundTargetsAllowed(): boolean {
+  const config = ConfigService.configFastButReadOnly;
+  // Read loosely: a value from NSC__* or NEST_SERVER_CONFIG may arrive as a string.
+  const flag = config?.security?.allowPrivateOutboundTargets as unknown;
+  if (flag === true || flag === 'true') {
+    return true;
+  }
+  if (flag === false || flag === 'false') {
+    return false;
+  }
+  const env = String(config?.env ?? process.env.NODE_ENV ?? '')
+    .trim()
+    .toLowerCase();
+  return LOCAL_ENVIRONMENTS.has(env);
+}
+
+/** Whether an IP address is internal. A hostname (not an IP) answers false — resolve it first. */
+export function isBlockedOutboundAddress(address: string): boolean {
+  const plain = stripBrackets(address);
+  const family = isIP(plain);
+  if (family === 4) {
+    return blocked.check(plain, 'ipv4');
+  }
+  if (family === 6) {
+    const mapped = mappedIpv4(plain);
+    return mapped ? blocked.check(mapped, 'ipv4') : blocked.check(plain, 'ipv6');
+  }
+  return false;
+}
+
+/**
+ * Refuses a URL whose scheme is not http(s) or whose host is, or resolves to, an internal address.
+ * Returns the parsed URL. A redirect is NOT covered here — send the request through
+ * {@link outboundFetch} or {@link createOutboundDispatcher}.
+ */
+export async function assertOutboundUrlAllowed(url: string, options: IOutboundUrlOptions = {}): Promise<URL> {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid outbound URL: "${url}"`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`Outbound URL must use http:// or https://: "${url}"`);
+  }
+  const host = stripBrackets(parsed.hostname);
+  if (privateOutboundTargetsAllowed() || isAllowedHost(host, effectivePort(parsed.port, parsed.protocol), options)) {
+    return parsed;
+  }
+  const addresses = isIP(host) ? [host] : await resolveAll(host);
+  const internal = addresses.find(isBlockedOutboundAddress);
+  if (internal) {
+    throw new OutboundUrlBlockedError(host, internal);
+  }
+  return parsed;
+}
+
+const plainConnect = buildConnector({});
+const guardedConnect = buildConnector({ lookup: guardedLookup as never });
+
+/**
+ * An undici dispatcher that refuses every connection to an internal address — whether the host came
+ * as a name or as a literal, and whether it is the first URL or a redirect's next hop. Use it with
+ * undici's own `fetch`/`request`; {@link outboundFetch} does that for you.
+ */
+export function createOutboundDispatcher(options: IOutboundUrlOptions = {}): Agent {
+  return new Agent({
+    connect: (connectOptions, callback) => {
+      const host = stripBrackets(String(connectOptions.hostname ?? ''));
+      const port = effectivePort(connectOptions.port, connectOptions.protocol);
+      if (privateOutboundTargetsAllowed() || isAllowedHost(host, port, options)) {
+        plainConnect(connectOptions, callback);
+        return;
+      }
+      if (isIP(host) && isBlockedOutboundAddress(host)) {
+        callback(new OutboundUrlBlockedError(host, host), null);
+        return;
+      }
+      guardedConnect(connectOptions, callback);
+    },
+  });
+}
+
+let defaultDispatcher: Agent | undefined;
+const allowListDispatchers = new Map<string, Agent>();
+const MAX_ALLOW_LIST_DISPATCHERS = 50;
+
+/**
+ * `fetch` for a user-entered URL: the URL check first (a readable {@link OutboundUrlBlockedError}),
+ * then the request through a guarded dispatcher. Uses undici's own `fetch`, so the dispatcher always
+ * matches the client — Node's built-in `fetch` bundles a different undici major on Node 22.
+ *
+ * A refusal on a later hop (redirect, rebinding) surfaces as undici's `TypeError: fetch failed` with
+ * the {@link OutboundUrlBlockedError} as its `cause`.
+ */
+export async function outboundFetch(
+  url: string,
+  init: Parameters<typeof undiciFetch>[1] = {},
+  options: IOutboundUrlOptions = {},
+): ReturnType<typeof undiciFetch> {
+  await assertOutboundUrlAllowed(url, options);
+  return undiciFetch(url, { ...init, dispatcher: dispatcherFor(options) });
+}
+
+function dispatcherFor(options: IOutboundUrlOptions): Agent {
+  const hosts = (options.allowedHosts ?? []).map(normalizeHost).filter(Boolean).sort();
+  if (!hosts.length) {
+    defaultDispatcher ??= createOutboundDispatcher();
+    return defaultDispatcher;
+  }
+  const key = hosts.join(',');
+  let dispatcher = allowListDispatchers.get(key);
+  if (!dispatcher) {
+    if (allowListDispatchers.size >= MAX_ALLOW_LIST_DISPATCHERS) {
+      const [oldestKey, oldest] = allowListDispatchers.entries().next().value as [string, Agent];
+      allowListDispatchers.delete(oldestKey);
+      void oldest.close().catch(() => undefined);
+    }
+    dispatcher = createOutboundDispatcher({ allowedHosts: hosts });
+    allowListDispatchers.set(key, dispatcher);
+  }
+  return dispatcher;
+}
+
+function guardedLookup(
+  hostname: string,
+  options: { all?: boolean; family?: number },
+  callback: (err: Error | null, address?: LookupAddress[] | string, family?: number) => void,
+): void {
+  dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {
+    if (err) {
+      callback(err);
+      return;
+    }
+    const list = addresses as LookupAddress[];
+    const internal = list.find((entry) => isBlockedOutboundAddress(entry.address));
+    if (internal) {
+      callback(new OutboundUrlBlockedError(hostname, internal.address));
+      return;
+    }
+    if (options.all) {
+      callback(null, list);
+      return;
+    }
+    callback(null, list[0]?.address, list[0]?.family);
+  });
+}
+
+function resolveAll(host: string): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    dnsLookup(host, { all: true }, (err, addresses) => {
+      if (err) {
+        reject(new Error(`Outbound target cannot be resolved: "${host}" (${err.message})`));
+        return;
+      }
+      resolve(addresses.map((entry) => entry.address));
+    });
+  });
+}
+
+function isAllowedHost(host: string, port: string, options: IOutboundUrlOptions): boolean {
+  const wanted = host.toLowerCase();
+  return (options.allowedHosts ?? []).some((entry) => {
+    const normalized = normalizeHost(entry);
+    if (!normalized) {
+      return false;
+    }
+    const [entryHost, entryPort] = splitHostPort(normalized);
+    return entryHost === wanted && (!entryPort || entryPort === port);
+  });
+}
+
+/** `Host`, `host:port`, `[v6]` and `[v6]:port`, lowercased, IPv6 canonicalised; '' when unusable. */
+function normalizeHost(entry: string): string {
+  if (typeof entry !== 'string' || !entry.trim()) {
+    return '';
+  }
+  try {
+    const url = new URL(`http://${entry.trim()}`);
+    const host = stripBrackets(url.hostname).toLowerCase();
+    return url.port ? `${host.includes(':') ? `[${host}]` : host}:${url.port}` : host;
+  } catch {
+    return '';
+  }
+}
+
+function splitHostPort(normalized: string): [string, string] {
+  const v6 = /^\[(.+)\]:(\d+)$/.exec(normalized);
+  if (v6) {
+    return [v6[1], v6[2]];
+  }
+  if (isIP(normalized) === 6) {
+    return [normalized, ''];
+  }
+  const index = normalized.lastIndexOf(':');
+  return index === -1 ? [normalized, ''] : [normalized.slice(0, index), normalized.slice(index + 1)];
+}
+
+function effectivePort(port: number | string | null | undefined, protocol: string | null | undefined): string {
+  if (port !== undefined && port !== null && String(port) !== '') {
+    return String(port);
+  }
+  return protocol === 'https:' ? '443' : '80';
+}
+
+function stripBrackets(value: string): string {
+  return value.replace(/^\[|\]$/g, '');
+}
+
+/** The IPv4 address inside an IPv4-mapped IPv6 address, in any notation. */
+function mappedIpv4(address: string): string | undefined {
+  let canonical: string;
+  try {
+    canonical = stripBrackets(new URL(`http://[${address}]`).hostname);
+  } catch {
+    return undefined;
+  }
+  const match = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(canonical);
+  if (!match) {
+    return undefined;
+  }
+  const high = parseInt(match[1], 16);
+  const low = parseInt(match[2], 16);
+  return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}

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

@@ -10,6 +10,7 @@ import type { MongoosePingCheckSettings } from '@nestjs/terminus/dist/health-ind
 import type { DiskHealthIndicatorOptions } from '@nestjs/terminus/dist/health-indicator/disk/disk-health-options.type.js';
 import compression from 'compression';
 import { CollationOptions } from 'mongodb';
+import type { Connection } from 'mongoose';
 import type * as JSONTransport from 'nodemailer/lib/json-transport';
 import type * as SendmailTransport from 'nodemailer/lib/sendmail-transport';
 import type * as SESTransport from 'nodemailer/lib/ses-transport';
@@ -1477,6 +1478,43 @@ export interface IMultiTenancy {
    * @since 11.21.1
    */
   cacheTtlMs?: number;
+
+  /**
+   * Whether a tenant may be used at all — the hook that makes a DEACTIVATED tenant stop working.
+   *
+   * The tenant guard validates a membership and nothing else, so without this a tenant a project
+   * switched off keeps working for every member, every API token and every request without a tenant
+   * header. Asked after the membership check, on every path that establishes a tenant:
+   *
+   * - header paths (tenant roles, `S_USER` / `S_VERIFIED` with a header): **403**
+   * - tenant API tokens: **403**
+   * - public (`S_EVERYONE`) routes: not blocked, but no tenant context is set
+   * - no header: the tenant is dropped from the user's tenant list, so its data stays out of reach
+   * - GraphQL over WebSocket: no tenant is resolved for a NEW subscription; one already open keeps
+   *   its tenant until the client reconnects (as it does after a removed membership)
+   *
+   * A platform administrator under `adminBypass` still reaches the tenant — somebody has to be able to
+   * look into it and switch it back on.
+   *
+   * Return `false` for an inactive tenant; any other value (including `undefined`) counts as active.
+   * `context.connection` is the main database connection, for a lookup in the project's own tenant
+   * collection. Answers are cached for {@link cacheTtlMs}; after switching a tenant on or off, call
+   * `CoreTenantGuard.invalidateTenant(tenantId)` (broadcast to every replica when Redis is
+   * configured). A function cannot arrive through `NSC__*` / `NEST_SERVER_CONFIG` — set it in
+   * `config.env.ts`.
+   *
+   * @example
+   * ```typescript
+   * multiTenancy: {
+   *   isTenantActive: async (tenantId, { connection }) =>
+   *     (await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false,
+   * }
+   * ```
+   *
+   * @default undefined (every tenant is active)
+   * @since 11.42.0
+   */
+  isTenantActive?: (tenantId: string, context: { connection: Connection }) => boolean | Promise<boolean>;
 }
 
 /**
@@ -2855,6 +2893,22 @@ export interface IServerOptions {
    * Configuration for security pipes and interceptors
    */
   security?: {
+    /**
+     * Whether the outbound URL guard (`outboundFetch`, `assertOutboundUrlAllowed`,
+     * `createOutboundDispatcher`) may reach INTERNAL addresses — loopback, private networks,
+     * link-local incl. the cloud metadata service.
+     *
+     * The guard is for URLs a USER entered (webhooks, export targets); configured targets do not use
+     * it. Unset, internal targets are allowed in the `local`, `e2e` and `ci` environments and
+     * refused everywhere else. `true` / `false` decide it explicitly
+     * (`NSC__SECURITY__ALLOW_PRIVATE_OUTBOUND_TARGETS`). To free a single internal host, pass
+     * `allowedHosts` to the call instead of opening all of them.
+     *
+     * @default undefined (allowed only in local, e2e and ci — not in `test`, a deployed stage in starter-based projects)
+     * @since 11.42.0
+     */
+    allowPrivateOutboundTargets?: boolean;
+
     /**
      * Check restrictions for output (models and output objects)
      * See @lenne.tech/nest-server/src/core/common/interceptors/check-response.interceptor.ts

package/src/core/common/middleware/request-context.middleware.ts

@@ -33,6 +33,7 @@ export class RequestContextMiddleware implements NestMiddleware {
       get isAdminBypass() {
         return (req as any).isAdminBypass ?? false;
       },
+      fromRequest: true,
     };
     RequestContext.run(context, () => next());
   }

package/src/core/common/services/request-context.service.ts

@@ -19,6 +19,15 @@ export interface IRequestContext {
   tenantRole?: string;
   /** When true, indicates admin bypass is active (admin without header sees all data) */
   isAdminBypass?: boolean;
+  /**
+   * Set by `RequestContextMiddleware` (HTTP) and the GraphQL WebSocket context builder: this context
+   * belongs to a CLIENT operation, signed in or not. Absent for work the server does on its own —
+   * cron jobs, migrations, seeds, a `runWithBypass…()` outside a request.
+   *
+   * It is what tells an anonymous request apart from system work: both have no current user, and a
+   * check that exempts system work must not exempt the anonymous caller of a public route with it.
+   */
+  fromRequest?: boolean;
   /**
    * Tracks the nesting depth of process() calls.
    * 0 = outermost call (full pipeline), > 0 = nested call (reduced pipeline).

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

@@ -600,6 +600,31 @@ ai: {
 
 - tokens, limits, reset) is available via the `aiUsage` query / `GET /ai/usage`.
 
+## Tool access is the user's access
+
+An AI client — the chat's agent loop or an MCP client — acts **on behalf of the signed-in user and
+never beyond that user's rights**. Three things make that hold, and a project's tools must not undo
+them:
+
+- **Visibility and execution** are decided by `AiToolRegistry.userCanAccess()`, evaluated per request —
+  over MCP with the user as of THAT request, not as of the session's `initialize` (11.42.0+), so a
+  revoked role stops working without a reconnect.
+  Under multi-tenancy (11.42.0+) it resolves a tool's `roles` like `CoreTenantGuard` resolves
+  `@Roles()`: a global role (`RoleEnum.ADMIN`, `multiTenancy.globalOnlyRoles`) against `user.roles`, a
+  tenant role against the **membership role in the request's tenant** (by hierarchy), and the ADMIN
+  bypass only where `multiTenancy.adminBypass` grants it. Before, every role was compared with the
+  global `user.roles` — a tool requiring the tenant role `owner` was offered to nobody who held it as
+  a membership, and to anyone holding a global role of that name.
+- **Data** is scoped by the request context: a tool runs inside the HTTP request (chat or `/ai/mcp`),
+  so `mongooseTenantPlugin` filters by the tenant the guard validated. Without a tenant header there
+  is no tenant scope on these routes and tenant-scoped reads are refused (403) — an AI client is
+  never broader than its user, at worst narrower.
+- **Service-level rules** apply on every entry point when the service enforces them itself —
+  `assertTenantRole()` (see the tenant module README) — instead of relying on a controller's
+  `@Roles()`, which a tool calling the service never passes through.
+
+Without multi-tenancy, tool roles are compared with `user.roles` exactly as before.
+
 ## MCP server (`ai.mcp: true`)
 
 The `AiToolRegistry` also feeds a real **MCP server** at `POST/GET/DELETE /ai/mcp`

package/src/core/modules/ai/core-ai-mcp.controller.ts

@@ -11,6 +11,7 @@ import { CoreBetterAuthModule } from '../better-auth/core-better-auth.module';
 import { ErrorCode } from '../error-code/error-codes';
 import { CoreAiMcpOAuthService } from './services/core-ai-mcp-oauth.service';
 import { CoreAiMcpService } from './services/core-ai-mcp.service';
+import { AiToolUser } from './tools/ai-tool.registry';
 
 /**
  * MCP Streamable-HTTP endpoint at `/ai/mcp`.
@@ -49,6 +50,18 @@ import { CoreAiMcpService } from './services/core-ai-mcp.service';
  * ids would learn both that a session id is valid and the internal hostname/PID holding it,
  * where the same probe against the local map deliberately answers 404.
  */
+/**
+ * One MCP session: its transport, its owner, and the owner AS OF THE LATEST REQUEST. `user` is
+ * refreshed on every request so the server — which reads it through a getter — always acts with the
+ * user's current rights rather than those from `initialize`.
+ */
+interface McpSessionEntry {
+  lastUsed: number;
+  ownerId: string;
+  transport: any;
+  user: AiToolUser;
+}
+
 @ApiExcludeController()
 @Controller('ai/mcp')
 @Roles(RoleEnum.S_EVERYONE)
@@ -65,7 +78,7 @@ export class CoreAiMcpController implements OnModuleDestroy {
    * anyone holding another user's session id drives that user's server — the id travels in a
    * response header, through proxies and client logs.
    */
-  private readonly transports = new Map<string, { lastUsed: number; ownerId: string; transport: any }>();
+  private readonly transports = new Map<string, McpSessionEntry>();
 
   /**
    * Cap on concurrent MCP sessions held by ONE user.
@@ -160,7 +173,10 @@ export class CoreAiMcpController implements OnModuleDestroy {
       }
       const { randomUUID } = await import('node:crypto');
       const transport: any = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
-      const server = await this.mcpService.createServer(user);
+      // The server reads the user through a getter on every request; `user` below is refreshed by
+      // each request of the session, so a role revoked mid-session takes effect at once.
+      const created: McpSessionEntry = { lastUsed: Date.now(), ownerId: user.id, transport, user };
+      const server = await this.mcpService.createServer(() => created.user);
       await server.connect(transport);
       // The MCP SDK transport exposes `onclose` as a callback property (not a DOM
       // EventTarget), so addEventListener does not apply here.
@@ -171,10 +187,12 @@ export class CoreAiMcpController implements OnModuleDestroy {
           this.releaseSession(transport.sessionId);
         }
       };
-      entry = { lastUsed: Date.now(), ownerId: user.id, transport };
+      entry = created;
     }
 
     entry.lastUsed = Date.now();
+    // Same owner (checked above), possibly different rights than at `initialize`.
+    entry.user = user;
     await entry.transport.handleRequest(req, res, req.body);
 
     // The sessionId is assigned during handleRequest (initialize); register after.
@@ -280,6 +298,7 @@ export class CoreAiMcpController implements OnModuleDestroy {
       return;
     }
     entry.lastUsed = Date.now();
+    entry.user = user;
     this.registerSession(sessionId as string, user.id);
     await entry.transport.handleRequest(req, res, (req as any).body);
   }

package/src/core/modules/ai/services/core-ai-mcp.service.ts

@@ -76,17 +76,23 @@ export class CoreAiMcpService {
   /**
    * Create a low-level MCP server bound to a user. Uses the JSON-schema tool
    * definitions directly (no zod conversion needed). The SDK is imported lazily.
+   *
+   * Pass a GETTER rather than a user object: an MCP session stays open for hours, and every
+   * `tools/list` / `tools/call` must use the user's CURRENT rights — a role revoked after
+   * `initialize` must not survive in the session. `CoreAiMcpController` passes a getter it refreshes
+   * on every request (11.42.0+). A plain object is still accepted and is then fixed for the session.
    */
-  async createServer(user: AiToolUser): Promise<any> {
+  async createServer(user: AiToolUser | (() => AiToolUser)): Promise<any> {
+    const currentUser = (): AiToolUser => (typeof user === 'function' ? user() : user);
     const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
     const { CallToolRequestSchema, ListToolsRequestSchema } = await import('@modelcontextprotocol/sdk/types.js');
 
     // Loosely typed to decouple from the SDK's strict request/result types.
     const server: any = new Server({ name: 'lt-nest-server-ai', version: '1.0.0' }, { capabilities: { tools: {} } });
 
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this.mcpListTools(user) }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this.mcpListTools(currentUser()) }));
     server.setRequestHandler(CallToolRequestSchema, async (request: any) =>
-      this.mcpCallTool(user, request.params.name, request.params.arguments ?? {}),
+      this.mcpCallTool(currentUser(), request.params.name, request.params.arguments ?? {}),
     );
 
     return server;

package/src/core/modules/ai/tools/ai-tool.registry.ts

@@ -1,6 +1,14 @@
 import { Injectable, Logger } from '@nestjs/common';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
+import { ConfigService } from '../../../common/services/config.service';
+import { RequestContext } from '../../../common/services/request-context.service';
+import {
+  checkRoleAccess,
+  isMultiTenancyActive,
+  resolveGlobalAndTenantRoles,
+  tenantSatisfiableRoles,
+} from '../../tenant/core-tenant.helpers';
 import { IAiTool } from '../interfaces/ai-tool.interface';
 
 /**
@@ -75,6 +83,13 @@ export class AiToolRegistry {
 
   /**
    * Whether a user satisfies a tool's role requirements.
+   *
+   * The answer is what an AI client — the MCP server or the chat's agent loop — may do on the user's
+   * behalf, so it must not exceed what the user may do through the API. Under multi-tenancy each role
+   * is therefore resolved like `CoreTenantGuard` resolves a `@Roles()`: a global role against
+   * `user.roles`, a tenant role against the membership role of the current request's tenant (by
+   * hierarchy), and the ADMIN bypass only where `multiTenancy.adminBypass` grants it. Without
+   * multi-tenancy, roles are compared with `user.roles` as they always were.
    */
   userCanAccess(tool: IAiTool, user: AiToolUser | null | undefined): boolean {
     const roles = tool.roles ?? [];
@@ -94,8 +109,11 @@ export class AiToolRegistry {
       return false;
     }
 
-    // Admin bypass.
-    if (user.roles?.includes(RoleEnum.ADMIN)) {
+    const multiTenancy = isMultiTenancyActive();
+
+    // Admin bypass — unless multi-tenancy withholds it (adminBypass: false).
+    const adminBypass = !multiTenancy || ConfigService.configFastButReadOnly?.multiTenancy?.adminBypass !== false;
+    if (adminBypass && user.roles?.includes(RoleEnum.ADMIN)) {
       return true;
     }
 
@@ -119,6 +137,18 @@ export class AiToolRegistry {
       RoleEnum.S_VERIFIED,
     ];
     const requiredRealRoles = roles.filter((r) => !systemRoles.includes(r));
-    return requiredRealRoles.some((r) => user.roles?.includes(r));
+    if (!multiTenancy) {
+      return requiredRealRoles.some((r) => user.roles?.includes(r));
+    }
+
+    // Multi-tenancy: each role answered by the source entitled to answer it.
+    const { global } = resolveGlobalAndTenantRoles(requiredRealRoles);
+    if (global.some((r) => user.roles?.includes(r))) {
+      return true;
+    }
+    // In a tenant, only the membership role counts; outside one, user.roles — as in the guard.
+    // The length guard matters: checkRoleAccess() answers TRUE for an empty required list.
+    const tenantRoles = tenantSatisfiableRoles(requiredRealRoles);
+    return tenantRoles.length > 0 && checkRoleAccess(tenantRoles, user.roles, RequestContext.get()?.tenantRole);
   }
 }

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -494,7 +494,12 @@ See: `.claude/rules/module-inheritance.md` for the full pattern.
 
 ## Client-Side Configuration
 
-Clients must be configured to use the correct base path and hash passwords:
+Clients must be configured to use the correct base path and hash passwords.
+
+> **Nuxt projects on `@lenne.tech/nuxt-extensions`** get all of this preconfigured: `useLtAuthClient()`
+> is the Better-Auth client (base path, password hashing, plugins), and `useLtAuth()` holds the auth
+> state plus the JWT-safe passkey helpers used below. The hand-written client that follows is for
+> clients outside that stack.
 
 ```typescript
 // auth-client.ts (e.g., for Nuxt/Vue)
@@ -622,14 +627,14 @@ async function useBackupCode(code: string) {
 
 Handle passkey authentication with session validation fallback.
 
-**IMPORTANT:** For JWT mode (`cookies: false`), you MUST use the `authenticateWithPasskey()` function from the composable instead of `authClient.signIn.passkey()` directly. This is because JWT mode requires sending a `challengeId` to the server for challenge verification.
+**IMPORTANT:** For JWT mode (`cookies: false`), you MUST use the `authenticateWithPasskey()` function from `useLtAuth()` instead of `authClient.signIn.passkey()` directly. This is because JWT mode requires sending a `challengeId` to the server for challenge verification.
 
 **Note on Passkey Login Response (v11.13.0+):** The server enriches the passkey verify-authentication response with user data. Better Auth's passkey plugin only returns `{ session }`, but the server fetches the user from the database and adds it to the response. The composable handles both scenarios (user in response vs. fallback to get-session).
 
 ```typescript
 // login.vue - Passkey login (JWT-compatible)
-// Use authenticateWithPasskey from useBetterAuth composable
-const { authenticateWithPasskey, setUser, validateSession } = useBetterAuth();
+// authenticateWithPasskey from useLtAuth() (@lenne.tech/nuxt-extensions)
+const { authenticateWithPasskey, setUser, validateSession } = useLtAuth();
 
 async function onPasskeyLogin() {
   try {
@@ -677,11 +682,13 @@ In JWT mode (`cookies: false`), the server stores WebAuthn challenges in the dat
 
 Register a new passkey for an authenticated user.
 
-**IMPORTANT:** For JWT mode (`cookies: false`), you MUST use the `registerPasskey()` function from the composable. This ensures the `challengeId` is correctly sent to the server.
+**IMPORTANT:** For JWT mode (`cookies: false`), you MUST use the `registerPasskey()` function from `useLtAuth()`. This ensures the `challengeId` is correctly sent to the server.
 
 ```typescript
 // settings.vue - Register new passkey (JWT-compatible)
-const { registerPasskey, listPasskeys, deletePasskey } = useBetterAuth();
+// registerPasskey from useLtAuth(); listing and deleting go through the Better-Auth client
+const { registerPasskey } = useLtAuth();
+const authClient = useLtAuthClient();
 
 async function onRegisterPasskey() {
   try {
@@ -707,16 +714,16 @@ async function onRegisterPasskey() {
 
 // List user's passkeys (works in both modes)
 async function loadPasskeys() {
-  const result = await listPasskeys();
-  if (result.success) {
-    passkeys.value = result.passkeys || [];
+  const { data, error } = await authClient.passkey.listUserPasskeys();
+  if (!error) {
+    passkeys.value = data ?? [];
   }
 }
 
 // Delete a passkey (works in both modes)
 async function onDeletePasskey(passkeyId: string) {
-  const result = await deletePasskey(passkeyId);
-  if (result.success) {
+  const { error } = await authClient.passkey.deletePasskey({ id: passkeyId });
+  if (!error) {
     await loadPasskeys();
   }
 }