@lenne.tech/nest-server 11.42.8 → 11.42.9

package/src/core/modules/better-auth/core-better-auth.service.ts

@@ -1,5 +1,19 @@
-import { BadRequestException, Inject, Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
+import {
+  BadRequestException,
+  Inject,
+  Injectable,
+  Logger,
+  OnApplicationBootstrap,
+  OnModuleInit,
+  Optional,
+} from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
+import {
+  freshSessionMiddleware,
+  requestOnlySessionMiddleware,
+  sensitiveSessionMiddleware,
+  sessionMiddleware,
+} from 'better-auth/api';
 import { Request } from 'express';
 import { importJWK, jwtVerify } from 'jose';
 import { Connection } from 'mongoose';
@@ -12,6 +26,14 @@ import { ErrorCode } from '../error-code/error-codes';
 import { resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper';
 import { BetterAuthInstance } from './better-auth.config';
 import { legacyCredentialAccountIssuer, usesLegacyAccountIssuer } from './core-better-auth-account-issuer.helper';
+import {
+  BUILT_IN_BETTER_AUTH_PLUGIN_IDS,
+  HANDLER_SESSION_PATHS,
+  isUnavailableOperation,
+  toOpenApiPath,
+  unavailableBetterAuthOperations,
+} from './core-better-auth-openapi.helper';
+import type { IBetterAuthOpenApiDocument, IBetterAuthRuntime } from './core-better-auth-openapi.helper';
 import { isJwtShaped } from './core-better-auth-token.helper';
 import { BetterAuthSessionUser } from './core-better-auth-user.mapper';
 import { convertExpressHeaders, parseCookieHeader, signCookieValueIfNeeded } from './core-better-auth-web.helper';
@@ -81,9 +103,11 @@ export { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN } from './core-better-aut
  * ```
  */
 @Injectable()
-export class CoreBetterAuthService implements OnModuleInit {
+export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleInit {
   private readonly logger = new Logger(CoreBetterAuthService.name);
   private readonly config: IBetterAuth;
+  private openApiSchema: IBetterAuthOpenApiDocument | undefined;
+  private unavailableOperations: Set<string> | undefined;
   // Cached cookie prefix — frozen on first read so the value cannot drift away
   // from the Better-Auth instance (which captured it at bootstrap). Without
   // this cache a test or fork that mutates `process.env.COOKIE_PREFIX` after
@@ -131,6 +155,146 @@ export class CoreBetterAuthService implements OnModuleInit {
     }
   }
 
+  /**
+   * Prepares the OpenAPI description of Better-Auth's own routes for `setupSwagger()`.
+   *
+   * Its own hook rather than part of `onModuleInit()`, which returns early without a database
+   * connection: the description depends on the configured plugins only. Built once here because the
+   * Swagger document factory is synchronous while Better-Auth's generator is not.
+   */
+  async onApplicationBootstrap(): Promise<void> {
+    await this.prepareOpenApiSchema();
+  }
+
+  /**
+   * The OpenAPI description of the routes Better-Auth serves itself under the base path — exactly the
+   * ones the configured plugins add (paths relative to the base path, OpenAPI 3.1). `undefined` when
+   * Better-Auth is disabled or the description could not be generated.
+   */
+  getOpenApiSchema(): IBetterAuthOpenApiDocument | undefined {
+    return this.openApiSchema;
+  }
+
+  /**
+   * Operations under the base path that the running Better-Auth options make answer an error for every
+   * caller (`unavailableBetterAuthOperations()`), read from the live instance at bootstrap — so options a
+   * project passes through `betterAuth.options` count too. `setupSwagger()` applies them to the
+   * controller's own routes as well. `undefined` before bootstrap or when Better-Auth is disabled.
+   */
+  getUnavailableOperations(): Set<string> | undefined {
+    return this.unavailableOperations;
+  }
+
+  /**
+   * Runs Better-Auth's OpenAPI generator, which it exposes through the `openAPI()` plugin
+   * `buildPlugins()` registers. A failure costs the Swagger document its generated routes, never the boot.
+   */
+  /**
+   * The operations (`<method> <openapi path>`) Better-Auth answers only with a session: a session
+   * middleware in the endpoint's `use` chain (directly or nested), a check in its handler
+   * (`HANDLER_SESSION_PATHS`), or — unknowable, so assumed — a plugin nest-server does not register
+   * itself (`BUILT_IN_BETTER_AUTH_PLUGIN_IDS`).
+   *
+   * `undefined` when no endpoint carries one of the middlewares — then the instance's middlewares are
+   * not the ones imported here (two copies of better-auth), the distinction cannot be made, and every
+   * route keeps the global requirement. A public route documented as authenticated costs a header; a
+   * session route documented as public sends clients without one.
+   */
+  protected sessionGuardedOperations(): Set<string> | undefined {
+    const middlewares = new Set<unknown>([
+      freshSessionMiddleware,
+      requestOnlySessionMiddleware,
+      sensitiveSessionMiddleware,
+      sessionMiddleware,
+    ]);
+    // A middleware guards when it IS one of them or runs one itself — `organization()` nests
+    // sessionMiddleware inside its own. Depth-bounded, so a cyclic chain cannot hang the bootstrap.
+    const guards = (middleware: unknown, depth = 0): boolean =>
+      depth < 5 &&
+      (middlewares.has(middleware) ||
+        ((middleware as { options?: { use?: unknown[] } })?.options?.use ?? []).some((inner) =>
+          guards(inner, depth + 1),
+        ));
+    // Routes of plugins nest-server does not register itself keep the global requirement: their own
+    // middleware may check the session in its body (`admin()` does), which nothing here can see.
+    const plugins = ((this.getInstance() as unknown as { options?: { plugins?: unknown[] } })?.options?.plugins ??
+      []) as { endpoints?: Record<string, { path?: unknown }>; id?: string }[];
+    const foreignPaths = new Set(
+      plugins
+        .filter((plugin) => !BUILT_IN_BETTER_AUTH_PLUGIN_IDS.includes(String(plugin?.id)))
+        .flatMap((plugin) => Object.values(plugin?.endpoints ?? {}).map((endpoint) => endpoint?.path)),
+    );
+    const endpoints = Object.values((this.getApi() ?? {}) as Record<string, unknown>) as {
+      options?: { method?: string | string[]; use?: unknown[] };
+      path?: string;
+    }[];
+    const operations = new Set<string>();
+    let middlewareSeen = false;
+    for (const endpoint of endpoints) {
+      if (typeof endpoint?.path !== 'string') continue;
+      const byMiddleware = !!endpoint.options?.use?.some((middleware) => guards(middleware));
+      middlewareSeen ||= byMiddleware;
+      if (!byMiddleware && !HANDLER_SESSION_PATHS.includes(endpoint.path) && !foreignPaths.has(endpoint.path)) {
+        continue;
+      }
+      for (const method of ([] as string[]).concat(endpoint.options?.method ?? [])) {
+        operations.add(`${method.toLowerCase()} ${toOpenApiPath(endpoint.path)}`);
+      }
+    }
+    if (!middlewareSeen) {
+      this.logger.warn(
+        "Could not tell which Better-Auth routes need a session (no endpoint uses better-auth's session " +
+          'middleware as imported here); Swagger documents all of them as authenticated',
+      );
+      return undefined;
+    }
+    return operations;
+  }
+
+  protected async prepareOpenApiSchema(): Promise<void> {
+    if (!this.isEnabled()) return;
+    const api = this.getApi() as { generateOpenAPISchema?: () => Promise<unknown> } | null;
+    if (typeof api?.generateOpenAPISchema !== 'function') return;
+    try {
+      const schema = (await api.generateOpenAPISchema()) as IBetterAuthOpenApiDocument;
+      // The generator lists every registered endpoint, including those the running options make
+      // answer an error for everybody (POST /get-session without deferSessionRefresh, social routes
+      // without a provider, OTP routes without sendOTP, …). Only what can succeed is described.
+      const context = (await (this.getInstance() as unknown as { $context?: Promise<IBetterAuthRuntime> })
+        ?.$context) as IBetterAuthRuntime | undefined;
+      const unavailable = unavailableBetterAuthOperations(context);
+      this.unavailableOperations = unavailable;
+      // The generator also marks every route bearer-only, public ones included. What a route needs is
+      // what Better-Auth enforces on it, so that replaces the generator's guess: `security: []` for a
+      // public route, none (the document's global requirement) for one that needs a session.
+      const sessionGuarded = this.sessionGuardedOperations();
+      for (const [path, item] of Object.entries(schema.paths ?? {})) {
+        for (const method of Object.keys(item)) {
+          if (isUnavailableOperation(unavailable, method, path)) {
+            delete item[method];
+            continue;
+          }
+          const operation = item[method] as { security?: unknown[] } | undefined;
+          if (operation && typeof operation === 'object') {
+            if (!sessionGuarded || sessionGuarded.has(`${method} ${path}`)) {
+              delete operation.security;
+            } else {
+              operation.security = [];
+            }
+          }
+        }
+        if (!Object.keys(item).length) {
+          delete schema.paths[path];
+        }
+      }
+      this.openApiSchema = schema;
+    } catch (error) {
+      this.logger.warn(
+        `Could not describe Better-Auth's routes for Swagger: ${error instanceof Error ? error.message : 'unknown'}`,
+      );
+    }
+  }
+
   /**
    * Ensure performance indices exist on the session, users, account and verification collections.
    * Indices are idempotent — calling createIndex on an existing index is a no-op.

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

@@ -95,6 +95,11 @@ All endpoints are handled by the TUS protocol via `@tus/server`:
 | PATCH   | `/tus/:id` | Continue upload          |
 | DELETE  | `/tus/:id` | Terminate upload         |
 
+The two `@All()` handlers carry `@ApiMethods()` (11.42.9), so the Swagger document built by
+`setupSwagger()` lists exactly POST on `/tus` and HEAD/PATCH/DELETE on `/tus/{id}` — not the eight
+operations `@nestjs/swagger` derives from `@All()`. A project controller that re-declares the handlers
+re-declares `@ApiMethods()` with them.
+
 ### CORS Headers
 
 The TUS server automatically handles CORS headers for browser-based clients:
@@ -132,6 +137,14 @@ TusModule.forRoot({ config: false });
 tus: false;
 ```
 
+### Where the Configuration Comes From (11.42.9+)
+
+`TusModule.forRoot({ config })` wins. Without a `config`, the server configuration's `tus` key applies
+— the block in `config.env.ts` (or `NSC__TUS__*`), the same zero-config rule `BetterAuthModule.forRoot()`
+follows. **Before 11.42.9 that key was never read**: `TusModule.forRoot()` without `config` always
+enabled TUS with the defaults, so `tus: false`, `allowedTypes`, `maxSize` and `roles` in `config.env.ts`
+did nothing. Projects that set them get them applied on upgrade — check that block before you deploy.
+
 ### Custom Configuration
 
 ```typescript
@@ -164,20 +177,21 @@ TusModule.forRoot({
 
 ### Configuration Options
 
-| Option               | Type              | Default                | Description                                              |
-| -------------------- | ----------------- | ---------------------- | -------------------------------------------------------- |
-| `enabled`            | boolean           | `true`                 | Enable/disable TUS                                       |
-| `path`               | string            | `/tus`                 | Endpoint path                                            |
-| `maxSize`            | number            | 50 GB                  | Maximum file size in bytes                               |
-| `allowedTypes`       | string[]          | undefined              | Allowed MIME types (all if undefined)                    |
-| `allowedHeaders`     | string[]          | `[]`                   | Additional custom headers (TUS headers already included) |
-| `uploadDir`          | string            | `uploads/tus`          | Temporary upload directory                               |
-| `creation`           | boolean           | `true`                 | Enable creation extension                                |
-| `creationWithUpload` | boolean           | `true`                 | Enable creation-with-upload extension                    |
-| `termination`        | boolean           | `true`                 | Enable termination extension                             |
-| `expiration`         | boolean \| object | `{ expiresIn: '24h' }` | Expiration configuration                                 |
-| `checksum`           | boolean           | `true`                 | Enable checksum extension                                |
-| `concatenation`      | boolean           | `true`                 | Enable concatenation extension                           |
+| Option               | Type              | Default                | Description                                                                                                                                                                                                                 |
+| -------------------- | ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`            | boolean           | `true`                 | Enable/disable TUS                                                                                                                                                                                                          |
+| `path`               | string            | `/tus`                 | Endpoint path — see [Upload URLs](#upload-urls-11429). A new route (`/uploads`) mounts the controller there; a path ending with the controller's route (`/api/tus`) is the public URL and leaves the controller where it is |
+| `relativeLocation`   | boolean           | `false`                | Hand out upload URLs without scheme and host — for a frontend that reaches TUS through a same-origin proxy (11.42.9+)                                                                                                       |
+| `maxSize`            | number            | 50 GB                  | Maximum file size in bytes                                                                                                                                                                                                  |
+| `allowedTypes`       | string[]          | undefined              | Allowed MIME types (all if undefined)                                                                                                                                                                                       |
+| `allowedHeaders`     | string[]          | `[]`                   | Additional custom headers (TUS headers already included)                                                                                                                                                                    |
+| `uploadDir`          | string            | `uploads/tus`          | Temporary upload directory                                                                                                                                                                                                  |
+| `creation`           | boolean           | `true`                 | Creation extension. `false`: POST answers 501 and OPTIONS stops advertising it (enforced since 11.42.9)                                                                                                                     |
+| `creationWithUpload` | boolean           | `true`                 | Creation-with-upload extension. `false`: a POST carrying data answers 501 (11.42.9+)                                                                                                                                        |
+| `termination`        | boolean           | `true`                 | Termination extension. `false`: DELETE answers 501 and OPTIONS stops advertising it (11.42.9+; before, the flag was only logged)                                                                                            |
+| `expiration`         | boolean \| object | `{ expiresIn: '24h' }` | Expiration configuration                                                                                                                                                                                                    |
+| `checksum`           | boolean           | `true`                 | No effect: the built-in stores (file system, S3) do not support it                                                                                                                                                          |
+| `concatenation`      | boolean           | `true`                 | No effect: the built-in stores (file system, S3) do not support it                                                                                                                                                          |
 
 **Note on `allowedHeaders`:**
 
@@ -190,6 +204,28 @@ TusModule.forRoot({
 
 The `allowedHeaders` option is only for **project-specific custom headers**.
 
+### Upload URLs (11.42.9+)
+
+The URL a client receives for a new upload (`Location`) is built from the path the upload was CREATED
+at: it therefore points where the controller actually listens — below a global prefix, a URI version or
+a project controller's own route alike. Before 11.42.9 it was built from `path` alone, so in each of
+those cases every HEAD / PATCH on it answered 404 and no upload could be resumed.
+
+`path` decides the rest:
+
+| `path`                                                          | Effect                                                                                                                                                                                                              |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| unset                                                           | upload URLs follow the request, the controller keeps its route                                                                                                                                                      |
+| a new route (`'/uploads'`)                                      | the controller is mounted there — below the global prefix, like any route                                                                                                                                           |
+| ends with the controller's route (`'/api/tus'`, `'/files/tus'`) | the public URL: the controller stays, upload URLs use this path. For a global prefix, or a proxy that strips a prefix on the way in — and what `path` had to be set to before 11.42.9, so those setups keep working |
+
+A proxy that renames the route (public `/files/upload` forwarded as `/tus`) fits none of these: leave
+`path` unset and override `uploadCollectionPath(req)` in a `CoreTusService` subclass to return the
+public path. For relative upload URLs (`/tus/<id>`, a same-origin frontend proxy) set
+`relativeLocation: true`; the framework builds the URL itself, so `@tus/server`'s own option of that
+name only takes effect through this one — or when passed to the tus server directly, which is
+honoured too.
+
 ### Expiration Configuration
 
 ```typescript

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

@@ -1,6 +1,7 @@
 import { All, Controller, Logger, Options, Req, Res } from '@nestjs/common';
 import { Request, Response } from 'express';
 
+import { ApiMethods } from '../../common/decorators/api-methods.decorator';
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
 import { SkipTenantCheck } from '../tenant/core-tenant.decorators';
@@ -92,6 +93,8 @@ export class CoreTusController {
    * - DELETE: Terminate upload (if termination extension enabled)
    */
   @All()
