@lenne.tech/nest-server 11.41.8 → 11.42.0

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

@@ -15,7 +15,7 @@
 | Use TUS with defaults (signed-in users may upload) | No - works automatically                             |
 | **Allow anonymous uploads** (public form)          | **Yes - Step 0** (the default no longer allows this) |
 | Restrict uploads to specific roles                 | Yes - Step 0                                         |
-| Custom upload handling (notifications, etc.)       | Yes - Step 2                                         |
+| Custom upload handling (quota, notifications, ...) | Yes - Step 2                                         |
 | Hard-code a policy that config must NOT change     | Yes - Step 1                                         |
 | Disable TUS completely                             | No - just use `TusModule.forRoot({ config: false })` |
 
@@ -134,25 +134,49 @@ export class ServerModule {}
 **Create:** `src/server/modules/tus/tus.service.ts`
 
 ```typescript
-import { Injectable } from '@nestjs/common';
 import { CoreTusService } from '@lenne.tech/nest-server';
 import { Upload } from '@tus/server';
 
-@Injectable()
 export class TusService extends CoreTusService {
-  protected override async onUploadComplete(upload: Upload): Promise<void> {
-    // Call parent to handle GridFS migration
-    await super.onUploadComplete(upload);
+  // Before the first byte: the declared Upload-Length is known, nothing is stored yet.
+  protected override async onUploadCreate(req: any, upload: Upload) {
+    const quota = this.options?.moduleRef?.get(QuotaService, { strict: false });
+    if (!(await quota?.hasRoomFor(req, upload.size))) {
+      const error = new Error('Storage quota exceeded');
+      (error as any).status_code = 413;
+      throw error;
+    }
+    return super.onUploadCreate(req, upload); // records owner + tenant, enforces allowedTypes
+  }
 
-    // Add custom logic
-    const metadata = upload.metadata;
-    console.log(`Upload complete: ${metadata.filename}`);
-    // await this.notificationService.sendUploadComplete(...);
+  // After the last byte.
+  protected override async onUploadComplete(upload: Upload): Promise<void> {
+    await super.onUploadComplete(upload); // migrates the file into the configured storage
+    // custom logic
   }
 }
 ```
 
-**Note:** To use a custom service, you'll need to create a custom TusModule that provides your service instead of CoreTusService.
+**Register it** (11.41.9+):
+
+```typescript
+// server.module.ts
+TusModule.forRoot({ controller: TusController, service: TusService });
+```
+
+**WHY no constructor dependencies?** The module constructs the service itself, with exactly
+`(connection, options)`. A constructor of your own would receive the wrong arguments. Resolve
+project providers at call time via `this.options?.moduleRef` instead.
+
+**WHY always return `super.onUploadCreate()`?** It writes the framework-owned owner and tenant keys
+and checks `allowedTypes`. An override that skips it produces owner-less uploads — reachable by
+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. 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.
 
 ---
 
@@ -216,6 +240,9 @@ TusModule.forRoot({ config: false });
 | Gating `OPTIONS` in a custom controller            | Every browser upload fails before the first byte          | Leave `handleTusOptions*` on `@Roles(RoleEnum.S_EVERYONE)` — the preflight sends no credentials |
 | Expecting a subclass `@Roles()` to win over config | Roles look ignored                                        | `applyRoles()` overwrites them — Step 1 table                                                   |
 | Forgot to register custom controller               | Custom handler logic never runs (core controller is used) | Add `controller: TusController` to `forRoot()`                                                  |
+| Forgot to register custom service                  | `onUploadCreate` / `onUploadComplete` overrides never run | Add `service: TusService` to `forRoot()` (11.41.9+) — Step 2                                    |
+| Constructor dependencies on the service subclass   | `undefined` dependencies, or a crash at boot              | Resolve them at call time via `this.options?.moduleRef` — Step 2                                |
+| Override of `onUploadCreate` without `super`       | Uploads have no owner or tenant; `allowedTypes` ignored   | `return super.onUploadCreate(req, upload)` — Step 2                                             |
 | Upload succeeds but the file cannot be downloaded  | `403` on `GET /files/id/:id`                              | `file.downloadRoles` defaults to `[ADMIN]` — widen it, or authorize per file in `checkRights()` |
 | Using wrong endpoint path                          | 404 on upload                                             | Ensure client uses same path as config                                                          |
 

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

