@bymax-one/nest-core 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -11,6 +11,91 @@ heading here.
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-08-15
+
+Documentation only; no source change. The 1.5.0 warning's known-limit note told
+readers that no tool could catch the one shape the warning cannot report, and
+that rendering the document twice was therefore the only check. That is true
+only of something reading the rendered document alone — a consumer's own suite
+knows the intent and can assert it on every commit — so the note was arguing
+against the better practice.
+
+**Apply to a derived backend:** nothing to change in code. Read the revised
+"Documenting authentication" section and write the assertion it now shows; it
+costs one test and replaces a manual step nobody remembers to run.
+
+### Documentation
+
+- **The credential-free warning's known limit no longer argues against the
+  practice that covers it.** The README said no tool could distinguish a
+  document that lost its requirements from one that never had any, and that
+  rendering the document twice was therefore the only check. The first half is
+  true only of something reading the rendered document alone; a consumer's own
+  suite knows which of the two it is and can assert it on every commit. Saying
+  otherwise did not merely overstate a limit — it told readers that the standing
+  check they should write does not exist. The section now attributes the limit
+  correctly, states why the warning cannot fire on that shape (it follows from
+  the trigger, in every version), gives the assertion as the practice, and
+  leaves render-and-diff the narrower job it is genuinely good at: seeing what
+  moved when you change something, so you can turn it into an assertion.
+
+- **A contributed scheme's presence is documented as part of the contributor's
+  configuration.** Which security schemes a library contributes can depend on
+  how that library is configured — the names are stable, their presence is not.
+  A document-level default must therefore be derived from the same configuration
+  the contributor reads. A literal is correct only for the configuration it was
+  written against: elsewhere it either resolves while describing one of two
+  credentials a route accepts (quietly incomplete) or names a scheme nobody
+  declares (a failed document build). Guarding on whether the scheme exists
+  clears the loud case and ships the quiet one.
+
+- **What a document-level default does not let you say** is now stated. Its
+  entries are alternatives applied to every operation that says nothing, so a
+  backend with two credential families _can_ list both and nothing rejects it —
+  the result asserts that either credential works for every inheriting route,
+  which is false in the permissive direction. The minority family belongs in
+  `openapi.operationSecurity`, which outranks the default.
+
+## [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 +734,6 @@ 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
+[1.5.1]: https://github.com/bymaxone/nest-core/compare/v1.5.0...v1.5.1
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.1...HEAD

package/README.md

@@ -379,6 +379,126 @@ 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.
+
+**There is one shape this warning cannot report.** If you remove _every_
+requirement at once — no library describing anything, no decorator, no override,
+no document default — the second condition above is never met: nothing states a
+requirement, so there are no bare operations sitting _beside_ described ones.
+That follows from the trigger and therefore holds in every version; it is not a
+gap a later release closes, and a reader who expects one is exactly the reader
+who stops checking.
+
+The limit belongs to **anything reading only the rendered document**. Such a
+document is indistinguishable from that of an API which is public on purpose —
+both are a set of operations asking for nothing — and this package cannot tell
+them apart without also warning at every genuinely public API, which is how a
+warning earns the right to be ignored.
+
+**Your own suite has no such handicap, because you know which one you are.**
+Assert it, and the check runs on every commit rather than when somebody
+remembers to look:
+
+```ts
+it('still requires a credential everywhere it should', () => {
+  const document = buildYourDocument()
+
+  // Assert the default you expect, not merely that one exists. `[]` is a
+  // defined value that requires nothing, so a "toBeDefined" check passes for
+  // a default that degraded to empty — which is the regression this test is
+  // here to catch, wearing the shape of a pass.
+  expect(document.security).toEqual([{ cookieAuth: [] }])
+
+  // An explicit `[]` is how an operation says "public". The set of operations
+  // saying it should be the set you meant — no more, no fewer.
+  expect(publicOperationsOf(document)).toEqual(['POST /auth/login'])
+})
+```
+
+Render-and-diff keeps a narrower job, and it is a good one: when you are
+_changing_ something — adopting a library that describes its own routes, moving
+a default — render with and without the change and compare the operations you
+mount. It shows you what moved without your having to predict it. Then turn what
+it showed you into an assertion, so the next change is caught rather than
+inspected.
+
+#### A contributed scheme's presence is part of the contributor's configuration
+
+A library contributes security schemes, and **which** ones it contributes can
+depend on how you configured it. Any of them, gated on any of its inputs, and
+often on more than one — the scheme you have in mind may be the absent one, and
+the setting you are thinking of may not be the only gate. The names are stable;
+their presence is not.
+
+That has one consequence worth stating as a rule, because getting it wrong
+produces a failure at either end of the loudness scale:
+
+> Derive a document-level default from **the same configuration the contributor
+> reads**, never from the scheme names, and never from what the document
+> happened to contain before you adopted the library.
+
+Writing the name as a literal is correct only for the configuration you wrote it
+against. Under a configuration that declares that scheme plus another, the
+default still resolves but describes one of two credentials the route accepts —
+**quietly incomplete**. Under one that declares it not at all, the name resolves
+to nothing and the document build **fails** with the undeclared-scheme error
+above. Guarding on whether the scheme exists is the tempting fix and it is the
+wrong one: it clears the case that already announced itself and ships the one
+that does not.
+
+Note what a document-level default does not let you _say_. Its entries are
+**alternatives** — any one of them satisfies an operation — and they apply to
+every operation that states nothing. So a backend whose routes sit behind **two
+different credential families** can certainly list both, and nothing rejects it:
+the result is a document asserting that _either_ credential works for _every_
+inheriting route. That is not an incomplete document, it is a false one, and it
+is false in the permissive direction — it tells a client that a credential the
+route will reject is one the route accepts.
+
+Give the majority family the default and the minority explicit
+`operationSecurity` entries. Those outrank the default, and an operation
+carrying one is never named by the warning above, because it states a
+requirement.
+
 ## 🔑 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.1",
   "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",