@bymax-one/nest-core 1.3.1 → 1.3.2

package/dist/index.d.ts

@@ -68,6 +68,44 @@ interface OpenApiServerDescriptor {
  * so the consumer's declaration reaches the UI unchanged.
  */
 type OpenApiSecurityScheme = Readonly<Record<string, unknown>>;
+/**
+ * One security requirement: scheme name to the scopes it needs, empty for a
+ * scheme that takes none. An operation's requirements are alternatives — any
+ * one of them satisfies it — so an empty *array* of requirements means the
+ * operation needs no authentication at all, which is how the specification
+ * expresses a public route that overrides a document-level default.
+ */
+type OpenApiSecurityRequirement = Readonly<Record<string, readonly string[]>>;
+/** The HTTP methods an OpenAPI path item can carry an operation under. */
+type OpenApiHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
+/**
+ * Addresses one operation in the generated document, as `"<METHOD> <path>"`.
+ *
+ * This format is a documented contract, not an implementation detail: a sibling
+ * library may ship a plain-data map of its own operations keyed this way, so a
+ * consumer spreads it into {@link OpenApiOptions.operationSecurity} instead of
+ * restating which of that library's routes are public. Import the type to get
+ * that map checked at the library's own compile time.
+ *
+ * The method is uppercase, one space separates the two parts, and the path is
+ * written **exactly as it appears in the generated document**: leading slash,
+ * OpenAPI template braces (`/users/{id}`), no trailing slash, and including any
+ * global prefix the application sets. That last part is the one that surprises:
+ * `@nestjs/swagger` includes `app.setGlobalPrefix('api')` in the documented
+ * paths, so the key is `'POST /api/auth/login'` in an application that sets one.
+ * A library shipping such a map should therefore expose a *function* taking the
+ * prefix rather than a frozen constant — the call site is the only place that
+ * knows it.
+ *
+ * @example 'GET /users/{id}'
+ * @example 'POST /api/auth/login'
+ */
+type OpenApiOperationKey = `${OpenApiHttpMethod} /${string}`;
+/**
+ * Per-operation security requirements, keyed by {@link OpenApiOperationKey}.
+ * An empty array marks the operation public, overriding any document default.
+ */
+type OperationSecurityMap = Readonly<Record<OpenApiOperationKey, readonly OpenApiSecurityRequirement[]>>;
 /**
  * OpenAPI document configuration.
  *
@@ -96,10 +134,53 @@ interface OpenApiOptions {
     servers?: readonly OpenApiServerDescriptor[];
     /** Security schemes added to the document's components. Default: `{}`. */
     securitySchemes?: Readonly<Record<string, OpenApiSecurityScheme>>;
+    /**
+     * The requirement every operation carries unless it says otherwise, naming
+     * schemes declared in {@link OpenApiOptions.securitySchemes}. Default: `[]`,
+     * which documents nothing and leaves every operation as it was generated.
+     *
+     * Set this when most of the API is authenticated, and mark the exceptions
+     * public through {@link OpenApiOptions.operationSecurity}. An operation that
+     * already declares its own requirement is never overwritten.
+     *
+     * @example [{ cookieAuth: [] }]
+     */
+    security?: readonly OpenApiSecurityRequirement[];
+    /**
+     * Per-operation overrides of {@link OpenApiOptions.security}, keyed by
+     * {@link OpenApiOperationKey}. An empty array marks that operation public.
+     * Default: `{}`.
+     *
+     * A key matching no operation in the generated document is a configuration
+     * error and fails the document build, naming the keys that do exist. Silence
+     * would be worse: a route renamed out from under a stale key would quietly
+     * inherit the document default and be documented as authenticated when it is
+     * not, or the reverse.
+     *
+     * That check runs only when the document is built. With
+     * {@link OpenApiOptions.enabled} false, or in a production runtime where the
+     * feature is forced off, a stale key is not reported — refusing to boot a
+     * service over a documentation setting it never serves would be the wrong
+     * trade. The cost is that the error waits for an environment that has the
+     * document switched on.
+     *
+     * @example
+     *   {
+     *     'POST /auth/login': [],
+     *     'POST /auth/refresh': [{ refreshCookie: [] }]
+     *   }
+     */
+    operationSecurity?: OperationSecurityMap;
     /**
      * Contribute the schemas this package owns — the error envelope, the health
-     * response, and the pagination shapes — to the document's components.
-     * Default: `true`.
+     * response, and the pagination shapes — to the document's components, and
+     * reference them from the operations that return them: the error envelope as
+     * every operation's `default` response, and the health response on the health
+     * endpoints this package registers. Default: `true`.
+     *
+     * The two halves are one switch because they are one decision. Referencing a
+     * schema this package did not contribute would leave a dangling `$ref`, and a
+     * document that resolves nowhere is worse than one that says less.
      */
     includeCoreSchemas?: boolean;
 }
