@bymax-one/nest-core 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -11,6 +11,46 @@ heading here.
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-08-15
+
+An OpenAPI document could stop requiring credentials without anything saying
+so. Deleting a document-level `security` default — typically alongside the
+per-operation entries a library has taken over describing — leaves every route
+the backend itself owns with no requirement from any source, and the document
+stays valid, no requirement dangles, and the runtime still answers `401`. The
+only observable change is that a client generated from the document stops
+sending credentials.
+
+**Apply to a derived backend:** bump the dependency. No code change is needed.
+If the boot log now names operations, they are the ones a generated client will
+call without credentials — set `openapi.security`, or mark each public with an
+explicit `[]` in `openapi.operationSecurity`.
+
+### Added
+
+- **The document build warns when an operation ends up requiring no credential
+  at all.** Deleting a document-level `security` default — typically alongside
+  the per-operation entries a library has taken over describing — leaves every
+  route the backend itself owns with no requirement from any source. Nothing
+  catches it today: the document is valid, no requirement dangles so
+  `assertSchemesDeclared` is satisfied, the runtime still answers `401` so a
+  status-code probe finds nothing, and a consumer's document test stays green if
+  it asserts only the operations it enumerated. The only observable change is
+  that a client generated from the document sends no credentials.
+  `applyBymaxOpenApi` now emits one warning per build naming the affected
+  operations, capped at ten with a count of the rest.
+
+  It warns and never throws — an API that is public on purpose is legitimate —
+  and the trigger is narrow so the line stays worth reading: only when the
+  document declares no top-level `security`, **and** at least one other
+  operation does state a requirement, **and** the operation is not one of the
+  three this package registers. An explicit `[]` — from `operationSecurity`, a
+  decorator, or a library's fragment — states the intent and stops the report.
+  The known limit is documented rather than closed: a document with nothing
+  explicit anywhere is indistinguishable from an API that is public on purpose,
+  so removing _every_ requirement at once is not warned. Render the document
+  with and without your libraries and diff the operations you mount.
+
 ## [1.4.0] - 2026-08-13
 
 HTTP metrics were blind to every request that did not reach a handler. Nest runs
@@ -649,4 +689,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.2.1]: https://github.com/bymaxone/nest-core/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/bymaxone/nest-core/compare/v1.1.1...v1.2.0
 [1.4.0]: https://github.com/bymaxone/nest-core/compare/v1.3.2...v1.4.0
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.4.0...HEAD
+[1.5.0]: https://github.com/bymaxone/nest-core/compare/v1.4.0...v1.5.0
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.0...HEAD

package/README.md

@@ -379,6 +379,56 @@ configuration went wrong. If you gate the document behind an environment flag,
 make sure at least one environment that runs your tests has it on, or these
 checks never fire.
 
+#### When an operation ends up requiring nothing
+
+The checks above catch a requirement that points at nothing. The opposite
+mistake — an operation that ends up pointing at _no requirement at all_ — breaks
+nothing, and that is what makes it dangerous. It is a valid document. No name
+dangles. The runtime still answers `401`. A document test that asserts only the
+operations you enumerated stays green. The only thing that changed is that a
+client generated from the document now sends no credentials.
+
+The edit that produces it is ordinary: a library starts describing its own
+routes, its adoption note tells you to delete the entries you had written for
+them, and the document-level `security` default is sitting in the same options
+block and goes with them. Every route _you_ own then reads as public.
+
+So the document build says so, once, naming the operations:
+
+```
+[BymaxCoreModule] a client generated from the OpenAPI document will send no
+credentials to 2 operation(s): GET /examples, POST /orders. They state no
+security requirement, the document declares no default, and other operations in
+it do state one — so this is more often a missing openapi.security default than
+a public API. Set openapi.security, or state the intent per operation with an
+explicit [] in openapi.operationSecurity.
+```
+
+It is a **warning, not a failure**: an API that is public on purpose is a
+legitimate configuration, and failing a boot over one would be worse than the
+silence it replaces. The trigger is deliberately narrow, so the line stays worth
+reading:
+
+| Condition                                               | Why                                                                                                                    |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| The document declares no top-level `security`           | With a default present, a bare operation inherits it. An explicit `security: []` counts as an answer, not an omission. |
+| At least one other operation _does_ state a requirement | Somebody described a posture on purpose, so the bare ones beside it are an omission rather than a public API.          |
+| The operation is not one of this package's own          | A health probe carrying nothing is the correct description of a route an orchestrator polls without a credential.      |
+
+The escape hatch is to say what you mean, in the document's own vocabulary
+rather than by silencing output: `operationSecurity: { 'GET /examples': [] }`
+marks the operation public, and it stops being reported. A library can do the
+same for its own routes by contributing `security: []` in its fragment.
+
+**And there is one shape nothing can warn you about, so the diff is the only
+check that covers it.** If you remove _every_ requirement at once — no library
+describing anything, no decorator, no override, no document default — what
+remains is indistinguishable from the document of an API that is public on
+purpose. Both are a set of operations that ask for nothing. No tool can separate
+the two without also shouting at every genuinely public API, which is how a
+warning earns the right to be ignored. Render the document twice and compare; it
+is the one step that does not depend on somebody having anticipated your case.
+
 ## 🔑 DI Tokens
 
 Every token is a `Symbol`. `BYMAX_CORRELATION_PROVIDER` and

