@lenne.tech/nest-server 11.42.7 → 11.42.9

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

package/src/core/modules/ai/core-ai-mcp.controller.ts

@@ -1,5 +1,5 @@
 import { Controller, Delete, Get, Logger, OnModuleDestroy, Optional, Post, Req, Res } from '@nestjs/common';
-import { ApiExcludeController } from '@nestjs/swagger';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
 import { Request, Response } from 'express';
 import { hostname } from 'node:os';
 
@@ -62,7 +62,10 @@ interface McpSessionEntry {
   user: AiToolUser;
 }
 
-@ApiExcludeController()
+// The route guard admits everybody because the endpoint authenticates itself (session/JWT bearer, or an
+// MCP OAuth token): the bearer requirement is declared for Swagger, which setupSwagger() keeps.
+@ApiBearerAuth('bearer')
+@ApiTags('AI MCP')
 @Controller('ai/mcp')
 @Roles(RoleEnum.S_EVERYONE)
 export class CoreAiMcpController implements OnModuleDestroy {
@@ -108,6 +111,12 @@ export class CoreAiMcpController implements OnModuleDestroy {
     @Optional() protected readonly redisService?: CoreRedisService,
   ) {}
 
+  @ApiOperation({
+    description:
+      'Model Context Protocol endpoint (Streamable HTTP) for MCP clients: JSON-RPC 2.0 messages, starting with `initialize`. ' +
+      'The response carries the `mcp-session-id` header that later requests send back. Requires a bearer token (session, JWT or MCP OAuth token).',
+    summary: 'MCP request',
+  })
   @Post()
   async handlePost(@Req() req: Request, @Res() res: Response): Promise<void> {
     const user = await this.resolveUser(req);
@@ -206,11 +215,19 @@ export class CoreAiMcpController implements OnModuleDestroy {
     }
   }
 
+  @ApiOperation({
+    description: 'Server-sent event stream of an MCP session (`mcp-session-id` header). Requires a bearer token.',
+    summary: 'MCP event stream',
+  })
   @Get()
   async handleGet(@Req() req: Request, @Res() res: Response): Promise<void> {
     await this.handleSessionRequest(req, res);
   }
 
+  @ApiOperation({
+    description: 'Ends an MCP session (`mcp-session-id` header). Requires a bearer token.',
+    summary: 'End MCP session',
+  })
   @Delete()
   async handleDelete(@Req() req: Request, @Res() res: Response): Promise<void> {
     await this.handleSessionRequest(req, res);

package/src/core/modules/ai/helpers/ai-mcp-oauth.helper.ts

@@ -3,6 +3,7 @@ import { Logger } from '@nestjs/common';
 import { resolveServerUrls } from '../../../common/helpers/cookies.helper';
 import { ConfigService } from '../../../common/services/config.service';
 import { CoreAiMcpOAuthService } from '../services/core-ai-mcp-oauth.service';
+import { setMountedMcpOAuth } from './ai-mcp-oauth.registry';
 
 /**
  * Mount the MCP OAuth 2.1 router (`mcpAuthRouter`) on a NestJS application.
@@ -10,7 +11,9 @@ import { CoreAiMcpOAuthService } from '../services/core-ai-mcp-oauth.service';
  * Call this in `main.ts` AFTER `app.init()` when `ai.mcp.oauth` is enabled. It
  * lazy-imports `@modelcontextprotocol/sdk` and wires the OAuth provider built from
  * {@link CoreAiMcpOAuthService}, exposing the standard discovery + token endpoints
- * (`/.well-known/oauth-*`, `/authorize`, `/token`, `/register`, `/revoke`).
+ * (`/.well-known/oauth-*`, `/authorize`, `/token`, `/register`; `/revoke` only for a provider that
+ * implements `revokeToken`, which the built-in one does not). `setupSwagger()` documents exactly the
+ * endpoints mounted here.
  *
  * The interactive consent step requires `CoreAiMcpOAuthService.authorizeConsent`
  * to be overridden with your login/consent UI (see INTEGRATION-CHECKLIST).
@@ -46,10 +49,11 @@ export async function mountAiMcpOAuth(
   const mcpPath = options.mcpPath ?? '/ai/mcp';
 
   let router: unknown;
+  const provider = oauthService.buildOAuthProvider() as any;
   try {
     router = mcpAuthRouter({
       issuerUrl,
-      provider: oauthService.buildOAuthProvider() as any,
+      provider,
       resourceServerUrl: new URL(`${baseUrl.replace(/\/$/, '')}${mcpPath}`),
     });
   } catch (error) {
@@ -63,6 +67,12 @@ export async function mountAiMcpOAuth(
   }
 
   app.use(router);
+  // The same conditions mcpAuthRouter() uses to decide whether /register and /revoke exist.
+  setMountedMcpOAuth({
+    mcpPath,
+    registration: !!provider?.clientsStore?.registerClient,
+    revocation: !!provider?.revokeToken,
+  });
   new Logger('mountAiMcpOAuth').log(`MCP OAuth issuer: ${issuerUrl.href} (from ${source})`);
 }
 

package/src/core/modules/ai/helpers/ai-mcp-oauth.registry.ts

@@ -0,0 +1,29 @@
+/**
+ * What `mountAiMcpOAuth()` mounted, for `setupSwagger()`.
+ *
+ * The MCP OAuth endpoints are an Express router mounted with `app.use()`, not Nest controllers, so
+ * `@nestjs/swagger` cannot see them. The mount records here what it put in place — only then are the
+ * endpoints documented, so the document follows the actual call in `main.ts`, not a config flag.
+ *
+ * Imports nothing on purpose: read by the common Swagger helper without pulling in the AI module.
+ */
+export interface IMountedMcpOAuth {
+  /** Path of the protected MCP resource (`/ai/mcp`) */
+  mcpPath: string;
+  /** Whether `/register` (dynamic client registration) is mounted */
+  registration: boolean;
+  /** Whether `/revoke` is mounted */
+  revocation: boolean;
+}
+
+let mounted: IMountedMcpOAuth | undefined;
+
+/** Records the mounted MCP OAuth endpoints (called by `mountAiMcpOAuth()`). */
+export function setMountedMcpOAuth(value: IMountedMcpOAuth | undefined): void {
+  mounted = value;
+}
+
+/** The mounted MCP OAuth endpoints, or `undefined` when `mountAiMcpOAuth()` was not called. */
+export function getMountedMcpOAuth(): IMountedMcpOAuth | undefined {
+  return mounted;
+}

package/src/core/modules/better-auth/README.md

@@ -1146,6 +1146,40 @@ When enabled, Better-Auth exposes the following endpoints at the configured `bas
 | `/iam/reset-password`  | POST   | Reset password with token     |
 | `/iam/verify-email`    | POST   | Verify email address          |
 
+### In the Swagger document (since 11.42.9)
+
+`setupSwagger()` documents every route this module makes reachable under the base path, as the server
+is configured:
+
+- The routes `CoreBetterAuthController` handles itself (`sign-in/email`, `sign-up/email`, `sign-out`,
+  `session`, `features`) come from the controller, as for any Nest controller.
+- The routes Better-Auth serves itself — everything the configured plugins add (two-factor, passkey,
+  sessions, password change, …) — come from Better-Auth's own OpenAPI generator
+  (`CoreBetterAuthService.getOpenApiSchema()`, prepared at bootstrap). They are documented under the
+  project's Better-Auth controller: its tags, its `operationTags`, operation ids
+  `<Controller>_betterAuth_<betterAuthOperationId>`, schemas prefixed `BetterAuth` (`BetterAuthUser`).
+- Only what can succeed is documented. `switchedOffBetterAuthPaths()` reads the nest-server switches
+  (sign-in/sign-up under `emailAndPassword.enabled: false`, `sign-up/email` under `disableSignUp`, the
+  reset routes under `passwordReset: false`); `unavailableBetterAuthOperations()` reads the LIVE
+  instance at bootstrap — so `betterAuth.options` and project plugins count — and drops e.g. POST
+  `/get-session` without `session.deferSessionRefresh`, social routes without a provider, two-factor OTP
+  routes without `otpOptions.sendOTP`. Both apply to the controller's own routes as well.
+- Security says what Better-Auth enforces, not what its generator writes (every route bearer-only): a
+  route guarded by one of Better-Auth's session middlewares — or one of the three social-account routes
+  that check the session in their handler (`HANDLER_SESSION_PATHS`) — carries the document's global
+  requirement; every other route is public (`security: []`): sign-in, password reset, get-session, the
+  two-factor verification steps of a sign-in. Routes of a plugin the module does not register itself
+  (`admin()`, `organization()`, anything in `betterAuth.plugins`) always keep the global requirement:
+  such a plugin may check the session in a middleware of its own, which cannot be recognised from outside.
+- Under a global prefix or URI versioning the middleware does not forward Better-Auth's own routes, so
+  they are not documented then (a warning says so).
+
+Better-Auth exposes its generator only through its `openAPI()` plugin, so the module registers that plugin
+itself (`disableDefaultReference: true`). Its own route, `/iam/open-api/generate-schema`, is not part of
+the API: the plugin's endpoints are marked server-only, so Better-Auth never routes them (404, however the
+path is spelled) and the module calls the generator in-process. A project that adds `openAPI()` to
+`betterAuth.plugins` itself keeps those routes — then it is the project's decision.
+
 ### JWT Token Endpoint
 
 The `/iam/token` endpoint returns a fresh JWT token for the current session. Use this when your JWT has expired but your session is still valid.

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

@@ -2,7 +2,7 @@ import { passkey } from '@better-auth/passkey';
 import { Logger } from '@nestjs/common';
 import { betterAuth, BetterAuthPlugin } from 'better-auth';
 import { mongodbAdapter } from 'better-auth/adapters/mongodb';
-import { jwt, twoFactor } from 'better-auth/plugins';
+import { jwt, openAPI, twoFactor } from 'better-auth/plugins';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -11,6 +11,7 @@ import { resolveServerUrls, strippedApiHostname } from '../../common/helpers/coo
 import { revalidateWsConnectionsOf } from '../../common/helpers/graphql-ws-connection.helper';
 import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface';
 import { detectCookiePrefixDrift, resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper';
+import { projectProvidesOpenApiPlugin } from './core-better-auth-openapi.helper';
 
 /**
  * Type for better-auth instance with plugins
@@ -978,6 +979,16 @@ function buildPlugins(
     plugins.push(passkey(passkeyOptions));
   }
 
+  // Better-Auth's OpenAPI generator, so setupSwagger() can document exactly the routes the configured
+  // plugins add (CoreBetterAuthService.getOpenApiSchema()). Better-Auth exposes the generator only
+  // through this plugin, and the plugin only as HTTP routes — which are not part of the API. They are
+  // kept off the router rather than refused by path: a path check sees the request as sent, while
+  // Better-Auth resolves `/iam/./open-api/…` or `/iam/x/%2e%2e/open-api/…` to the very same route.
+  // A project that registers openAPI() itself keeps its routes.
+  if (!projectProvidesOpenApiPlugin(config)) {
+    plugins.push(serverOnlyPlugin(openAPI({ disableDefaultReference: true })));
+  }
+
   // Merge custom plugins from configuration
   // This allows projects to add any Better-Auth plugin without modifying this package
   if (config.plugins?.length) {
@@ -987,6 +998,21 @@ function buildPlugins(
   return plugins;
 }
 
+/**
+ * Keeps every endpoint of a plugin off the HTTP router. better-call skips an endpoint whose metadata
+ * carries `SERVER_ONLY` when it builds the router, whatever path a request names, while
+ * `auth.api.<endpoint>()` still calls it in-process. Better-Auth's own generator leaves such endpoints
+ * out of its schema too.
+ */
+function serverOnlyPlugin<T extends BetterAuthPlugin>(plugin: T): T {
+  for (const endpoint of Object.values(plugin.endpoints ?? {}) as { options?: { metadata?: object } }[]) {
+    if (endpoint?.options) {
+      endpoint.options.metadata = { ...endpoint.options.metadata, SERVER_ONLY: true };
+    }
+  }
+  return plugin;
+}
+
 /**
  * Builds the social providers configuration object dynamically.
  * Iterates over all configured providers and includes those that are enabled

package/src/core/modules/better-auth/core-better-auth-api.middleware.ts

@@ -6,26 +6,12 @@ import { ConfigService } from '../../common/services/config.service';
 import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service';
 import { BetterAuthCookieHelper, createCookieHelper } from './core-better-auth-cookie.helper';
 import { wrapBetterAuthErrorResponse } from './core-better-auth-error-codes.helper';
+import { isControllerHandledPath } from './core-better-auth-openapi.helper';
 import { runWithResetPassword } from './core-better-auth-password-reset.registry';
 import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
 import { extractSessionToken, sendWebResponse, signCookieValue, toWebRequest } from './core-better-auth-web.helper';
 import { CoreBetterAuthService } from './core-better-auth.service';
 
-/**
- * List of paths that are handled by CoreBetterAuthController
- * These should NOT be forwarded to Better Auth's native handler
- *
- * Only paths with nest-server-specific logic belong here:
- * - sign-in/email: Legacy user migration, password normalization
- * - sign-up/email: User linking to own DB, password sync
- * - sign-out: Custom cookie clearing
- * - session: Custom response format with mapped user
- *
- * All other paths (Passkey, 2FA, etc.) go directly to Better Auth's
- * native handler via this middleware for maximum compatibility.
- */
-const CONTROLLER_HANDLED_PATHS = ['/features', '/sign-in/email', '/sign-up/email', '/sign-out', '/session'];
-
 /**
  * Native Better-Auth routes that set a NEW password from a token or OTP, with the body
  * field each of them carries it in.
@@ -227,8 +213,9 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
     // Get the path relative to the base path
     const relativePath = requestPath.slice(basePath.length);
 
-    // Skip paths that are handled by CoreBetterAuthController (nest-server-specific logic)
-    if (CONTROLLER_HANDLED_PATHS.some((path) => relativePath === path || relativePath.startsWith(`${path}/`))) {
+    // Skip paths that are handled by CoreBetterAuthController (nest-server-specific logic).
+    // All other paths (Passkey, 2FA, etc.) go directly to Better Auth's native handler.
+    if (isControllerHandledPath(relativePath)) {
       return next();
     }
 

package/src/core/modules/better-auth/core-better-auth-openapi.helper.ts

@@ -0,0 +1,219 @@
+import type { IBetterAuth } from '../../common/interfaces/server-options.interface';
+
+/**
+ * What the Swagger document needs to know about the routes under the Better-Auth base path.
+ *
+ * Two kinds of route live there. The few with nest-server-specific logic are handled by
+ * `CoreBetterAuthController` (`CONTROLLER_HANDLED_PATHS`); every other request is forwarded by
+ * `CoreBetterAuthApiMiddleware` to Better-Auth's own handler, which serves whatever the configured
+ * plugins add (two-factor, passkey, sessions, password change, …). Those forwarded routes have no
+ * Nest handler, so `@nestjs/swagger` cannot see them; `setupSwagger()` documents them from Better-Auth's
+ * OpenAPI generator instead (see `CoreBetterAuthService.getOpenApiSchema()`).
+ *
+ * This file imports types only, so the middleware, the plugin builder and the Swagger helper can all
+ * read the same rules without importing each other.
+ */
+
+/**
+ * Paths (relative to the base path) handled by `CoreBetterAuthController` rather than forwarded.
+ *
+ * Only paths with nest-server-specific logic belong here:
+ * - sign-in/email: legacy user migration, password normalization
+ * - sign-up/email: user linking to own DB, password sync
+ * - sign-out: custom cookie clearing
+ * - session: custom response format with mapped user
+ * - features: nest-server's own feature report
+ */
+export const CONTROLLER_HANDLED_PATHS = ['/features', '/sign-in/email', '/sign-up/email', '/sign-out', '/session'];
+
+/**
+ * Routes Better-Auth guards with a session check in the HANDLER instead of a session middleware: the
+ * social-account routes resolve their caller through `resolveUserId()` (better-auth `api/routes/account`),
+ * which refuses an HTTP caller without a session. Every other route without a session middleware is
+ * public. Pinned against better-auth's source by tests/unit/better-auth-openapi-availability.spec.ts.
+ */
+export const HANDLER_SESSION_PATHS = ['/account-info', '/get-access-token', '/refresh-token'];
+
+/**
+ * The plugins `buildPlugins()` registers itself. Their routes — like Better-Auth's core routes — are
+ * classified by the session middleware they carry. Any other plugin's routes keep the global security
+ * requirement: such a plugin may check the session in a middleware of its own (`admin()` does), which
+ * nothing outside it can recognise, and a session route documented as public sends clients without one.
+ */
+export const BUILT_IN_BETTER_AUTH_PLUGIN_IDS = ['jwt', 'lt-ws-session-revocation', 'open-api', 'passkey', 'two-factor'];
+
+/** Better-Auth's `:param` route syntax as OpenAPI's `{param}`, which its generator writes. */
+export function toOpenApiPath(path: string): string {
+  return path.replace(/:([^/]+)/g, '{$1}');
+}
+
+/** Base of the routes Better-Auth's `openAPI()` plugin adds (`/open-api/generate-schema`). */
+export const BETTER_AUTH_OPEN_API_PATH = '/open-api';
+
+/** Id of Better-Auth's `openAPI()` plugin */
+export const BETTER_AUTH_OPEN_API_PLUGIN_ID = 'open-api';
+
+/**
+ * Minimal shape of the document Better-Auth's OpenAPI generator returns (OpenAPI 3.1, paths relative to
+ * the base path).
+ */
+export interface IBetterAuthOpenApiDocument {
+  components?: { schemas?: Record<string, unknown> };
+  paths: Record<string, Record<string, unknown>>;
+}
+
+/** Whether a path relative to the base path is handled by `CoreBetterAuthController`. */
+export function isControllerHandledPath(relativePath: string): boolean {
+  return CONTROLLER_HANDLED_PATHS.some((path) => relativePath === path || relativePath.startsWith(`${path}/`));
+}
+
+/** Whether a path relative to the base path belongs to Better-Auth's `openAPI()` plugin. */
+export function isBetterAuthOpenApiPath(relativePath: string): boolean {
+  return relativePath === BETTER_AUTH_OPEN_API_PATH || relativePath.startsWith(`${BETTER_AUTH_OPEN_API_PATH}/`);
+}
+
+/**
+ * Whether the project registered `openAPI()` itself in `betterAuth.plugins`. Then its routes are the
+ * project's decision and stay reachable; otherwise nest-server registers the plugin only to feed the
+ * Swagger document, with its endpoints kept off the router (`serverOnlyPlugin()` in better-auth.config.ts).
+ */
+export function projectProvidesOpenApiPlugin(config: IBetterAuth | null | undefined): boolean {
+  return !!config?.plugins?.some(
+    (plugin) => (plugin as { id?: unknown } | null)?.id === BETTER_AUTH_OPEN_API_PLUGIN_ID,
+  );
+}
+
+/**
+ * The parts of a running Better-Auth instance (`await auth.$context`) that decide whether a route it
+ * serves can succeed. Typed loosely on purpose: these are Better-Auth's resolved options, including
+ * whatever a project passed through `betterAuth.options` or added as a plugin.
+ */
+export interface IBetterAuthRuntime {
+  options?: {
+    account?: { accountLinking?: { allowUnlinkingAll?: boolean } };
+    emailAndPassword?: { disableSignUp?: boolean; enabled?: boolean; sendResetPassword?: unknown };
+    emailVerification?: { sendVerificationEmail?: unknown };
+    plugins?: {
+      id?: string;
+      options?: Record<string, any>;
+      schema?: { session?: { fields?: Record<string, { input?: boolean }> } };
+    }[];
+    session?: { additionalFields?: Record<string, { input?: boolean }>; deferSessionRefresh?: boolean };
+    user?: { changeEmail?: { enabled?: boolean }; deleteUser?: { enabled?: boolean } };
+  };
+  socialProviders?: unknown[];
+}
+
+/**
+ * Operations Better-Auth serves but answers with an error for EVERY caller under the running
+ * configuration. Better-Auth's OpenAPI generator lists each registered endpoint regardless of the options
+ * it checks at request time, so `CoreBetterAuthService` removes these from the description it hands to
+ * `setupSwagger()`. Keys: `/path` (every method) or `<method> /path`.
+ *
+ * Each row mirrors a check in better-auth's own source (1.7.7, `dist/…`), pinned by
+ * `tests/unit/better-auth-openapi-availability.spec.ts`:
+ *
+ * | Unavailable | Unless | Better-Auth answers |
+ * |---|---|---|
+ * | `post /get-session` | `session.deferSessionRefresh` | 405 `METHOD_NOT_ALLOWED_DEFER_SESSION_REQUIRED` (api/routes/session.mjs) |
+ * | update-session | a session field accepts input (`session.additionalFields` or a plugin's session schema) | "No fields to update" (update-session.mjs) |
+ * | social sign-in, callback, link, provider tokens | a social provider is configured | `PROVIDER_NOT_FOUND` / "Provider … is not supported" (sign-in, callback, account.mjs) |
+ * | unlink-account | a social provider, or `account.accountLinking.allowUnlinkingAll` | `FAILED_TO_UNLINK_LAST_ACCOUNT` — without a provider a user has one account (account.mjs) |
+ * | send-verification-email, verify-email | `emailVerification.sendVerificationEmail` | "Verification email isn't enabled" (email-verification.mjs) |
+ * | request + reset password | `emailAndPassword.sendResetPassword` | `RESET_PASSWORD_DISABLED` (password.mjs) |
+ * | sign-in + sign-up with email | `emailAndPassword.enabled` | `EMAIL_PASSWORD_DISABLED` (sign-in.mjs, sign-up.mjs). Not change/verify password: Better-Auth does not check `enabled` there |
+ * | `/sign-up/email` | not `emailAndPassword.disableSignUp` | "Email and password sign up is not enabled" (sign-up.mjs) |
+ * | delete-user (+ callback) | `user.deleteUser.enabled` | error (update-user.mjs) |
+ * | change-email | `user.changeEmail.enabled` | `CHANGE_EMAIL_DISABLED` (update-user.mjs) |
+ * | two-factor OTP send/verify | the two-factor plugin's `otpOptions.sendOTP` | `OTP_NOT_CONFIGURED` (plugins/two-factor) |
+ * | two-factor TOTP uri/verify | not the two-factor plugin's `totpOptions.disable` | `TOTP_NOT_CONFIGURED` (plugins/two-factor) |
+ *
+ * Add a row when an upgrade of better-auth introduces a new option-dependent refusal.
+ */
+export function unavailableBetterAuthOperations(runtime: IBetterAuthRuntime | null | undefined): Set<string> {
+  const options = runtime?.options ?? {};
+  const unavailable = new Set<string>();
+  const add = (...keys: string[]) => keys.forEach((key) => unavailable.add(key));
+
+  if (!options.session?.deferSessionRefresh) {
+    add('post /get-session');
+  }
+  const acceptsInput = (fields: Record<string, { input?: boolean }> | undefined) =>
+    Object.values(fields ?? {}).some((field) => field?.input !== false);
+  if (
+    !acceptsInput(options.session?.additionalFields) &&
+    !options.plugins?.some((plugin) => acceptsInput(plugin?.schema?.session?.fields))
+  ) {
+    add('/update-session');
+  }
+  if (!runtime?.socialProviders?.length) {
+    add('/sign-in/social', '/callback/{id}', '/link-social', '/refresh-token', '/get-access-token', '/account-info');
+    if (!options.account?.accountLinking?.allowUnlinkingAll) {
+      add('/unlink-account');
+    }
+  }
+  if (!options.emailVerification?.sendVerificationEmail) {
+    add('/send-verification-email', '/verify-email');
+  }
+  if (!options.emailAndPassword?.sendResetPassword) {
+    add('/request-password-reset', '/reset-password', '/reset-password/{token}');
+  }
+  if (!options.emailAndPassword?.enabled) {
+    add('/sign-in/email', '/sign-up/email');
+  }
+  if (options.emailAndPassword?.disableSignUp) {
+    add('/sign-up/email');
+  }
+  if (!options.user?.deleteUser?.enabled) {
+    add('/delete-user', '/delete-user/callback');
+  }
+  if (!options.user?.changeEmail?.enabled) {
+    add('/change-email');
+  }
+  const twoFactor = options.plugins?.find((plugin) => plugin?.id === 'two-factor');
+  if (twoFactor) {
+    if (!twoFactor.options?.otpOptions?.sendOTP) {
+      add('/two-factor/send-otp', '/two-factor/verify-otp');
+    }
+    if (twoFactor.options?.totpOptions?.disable) {
+      add('/two-factor/get-totp-uri', '/two-factor/verify-totp');
+    }
+  }
+  return unavailable;
+}
+
+/** Whether an operation is listed by `unavailableBetterAuthOperations()` (or `switchedOffBetterAuthPaths()`). */
+export function isUnavailableOperation(unavailable: Set<string>, method: string, relativePath: string): boolean {
+  return unavailable.has(relativePath) || unavailable.has(`${method.toLowerCase()} ${relativePath}`);
+}
+
+/**
+ * Paths (relative to the base path) the configuration switches off for every caller. Documented, they
+ * could only ever answer an error, so the Swagger document leaves them out — explicit controller routes
+ * and generated ones alike. Each rule mirrors the switch it reads:
+ *
+ * | Configuration | Paths | Why they cannot succeed |
+ * |---|---|---|
+ * | `emailAndPassword.enabled: false` | sign-in + sign-up with email | `EMAIL_PASSWORD_DISABLED` (the only routes Better-Auth checks it on) |
+ * | `emailAndPassword.disableSignUp: true` | `/sign-up/email` | `SIGNUP_DISABLED` (`isSignUpEnabled()`) |
+ * | `emailAndPassword.passwordReset: false` | request + reset | no reset hook, so no token can be minted |
+ */
+export function switchedOffBetterAuthPaths(config: IBetterAuth | null | undefined): Set<string> {
+  const emailAndPassword = config?.emailAndPassword;
+  const paths = new Set<string>();
+  if (emailAndPassword?.enabled === false) {
+    // Better-Auth checks `enabled` in sign-in and sign-up only; password change/verify/reset keep
+    // working for accounts that have a password.
+    paths.add('/sign-in/email');
+    paths.add('/sign-up/email');
+  }
+  if (emailAndPassword?.disableSignUp === true) {
+    paths.add('/sign-up/email');
+  }
+  if (emailAndPassword?.passwordReset === false) {
+    for (const path of ['/request-password-reset', '/reset-password', '/reset-password/{token}']) {
+      paths.add(path);
+    }
+  }
+  return paths;
+}

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

@@ -753,6 +753,7 @@ export class CoreBetterAuthController {
    * @see README.md "Architecture: Why Custom Controllers?"
    */
   @All('*path')
+  @ApiExcludeEndpoint() // A pass-through to Better-Auth: one `/iam/{path}` per HTTP method, with nothing to document
   @Roles(RoleEnum.S_EVERYONE)
   async handlePluginRoutes(@Req() req: Request, @Res() res: Response): Promise<void> {
     return this.handleBetterAuthPlugins(req, res);