@@ -221,6 +302,8 @@ interface ResolvedOpenApiOptions {
     version: string;
     servers: readonly OpenApiServerDescriptor[];
     securitySchemes: Readonly<Record<string, OpenApiSecurityScheme>>;
+    security: readonly OpenApiSecurityRequirement[];
+    operationSecurity: OperationSecurityMap;
     includeCoreSchemas: boolean;
 }
 /**
@@ -824,4 +907,4 @@ declare const BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
  */
 declare function codeForStatus(status: number): string;
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiOptions, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, buildErrorEnvelope, codeForStatus };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, buildErrorEnvelope, codeForStatus };

package/dist/index.mjs

@@ -15,6 +15,10 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 
+// src/route-defaults.ts
+var DEFAULT_HEALTH_PATH = "health";
+var DEFAULT_METRICS_PATH = "metrics";
+
 // src/runtime.environment.ts
 var NON_PRODUCTION_ENVIRONMENTS = /* @__PURE__ */ new Set(["development", "test"]);
 function isProductionRuntime(value = process.env["NODE_ENV"]) {
@@ -25,9 +29,7 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
 }
 
 // src/core.options.ts
-var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
-var DEFAULT_METRICS_PATH = "metrics";
 var DEFAULT_OPENAPI_PATH = "docs";
 var DEFAULT_OPENAPI_JSON_PATH = "docs-json";
 var DEFAULT_OPENAPI_TITLE = "API";
@@ -103,6 +105,11 @@ function resolveOpenApi(raw) {
     // consumer-owned nested objects, and the deep-freeze below would otherwise
     // reach into them.
     securitySchemes: structuredClone(raw?.securitySchemes ?? {}),
+    // Cloned for the same reason as the schemes above: both are consumer-owned
+    // nested structures, and the deep-freeze applied to the snapshot would
+    // otherwise reach into objects the consumer still holds a reference to.
+    security: structuredClone(raw?.security ?? []),
+    operationSecurity: structuredClone(raw?.operationSecurity ?? {}),
     includeCoreSchemas: raw?.includeCoreSchemas ?? true
   };
 }

package/dist/openapi/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var common = require('@nestjs/common');
+var core = require('@nestjs/core');
 
 // src/openapi/openapi.bootstrap.ts
 
@@ -16,6 +17,10 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
 
+// src/route-defaults.ts
+var DEFAULT_HEALTH_PATH = "health";
+var DEFAULT_METRICS_PATH = "metrics";
+
 // src/envelope/error-codes.ts
 var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
 var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
@@ -177,6 +182,19 @@ var CORE_PARAMETERS = {
 };
 
 // src/openapi/openapi.document.ts
