@lenne.tech/nest-server 11.41.9 → 11.42.1

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
@@ -3552,6 +3606,23 @@ export interface ITusConfig {
    */
   allowedHeaders?: string[];
 
+  /**
+   * Origins the tus handler may answer a cross-origin request with (`Access-Control-Allow-Origin`).
+   *
+   * Unset, they come from the API's own CORS configuration — `buildCorsConfig()`, the function REST,
+   * GraphQL and Better-Auth share (`appUrl`, `baseUrl`, `cors.allowedOrigins`, `cors.allowAll`).
+   * Without credentialed CORS configured (cookies off, or no origin resolvable) the tus server keeps
+   * its own default, `*`.
+   *
+   * The wildcard is what broke browser uploads with cookie authentication and separate app/API
+   * origins before 11.42.1: a credentialed response with `Access-Control-Allow-Origin: *` is refused
+   * by every browser, although the server answered 201.
+   *
+   * @default undefined (derived from the API CORS configuration)
+   * @since 11.42.1
+   */
+  allowedOrigins?: string[];
+
   /**
    * Allowed MIME types for uploads.
    * If undefined, all types are allowed.

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();
   }
 }

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

@@ -161,6 +161,20 @@ betterAuth: {
 
 See [Tenant README — BetterAuth Integration](./README.md#betterauth-iam-integration) for details.
 
+### 11. Deactivated Tenants and Service-Level Roles (since 11.42.0)
+
+- **Can a tenant be switched off in your project?** Set `multiTenancy.isTenantActive` in
+  `config.env.ts` and call `tenantGuard.invalidateTenant(tenantId)` after switching. WHY: the guard
+  checks the membership only; without the hook a deactivated tenant keeps working for its members,
+  its API tokens and every request without a tenant header.
+- **Does a service enforce a tenant role that a controller also demands?** Call
+  `assertTenantRole(...)` in the service. WHY: MCP and AI tools call the service directly and never
+  pass the controller's `@Roles()`.
+- **Running with `adminBypass: false`?** Platform administrators can no longer set a tenant account's
+  e-mail address or password through `updateUser`; support goes through the password-reset flow.
+
+See the module README: "Deactivated Tenants" and "Service-Level Role Checks".
+
 ## Verification Checklist
 
 - [ ] `pnpm run build` succeeds

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

@@ -211,15 +211,87 @@ It also suppresses tenant membership validation for `S_USER`/`S_VERIFIED` system
 System admins (`RoleEnum.ADMIN`) bypass the membership check by default.
 Disable with `multiTenancy: { adminBypass: false }`.
 
+`adminBypass: false` promises that a platform administrator has no way into a tenant. Since 11.42.0
+two paths that went around that promise follow it too:
+
+- **Credentials:** `CoreUserService.update()` refuses a change of another account's e-mail address or
+  password (403) — for any caller, including the account's creator and other administrators. Exempt:
+  the account itself, profile fields, an unchanged address sent along, and system work without a
+  current user (invitation, password reset). Administrator TARGETS are deliberately not exempt: an
+  administrator may write `roles`, so promote-then-change would open every account. Override
+  `assertCredentialChangeAllowed()` to adjust.
+- **AI tools** (chat and MCP): no ADMIN bypass in the tool registry; tenant-role tools need a
+  membership role like anyone's.
+
+### Deactivated Tenants (`isTenantActive`, since 11.42.0)
+
+The guard validates a membership and nothing else, so a tenant a project switched off keeps working —
+for members, API tokens and the header-less tenant list — unless the project tells the guard:
+
+```typescript
+// config.env.ts
+multiTenancy: {
+  isTenantActive: async (tenantId, { connection }) =>
+    (await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false,
+}
+```
+
+| Path                                                           | Deactivated tenant                                                                                                           |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Header + tenant role, or `S_USER` / `S_VERIFIED` with a header | **403** `Tenant is inactive`                                                                                                 |
+| Tenant API token                                               | **403**                                                                                                                      |
+| `S_EVERYONE` with a header                                     | not blocked, but no tenant context is set                                                                                    |
+| No header                                                      | dropped from the user's tenant list — its data stays out of reach                                                            |
+| GraphQL over WebSocket                                         | no tenant resolved for a new subscription — an open one keeps its tenant until it reconnects (as after a removed membership) |
+| Admin under `adminBypass`                                      | still allowed — somebody has to be able to switch it back on                                                                 |
+
+The hook is asked **after** the membership check, so a non-member learns nothing about a tenant's
+state. Return `false` for inactive; anything else counts as active. Answers are cached for
+`cacheTtlMs`; call `tenantGuard.invalidateTenant(tenantId)` right after switching a tenant on or off
+(broadcast to every replica with Redis). A function cannot come through `NSC__*` — set it in
+`config.env.ts`. A custom guard can override the protected `isTenantActive(tenantId)` instead.
+
+### Service-Level Role Checks (`assertTenantRole`, since 11.42.0)
+
+`@Roles()` protects a controller or resolver method — the route, not the operation. MCP tools, AI tools,
+queue processors and other services call the service directly and never pass that route. Enforce a
+tenant role in the service itself to close every entry point at once:
+
+```typescript
+import { assertTenantRole, DefaultHR } from '@lenne.tech/nest-server';
+
+async updateAiModels(input: AiModelsInput, serviceOptions?: ServiceOptions) {
+  assertTenantRole(DefaultHR.OWNER, 'Only owners may change the AI models');
+  // …
+}
+```
+
+Decided like the guard decides `@Roles()` on the header path: `adminBypass` passes, a global role
+answers from `user.roles`, a tenant role from the request's membership role (by hierarchy; without
+tenant context it fails). Several roles are alternatives. `hasTenantRole(...roles)` answers the same
+question as a boolean.
+
+| Caller                                                                                     | Result  |
+| ------------------------------------------------------------------------------------------ | ------- |
+| Signed in, role held                                                                       | passes  |
+| Signed in, role not held                                                                   | **403** |
+| Anonymous client request (public route)                                                    | **401** |
+| System work — no request context, or one no client request created (cron, migration, seed) | passes  |
+
+The last two rows are told apart by `RequestContext.fromRequest`, which `RequestContextMiddleware` and
+the GraphQL WebSocket context set. Treating "no current user" alone as system work would wave the
+anonymous caller of a public route through.
+
 ### Filtering Without Header
 
-| User State                     | Filter Applied                                                      |
-| ------------------------------ | ------------------------------------------------------------------- |
-| Not authenticated, no context  | Safety Net: `ForbiddenException` on tenantId-schemas                |
-| Authenticated, no memberships  | Safety Net: `ForbiddenException` on tenantId-schemas                |
-| Authenticated, has memberships | `{ tenantId: { $in: [user's tenant IDs] } }`                        |
-| Authenticated + hierarchy role | `{ tenantId: { $in: [qualified tenant IDs] } }` (filtered by level) |
-| Admin without header           | No filter (sees all data via `isAdminBypass`)                       |
+| User State                                            | Filter Applied                                                      |
+| ----------------------------------------------------- | ------------------------------------------------------------------- |
+| Not authenticated, no context                         | Safety Net: `ForbiddenException` on tenantId-schemas                |
+| Authenticated, no memberships                         | Safety Net: `ForbiddenException` on tenantId-schemas                |
+| Authenticated, has memberships                        | `{ tenantId: { $in: [user's tenant IDs] } }`                        |
+| Authenticated + hierarchy role                        | `{ tenantId: { $in: [qualified tenant IDs] } }` (filtered by level) |
+| Admin without header                                  | No filter (sees all data via `isAdminBypass`)                       |
+| Tenant deactivated (`isTenantActive` returns `false`) | Dropped from the user's tenant IDs (11.42.0+)                       |
 
 ## Extending via Module Inheritance
 
@@ -290,7 +362,7 @@ Both are **instance** methods on the singleton `CoreTenantGuard` — inject it a
 Mechanism, for anyone extending the guard (`core-tenant.guard.ts`):
 
 - The channel is namespaced with the framework's Redis key prefix, so two applications sharing one Redis instance do not clear each other's caches. Two **stages** of the same application do, unless you set `redis.keyPrefix` or `redis.db`.
-- The message is `{ scope: 'user', userId }` or `{ scope: 'all' }`, JSON-encoded.
+- The message is `{ scope: 'user', userId }`, `{ scope: 'tenant', tenantId }` (from `invalidateTenant()`, 11.42.0+) or `{ scope: 'all' }`, JSON-encoded.
 - Subscription uses the shared subscriber connection from `CoreRedisService.getSubscriber()`; the listener is held in a field and detached on destroy, because that connection is shared.
 - **A received broadcast clears locally and does NOT re-publish** (`applyInvalidation()` → `clearUser()` / `clearAll()`, the no-broadcast variants). Re-publishing would bounce the message around the cluster forever.
 - **Publishing is fire-and-forget and failures are debug-level only.** A missed broadcast is not an error: it merely leaves the other replicas' caches stale until their TTL — exactly the no-Redis behaviour. Nothing about a request path depends on the broadcast succeeding.

package/src/core/modules/tenant/core-tenant-role.helper.ts

@@ -0,0 +1,75 @@
+import { looksLikeSystemRole } from '../../common/enums/role.enum';
+import { accessDeniedException } from '../../common/exceptions/access-denied.exception';
+import { RequestContext } from '../../common/services/request-context.service';
+import { checkRoleAccess, resolveGlobalAndTenantRoles, tenantSatisfiableRoles } from './core-tenant.helpers';
+
+/**
+ * Service-level tenant role checks.
+ *
+ * `@Roles()` protects a controller or resolver method — the route, not the operation. A service is
+ * also reached from MCP tools, AI tools, queue processors and other services, and on those paths a
+ * tenant role the controller demands is demanded by nobody. Checking in the service closes every
+ * entry point at once.
+ *
+ * The decision mirrors `CoreTenantGuard` on the tenant-header path:
+ * - an administrator under `adminBypass` passes,
+ * - a GLOBAL role (`RoleEnum.ADMIN`, `multiTenancy.globalOnlyRoles`) is answered by `user.roles`,
+ *   never by a membership role,
+ * - a tenant role is answered by the validated `tenantRole` of the current request (hierarchy roles
+ *   by level, others by exact match) — without tenant context there is nothing to compare, and it
+ *   fails,
+ * - system roles (`S_*`) are runtime checks of their own and never satisfy anything here.
+ *
+ * Several roles read as alternatives, as in `@Roles()`.
+ */
+
+/**
+ * Whether the current request holds one of `roles` in its tenant. `false` without a signed-in user.
+ */
+export function hasTenantRole(...roles: string[]): boolean {
+  const context = RequestContext.get();
+  const user = context?.currentUser;
+  if (!user) {
+    return false;
+  }
+  if (context?.isAdminBypass) {
+    return true;
+  }
+
+  const required = roles.filter((role) => typeof role === 'string' && !looksLikeSystemRole(role));
+  const { global } = resolveGlobalAndTenantRoles(required);
+  if (global.some((role) => user.roles?.includes(role))) {
+    return true;
+  }
+
+  // The length guard matters: checkRoleAccess() answers TRUE for an empty required list.
+  const tenantRoles = tenantSatisfiableRoles(required);
+  return tenantRoles.length > 0 && !!context?.tenantRole && checkRoleAccess(tenantRoles, undefined, context.tenantRole);
+}
+
+/**
+ * Refuses the current operation unless it holds one of `roles` in its tenant.
+ *
+ * Work the server does on its own — no request context at all, or one no client request created
+ * (cron, migration, seed, `runWithBypass…()` outside a request) — passes: there is no caller whose
+ * role could be wrong. An ANONYMOUS client request does not pass: it gets 401, and a signed-in caller
+ * without the role gets 403.
+ *
+ * @example
+ * ```typescript
+ * async updateAiModels(input: AiModelsInput, serviceOptions?: ServiceOptions) {
+ *   assertTenantRole(DefaultHR.OWNER, 'Only owners may change the AI models');
+ *   …
+ * }
+ * ```
+ */
+export function assertTenantRole(roles: string | string[], message?: string): void {
+  const context = RequestContext.get();
+  if (!context?.currentUser && !context?.fromRequest) {
+    return;
+  }
+  const list = Array.isArray(roles) ? roles : [roles];
+  if (!hasTenantRole(...list)) {
+    throw accessDeniedException(context?.currentUser, message);
+  }
+}