package/dist/openapi/index.cjs

@@ -131,6 +131,34 @@ function collectContributions(discovery, reflector, handlers) {
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_METRICS_PATH = "metrics";
 
+// src/openapi/openapi.routes.ts
+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 isOwnRoute(path, method, routes) {
+  return method === "get" && (routes.isHealth(path) || routes.isMetrics(path));
+}
+
 // src/envelope/error-codes.ts
 var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
 var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
@@ -329,29 +357,6 @@ function mergeResponses(existing, additions) {
   }
   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]) => {
@@ -435,6 +440,25 @@ function augmentOperation(operation, path, method, options, routes, contribution
   }
   return result;
 }
+function consumerOperations(paths, routes) {
+  return Object.entries(paths).flatMap(
+    ([path, item]) => operationsOf(item).filter(([method]) => !isOwnRoute(path, method, routes)).map(([method, operation]) => ({
+      key: operationKey(method, path),
+      operation: asRecord(operation)
+    }))
+  );
+}
+function unsecuredOperations(document, options, pathPrefixes = [""]) {
+  if (document.security !== void 0) {
+    return [];
+  }
+  const routes = indexOwnRoutes(options, pathPrefixes);
+  const candidates = consumerOperations(asRecord(document.paths), routes);
+  if (!candidates.some(({ operation }) => operation["security"] !== void 0)) {
+    return [];
+  }
+  return candidates.filter(({ operation }) => operation["security"] === void 0).map(({ key }) => key);
+}
 function assertSchemesDeclared(openapi, schemes) {
   const required = [...openapi.security, ...Object.values(openapi.operationSecurity).flat()];
   const named = [...new Set(required.flatMap((requirement) => Object.keys(requirement)))];
@@ -549,6 +573,7 @@ async function loadSwagger() {
 }
 
 // src/openapi/openapi.bootstrap.ts
+var MAX_WARNED_OPERATIONS = 10;
 var OPTIONS_UNRESOLVED_MESSAGE = "[BymaxCoreModule] applyBymaxOpenApi could not resolve BYMAX_CORE_OPTIONS from the application. Register BymaxCoreModule (forRoot or forRootAsync) before calling it, and keep the module global or import it into the module you bootstrap.";
 function resolveCoreOptions(app) {
   try {
@@ -607,6 +632,16 @@ function readContributions(app, handlers) {
   }
   return collectContributions(discovery, reflector, handlers);
 }
+function warnUnsecuredOperations(logger, keys) {
+  if (keys.length === 0) {
+    return;
+  }
+  const elided = keys.length - MAX_WARNED_OPERATIONS;
+  const listed = keys.slice(0, MAX_WARNED_OPERATIONS).join(", ");
+  logger.warn(
+    `a client generated from the OpenAPI document will send no credentials to ${keys.length} operation(s): ${listed}${elided > 0 ? `, and ${elided} more` : ""}. They state no security requirement, the document declares no default, and other operations in it do state one \u2014 so this is more often a missing openapi.security default than a public API. Set openapi.security, or state the intent per operation with an explicit [] in openapi.operationSecurity.`
+  );
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -635,12 +670,9 @@ async function applyBymaxOpenApi(app) {
   const generated = swagger.SwaggerModule.createDocument(app, config, {
     operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
   });
-  const document = augmentDocument(
-    generated,
-    resolved,
-    readPathPrefixes(app),
-    readContributions(app, handlers)
-  );
+  const prefixes = readPathPrefixes(app);
+  const document = augmentDocument(generated, resolved, prefixes, readContributions(app, handlers));
+  warnUnsecuredOperations(logger, unsecuredOperations(document, resolved, prefixes));
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
   });

package/dist/openapi/index.mjs

@@ -129,6 +129,34 @@ function collectContributions(discovery, reflector, handlers) {
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_METRICS_PATH = "metrics";
 
+// src/openapi/openapi.routes.ts
+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 isOwnRoute(path, method, routes) {
+  return method === "get" && (routes.isHealth(path) || routes.isMetrics(path));
+}
+
 // src/envelope/error-codes.ts
 var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
 var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
@@ -327,29 +355,6 @@ function mergeResponses(existing, additions) {
   }
   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]) => {
@@ -433,6 +438,25 @@ function augmentOperation(operation, path, method, options, routes, contribution
   }
   return result;
 }
+function consumerOperations(paths, routes) {
+  return Object.entries(paths).flatMap(
+    ([path, item]) => operationsOf(item).filter(([method]) => !isOwnRoute(path, method, routes)).map(([method, operation]) => ({
+      key: operationKey(method, path),
+      operation: asRecord(operation)
+    }))
+  );
+}
+function unsecuredOperations(document, options, pathPrefixes = [""]) {
+  if (document.security !== void 0) {
+    return [];
+  }
+  const routes = indexOwnRoutes(options, pathPrefixes);
+  const candidates = consumerOperations(asRecord(document.paths), routes);
+  if (!candidates.some(({ operation }) => operation["security"] !== void 0)) {
+    return [];
+  }
+  return candidates.filter(({ operation }) => operation["security"] === void 0).map(({ key }) => key);
+}
 function assertSchemesDeclared(openapi, schemes) {
   const required = [...openapi.security, ...Object.values(openapi.operationSecurity).flat()];
   const named = [...new Set(required.flatMap((requirement) => Object.keys(requirement)))];
@@ -547,6 +571,7 @@ async function loadSwagger() {
 }
 
 // src/openapi/openapi.bootstrap.ts
+var MAX_WARNED_OPERATIONS = 10;
 var OPTIONS_UNRESOLVED_MESSAGE = "[BymaxCoreModule] applyBymaxOpenApi could not resolve BYMAX_CORE_OPTIONS from the application. Register BymaxCoreModule (forRoot or forRootAsync) before calling it, and keep the module global or import it into the module you bootstrap.";
 function resolveCoreOptions(app) {
   try {
@@ -605,6 +630,16 @@ function readContributions(app, handlers) {
   }
   return collectContributions(discovery, reflector, handlers);
 }
+function warnUnsecuredOperations(logger, keys) {
+  if (keys.length === 0) {
+    return;
+  }
+  const elided = keys.length - MAX_WARNED_OPERATIONS;
+  const listed = keys.slice(0, MAX_WARNED_OPERATIONS).join(", ");
+  logger.warn(
+    `a client generated from the OpenAPI document will send no credentials to ${keys.length} operation(s): ${listed}${elided > 0 ? `, and ${elided} more` : ""}. They state no security requirement, the document declares no default, and other operations in it do state one \u2014 so this is more often a missing openapi.security default than a public API. Set openapi.security, or state the intent per operation with an explicit [] in openapi.operationSecurity.`
+  );
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -633,12 +668,9 @@ async function applyBymaxOpenApi(app) {
   const generated = swagger.SwaggerModule.createDocument(app, config, {
     operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
   });
-  const document = augmentDocument(
-    generated,
-    resolved,
-    readPathPrefixes(app),
-    readContributions(app, handlers)
-  );
+  const prefixes = readPathPrefixes(app);
+  const document = augmentDocument(generated, resolved, prefixes, readContributions(app, handlers));
+  warnUnsecuredOperations(logger, unsecuredOperations(document, resolved, prefixes));
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",