@lenne.tech/nest-server 11.41.8 → 11.41.9

package/docs/REQUEST-LIFECYCLE.md

@@ -165,7 +165,7 @@ JWT-based authentication for existing projects:
 | **REST Endpoints** | `GET /files/id/:id`, `GET /files/:filename` (core, gated by `file.downloadRoles`, default ADMIN); `POST /files/upload`, `DELETE /files/:id` (project-specific) |
 | **GraphQL Endpoints** | `getFileInfo` (`file.downloadRoles`), `uploadFile` / `uploadFiles` (`file.uploadRoles`), `deleteFile` (`file.deleteRoles`) — all default ADMIN |
 | **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Cover BOTH the `id` and the `filename` branch — the filename route authorizes on the by-name lookup alone when presigned S3 downloads are on, and `deleteFileByName()` always does. Working reference: `src/server/modules/file/file.service.ts` (with `file.downloadRoles: [S_USER]` in `src/config.env.ts`, so the rule is actually reached). Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
-| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight |
+| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })` |
 | **GridFS Migration** | Completed TUS uploads auto-migrate to GridFS |
 | **CORS Support** | Automatic CORS headers for browser uploads |
 

package/migration-guides/11.41.8-to-11.41.9.md

@@ -0,0 +1,111 @@
+# Migration Guide: 11.41.8 → 11.41.9
+
+## Overview
+
+| Category              | Details                                                                                                                                                                  |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **New Features**      | A custom TUS service via `TusModule.forRoot({ service })`, and an overridable `onUploadCreate()` (§1)                                                                    |
+| **Behaviour Changes** | Only with `multiTenancy` configured: TUS uploads record the validated tenant, and a tenant header naming a tenant the caller does not belong to is refused with 403 (§2) |
+| **Breaking Changes**  | None for projects without `multiTenancy`                                                                                                                                 |
+| **Migration Effort**  | None — `pnpm update`. Projects that want upload rules (quota, validation) adopt §1                                                                                       |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run build && pnpm test
+```
+
+Vendor-mode projects pick up the core update; nothing else to change.
+
+## What's New in 11.41.9
+
+### 1. A custom TUS service, and a hook before the first byte
+
+Until now `TusModule` constructed `CoreTusService` directly in both of its provider factories, so a
+project could not plug in a subclass at all — and `onUploadCreate` sat inline inside a private method,
+so even a subclass could not have changed it. Both are open now:
+
+```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);
+  }
+}
+
+// server.module.ts
+TusModule.forRoot({ controller: TusController, service: TusService });
+```
+
+`onUploadCreate(req, upload)` runs once per upload, after the client declared `Upload-Length` and
+before anything is stored — the one point at which a quota can refuse an upload without the store
+having grown first.
+
+Three rules, all in the TUS [INTEGRATION-CHECKLIST](../src/core/modules/tus/INTEGRATION-CHECKLIST.md)
+Step 2:
+
+- **Keep the constructor signature `(connection, options?)`.** The module constructs the service
+  itself, with exactly those arguments. Project providers are reached at call time through
+  `this.options?.moduleRef`, which the module now passes in.
+- **Return `super.onUploadCreate()`.** It records the owner and the tenant and enforces
+  `allowedTypes`; skipping it produces owner-less uploads and accepts every file type.
+- **Throw an `Error` with `status_code`** to refuse — that is how `@tus/server` turns it into a
+  response.
+
+### 2. With multi-tenancy: TUS uploads carry their tenant
+
+**Projects without `multiTenancy` see no change** — no header is read, no field is written.
+
+With `multiTenancy` configured (and not `enabled: false`), TUS uploads used to carry no tenant at
+all: the routes carry `@SkipTenantCheck()`, the file stores sit outside Mongoose, and so every
+TUS-uploaded file bypassed tenant filtering and any per-tenant storage accounting. Now an upload that
+sends the tenant header is validated against the caller's active memberships — the same check
+GraphQL subscriptions use — and the finished file gets `metadata.tenantId`:
+
+| Request                                              | 11.41.8               | 11.41.9                 |
+| ---------------------------------------------------- | --------------------- | ----------------------- |
+| No tenant header                                     | tenant-less           | tenant-less (unchanged) |
+| Header naming a tenant the caller belongs to         | tenant-less           | `metadata.tenantId` set |
+| Header naming a tenant the caller does NOT belong to | accepted, tenant-less | **403**, nothing stored |
+
+The tenant is recorded under the framework-owned metadata key `TUS_TENANT_METADATA_KEY`
+(`ltTenantId`), next to the owner key. Like the owner key it is always overwritten, so a client
+cannot put a tenant into its own `Upload-Metadata`.
+
+**What this changes downstream:** the file module's `'tenant'` access preset and any
+`checkRights()` rule reading `metadata.tenantId` now see the tenant on TUS-uploaded files. Under the
+`'tenant'` preset such files used to be refused for every non-admin (no tenant on the file); new
+uploads are now readable within their tenant. Files uploaded before 11.41.9 keep no tenant.
+
+## Compatibility Notes
+
+| Pattern                                                               | Status                                                            |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `TusModule.forRoot()` / `forRoot({ controller })`                     | Unchanged                                                         |
+| Project without `multiTenancy`                                        | Unchanged — nothing read, nothing written (§2)                    |
+| Multi-tenant client sending a tenant header it is a member of         | Works; files now carry `tenantId` (§2)                            |
+| Multi-tenant client sending a header for a foreign tenant             | Now 403 (§2)                                                      |
+| Own `TusModule` replacement that provides a `CoreTusService` subclass | Keeps working; `forRoot({ service })` is now the simpler way (§1) |
+
+## Troubleshooting
+
+| Symptom                                              | Cause                                                                  | Fix                                               |
+| ---------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------- |
+| TUS `POST` answers 403 after the update              | The tenant header names a tenant the caller is not an active member of | Send the caller's own tenant, or no header (§2)   |
+| An `onUploadCreate` override never runs              | The subclass is not registered                                         | `TusModule.forRoot({ service: TusService })` (§1) |
+| Dependencies are `undefined` in the service subclass | Declared as constructor parameters                                     | Resolve via `this.options?.moduleRef` (§1)        |
+| Uploads have no `ownerId` after adding an override   | `onUploadCreate` override does not call `super`                        | `return super.onUploadCreate(req, upload)` (§1)   |
+
+## Module Documentation
+
+- [TUS README](../src/core/modules/tus/README.md) — Custom Service, Validate an Upload Before It Starts, Tenant Scoping
+- [TUS INTEGRATION-CHECKLIST](../src/core/modules/tus/INTEGRATION-CHECKLIST.md) — Step 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.41.8",
+  "version": "11.41.9",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

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,47 @@ 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. Nothing to do in the project either way.
 
 ---
 
