@lenne.tech/nest-server 11.41.9 → 11.42.0

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

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -61,7 +61,8 @@ interface CachedTenantIds {
  * Cache invalidation message broadcast between replicas via Redis pub/sub
  */
 interface TenantCacheInvalidation {
-  scope: 'all' | 'user';
+  scope: 'all' | 'tenant' | 'user';
+  tenantId?: string;
   userId?: string;
 }
 
@@ -148,6 +149,9 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
    */
   private readonly tenantIdsCache = new Map<string, CachedTenantIds>();
 
+  /** Answers of `multiTenancy.isTenantActive`, keyed by tenant id (same TTL as the other caches). */
+  private readonly tenantActiveCache = new Map<string, { active: boolean; expiresAt: number }>();
+
   /** Cache TTL in milliseconds. Configurable via multiTenancy.cacheTtlMs (default: 30s, 0 = disabled) */
   private cacheTtlMs: number = 30_000;
   /** Maximum cache entries before eviction */
@@ -223,7 +227,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
 
     if (trimmed) {
       const membership = await this.findMembershipCached(user.id, trimmed);
-      if (!membership) {
+      if (!membership || !(await this.isTenantActive(trimmed))) {
         return {};
       }
       return { tenantId: trimmed, tenantRole: membership.role as string };
@@ -288,6 +292,17 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     }
     this.membershipCache.clear();
     this.tenantIdsCache.clear();
+    this.tenantActiveCache.clear();
+  }
+
+  /**
+   * Forget the cached `multiTenancy.isTenantActive` answer for a tenant.
+   * Call this right after switching a tenant on or off — otherwise the previous answer holds for up to
+   * `cacheTtlMs`. Broadcast to every replica when Redis is enabled.
+   */
+  invalidateTenant(tenantId: string): void {
+    this.tenantActiveCache.delete(tenantId);
+    this.publishInvalidation({ scope: 'tenant', tenantId });
   }
 
   /**
@@ -349,6 +364,10 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       request,
     });
     if (apiTokenKind === ApiTokenKind.TENANT) {
+      // The token is bound to its tenant (set on the request by the helper); a deactivated one ends it.
+      if (request.tenantId) {
+        await this.assertTenantActive(request.tenantId);
+      }
       return true;
     }
     // A user token restricted to one tenant is bound to it like a header naming it — the helper has
@@ -397,7 +416,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       // Never block access — S_EVERYONE endpoints are always public.
       if (headerTenantId && request.user?.id) {
         const membership = await this.findMembershipCached(request.user.id, headerTenantId);
-        if (membership) {
+        if (membership && (await this.isTenantActive(headerTenantId))) {
           request.tenantId = headerTenantId;
           request.tenantRole = capApiTokenTenantRole(request.user, membership.role as string) ?? undefined;
         }
@@ -520,6 +539,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       if (!membership) {
         throw new ForbiddenException('Not a member of this tenant');
       }
+      await this.assertTenantActive(headerTenantId);
 
       // A user token with maxTenantRole acts with the lower of its cap and the membership role; `null`
       // (a role the hierarchy cannot compare with the cap) satisfies no tenant role at all.
@@ -620,7 +640,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       const now = Date.now();
       const cached = this.tenantIdsCache.get(cacheKey);
       if (cached && now < cached.expiresAt) {
-        request.tenantIds = cached.ids;
+        request.tenantIds = await this.filterActiveTenants(cached.ids);
         return;
       }
     }
@@ -648,7 +668,8 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       ids = memberships.map((m) => m.tenant as string);
     }
 
-    request.tenantIds = ids;
+    // The cache keeps the membership answer; activity is filtered per request through its own cache.
+    request.tenantIds = await this.filterActiveTenants(ids);
 
     // Store in process-level cache when enabled
     if (ttl > 0) {
@@ -689,6 +710,8 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       this.clearAll();
     } else if (parsed?.scope === 'user' && parsed.userId) {
       this.clearUser(parsed.userId);
+    } else if (parsed?.scope === 'tenant' && parsed.tenantId) {
+      this.tenantActiveCache.delete(parsed.tenantId);
     }
   }
 
@@ -698,6 +721,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
   protected clearAll(): void {
     this.membershipCache.clear();
     this.tenantIdsCache.clear();
+    this.tenantActiveCache.clear();
   }
 
   /**
@@ -814,6 +838,54 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
         this.tenantIdsCache.delete(key);
       }
     }
+    for (const [key, entry] of this.tenantActiveCache.entries()) {
+      if (now >= entry.expiresAt) {
+        this.tenantActiveCache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Whether a tenant may be used at all — `multiTenancy.isTenantActive`, cached for `cacheTtlMs`.
+   *
+   * Always true without the hook. Asked only AFTER the membership check, so a non-member learns
+   * nothing about a tenant's state. Protected so a custom guard can answer it differently.
+   */
+  protected async isTenantActive(tenantId: string): Promise<boolean> {
+    const hook = ConfigService.configFastButReadOnly?.multiTenancy?.isTenantActive;
+    if (typeof hook !== 'function') {
+      return true;
+    }
+    const ttl = this.cacheTtlMs;
+    const now = Date.now();
+    if (ttl > 0) {
+      const cached = this.tenantActiveCache.get(tenantId);
+      if (cached && now < cached.expiresAt) {
+        return cached.active;
+      }
+    }
+    const active = (await hook(tenantId, { connection: this.memberModel.db })) !== false;
+    if (ttl > 0) {
+      this.evictIfOverCapacity(this.tenantActiveCache);
+      this.tenantActiveCache.set(tenantId, { active, expiresAt: now + ttl });
+    }
+    return active;
+  }
+
+  /** 403 for a deactivated tenant. */
+  private async assertTenantActive(tenantId: string): Promise<void> {
+    if (!(await this.isTenantActive(tenantId))) {
+      throw new ForbiddenException('Tenant is inactive');
+    }
+  }
+
+  /** The tenant list without deactivated tenants — unchanged (and free) without the hook. */
+  private async filterActiveTenants(ids: string[]): Promise<string[]> {
+    if (typeof ConfigService.configFastButReadOnly?.multiTenancy?.isTenantActive !== 'function') {
+      return ids;
+    }
+    const active = await Promise.all(ids.map((id) => this.isTenantActive(id)));
+    return ids.filter((_id, index) => active[index]);
   }
 
   /**
@@ -847,6 +919,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     if (!membership) {
       throw new ForbiddenException('Not a member of this tenant');
     }
+    await this.assertTenantActive(headerTenantId);
     request.tenantId = headerTenantId;
     request.tenantRole = capApiTokenTenantRole(user, membership.role as string) ?? undefined;
     return true;

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

@@ -174,7 +174,9 @@ every caller allowed to use TUS — and accepts every file type.
 
 **Multi-tenancy:** with `multiTenancy` configured, the core validates the tenant header against the
 caller's memberships and stores `metadata.tenantId` on the finished file; a non-member gets 403.
-Without `multiTenancy` nothing changes. Nothing to do in the project either way.
+Without `multiTenancy` nothing changes. On the server nothing to do. On the client, send the tenant header with the TUS upload itself
+(`useLtTusUpload({ headers })`): a header added by the project's API-client interceptor does not reach
+`tus-js-client`, and without it the upload silently stays tenant-less.
 
 ---