+var OPERATION_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+  "trace"
+];
+var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
+var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
+var HEALTH_RESPONSE_SCHEMA = "BymaxHealthResponse";
 function asRecord(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return {};
@@ -186,21 +204,192 @@ function asRecord(value) {
 function mergeAbsent(existing, additions) {
   return { ...additions, ...existing };
 }
-function augmentDocument(document, options) {
+function operationsOf(item) {
+  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
+}
+function mergeResponses(existing, additions) {
+  const merged = new Map(Object.entries(existing));
+  for (const [status, contributed] of Object.entries(additions)) {
+    const current = asRecord(merged.get(status));
+    if (current["content"] === void 0 && current["$ref"] === void 0) {
+      const described = current["description"] === void 0 || current["description"] === "" ? contributed["description"] : current["description"];
+      merged.set(status, { ...current, ...contributed, description: described });
+    }
+  }
+  return Object.fromEntries(merged);
+}
+function trimSlashes(segment) {
+  return segment.split("/").filter((part) => part !== "").join("/");
+}
+function routePath(prefix, suffix) {
+  return prefix === "" ? `/${suffix}` : `/${prefix}/${suffix}`;
+}
+function healthRoutes(options) {
+  const bases = /* @__PURE__ */ new Set([trimSlashes(options.health.path), DEFAULT_HEALTH_PATH]);
+  return [...bases].flatMap((base) => [`${base}/live`, `${base}/ready`]);
+}
+function metricsRoutes(options) {
+  return [.../* @__PURE__ */ new Set([trimSlashes(options.metrics.path), DEFAULT_METRICS_PATH])];
+}
+function indexOwnRoutes(options, prefixes) {
+  const normalized = prefixes.map(trimSlashes);
+  const expand = (suffixes) => normalized.flatMap((prefix) => suffixes.map((suffix) => routePath(prefix, suffix)));
+  const health = expand(healthRoutes(options));
+  const metrics = expand(metricsRoutes(options));
+  return {
+    isHealth: (path) => health.includes(path),
+    isMetrics: (path) => metrics.includes(path)
+  };
+}
+function withoutDisabledRoutes(paths, options, routes) {
+  const disabled = (path) => !options.health.enabled && routes.isHealth(path) || !options.metrics.enabled && routes.isMetrics(path);
+  const kept = Object.entries(paths).map(([path, item]) => {
+    if (!disabled(path)) {
+      return [path, item];
+    }
+    const remaining = Object.fromEntries(
+      Object.entries(asRecord(item)).filter(([key]) => key !== "get")
+    );
+    return [path, operationsOf(remaining).length === 0 ? void 0 : remaining];
+  });
+  return Object.fromEntries(kept.filter(([, item]) => item !== void 0));
+}
+function ownRouteSecurity(path, method, options, routes) {
+  if (method !== "get") {
+    return void 0;
+  }
+  if (options.metrics.authToken !== void 0 && routes.isMetrics(path)) {
+    return [{ [METRICS_SCHEME_NAME]: [] }];
+  }
+  if (options.openapi.security.length > 0 && routes.isHealth(path)) {
+    return [];
+  }
+  return void 0;
+}
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+function coreResponses(path, options, routes) {
+  const responses = {};
+  if (options.envelope.enabled) {
+    responses["default"] = {
+      description: "Error envelope returned by every failing request.",
+      content: {
+        "application/json": { schema: { $ref: `#/components/schemas/${ERROR_ENVELOPE_SCHEMA}` } }
+      }
+    };
+  }
+  if (routes.isHealth(path)) {
+    responses["200"] = {
+      description: "Aggregated health report.",
+      content: {
+        "application/json": { schema: { $ref: `#/components/schemas/${HEALTH_RESPONSE_SCHEMA}` } }
+      }
+    };
+  }
+  return responses;
+}
+function augmentOperation(operation, path, method, options, routes) {
+  const result = { ...operation };
+  if (result["security"] === void 0) {
+    const override = options.openapi.operationSecurity[operationKey(method, path)];
+    const security = override ?? ownRouteSecurity(path, method, options, routes);
+    if (security !== void 0) {
+      result["security"] = security;
+    }
+  }
+  if (options.openapi.includeCoreSchemas) {
+    result["responses"] = mergeResponses(
+      asRecord(result["responses"]),
+      coreResponses(path, options, routes)
+    );
+  }
+  return result;
+}
+function assertSchemesDeclared(openapi, schemes) {
+  const required = [...openapi.security, ...Object.values(openapi.operationSecurity).flat()];
+  const named = [...new Set(required.flatMap((requirement) => Object.keys(requirement)))];
+  const declared = Object.keys(schemes);
+  const missing = named.filter((name) => !declared.includes(name));
+  if (missing.length === 0) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] openapi security names ${missing.length} scheme(s) that the document does not define: ${missing.join(", ")}. Declare them in openapi.securitySchemes, or drop the requirement. The document defines: ${declared.length === 0 ? "(none)" : declared.join(", ")}.`
+  );
+}
+function assertScrapeSchemeIsOurs(openapi, components, contributes) {
+  if (!contributes) {
+    return;
+  }
+  const declaredByConsumer = Object.keys(openapi.securitySchemes).includes(METRICS_SCHEME_NAME);
+  const declaredByDocument = Object.keys(asRecord(components["securitySchemes"])).includes(
+    METRICS_SCHEME_NAME
+  );
+  if (!declaredByConsumer && !declaredByDocument) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] the security scheme "${METRICS_SCHEME_NAME}" is reserved: this package contributes it to document the bearer token the scrape endpoint checks, and it is already defined ${declaredByConsumer ? "in openapi.securitySchemes" : "by the generated document"}. Rename yours, or unset metrics.authToken if the endpoint is not protected.`
+  );
+}
+function documentedOperationKeys(paths) {
+  return Object.entries(paths).flatMap(
+    ([path, item]) => operationsOf(item).map(([method]) => operationKey(method, path))
+  );
+}
+function assertOverridesMatch(paths, openapi) {
+  const configured = Object.keys(openapi.operationSecurity);
+  const documented = documentedOperationKeys(paths);
+  const unmatched = configured.filter((key) => !documented.includes(key));
+  if (unmatched.length === 0) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] openapi.operationSecurity addresses ${unmatched.length} operation(s) that the document does not contain: ${unmatched.join(", ")}. Keys are "<METHOD> <path>" with the path exactly as documented, including any global prefix. The document contains: ${documented.length === 0 ? "(none)" : documented.join(", ")}.`
+  );
+}
+function augmentPaths(paths, options, routes) {
+  return Object.fromEntries(
+    Object.entries(paths).map(([path, item]) => {
+      const augmented = operationsOf(item).map(([method, operation]) => [
+        method,
+        augmentOperation(asRecord(operation), path, method, options, routes)
+      ]);
+      return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
+    })
+  );
+}
+function augmentDocument(document, options, pathPrefixes = [""]) {
+  const { openapi } = options;
   const components = asRecord(document.components);
   const merged = { ...components };
-  if (options.includeCoreSchemas) {
+  if (openapi.includeCoreSchemas) {
     merged["schemas"] = mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS);
     merged["parameters"] = mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS);
   }
-  const securitySchemeNames = Object.keys(options.securitySchemes);
-  if (securitySchemeNames.length > 0) {
-    merged["securitySchemes"] = mergeAbsent(
-      asRecord(components["securitySchemes"]),
-      options.securitySchemes
-    );
+  const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
+    [METRICS_SCHEME_NAME]: {
+      type: "http",
+      scheme: "bearer",
+      description: "Bearer token required by the metrics scrape endpoint."
+    }
+  };
+  assertScrapeSchemeIsOurs(openapi, components, options.metrics.authToken !== void 0);
+  const schemes = mergeAbsent(asRecord(components["securitySchemes"]), {
+    ...openapi.securitySchemes,
+    ...scrapeScheme
+  });
+  if (Object.keys(schemes).length > 0) {
+    merged["securitySchemes"] = schemes;
   }
-  return { ...document, components: merged };
+  assertSchemesDeclared(openapi, schemes);
+  const routes = indexOwnRoutes(options, pathPrefixes);
+  const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
+  assertOverridesMatch(served, openapi);
+  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes) };
+  const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
+  return { ...document, components: merged, ...paths, ...security };
 }
 
 // src/optional-peer.ts
@@ -234,6 +423,35 @@ function resolveCoreOptions(app) {
     throw new Error(OPTIONS_UNRESOLVED_MESSAGE, { cause });
   }
 }
+function readAppConfig(app) {
+  try {
+    return app.get(core.ApplicationConfig);
+  } catch {
+    return void 0;
+  }
+}
+function versionSegments(versioning) {
+  if (versioning === void 0 || versioning.type !== common.VersioningType.URI) {
+    return [""];
+  }
+  const prefix = versioning.prefix === false ? "" : versioning.prefix ?? "v";
+  const declared = versioning.defaultVersion;
+  if (declared === void 0) {
+    return [""];
+  }
+  const versions = Array.isArray(declared) ? declared : [declared];
+  return versions.map(
+    (version) => version === common.VERSION_NEUTRAL ? "" : `${prefix}${String(version)}`
+  );
+}
+function readPathPrefixes(app) {
+  const config = readAppConfig(app);
+  if (config === void 0) {
+    return [""];
+  }
+  const globalPrefix = config.getGlobalPrefix();
+  return versionSegments(config.getVersioning()).map((segment) => `${globalPrefix}/${segment}`);
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -243,7 +461,8 @@ function buildConfig(builder, options) {
 }
 async function applyBymaxOpenApi(app) {
   const logger = new common.Logger("BymaxCoreModule");
-  const options = resolveCoreOptions(app).openapi;
+  const resolved = resolveCoreOptions(app);
+  const options = resolved.openapi;
   if (isProductionRuntime()) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
@@ -257,7 +476,11 @@ async function applyBymaxOpenApi(app) {
   }
   const swagger = await loadSwagger();
   const config = buildConfig(new swagger.DocumentBuilder(), options);
-  const document = augmentDocument(swagger.SwaggerModule.createDocument(app, config), options);
+  const document = augmentDocument(
+    swagger.SwaggerModule.createDocument(app, config),
+    resolved,
+    readPathPrefixes(app)
+  );
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
   });

package/dist/openapi/index.d.cts

@@ -30,10 +30,20 @@ interface OpenApiMountOutcome {
  * It is safe to call unconditionally: with the feature disabled, or in
  * production, it mounts nothing, loads no optional peer, and returns why.
  *
+ * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
+ * dynamic `import()`, which is what keeps the peer optional for everyone who
+ * never enables the document — and Jest's module registry cannot service a
+ * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
+ * only the *enabled* path fails, with `dynamic import callback invoked without
+ * --experimental-vm-modules`; the disabled and production paths never reach the
+ * loader and pass either way, which is what makes the omission confusing.
+ *
  * @param app - The created Nest application, not yet listening.
  * @returns What happened: mounted, or skipped with a reason.
- * @throws Error When `BymaxCoreModule` is not registered, or when the feature is
- *   enabled and the optional peer `@nestjs/swagger` is not installed.
+ * @throws Error When `BymaxCoreModule` is not registered, when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
+ *   `openapi.operationSecurity` addresses an operation the generated document
+ *   does not contain.
  * @example
  *   const app = await NestFactory.create(AppModule)
  *   await applyBymaxOpenApi(app)

package/dist/openapi/index.d.ts

@@ -30,10 +30,20 @@ interface OpenApiMountOutcome {
  * It is safe to call unconditionally: with the feature disabled, or in
  * production, it mounts nothing, loads no optional peer, and returns why.
  *
+ * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
+ * dynamic `import()`, which is what keeps the peer optional for everyone who
+ * never enables the document — and Jest's module registry cannot service a
+ * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
+ * only the *enabled* path fails, with `dynamic import callback invoked without
+ * --experimental-vm-modules`; the disabled and production paths never reach the
+ * loader and pass either way, which is what makes the omission confusing.
+ *
  * @param app - The created Nest application, not yet listening.
  * @returns What happened: mounted, or skipped with a reason.
- * @throws Error When `BymaxCoreModule` is not registered, or when the feature is
- *   enabled and the optional peer `@nestjs/swagger` is not installed.
+ * @throws Error When `BymaxCoreModule` is not registered, when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
+ *   `openapi.operationSecurity` addresses an operation the generated document
+ *   does not contain.
  * @example
  *   const app = await NestFactory.create(AppModule)
  *   await applyBymaxOpenApi(app)