@lenne.tech/nest-server 11.42.8 → 11.42.10

package/src/core/common/helpers/swagger.helper.ts

@@ -1,11 +1,29 @@
 import { Logger } from '@nestjs/common';
+import { PATH_METADATA } from '@nestjs/common/constants';
 import { ModulesContainer } from '@nestjs/core';
+import { SchedulerRegistry } from '@nestjs/schedule';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 
+import { getMountedMcpOAuth } from '../../modules/ai/helpers/ai-mcp-oauth.registry';
 import { resolveApiTokenConfig } from '../../modules/api-token/core-api-token.helpers';
 import { API_TOKEN_SCOPES_KEY } from '../../modules/api-token/core-api-token.constants';
+import { CoreAuthController } from '../../modules/auth/core-auth.controller';
+import { isLegacyEndpointEnabled } from '../../modules/auth/helpers/legacy-endpoints.helper';
 import { resolveBetterAuthSessionCookieName } from '../../modules/better-auth/better-auth-cookie-prefix.helper';
+import {
+  isBetterAuthOpenApiPath,
+  isControllerHandledPath,
+  isUnavailableOperation,
+  switchedOffBetterAuthPaths,
+} from '../../modules/better-auth/core-better-auth-openapi.helper';
+import { CoreBetterAuthUserMapper } from '../../modules/better-auth/core-better-auth-user.mapper';
+import { CoreBetterAuthController } from '../../modules/better-auth/core-better-auth.controller';
+import { CoreBetterAuthService } from '../../modules/better-auth/core-better-auth.service';
+import { CoreHubActionsController } from '../../modules/hub/core-hub-actions.controller';
+import { CoreHubController } from '../../modules/hub/core-hub.controller';
+import { isHubEnabled, normalizeHubConfig } from '../../modules/hub/hub-config.helper';
 import { SKIP_TENANT_CHECK_KEY } from '../../modules/tenant/core-tenant.decorators';
+import { API_METHODS_KEY } from '../decorators/api-methods.decorator';
 import { mergeRolesMetadata } from '../../modules/tenant/core-tenant.helpers';
 import { RoleEnum } from '../enums/role.enum';
 import { ConfigService } from '../services/config.service';
@@ -20,6 +38,9 @@ import type {
   ReferenceObject,
   TagObject,
 } from '@nestjs/swagger';
+import type { IMountedMcpOAuth } from '../../modules/ai/helpers/ai-mcp-oauth.registry';
+import type { IBetterAuthOpenApiDocument } from '../../modules/better-auth/core-better-auth-openapi.helper';
+import type { ResolvedHubConfig } from '../../modules/hub/interfaces/hub-config.interface';
 import type { IServerOptions } from '../interfaces/server-options.interface';
 import type { ISwaggerApiTokenViewOptions, ISwaggerSetupOptions } from '../interfaces/swagger-setup-options.interface';
 
@@ -37,6 +58,15 @@ import type { ISwaggerApiTokenViewOptions, ISwaggerSetupOptions } from '../inter
  *   (`x-api-token-scopes` plus a line in the description). `@ApiTokenScopes()` on the method replaces
  *   the class-level declaration, exactly as in `assertApiTokenScopes()`.
  * - With multi-tenancy on, every operation that reads the tenant header documents it as a parameter.
+ * - The routes Better-Auth serves itself (two-factor, passkey, sessions, password change, … — whatever the
+ *   configured plugins add) are documented from Better-Auth's own OpenAPI generator, under the project's
+ *   Better-Auth controller (since 11.42.9); so are `/ai/mcp` and the MCP OAuth endpoints
+ *   `mountAiMcpOAuth()` mounted.
+ * - Only what can succeed under the running configuration is documented (since 11.42.9): an `@All()`
+ *   handler keeps the methods `@ApiMethods()` names; legacy `/auth/*` disappears while
+ *   `auth.legacyEndpoints` keeps REST closed; Better-Auth routes disappear when the configuration or the
+ *   live instance refuses them; Hub endpoints disappear with their switched-off panel. Every rule reads
+ *   the switch the handler itself reads — project modules are documented by the same scan, automatically.
  * - Optionally, a second document lists only the routes an API token may call.
  *
  * Each operation is mapped to its handler through the default operation id (`<Controller>_<method>`),