@@ -216,6 +238,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,94 @@ 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 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 +444,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+)
 

package/src/core/modules/tus/core-tus.service.ts

@@ -1,4 +1,5 @@
 import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
 import { FileStore } from '@tus/file-store';
 import { Server, Upload } from '@tus/server';
 import * as fs from 'fs';
@@ -11,6 +12,7 @@ import { ITusConfig } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
 import { CoreRedisService } from '../../common/services/core-redis.service';
 import { CoreS3Service } from '../../common/services/core-s3.service';
+import { getTenantContextResolver } from '../../common/services/core-tenant-context.registry';
 import { resolveFileStorage } from '../file/file-storage.helper';
 import {
   DEFAULT_FILESYSTEM_DIR,
@@ -18,7 +20,7 @@ import {
   FilesystemFileHelper,
 } from '../file/filesystem-file.helper';
 import { S3_FILES_COLLECTION, S3FileHelper } from '../file/s3-file.helper';
-import { TUS_OWNER_METADATA_KEY } from './tus.constants';
+import { TUS_OWNER_METADATA_KEY, TUS_TENANT_METADATA_KEY } from './tus.constants';
 import { TusRedisLocker } from './tus-redis-locker';
 import {
   DEFAULT_TUS_ALLOWED_HEADERS,
@@ -37,6 +39,14 @@ import {
 export interface CoreTusServiceOptions {
   configService?: ConfigService;
 
+  /**
+   * How a subclass reaches project providers. `TusModule` constructs the service itself, with
+   * exactly `(connection, options)`, so a subclass cannot declare constructor dependencies of its
+   * own — resolve them at call time instead:
+   * `this.options?.moduleRef?.get(QuotaService, { strict: false })`.
+   */
+  moduleRef?: ModuleRef;
+
   /** Central Redis; when present, upload locks are shared across replicas */
   redisService?: CoreRedisService;
 
@@ -187,6 +197,10 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
         // ADMIN, so a project following the documented pattern ended up with undownloadable files.
         // Written from the SERVER-recorded owner, never from the client's own metadata.
         ...(metadata[TUS_OWNER_METADATA_KEY] ? { ownerId: metadata[TUS_OWNER_METADATA_KEY] } : {}),
+        // The tenant the upload was created in — validated against an active membership in
+        // onUploadCreate(), never taken from the client. Present only with multi-tenancy active; it
+        // is what the file module's `'tenant'` access preset decides on.
+        ...(metadata[TUS_TENANT_METADATA_KEY] ? { tenantId: metadata[TUS_TENANT_METADATA_KEY] } : {}),
         tusUploadId: upload.id,
         uploadedAt: new Date(),
       };
@@ -579,6 +593,115 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
     return false;
   }
 
+  /**
+   * Runs when a client CREATES an upload — the one point where the declared `Upload-Length` is known
+   * and no byte has been written yet. Returning `{ metadata }` is what PERSISTS it: the tus server
+   * writes the returned value onto the upload (returning `{}` would keep the client's metadata
+   * verbatim). Throw an error carrying `status_code` to refuse the upload.
+   *
+   * Records two framework-owned keys, both OVERWRITTEN rather than merged, because the client's
+   * `Upload-Metadata` header must never be able to set them:
+   * - {@link TUS_OWNER_METADATA_KEY} — the authenticated creator (see `assertUploadOwnership()`).
+   * - {@link TUS_TENANT_METADATA_KEY} — the validated tenant, only while multi-tenancy is active
+   *   (see `resolveUploadTenantId()`); `null` otherwise.
+   *
+   * Override to add project rules — a quota, a per-tenant type policy — and call `super` to keep the
+   * owner, the tenant and `allowedTypes`. Register the subclass via `TusModule.forRoot({ service })`.
+   */
+  protected async onUploadCreate(req: any, upload: Upload): Promise<{ metadata: Record<string, null | string> }> {
+    // Record the creator and the tenant FIRST, so the checks below and later requests have something
+    // to compare against.
+    const metadata: Record<string, null | string> = {
+      ...upload.metadata,
+      [TUS_OWNER_METADATA_KEY]: this.readRequestUserId(req) ?? null,
+      [TUS_TENANT_METADATA_KEY]: (await this.resolveUploadTenantId(req)) ?? null,
+    };
+
+    // Validate file type if allowedTypes is configured
+    if (this.config.allowedTypes && this.config.allowedTypes.length > 0) {
+      const filetype = this.parseMetadata(upload.metadata).filetype;
+
+      if (!this.validateFileType(filetype)) {
+        const allowedList = this.config.allowedTypes.join(', ');
+        this.logger.warn(
+          `Upload rejected: file type '${filetype || 'unknown'}' not allowed. Allowed types: ${allowedList}`,
+        );
+
+        // Throw error to reject the upload
+        // @tus/server v2 expects throwing an error with status_code
+        const error = new Error(`File type '${filetype || 'unknown'}' is not allowed. Allowed types: ${allowedList}`);
+        (error as any).status_code = 415; // Unsupported Media Type
+        throw error;
+      }
+    }
+
+    return { metadata };
+  }
+
+  /**
+   * The VALIDATED tenant a new upload belongs to, or `undefined`.
+   *
+   * Only while multi-tenancy is active AND the tenant guard is registered — without it nothing can
+   * validate a tenant, and a project without multi-tenancy sees no change at all. The tus routes
+   * carry `@SkipTenantCheck()`, so the guard did NOT validate the request's tenant header; this asks
+   * the same membership logic directly (`core-tenant-context.registry.ts`, the path GraphQL
+   * subscriptions use).
+   *
+   * - No tenant header: `undefined` — the upload stays tenant-less, as before.
+   * - A header naming a tenant the caller is an active member of (or any tenant, for an admin under
+   *   `adminBypass`): that tenant.
+   * - A header naming a tenant the caller is NOT a member of: the upload is REFUSED with 403. Taking
+   *   the header verbatim would let anybody place a file in somebody else's tenant, and silently
+   *   dropping it would store the file somewhere the caller did not ask for.
+   *
+   * Override to derive the tenant from somewhere else (a subdomain, an API key).
+   */
+  protected async resolveUploadTenantId(req: any): Promise<string | undefined> {
+    const multiTenancy = ConfigService.configFastButReadOnly?.multiTenancy;
+    const resolver = getTenantContextResolver();
+    if (!multiTenancy || multiTenancy.enabled === false || !resolver) {
+      return undefined;
+    }
+
+    const headerName = (multiTenancy.headerName ?? 'x-tenant-id').toLowerCase();
+    const header = this.readRequestHeader(req, headerName)?.trim();
+    if (!header) {
+      return undefined;
+    }
+
+    const resolved = await resolver.resolve(this.readRequestUser(req), header);
+    if (!resolved?.tenantId) {
+      const error = new Error('Not a member of the requested tenant');
+      (error as any).status_code = 403;
+      throw error;
+    }
+    return resolved.tenantId;
+  }
+
+  /**
+   * The authenticated caller with roles, read the same way as {@link readRequestUserId} — the roles
+   * decide the admin bypass of the tenant resolution.
+   */
+  protected readRequestUser(req: any): undefined | { id: string; roles?: string[] } {
+    const id = this.readRequestUserId(req);
+    if (!id) {
+      return undefined;
+    }
+    const user = req?.user ?? req?.runtime?.node?.req?.user ?? req?.context?.user;
+    return { id, roles: Array.isArray(user?.roles) ? user.roles : undefined };
+  }
+
+  /**
+   * A request header, from either request shape `@tus/server` v2 hands its hooks: the WHATWG
+   * `ServerRequest` (a `Headers` object) or the original Node request behind `runtime.node.req`.
+   */
+  protected readRequestHeader(req: any, name: string): string | undefined {
+    const fromHeaders = typeof req?.headers?.get === 'function' ? req.headers.get(name) : req?.headers?.[name];
+    const value = fromHeaders ?? req?.runtime?.node?.req?.headers?.[name];
+    const single = Array.isArray(value) ? value[0] : value;
+    return typeof single === 'string' && single.length > 0 ? single : undefined;
+  }
+
   /**
    * Create the TUS server instance with configured extensions
    */
@@ -604,35 +727,7 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       // protocol is built around a per-upload URL. Appending is the sharp end — bytes PATCHed into
       // somebody else's upload are migrated into the file store under THEIR filename.
       onIncomingRequest: async (req, uploadId) => this.assertUploadOwnership(req, uploadId),
-      onUploadCreate: async (req, upload) => {
-        // Record the creator FIRST, so the ownership check below has something to compare against.
-        // Overwrites rather than merges: see TUS_OWNER_METADATA_KEY.
-        const metadata = { ...upload.metadata, [TUS_OWNER_METADATA_KEY]: this.readRequestUserId(req) ?? null };
-
-        // Validate file type if allowedTypes is configured
-        if (this.config.allowedTypes && this.config.allowedTypes.length > 0) {
-          const filetype = this.parseMetadata(upload.metadata).filetype;
-
-          if (!this.validateFileType(filetype)) {
-            const allowedList = this.config.allowedTypes.join(', ');
-            this.logger.warn(
-              `Upload rejected: file type '${filetype || 'unknown'}' not allowed. Allowed types: ${allowedList}`,
-            );
-
-            // Throw error to reject the upload
-            // @tus/server v2 expects throwing an error with status_code
-            const error = new Error(
-              `File type '${filetype || 'unknown'}' is not allowed. Allowed types: ${allowedList}`,
-            );
-            (error as any).status_code = 415; // Unsupported Media Type
-            throw error;
-          }
-        }
-
-        // Returning the metadata is what PERSISTS the owner — the tus server writes the returned
-        // value onto the upload. Returning `{}` here would keep the client's own metadata verbatim.
-        return { metadata };
-      },
+      onUploadCreate: async (req, upload) => this.onUploadCreate(req, upload),
       onUploadFinish: async (_req, upload) => {
         try {
           await this.onUploadComplete(upload);

package/src/core/modules/tus/tus.constants.ts

@@ -39,3 +39,15 @@ export const TUS_CONFIG = 'TUS_CONFIG';
  * `tests/unit/import-cycle-invariants.spec.ts` enforces exactly that placement.
  */
 export const TUS_OWNER_METADATA_KEY = 'ltOwnerId';
+
+/**
+ * Metadata key recording the VALIDATED tenant a tus upload was created in, in the upload's own
+ * (staged) metadata. On completion it becomes the finished file's `metadata.tenantId` — the field the
+ * file module's `'tenant'` access preset decides on.
+ *
+ * Framework-owned and ALWAYS overwritten in `onUploadCreate`, exactly like
+ * {@link TUS_OWNER_METADATA_KEY}: the client's `Upload-Metadata` header must never be able to place
+ * a file in a tenant. It is set only while multi-tenancy is active and the caller's tenant header
+ * resolves to a tenant they are an active member of; otherwise it is `null`.
+ */
+export const TUS_TENANT_METADATA_KEY = 'ltTenantId';