+  // The collection path creates uploads; every other method answers 404/412 there (@tus/server).
+  @ApiMethods('post')
   @Roles(RoleEnum.S_USER)
   async handleTus(@Req() req: Request, @Res() res: Response): Promise<void> {
     const server = this.tusService.getServer();
@@ -120,6 +123,9 @@ export class CoreTusController {
    * Routes like /tus/:id for HEAD, PATCH, DELETE
    */
   @All(':id')
+  // Status, resume and termination of one upload. GET answers 404 in practice (an unfinished upload
+  // fails the offset check, a finished one has left staging); PUT/SEARCH have no tus handler.
+  @ApiMethods('head', 'patch', 'delete')
   @Roles(RoleEnum.S_USER)
   async handleTusWithId(@Req() req: Request, @Res() res: Response): Promise<void> {
     const server = this.tusService.getServer();

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

@@ -112,10 +112,10 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
    * Called by TusModule.forRoot() with the resolved configuration
    */
   configure(config: boolean | ITusConfig | undefined): void {
-    const normalizedConfig = normalizeTusConfig(config);
-    if (normalizedConfig) {
-      this.config = normalizedConfig;
-    }
+    // A disabled configuration must reach onModuleInit() as disabled. Keeping the defaults here
+    // started a tus server — upload directory, hourly cleanup interval — behind a module that
+    // registers no endpoint at all.
+    this.config = normalizeTusConfig(config) ?? { ...DEFAULT_TUS_CONFIG, enabled: false };
   }
 
   async onModuleInit(): Promise<void> {
@@ -557,6 +557,72 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
     throw Object.assign(new Error('Upload not found'), { body: 'Upload not found', status_code: 404 });
   }
 
+  /**
+   * The tus extensions the configuration switched off. `@tus/server` consults none of these flags:
+   * the store advertises creation and termination whatever is configured, and POST / DELETE are
+   * served regardless — so before 11.42.9 `termination: false` was a line in the boot log and nothing
+   * else.
+   */
+  protected disabledExtensions(): Set<string> {
+    const disabled = new Set<string>();
+    if (this.config.creation === false) {
+      ['creation', 'creation-with-upload', 'creation-defer-length'].forEach((extension) => disabled.add(extension));
+    }
+    if (this.config.creationWithUpload === false) {
+      disabled.add('creation-with-upload');
+    }
+    if (this.config.termination === false) {
+      disabled.add('termination');
+    }
+    return disabled;
+  }
+
+  /**
+   * Refuses a request that needs an extension the configuration switched off, with the 501 `@tus/server`
+   * itself answers for an extension it does not support. Runs before the ownership check, so a
+   * refusal says nothing about whether the upload exists.
+   */
+  protected assertExtensionEnabled(req: any): void {
+    const disabled = this.disabledExtensions();
+    const method = String(req?.method ?? '').toUpperCase();
+    const contentType = this.readRequestHeader(req, 'content-type')?.toLowerCase() ?? '';
+    const needed =
+      method === 'DELETE'
+        ? 'termination'
+        : method === 'POST'
+          ? contentType.startsWith('application/offset+octet-stream')
+            ? 'creation-with-upload'
+            : 'creation'
+          : undefined;
+    if (needed && disabled.has(needed)) {
+      throw Object.assign(new Error(`The ${needed} extension is disabled`), {
+        body: `The ${needed} extension is disabled\n`,
+        status_code: 501,
+      });
+    }
+  }
+
+  /**
+   * The path a new upload's URL is built on: the one the creation request arrived at, so the URL
+   * points where the controller actually listens — under a global prefix, a URI version or a project's
+   * own route alike.
+   *
+   * Except when the configured `path` is longer and ends with it: then a reverse proxy strips a prefix
+   * on the way in (public `/files/tus`, forwarded as `/tus`), and the client must be handed the public
+   * path — which is what `path` was set to before 11.42.9 for exactly that reason. Override for a proxy
+   * that rewrites the path in any other way.
+   */
+  protected uploadCollectionPath(req: any): string {
+    const configured = (this.config.path || DEFAULT_TUS_CONFIG.path).replace(/\/+$/, '');
+    let requested: string;
+    try {
+      requested = new URL(String(req?.url ?? ''), 'http://localhost').pathname.replace(/\/+$/, '');
+    } catch {
+      return configured;
+    }
+    return configured.length > requested.length && configured.endsWith(requested) ? configured : requested;
+  }
+
   /**
    * Validate file type against allowedTypes configuration
    *
@@ -751,6 +817,10 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
    */
   private async createTusServer(uploadDir: string): Promise<Server> {
     const datastore = (await this.createS3Store()) || new FileStore({ directory: uploadDir });
+    // The store advertises what it CAN do (OPTIONS → Tus-Extension); narrowed to what is configured.
+    datastore.extensions = datastore.extensions.filter(
+      (extension: string) => !this.disabledExtensions().has(extension),
+    );
 
     // @tus/server's default locker is in-memory, which is exclusive within ONE process only:
     // behind a load balancer two replicas each hold their own lock for the same upload id and
@@ -774,8 +844,26 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       // this: it decides who may reach the endpoint, not which upload they may touch, and the tus
       // 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) => this.onUploadCreate(req, upload),
+      // The extension check sits here rather than in the overridable hooks, so a project override that
+      // forgets `super` cannot reopen what the configuration switched off.
+      onIncomingRequest: async (req, uploadId) => {
+        this.assertExtensionEnabled(req);
+        return this.assertUploadOwnership(req, uploadId);
+      },
+      onUploadCreate: async (req, upload) => {
+        this.assertExtensionEnabled(req);
+        return this.onUploadCreate(req, upload);
+      },
+      // Where the upload was CREATED, not a configured string: the controller may sit below a global
+      // prefix, a URI version or a project's own route, none of which `path` knows — and a Location
+      // pointing elsewhere breaks every resume (HEAD / PATCH answer 404).
+      // Relative when asked for: by `tus.relativeLocation`, or by @tus/server's own `relativeLocation`
+      // passed here by a project, which this generateUrl would otherwise silently override.
+      generateUrl: (req, { host, id, proto }) => {
+        const url = `${this.uploadCollectionPath(req)}/${id}`;
+        const relative = this.config.relativeLocation === true || (server as any)?.options?.relativeLocation === true;
+        return relative ? url : `${proto}://${host}${url}`;
+      },
       onUploadFinish: async (_req, upload) => {
         try {
           await this.onUploadComplete(upload);
@@ -1004,26 +1092,9 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
    * Log which features are enabled
    */
   private logEnabledFeatures(): void {
-    const features: string[] = [];
-
-    if (this.config.creation !== false) {
-      features.push('creation');
-    }
-    if (this.config.creationWithUpload !== false) {
-      features.push('creation-with-upload');
-    }
-    if (this.config.termination !== false) {
-      features.push('termination');
-    }
-    if (this.config.expiration !== false) {
-      features.push('expiration');
-    }
-    if (this.config.checksum !== false) {
-      features.push('checksum');
-    }
-    if (this.config.concatenation !== false) {
-      features.push('concatenation');
-    }
+    // What the server answers OPTIONS with, i.e. what a client can actually use — not the config flags:
+    // the stores support neither checksum nor concatenation, whatever the configuration says.
+    const features: string[] = [...((this.tusServer as any)?.datastore?.extensions ?? [])];
 
     if (features.length > 0) {
       this.logger.log(`TUS extensions: ${features.join(', ')}`);

package/src/core/modules/tus/interfaces/tus-config.interface.ts

@@ -50,6 +50,7 @@ export const DEFAULT_TUS_CONFIG: Required<
   expiration: { enabled: true, expiresIn: '24h' },
   maxSize: 50 * 1024 * 1024 * 1024, // 50 GB
   path: '/tus',
+  relativeLocation: false,
   // A tus upload writes into the SAME file store that `file.downloadRoles`
   // guards — GridFS or S3, whichever `file.storage` selects — and with the
   // termination extension it can delete from it too. Requiring a session is the

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

@@ -1,4 +1,5 @@
 import { DynamicModule, Global, Logger, Module, OnModuleInit, Type } from '@nestjs/common';
+import { PATH_METADATA } from '@nestjs/common/constants';
 import { ModuleRef } from '@nestjs/core';
 import { getConnectionToken } from '@nestjs/mongoose';
 import { Connection } from 'mongoose';
@@ -126,6 +127,8 @@ export class TusModule implements OnModuleInit {
   private static currentConfig: ITusConfig | null = null;
   private static customController: null | Type<CoreTusController> = null;
   private static customService: null | Type<CoreTusService> = null;
+  /** The route each controller class declared, before applyPath() moved it. */
+  private static declaredPaths = new WeakMap<Type<CoreTusController>, unknown>();
 
   constructor(private readonly tusService?: CoreTusService) {}
 
@@ -178,6 +181,37 @@ export class TusModule implements OnModuleInit {
     }
   }
 
+  /**
+   * Makes the controller's route and `tus.path` agree. A configured `path` mounts the controller there
+   * — config wins over a re-declared `@Controller()`, as it does for the roles; without one, `path`
+   * follows the route the controller declared. Before 11.42.9 the two were independent: the core
+   * controller always listened at `/tus` while a configured `path` only changed the URLs handed to the
+   * client, so every resume after a non-default `path` answered 404.
+   *
+   * The declared route is remembered per class, so a later forRoot() without `path` restores it.
+   */
+  private static applyPath(controller: Type<CoreTusController>, config: ITusConfig, configuredPath: unknown): void {
+    if (!this.declaredPaths.has(controller)) {
+      this.declaredPaths.set(controller, Reflect.getMetadata(PATH_METADATA, controller));
+    }
+    const trim = (value: string) => value.replace(/^\/+|\/+$/g, '');
+    const configured = typeof configuredPath === 'string' ? trim(configuredPath) : '';
+    const declared = this.declaredPaths.get(controller);
+    const declaredRoute = typeof declared === 'string' ? trim(declared) : '';
+    // A path that ENDS with the controller's own route (`api/tus` for `tus`) names the URL the route is
+    // publicly reachable under — a global prefix or a proxy in front of it. That is how `path` had to be
+    // used before 11.42.9, and those setups keep working: the controller stays, upload URLs use the
+    // path. Mounting it there would put the prefix in twice (`/api/api/tus`).
+    const publicUrl = !!declaredRoute && configured !== declaredRoute && configured.endsWith(`/${declaredRoute}`);
+    const route = configured && !publicUrl ? configured : declared;
+    Reflect.defineMetadata(PATH_METADATA, route, controller);
+    if (configured) {
+      config.path = `/${configured}`;
+    } else if (typeof route === 'string') {
+      config.path = `/${trim(route)}`;
+    }
+  }
+
   /**
    * Creates a dynamic module for TUS uploads
    *
@@ -185,7 +219,14 @@ export class TusModule implements OnModuleInit {
    * @returns Dynamic module configuration
    */
   static forRoot(options: TusModuleOptions = {}): DynamicModule {
-    const { config: rawConfig, controller, service } = options;
+    const { config: explicitConfig, controller, service } = options;
+
+    // Without an explicit `config`, the server configuration's `tus` key applies — the zero-config rule
+    // BetterAuthModule.forRoot() follows too: CoreModule.forRoot() runs first and fills ConfigService.
+    // Before 11.42.9 that key was never read, so `tus: false`, `allowedTypes` or `maxSize` in
+    // config.env.ts did nothing at all.
+    const rawConfig =
+      explicitConfig !== undefined ? explicitConfig : ConfigService.get<boolean | ITusConfig | undefined>('tus');
 
     // Normalize config: undefined/true → enabled with defaults, false → disabled
     const config = normalizeTusConfig(rawConfig);
@@ -243,6 +284,7 @@ export class TusModule implements OnModuleInit {
     // touches the members it knows), or register the controller outside
     // TusModule entirely.
     this.applyRoles(this.getControllerClass(), config.roles);
+    this.applyPath(this.getControllerClass(), config, typeof rawConfig === 'object' ? rawConfig?.path : undefined);
 
     return {
       controllers: [this.getControllerClass()],

package/src/core.module.ts

@@ -446,7 +446,8 @@ export class CoreModule implements NestModule {
       );
     }
 
-    if (config.healthCheck) {
+    // Presence implies enabled; `enabled: false` keeps the configured checks without the endpoints.
+    if (config.healthCheck && config.healthCheck.enabled !== false) {
       imports.push(CoreHealthCheckModule);
     }
 

package/src/index.ts

@@ -9,6 +9,7 @@ export * from './core.module';
 // =====================================================================================================================
 export * from './core/common/args/filter.args';
 export * from './core/common/args/pagination.args';
+export * from './core/common/decorators/api-methods.decorator';
 export * from './core/common/decorators/common-error.decorator';
 export * from './core/common/decorators/current-user.decorator';
 export * from './core/common/decorators/graphql-populate.decorator';