@@ -309,30 +309,103 @@ TusModule.forRoot({
 });
 ```
 
+### Custom Service (11.41.9+)
+
+Register a subclass of `CoreTusService` through `TusModule.forRoot({ service })`. Before 11.41.9
+both provider factories constructed `CoreTusService` directly, so a subclass could not be plugged in
+at all.
+
+```typescript
+// server.module.ts
+TusModule.forRoot({ controller: TusController, service: TusService });
+```
+
+The module constructs the service itself, with exactly `(connection, options)` — keep that
+constructor signature, and do not declare constructor dependencies of your own. Reach project
+providers at call time through `this.options?.moduleRef` instead:
+
+```typescript
+const quota = this.options?.moduleRef?.get(QuotaService, { strict: false });
+```
+
+### Validate an Upload Before It Starts
+
+`onUploadCreate(req, upload)` runs once per upload, after the client declared `Upload-Length` and
+before a single byte is written — the only point at which a quota can refuse an upload without the
+store having grown first. Throw an `Error` carrying `status_code` to refuse:
+
+```typescript
+import { CoreTusService } from '@lenne.tech/nest-server';
+import { Upload } from '@tus/server';
+
+export class TusService extends CoreTusService {
+  protected override async onUploadCreate(req: any, upload: Upload) {
+    const quota = this.options?.moduleRef?.get(QuotaService, { strict: false });
+    if (!(await quota?.hasRoomFor(req, upload.size))) {
+      const error = new Error('Storage quota exceeded');
+      (error as any).status_code = 413;
+      throw error;
+    }
+    return super.onUploadCreate(req, upload);
+  }
+}
+```
+
+Always return `super.onUploadCreate()`: it records the owner and the tenant and enforces
+`allowedTypes`. Skipping it leaves the upload owner-less (reachable by every caller who may use TUS)
+and lets any file type through.
+
 ### Custom Upload Handler
 
 Override `onUploadComplete` to customize what happens after upload:
 
 ```typescript
 // src/server/modules/tus/tus.service.ts
-import { Injectable } from '@nestjs/common';
 import { CoreTusService } from '@lenne.tech/nest-server';
 import { Upload } from '@tus/server';
 
-@Injectable()
 export class TusService extends CoreTusService {
   protected override async onUploadComplete(upload: Upload): Promise<void> {
-    // Call parent to migrate to GridFS
+    // Call parent to migrate to the configured file storage
     await super.onUploadComplete(upload);
 
     // Custom logic after upload
-    const metadata = upload.metadata;
-    await this.notificationService.sendUploadComplete(metadata.filename);
-    await this.analyticsService.trackUpload(upload.id, upload.size);
+    const notifications = this.options?.moduleRef?.get(NotificationService, { strict: false });
+    await notifications?.sendUploadComplete(upload.metadata?.filename);
   }
 }
 ```
 
+### Tenant Scoping (11.41.9+)
+
+**Only with `multiTenancy` configured.** Without it nothing changes: no header is read, no field is
+written.
+
+With multi-tenancy active, an upload carrying the tenant header (`multiTenancy.headerName`, default
+`x-tenant-id`) is validated against the caller's active memberships — the same check GraphQL
+subscriptions use. The TUS routes carry `@SkipTenantCheck()`, so the tenant guard does not do this
+for them.
+
+| Request                                              | Result                                     |
+| ---------------------------------------------------- | ------------------------------------------ |
+| No tenant header                                     | upload stays tenant-less, as before        |
+| Header naming a tenant the caller belongs to         | the finished file gets `metadata.tenantId` |
+| Header naming a tenant the caller does NOT belong to | **403**, nothing is stored                 |
+
+**The header has to come from the TUS client itself.** Projects usually add `X-Tenant-Id` in an
+interceptor of their generated API client, and `tus-js-client` does not go through that client. Without
+an explicit header the upload is accepted, stays tenant-less and bypasses tenant filtering and any
+per-tenant quota, with no error anywhere. Pass it to the upload, e.g. with nuxt-extensions:
+
+```typescript
+const { addFiles } = useLtTusUpload({ headers: { 'X-Tenant-Id': currentTenantId } });
+```
+
+The tenant is recorded under `TUS_TENANT_METADATA_KEY` (`ltTenantId`), next to the owner under
+`TUS_OWNER_METADATA_KEY`. Both keys are framework-owned and always overwritten, so a client cannot
+put either of them into its own `Upload-Metadata`. `metadata.tenantId` on the finished file is what
+the file module's `'tenant'` access preset and any per-file `checkRights()` rule read.
+
 ---
 
 ## Integration with FileModule
@@ -380,14 +453,15 @@ query {
 
 The following metadata is stored with each GridFS file:
 
-| Field              | Source                                |
-| ------------------ | ------------------------------------- |
-| `filename`         | From TUS `Upload-Metadata` header     |
-| `contentType`      | From TUS `filetype` metadata          |
-| `tusUploadId`      | Original TUS upload ID                |
-| `originalMetadata` | All TUS metadata                      |
-| `ownerId`          | The authenticated uploader (11.35.0+) |
-| `uploadedAt`       | Completion timestamp                  |
+| Field              | Source                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------- |
+| `filename`         | From TUS `Upload-Metadata` header                                                                       |
+| `contentType`      | From TUS `filetype` metadata                                                                            |
+| `tusUploadId`      | Original TUS upload ID                                                                                  |
+| `originalMetadata` | All TUS metadata                                                                                        |
+| `ownerId`          | The authenticated uploader (11.35.0+)                                                                   |
+| `tenantId`         | The validated tenant, only with `multiTenancy` (11.41.9+) — see [Tenant Scoping](#tenant-scoping-11419) |
+| `uploadedAt`       | Completion timestamp                                                                                    |
 
 ### Upload ownership (11.35.0+)