@lenne.tech/nest-server 11.41.7 → 11.41.9

package/src/core/modules/system-setup/core-system-setup.service.ts

@@ -1,10 +1,10 @@
-import { createLocalAccountIssuer } from '@better-auth/core/db';
 import { ForbiddenException, Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { isEmail } from 'class-validator';
 import { Connection } from 'mongoose';
 
 import { ConfigService } from '../../common/services/config.service';
+import { legacyCredentialAccountIssuer } from '../better-auth/core-better-auth-account-issuer.helper';
 import { CoreBetterAuthUserMapper } from '../better-auth/core-better-auth-user.mapper';
 import { CoreBetterAuthService } from '../better-auth/core-better-auth.service';
 import { ErrorCode } from '../error-code/error-codes';
@@ -305,18 +305,22 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
 
       // Hash password and create credential account
       const hashedPassword = await context.password.hash(normalizedPassword);
-      // better-auth >= 1.7 keys accounts by (issuer, accountId) and requires the
-      // issuer. Credential accounts have no real issuer, so better-auth derives a
-      // synthetic one — always via this helper, never a hand-written literal:
-      // the format is better-auth's to change, and a copy of it would silently
-      // stop matching the accounts better-auth writes itself.
+      // better-auth 1.7.0–1.7.2 key accounts by (issuer, accountId) and require the issuer;
+      // credential accounts carry a synthetic one, always derived via the helper, never a
+      // hand-written literal. better-auth 1.7.3+ went back to (providerId, accountId) and knows no
+      // issuer field, so the helper answers `undefined` there and nothing is written.
+      //
+      // Cast to the adapter's OWN parameter type: against better-auth 1.7.0–1.7.2 that type requires
+      // `issuer`, and a conditional spread reads as optional — a vendored core compiled against
+      // those versions would otherwise not build.
+      const credentialIssuer = legacyCredentialAccountIssuer();
       await context.internalAdapter.linkAccount({
         accountId: iamUser.id,
-        issuer: createLocalAccountIssuer('credential'),
+        ...(credentialIssuer ? { issuer: credentialIssuer } : {}),
         password: hashedPassword,
         providerId: 'credential',
         userId: iamUser.id,
-      });
+      } as Parameters<typeof context.internalAdapter.linkAccount>[0]);
 
       // Sync to nest-server users collection
       const syncedUser = await this.userMapper.linkOrCreateUser({

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';

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

@@ -1,4 +1,5 @@
 import { DynamicModule, Global, Logger, Module, OnModuleInit, Type } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
 import { getConnectionToken } from '@nestjs/mongoose';
 import { Connection } from 'mongoose';
 
@@ -54,6 +55,32 @@ export interface TusModuleOptions {
    * ```
    */
   controller?: Type<CoreTusController>;
+
+  /**
+   * Custom service class to use instead of CoreTusService.
+   * The class must extend CoreTusService and keep its constructor signature
+   * `(connection, options?)`: the module constructs it with exactly those arguments, so it cannot
+   * declare constructor dependencies of its own. Project providers are reached at call time through
+   * `this.options?.moduleRef`.
+   *
+   * The seam for project-specific upload rules — e.g. override `onUploadCreate()` to enforce a quota
+   * from the declared `Upload-Length` before a single byte is written, or `onUploadComplete()` to
+   * post-process the finished file.
+   *
+   * @example
+   * ```typescript
+   * export class TusService extends CoreTusService {
+   *   protected override async onUploadCreate(req: any, upload: Upload) {
+   *     const quota = this.options?.moduleRef?.get(QuotaService, { strict: false });
+   *     await quota?.assertRoomFor(req, upload.size); // throw an Error with status_code 413 to refuse
+   *     return super.onUploadCreate(req, upload);
+   *   }
+   * }
+   *
+   * TusModule.forRoot({ service: TusService })
+   * ```
+   */
+  service?: Type<CoreTusService>;
 }
 
 /**
@@ -98,6 +125,7 @@ export class TusModule implements OnModuleInit {
   private static tusEnabled = false;
   private static currentConfig: ITusConfig | null = null;
   private static customController: null | Type<CoreTusController> = null;
+  private static customService: null | Type<CoreTusService> = null;
 
   constructor(private readonly tusService?: CoreTusService) {}
 
@@ -157,15 +185,17 @@ export class TusModule implements OnModuleInit {
    * @returns Dynamic module configuration
    */
   static forRoot(options: TusModuleOptions = {}): DynamicModule {
-    const { config: rawConfig, controller } = options;
+    const { config: rawConfig, controller, service } = options;
 
     // Normalize config: undefined/true → enabled with defaults, false → disabled
     const config = normalizeTusConfig(rawConfig);
 
     // Store config for service configuration
     this.currentConfig = config;
-    // Store custom controller if provided
+    // Store custom controller and service if provided
     this.customController = controller || null;
+    this.customService = service || null;
+    const ServiceClass = this.customService || CoreTusService;
 
     // If TUS is disabled, return minimal module
     if (config === null) {
@@ -183,9 +213,9 @@ export class TusModule implements OnModuleInit {
             inject: [getConnectionToken()],
             provide: CoreTusService,
             useFactory: (connection: Connection) => {
-              const service = new CoreTusService(connection);
-              service.configure(false);
-              return service;
+              const tusService = new ServiceClass(connection);
+              tusService.configure(false);
+              return tusService;
             },
           },
         ],
@@ -230,6 +260,7 @@ export class TusModule implements OnModuleInit {
             ConfigService,
             { optional: true, token: CoreS3Service },
             { optional: true, token: CoreRedisService },
+            ModuleRef,
           ],
           provide: CoreTusService,
           useFactory: async (
@@ -238,14 +269,15 @@ export class TusModule implements OnModuleInit {
             configService: ConfigService,
             s3Service?: CoreS3Service,
             redisService?: CoreRedisService,
+            moduleRef?: ModuleRef,
           ) => {
-            const service = new CoreTusService(connection, { configService, redisService, s3Service });
-            service.configure(tusConfig);
+            const tusService = new ServiceClass(connection, { configService, moduleRef, redisService, s3Service });
+            tusService.configure(tusConfig);
             // NestJS DOES call onModuleInit on a factory-provided instance — its hook iterates
             // every non-alias provider, however it was constructed. Calling it here as well ran
             // init TWICE per boot: two TUS servers, two S3 stores, and two hourly expiration
             // intervals of which onModuleDestroy clears only the second.
-            return service;
+            return tusService;
           },
         },
       ],
@@ -260,5 +292,6 @@ export class TusModule implements OnModuleInit {
     this.tusEnabled = false;
     this.currentConfig = null;
     this.customController = null;
+    this.customService = null;
   }
 }