@@ -77,6 +107,25 @@ interface IOperationAccess {
   skipsTenantHeader: boolean;
 }
 
+/** What the document needs to know about the Better-Auth routes of the application. */
+interface IBetterAuthRoutes {
+  /** Base path every Better-Auth route lives under (`/iam`) */
+  basePath: string;
+  /** The project's Better-Auth controller, under which the generated routes are documented */
+  controller: Type<unknown>;
+  /** The controller's routes are not where its metadata puts them (global prefix, URI versioning) */
+  relocated?: boolean;
+  /** Better-Auth's own description of the routes it serves itself */
+  schema?: IBetterAuthOpenApiDocument;
+  /**
+   * Operations (relative to the base path) that answer an error for every caller: what the configuration
+   * switches off plus what the live Better-Auth instance refuses (`isUnavailableOperation()` keys)
+   */
+  switchedOff: Set<string>;
+  /** Tags of the controller's explicit routes, as Swagger built them (before `operationTags`) */
+  tags?: string[];
+}
+
 interface IResolvedApiTokenView {
   description?: string;
   enabled: boolean;
@@ -179,15 +228,36 @@ export function buildSwaggerDocument(
   }
 
   const handlers = indexHandlers(app);
+  const betterAuthRoutes = resolveBetterAuthRoutes(app, handlers, config);
+  const availability = resolveAvailability(app, config, betterAuthRoutes);
+  const switchedOff: [string, string][] = [];
   forEachOperation(document, (path, method, operation) => {
     const reference = resolveHandler(operation.operationId, handlers);
     if (!reference) {
       logger.warn(`No handler found for operation ${operation.operationId ?? `${method.toUpperCase()} ${path}`}`);
       return;
     }
+    if (betterAuthRoutes && isBetterAuthController(reference.controller)) {
+      betterAuthRoutes.tags ??= [...(operation.tags ?? [])];
+      // A global prefix or URI versioning puts the controller's routes below another base than its
+      // metadata says — and then Better-Auth's own routes are not reachable at all (see
+      // addBetterAuthRoutes). Compared by the controller's base only: a handler path is written in Nest's
+      // syntax (`:id`, `*path`), the document's in OpenAPI's (`{id}`), so a full comparison would read
+      // every parametrized route as relocated.
+      const base = declaredControllerBase(reference.controller);
+      if (base && path !== base && !path.startsWith(`${base}/`)) {
+        betterAuthRoutes.relocated = true;
+      }
+    }
+    if (isSwitchedOffOperation(reference, method, availability)) {
+      switchedOff.push([path, method]);
+      return;
+    }
     const access = describeAccess(reference, multiTenancy);
 
-    if (access.isPublic) {
+    // An explicit @ApiBearerAuth()/@ApiSecurity() wins over "public": a route the guards admit to
+    // everybody may still authenticate the caller itself (the MCP endpoint does).
+    if (access.isPublic && !declaresSecurity(reference)) {
       operation.security = [];
     }
     if (apiTokens.enabled) {
@@ -218,10 +288,393 @@ export function buildSwaggerDocument(
     }
   });
 
+  for (const [path, method] of switchedOff) {
+    const item = document.paths[path] as Record<string, unknown>;
+    delete item[method];
+    if (!operationsOf(document.paths[path]).length) {
+      delete document.paths[path];
+    }
+  }
+
+  const added = { apiTokensEnabled: apiTokens.enabled, operationTags: options.operationTags };
+  if (betterAuthRoutes?.schema) {
+    if (betterAuthRoutes.relocated) {
+      logger.warn(
+        "Better-Auth's own routes are not documented: under a global prefix or URI versioning the API " +
+          'middleware does not forward them, so none of them would be reachable at the documented path.',
+      );
+    } else {
+      addBetterAuthRoutes(document, betterAuthRoutes, added);
+    }
+  }
+  const mcpOAuth = getMountedMcpOAuth();
+  if (mcpOAuth) {
+    addMcpOAuthRoutes(document, mcpOAuth, added);
+  }
+
   document.tags = orderTags(document, options.tags);
   return document;
 }
 
+/** What decides whether a registered route can succeed under the running configuration. */
+interface IAvailability {
+  /** AI module registered (the Hub's AI panel reads it) */
+  ai: boolean;
+  betterAuth?: IBetterAuthRoutes;
+  /** Better-Auth's user mapper registered (the Hub's auth-migration panel reads it) */
+  betterAuthMapper: boolean;
+  config: Partial<IServerOptions>;
+  /** The Hub's resolved configuration, when the Hub is enabled */
+  hub?: ResolvedHubConfig;
+  /** `ScheduleModule` registered (the Hub's cron panel and actions read it) */
+  scheduler: boolean;
+}
+
+/** Legacy-auth REST handlers that answer 410 while `auth.legacyEndpoints` keeps REST closed */
+const LEGACY_REST_HANDLERS = new Set(['logout', 'refreshToken', 'signIn', 'signUp']);
+
+/**
+ * Hub endpoints that answer `{ available: false }` (or refuse) unless their source is present — keyed by
+ * handler name, read the way the Hub's own services decide it.
+ */
+const HUB_AVAILABILITY: Record<string, (availability: IAvailability, hub: ResolvedHubConfig) => boolean> = {
+  aiJson: (availability) => availability.ai,
+  authMigrationJson: (availability) => availability.betterAuthMapper,
+  cron: (availability) => availability.scheduler,
+  cronJson: (availability) => availability.scheduler,
+  dbJson: (_availability, hub) => hub.db !== false,
+  emailPreview: (_availability, hub) => hub.emailPreview,
+  emailsJson: (_availability, hub) => hub.emailPreview,
+  logsJson: (_availability, hub) => hub.collectors.logs !== false,
+  mailboxHtml: (_availability, hub) => hub.mailbox !== false,
+  mailboxJson: (_availability, hub) => hub.mailbox !== false,
+  migrationsDown: (_availability, hub) => hub.migrations !== false,
+  migrationsJson: (_availability, hub) => hub.migrations !== false,
+  migrationsRun: (_availability, hub) => hub.migrations !== false,
+  queriesJson: (_availability, hub) => hub.collectors.queries !== false,
+  tracesJson: (_availability, hub) => hub.collectors.traces !== false,
+};
+
+function resolveAvailability(
+  app: INestApplication,
+  config: Partial<IServerOptions>,
+  betterAuth: IBetterAuthRoutes | undefined,
+): IAvailability {
+  const ai = config.ai;
+  return {
+    ai: ai === true || (typeof ai === 'object' && ai !== null && (ai as { enabled?: boolean }).enabled !== false),
+    betterAuth,
+    betterAuthMapper: isProvided(app, CoreBetterAuthUserMapper),
+    config,
+    hub: isHubEnabled(config.hub) ? normalizeHubConfig(config.hub!, { env: config.env ?? '', version: '' }) : undefined,
+    scheduler: isProvided(app, SchedulerRegistry),
+  };
+}
+
+/** Whether a provider is registered anywhere in the application */
+function isProvided(app: INestApplication, token: Type<unknown>): boolean {
+  try {
+    return !!app.get(token, { strict: false });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether an operation of a registered handler answers an error for every caller under the running
+ * configuration — documented, it could never succeed. Each rule reads the switch the handler itself reads.
+ */
+function isSwitchedOffOperation(reference: IHandlerReference, method: string, availability: IAvailability): boolean {
+  const methods = Reflect.getMetadata(API_METHODS_KEY, reference.handler) as string[] | undefined;
+  if (methods && !methods.includes(method)) {
+    return true;
+  }
+  const { controller, handlerName } = reference;
+  if (extendsClass(controller, CoreAuthController) && LEGACY_REST_HANDLERS.has(handlerName)) {
+    return !isLegacyEndpointEnabled(availability.config.auth?.legacyEndpoints, 'rest');
+  }
+  if (availability.betterAuth && isBetterAuthController(controller)) {
+    const relativePath = declaredHandlerPath(reference.handler);
+    return (
+      relativePath !== undefined && isUnavailableOperation(availability.betterAuth.switchedOff, method, relativePath)
+    );
+  }
+  if (
+    availability.hub &&
+    (extendsClass(controller, CoreHubController) || extendsClass(controller, CoreHubActionsController)) &&
+    HUB_AVAILABILITY[handlerName]
+  ) {
+    return !HUB_AVAILABILITY[handlerName](availability, availability.hub);
+  }
+  return false;
+}
+
+/** `base` itself or a class extending it */
+function extendsClass(controller: Type<unknown>, base: Type<unknown>): boolean {
+  return controller === base || controller.prototype instanceof base;
+}
+
+/** The handler's own route path (`sign-up/email` → `/sign-up/email`), or `undefined` for several paths */
+function declaredHandlerPath(handler: IHandlerReference['handler']): string | undefined {
+  const path = Reflect.getMetadata(PATH_METADATA, handler) as string | string[] | undefined;
+  return typeof path === 'string' ? `/${path.replace(/^\/+/, '')}`.replace(/\/$/, '') || '/' : undefined;
+}
+
+/** The path controller + handler metadata declare, without global prefix or version */
+/** The path a controller declares (`/iam`), or `undefined` when it declares none or several. */
+function declaredControllerBase(controller: IHandlerReference['controller']): string | undefined {
+  const controllerPath = Reflect.getMetadata(PATH_METADATA, controller) as string | string[] | undefined;
+  const trimmed = typeof controllerPath === 'string' ? controllerPath.replace(/^\/+|\/+$/g, '') : '';
+  return trimmed ? `/${trimmed}` : undefined;
+}
+
+/** Whether the handler or its controller declares its security itself (`@ApiBearerAuth()`, `@ApiSecurity()`) */
+function declaresSecurity(reference: IHandlerReference): boolean {
+  return !!(
+    Reflect.getMetadata('swagger/apiSecurity', reference.handler) ??
+    Reflect.getMetadata('swagger/apiSecurity', reference.controller)
+  );
+}
+
+/**
+ * Documents the MCP OAuth 2.1 endpoints `mountAiMcpOAuth()` mounted on Express — the ones it mounted,
+ * nothing else. They authenticate the client themselves, so they carry no security requirement.
+ */
+function addMcpOAuthRoutes(
+  document: OpenAPIObject,
+  mounted: IMountedMcpOAuth,
+  context: { apiTokensEnabled: boolean; operationTags: ISwaggerSetupOptions['operationTags'] },
+): void {
+  const routes: [string, string, string, string][] = [
+    [
+      'get',
+      '/.well-known/oauth-authorization-server',
+      'authorizationServerMetadata',
+      'OAuth 2.1 authorization server metadata (RFC 8414) for MCP clients.',
+    ],
+    [
+      'get',
+      `/.well-known/oauth-protected-resource${mounted.mcpPath}`,
+      'protectedResourceMetadata',
+      `Protected resource metadata (RFC 9728) of the MCP endpoint \`${mounted.mcpPath}\`.`,
+    ],
+    ['get', '/authorize', 'authorize', 'Authorization endpoint (authorization code with PKCE S256).'],
+    ['post', '/authorize', 'authorizePost', 'Authorization endpoint, form post variant.'],
+    ['post', '/token', 'token', 'Token endpoint: exchanges an authorization code or refresh token.'],
+  ];
+  if (mounted.registration) {
+    routes.push(['post', '/register', 'register', 'Dynamic client registration (RFC 7591).']);
+  }
+  if (mounted.revocation) {
+    routes.push(['post', '/revoke', 'revoke', 'Token revocation (RFC 7009).']);
+  }
+  for (const [method, path, name, description] of routes) {
+    const operation: EnrichedOperation = {
+      description: context.apiTokensEnabled ? appendLine(description, apiTokenLine(undefined)) : description,
+      operationId: `McpOAuth_${name}`,
+      responses: { default: { description: 'See the MCP authorization specification' } },
+      security: [],
+      summary: description.split(':')[0].replace(/\.$/, ''),
+      tags: ['MCP OAuth'],
+    };
+    if (context.operationTags) {
+      const tags = context.operationTags({
+        controller: 'McpOAuth',
+        handler: name,
+        isPublic: true,
+        method,
+        path,
+        scopes: undefined,
+        tags: [...(operation.tags ?? [])],
+      });
+      if (tags) {
+        operation.tags = tags;
+      }
+    }
+    document.paths[path] = { ...document.paths[path], [method]: operation };
+  }
+}
+
+/** `CoreBetterAuthController` or a project controller extending it */
+function isBetterAuthController(controller: Type<unknown>): boolean {
+  return controller === CoreBetterAuthController || controller.prototype instanceof CoreBetterAuthController;
+}
+
+/**
+ * The Better-Auth routes of the application, or `undefined` when no Better-Auth controller is registered.
+ * The base path and Better-Auth's own route description come from `CoreBetterAuthService`; what the
+ * configuration switches off is read from `config`, like everything else this helper documents.
+ */
+function resolveBetterAuthRoutes(
+  app: INestApplication,
+  handlers: Map<string, Type<unknown>[]>,
+  config: Partial<IServerOptions>,
+): IBetterAuthRoutes | undefined {
+  const controller = [...handlers.values()].flat().find(isBetterAuthController);
+  if (!controller) {
+    return undefined;
+  }
+  let service: CoreBetterAuthService | undefined;
+  try {
+    service = app.get(CoreBetterAuthService, { strict: false });
+  } catch {
+    service = undefined;
+  }
+  const betterAuth = typeof config.betterAuth === 'object' && config.betterAuth !== null ? config.betterAuth : {};
+  return {
+    basePath: service?.getBasePath?.() || betterAuth.basePath || '/iam',
+    controller,
+    schema: service?.getOpenApiSchema?.(),
+    switchedOff: new Set([...switchedOffBetterAuthPaths(betterAuth), ...(service?.getUnavailableOperations?.() ?? [])]),
+  };
+}
+
+/**
+ * Adds the routes Better-Auth serves itself, documented like the routes of the project's Better-Auth
+ * controller: its tags and `operationTags`, the global security requirement, the API-token line. Leaves
+ * out what the controller handles (an explicit route always wins), what the configuration switches off,
+ * and the `openAPI()` plugin's own routes. Their schemas are added with a `BetterAuth` prefix — `User`
+ * and `Session` would otherwise collide with the project's models — and converted to OpenAPI 3.0.
+ */
+function addBetterAuthRoutes(
+  document: OpenAPIObject,
+  routes: IBetterAuthRoutes,
+  context: { apiTokensEnabled: boolean; operationTags: ISwaggerSetupOptions['operationTags'] },
+): void {
+  const renamed = new Map<string, string>();
+  const controllerTags = routes.tags ?? defaultControllerTags(routes.controller);
+  for (const [relativePath, item] of Object.entries(routes.schema?.paths ?? {})) {
+    if (isControllerHandledPath(relativePath) || isBetterAuthOpenApiPath(relativePath)) {
+      continue;
+    }
+    const path = `${routes.basePath}${relativePath}`;
+    for (const [method, source] of operationsOf(item as PathItemObject)) {
+      const existing = document.paths[path] as Record<string, unknown> | undefined;
+      if (existing?.[method] || isUnavailableOperation(routes.switchedOff, method, relativePath)) {
+        continue;
+      }
+      const operation = toOpenApi30(renameSchemaRefs(structuredClone(source), renamed)) as EnrichedOperation;
+      const betterAuthId = operation.operationId ?? `${method}${relativePath}`;
+      operation.operationId = `${routes.controller.name}_betterAuth_${betterAuthId}`;
+      // Better-Auth's generator marks every route bearer-only, public ones included.
+      // CoreBetterAuthService.prepareOpenApiSchema() replaces that with what Better-Auth enforces:
+      // `security: []` on a public route. Anything else gets the global requirement, so "Authorize"
+      // sends the session along — the safe reading of a description that did not say.
+      const isPublic = Array.isArray(operation.security) && operation.security.length === 0;
+      if (!isPublic) {
+        delete operation.security;
+      }
+      operation.tags = [...controllerTags];
+      if (context.apiTokensEnabled) {
+        // No route here releases a scope via @ApiTokenScopes(), so an API token is refused on all of them.
+        operation.description = appendLine(operation.description, apiTokenLine(undefined));
+      }
+      if (context.operationTags) {
+        const tags = context.operationTags({
+          controller: routes.controller.name,
+          handler: betterAuthId,
+          isPublic,
+          method,
+          path,
+          scopes: undefined,
+          tags: [...operation.tags],
+        });
+        if (tags) {
+          operation.tags = tags;
+        }
+      }
+      document.paths[path] = { ...document.paths[path], [method]: operation };
+    }
+  }
+  addRenamedSchemas(document, routes.schema?.components?.schemas ?? {}, renamed);
+}
+
+/** Tags `@ApiTags()` gives a controller, or the one `autoTagControllers` derives from its name */
+function defaultControllerTags(controller: Type<unknown>): string[] {
+  const tags = Reflect.getMetadata('swagger/apiUseTags', controller) as string[] | undefined;
+  return tags?.length ? [...tags] : [controller.name.replace(/Controller$/, '')];
+}
+
+/** Rewrites `#/components/schemas/<Name>` to `BetterAuth<Name>`, recording each rename. */
+function renameSchemaRefs<T>(value: T, renamed: Map<string, string>): T {
+  const prefix = '#/components/schemas/';
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+    } else if (typeof node === 'object' && node !== null) {
+      const record = node as Record<string, unknown>;
+      for (const [key, child] of Object.entries(record)) {
+        if (key === '$ref' && typeof child === 'string' && child.startsWith(prefix)) {
+          const name = child.slice(prefix.length);
+          const target = renamed.get(name) ?? `BetterAuth${name}`;
+          renamed.set(name, target);
+          record.$ref = `${prefix}${target}`;
+        } else {
+          visit(child);
+        }
+      }
+    }
+  };
+  visit(value);
+  return value;
+}
+
+/** Copies every renamed schema — and the schemas those refer to — into the document. */
+function addRenamedSchemas(
+  document: OpenAPIObject,
+  schemas: Record<string, unknown>,
+  renamed: Map<string, string>,
+): void {
+  const added = new Set<string>();
+  let pending = [...renamed.keys()];
+  while (pending.length) {
+    for (const name of pending) {
+      added.add(name);
+      if (!schemas[name]) {
+        continue;
+      }
+      document.components = document.components ?? {};
+      document.components.schemas = document.components.schemas ?? {};
+      document.components.schemas[renamed.get(name)!] ??= toOpenApi30(
+        renameSchemaRefs(structuredClone(schemas[name]), renamed),
+      ) as Record<string, unknown>;
+    }
+    pending = [...renamed.keys()].filter((name) => !added.has(name));
+  }
+}
+
+/**
+ * OpenAPI 3.1 → 3.0 for what Better-Auth's generator emits: a `type` array (`['string', 'null']`) becomes
+ * `type` plus `nullable`, or `anyOf` for several non-null types. The document itself is OpenAPI 3.0.
+ */
+function toOpenApi30<T>(value: T): T {
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+    } else if (typeof node === 'object' && node !== null) {
+      const record = node as Record<string, unknown>;
+      if (Array.isArray(record.type)) {
+        const types = record.type as string[];
+        const nonNull = types.filter((type) => type !== 'null');
+        if (nonNull.length > 1) {
+          record.anyOf = nonNull.map((type) => ({ type }));
+          delete record.type;
+        } else if (nonNull.length === 1) {
+          record.type = nonNull[0];
+        } else {
+          delete record.type;
+        }
+        if (types.includes('null')) {
+          record.nullable = true;
+        }
+      }
+      Object.values(record).forEach(visit);
+    }
+  };
+  visit(value);
+  return value;
+}
+
 /**
  * The document an API-token caller needs: only the operations that release a scope, authenticated with
  * the bearer scheme only, without the tenant header (a tenant token carries its tenant), and without the

package/src/core/common/interfaces/server-options.interface.ts

@@ -2801,7 +2801,11 @@ export interface IServerOptions {
     };
 
     /**
-     * Whether health check is enabled
+     * Whether the health check endpoints are registered. The block's presence enables them; `false`
+     * leaves them out (GET /health-check and the `healthCheck` query answer 404 / are absent) while
+     * keeping the configured checks for later. Honoured since 11.42.9 — before, any `healthCheck`
+     * object registered the endpoints, `enabled: false` included.
+     * @default true (when `healthCheck` is set)
      */
     enabled?: boolean;
   };
@@ -3455,6 +3459,10 @@ export interface IServerOptions {
    * Follows the "Enabled by Default" pattern - tus is automatically enabled
    * without any configuration. Set `tus: false` to explicitly disable.
    *
+   * Read by `TusModule.forRoot()` when it gets no `config` of its own; an explicit `config` wins.
+   * Before 11.42.9 this key was never read — `tus: false`, `allowedTypes`, `maxSize` and `roles` here
+   * did nothing.
+   *
    * Accepts:
    * - `true` or `undefined`: Enable with defaults (enabled by default)
    * - `false`: Disable TUS uploads
@@ -3756,28 +3764,29 @@ export interface ITusConfig {
 
   /**
    * Checksum extension configuration.
-   * Enables data integrity verification.
+   * Has no effect with the built-in stores (file system, S3): neither supports the extension.
    * @default true
    */
   checksum?: boolean;
 
   /**
    * Concatenation extension configuration.
-   * Allows parallel uploads that are merged.
+   * Has no effect with the built-in stores (file system, S3): neither supports the extension.
    * @default true
    */
   concatenation?: boolean;
 
   /**
    * Creation extension configuration.
-   * Allows creating new uploads via POST.
+   * Allows creating new uploads via POST. `false`: POST answers 501 and OPTIONS no longer advertises it
+   * (enforced since 11.42.9 — `@tus/server` itself ignores the flag).
    * @default true
    */
   creation?: boolean | ITusCreationConfig;
 
   /**
    * Creation With Upload extension configuration.
-   * Allows sending data in the initial POST request.
+   * Allows sending data in the initial POST request. `false`: a POST carrying data answers 501 (11.42.9+).
    * @default true
    */
   creationWithUpload?: boolean;
@@ -3802,11 +3811,30 @@ export interface ITusConfig {
   maxSize?: number;
 
   /**
-   * Base path for tus endpoints
+   * Base path for tus endpoints (11.42.9+):
+   * - a new route (`'/uploads'`): the controller is mounted there — a project controller too, as with
+   *   `roles`. Like any controller route it sits BELOW a global prefix and a URI version.
+   * - a path ending with the controller's own route (`'/api/tus'` for `tus`): the URL the route is
+   *   publicly reachable under — a global prefix, or a proxy that strips a prefix. The controller stays
+   *   and upload URLs use this path. That is how `path` had to be set before 11.42.9, and it still works.
+   * - unset: follows the controller's own route.
+   *
+   * Otherwise the URL handed to a client for a new upload is built from the path the upload was created
+   * at, so it is correct below a global prefix or a URI version without any `path`.
    * @default '/tus'
    */
   path?: string;
 
+  /**
+   * Hand out upload URLs (`Location`) without scheme and host — `/tus/<id>` instead of
+   * `https://api.example.com/tus/<id>`. For a frontend that reaches TUS through a same-origin proxy:
+   * an absolute URL names the origin the API saw, which the browser cannot reach. A project passing
+   * @tus/server's own `relativeLocation` is honoured too.
+   * @default false
+   * @since 11.42.9
+   */
+  relativeLocation?: boolean;
+
   /**
    * Roles allowed to use the tus endpoints (create, write, read offset, terminate).
    *
@@ -3849,7 +3877,8 @@ export interface ITusConfig {
 
   /**
    * Termination extension configuration.
-   * Allows deleting uploads via DELETE.
+   * Allows deleting uploads via DELETE. `false`: DELETE answers 501 and OPTIONS no longer advertises it
+   * (enforced since 11.42.9 — before, the flag was only logged).
    * @default true
    */
   termination?: boolean;
@@ -4071,6 +4100,8 @@ interface IBetterAuthBase {
      * Disable user registration (sign-up) via BetterAuth.
      * Passed through to better-auth's native emailAndPassword.disableSignUp.
      * Custom endpoints (GraphQL + REST) also check this flag early.
+     * The Swagger document built by `setupSwagger()` then leaves out `POST /iam/sign-up/email`,
+     * which would answer `SIGNUP_DISABLED` to every caller.
      * @default false
      */
     disableSignUp?: boolean;
@@ -4091,6 +4122,8 @@ interface IBetterAuthBase {
      * Set `false` to withhold the hook, which makes that route answer `RESET_PASSWORD_DISABLED`
      * again. For deployments whose reset policy is support-mediated or SSO-primary, and which
      * therefore do not want an unauthenticated, token-minting, mail-sending endpoint at all.
+     * The Swagger document built by `setupSwagger()` then leaves out `/iam/request-password-reset`,
+     * `/iam/reset-password` and `/iam/reset-password/{token}`.
      *
      * @default true
      * @since 11.36.1
@@ -4243,7 +4276,12 @@ interface IBetterAuthBase {
 
   /**
    * Additional Better-Auth plugins to include.
-   * These will be merged with the built-in plugins (jwt, twoFactor, passkey).
+   * These will be merged with the built-in plugins (jwt, twoFactor, passkey). Their routes appear in the
+   * Swagger document built by `setupSwagger()` automatically.
+   *
+   * Better-Auth's `openAPI()` plugin is registered internally (it feeds `setupSwagger()`), with its routes
+   * kept off the router. Add `openAPI()` here only if the project wants those routes public; it then
+   * replaces the internal registration.
    * @see https://www.better-auth.com/docs/plugins
    * @example
    * ```typescript

package/src/core/common/interfaces/swagger-setup-options.interface.ts

@@ -6,10 +6,13 @@ import type { DocumentBuilder, SwaggerCustomOptions, SwaggerDocumentOptions } fr
  * @since 11.42.7
  */
 export interface ISwaggerOperationInfo {
-  /** Class name of the controller that serves the operation */
+  /**
+   * Class name of the controller that serves the operation. For a route Better-Auth serves itself, the
+   * project's Better-Auth controller (`BetterAuthController` / `CoreBetterAuthController`).
+   */
   controller: string;
 
-  /** Name of the handler method */
+  /** Name of the handler method; for a route Better-Auth serves itself, Better-Auth's operation id */
   handler: string;
 
   /** True when neither the role guard nor the tenant guard requires a sign-in */

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

@@ -693,6 +693,13 @@ import { mountAiMcpOAuth } from '@lenne.tech/nest-server';
 await mountAiMcpOAuth(app);
 ```
 
+**Swagger (11.42.9):** `setupSwagger()` documents `/ai/mcp` (POST/GET/DELETE, with the bearer
+requirement the endpoint enforces itself) whenever the MCP server is registered, and — because the
+OAuth endpoints are an Express router, invisible to `@nestjs/swagger` — exactly the OAuth endpoints
+`mountAiMcpOAuth()` mounted (`/.well-known/oauth-authorization-server`,
+`/.well-known/oauth-protected-resource/ai/mcp`, `/authorize`, `/token`, `/register`; `/revoke` only for a
+provider with `revokeToken`). Without the call they are not documented, because they do not exist.
+
 The issuer — and with it every endpoint URL in the discovery metadata, which MCP clients follow —
 is the server's `baseUrl` (`NSC__BASE_URL` when deployed), resolved the same way BetterAuth and
 CORS resolve it. `local` / `ci` / `e2e` fall back to `http://localhost:3000`; any other environment