@bymax-one/nest-core 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -11,6 +11,93 @@ heading here.
 
 ## [Unreleased]
 
+## [1.5.2] - 2026-08-15
+
+The production guard read `NODE_ENV` and nothing else, and treated an unset
+variable as production. An application that validates its own `APP_ENV` and
+never sets `NODE_ENV` was therefore classified as production on evidence it
+never gave — the OpenAPI document was refused in a development deployment, with
+no way to answer back. Two independent consumers reported the same split.
+
+**Apply to a derived backend:** nothing to change. A deployment that sets
+`NODE_ENV` behaves exactly as before. If yours validates its own variable
+instead, pass it as `environment` and the document is served where that variable
+says `development` or `test`.
+
+### Added
+
+- **`environment`, for applications that validate their own environment
+  variable.** The production guard read `NODE_ENV` and nothing else, and treated
+  an unset variable as production. An application that parses an `APP_ENV`
+  through its config schema and never sets `NODE_ENV` was therefore classified
+  as production on evidence it never gave — the OpenAPI document was refused in
+  a development deployment, with no way to answer back. Two independent
+  consumers reported the same split between the library's view of the
+  environment and their own validated one.
+
+  A top-level `environment` option is now consulted **where the process declares
+  nothing**: `NODE_ENV` unset, or set to whitespace. `NODE_ENV` wins whenever it
+  says anything at all, so no configured value can make a runtime that named
+  itself production serve the document — asserted in both guards rather than in
+  one. The declaration enters the same fail-closed classification, so an
+  unrecognized name is production like any other: this is a second source for
+  the value, never a second set of rules.
+
+  The narrowing is stated rather than buried. Both guards previously classified
+  from the process alone; now, in the single case where the process says
+  nothing, the snapshot a consumer bound decides the answer, because there is
+  nothing else to decide it with. Replacing a guess with a declaration is not an
+  override, but it is a real change to what the second guard depends on.
+
+  **Apply to a derived backend:** nothing to change. The option is optional and
+  every existing classification is unchanged — a deployment that sets `NODE_ENV`
+  behaves exactly as before.
+
+## [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
@@ -690,4 +777,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [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
 [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
+[1.5.1]: https://github.com/bymaxone/nest-core/compare/v1.5.0...v1.5.1
+[1.5.2]: https://github.com/bymaxone/nest-core/compare/v1.5.1...v1.5.2
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.2...HEAD

package/README.md

@@ -202,6 +202,20 @@ BymaxCoreModule.forRoot({ isGlobal: false })
 Every block is optional; an omitted block, or an omitted field within it,
 falls back to the documented default. Pass only what you want to change.
 
+### `environment`
+
+The one top-level option rather than a block, because it describes the
+deployment rather than a feature.
+
+| Option        | Type     | Default | Description                                                                           |
+| ------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
+| `environment` | `string` | unset   | The environment this deployment runs in, read only where `NODE_ENV` declares nothing. |
+
+Set it when your application validates its own environment variable and does not
+also set `NODE_ENV`. `NODE_ENV` wins whenever it says anything, so this can never
+serve the OpenAPI document in a runtime that named itself production. Full rules
+and the classification table: [Production is a closed door](#production-is-a-closed-door).
+
 ### `envelope`
 
 | Option            | Type      | Default | Description                                                                                    |
@@ -420,14 +434,84 @@ 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.
+**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
 
@@ -889,16 +973,61 @@ can emit it once and never branch:
 ### Production is a closed door
 
 `NODE_ENV` decides, and the decision is fail-closed: only `development` and
-`test` are non-production. Any other value — including an unset variable —
-is production, and in production the document is never built and never mounted,
-whatever the configuration says. The guard runs twice, independently: the option
-resolver forces the feature off, and the bootstrap helper refuses again without
-trusting that resolution. There is no override.
+`test` are non-production. Any other value is production, and in production the
+document is never built and never mounted, whatever the configuration says. The
+guard runs twice, independently: the option resolver forces the feature off, and
+the bootstrap helper classifies the runtime again without trusting that
+resolution.
+
+**`NODE_ENV` cannot be overridden.** With it set to anything, no option serves
+the document in a runtime it named production.
 
 Enabling it in production is not an error, it is a no-op with a warning naming
 the option that was ignored, so a single configuration can be shared across
 environments.
 
+#### When your application validates its own environment variable
+
+Plenty of applications parse an `APP_ENV` through a config schema and never set
+`NODE_ENV` at all. Those deployments used to be classified as production —
+absence was the only evidence available — so the document was refused in an
+environment that never asked for the refusal, with no way to answer back.
+
+Declare the environment and it is used **where the process declares nothing**:
+
+```typescript
+BymaxCoreModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    // Your validated value, not a second copy of NODE_ENV.
+    environment: config.get('APP_ENV'),
+    openapi: { enabled: true }
+  })
+})
+```
+
+| `NODE_ENV`      | `environment` | Classified as  |
+| --------------- | ------------- | -------------- |
+| `production`    | `development` | **production** |
+| `development`   | (anything)    | development    |
+| unset, or blank | `development` | development    |
+| unset, or blank | `staging`     | **production** |
+| unset, or blank | unset         | **production** |
+
+Two properties are worth reading off that table. A declaration never overrules a
+process that named its own environment — the first row is the one that matters,
+and it is asserted in both guards rather than in one. And the declaration enters
+the same fail-closed classification, so an unrecognized name is production like
+any other; this is a second **source** for the value, never a second set of
+rules.
+
+The narrowing is deliberate and worth naming rather than burying: in the one
+case where the process declares nothing, the configuration a consumer bound does
+decide the answer, because there is nothing else to decide it with. Replacing a
+guess with a declaration is not the same as allowing an override — but it is a
+real change to what the second guard depends on, and you should know it before
+relying on either.
+
 ### Testing the enabled path under Jest
 
 `applyBymaxOpenApi` loads `@nestjs/swagger` through a dynamic `import()` — that
@@ -1289,9 +1418,11 @@ guard you would apply to any internal endpoint, or keep it off the public listen
 A published document is a map of every route, parameter and error shape an application has —
 useful to a developer, and just as useful to anyone probing the service. So unlike the metrics
 endpoint, it is not left to a guard: it is refused outright whenever the runtime is not
-positively `development` or `test`, in two independent layers, with no option to override.
-An unset `NODE_ENV` counts as production, because the deployment nobody configured is the one
-most likely to be exposed.
+positively `development` or `test`, in two independent layers. **`NODE_ENV` cannot be
+overridden** — with it set to anything, no option serves the document in a runtime it named
+production. A runtime that declares nothing is classified from the application's own
+[`environment`](#environment) when it supplied one, and counts as production otherwise, because
+the deployment nobody configured is the one most likely to be exposed.
 
 ---
 

package/dist/index.cjs

@@ -30,6 +30,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
@@ -92,9 +99,9 @@ function cloneServers(raw) {
     (server) => server.description === void 0 ? { url: server.url } : { url: server.url, description: server.description }
   );
 }
-function resolveOpenApi(raw) {
+function resolveOpenApi(raw, declaredEnvironment) {
   const requested = raw?.enabled ?? false;
-  const production = isProductionRuntime();
+  const production = isProductionRuntime(runtimeEnvironmentName(declaredEnvironment));
   return {
     enabled: requested && !production,
     suppressedInProduction: requested && production,
@@ -131,8 +138,12 @@ function normalizeCoreOptions(raw) {
     timing: resolveTiming(raw?.timing),
     health: resolveHealth(raw?.health),
     metrics: resolveMetrics(raw?.metrics),
-    openapi: resolveOpenApi(raw?.openapi),
-    telemetry: resolveTelemetry(raw?.telemetry)
+    openapi: resolveOpenApi(raw?.openapi, raw?.environment),
+    telemetry: resolveTelemetry(raw?.telemetry),
+    // Spread rather than assigned so an application that declared nothing has
+    // no `environment` member at all, matching every other optional member on
+    // this snapshot under `exactOptionalPropertyTypes`.
+    ...raw?.environment === void 0 ? {} : { environment: raw.environment }
   });
 }
 normalizeCoreOptions();

package/dist/index.d.cts

@@ -273,6 +273,28 @@ interface BymaxCoreModuleOptions {
     openapi?: OpenApiOptions;
     /** Trace correlation. Default: disabled. */
     telemetry?: TelemetryOptions;
+    /**
+     * The environment this deployment is running in, for the features that must
+     * never exist outside development — today, the OpenAPI document and its UI.
+     *
+     * **`NODE_ENV` always wins.** This is consulted only when the process
+     * declares nothing: `NODE_ENV` unset, or set to whitespace. It cannot make a
+     * runtime that identified itself as production serve the document, and no
+     * value here overrides one there.
+     *
+     * Set it when your application validates its own environment variable — an
+     * `APP_ENV` your config schema parses — and does not also set `NODE_ENV`.
+     * Without it, that deployment is classified as production because absence was
+     * the only evidence available, and the document is refused in an environment
+     * that never asked for the refusal.
+     *
+     * Recognized non-production values are `development` and `test`, compared
+     * case-insensitively and ignoring surrounding whitespace. Anything else,
+     * including an unrecognized name, is production.
+     *
+     * @example 'development'
+     */
+    environment?: string;
 }
 /** Fully-resolved envelope options. */
 interface ResolvedEnvelopeOptions {
@@ -334,9 +356,9 @@ interface ResolvedOpenApiOptions {
 }
 /**
  * The effective, defaults-applied configuration exposed under
- * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present;
- * the only optional field is `timing.slowRequestThresholdMs`, which has no
- * default and is absent unless the consumer sets it.
+ * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present.
+ * Two fields have no default and are absent unless the consumer supplies them:
+ * `timing.slowRequestThresholdMs`, and `environment`.
  */
 interface ResolvedCoreOptions {
     envelope: ResolvedEnvelopeOptions;
@@ -345,6 +367,12 @@ interface ResolvedCoreOptions {
     metrics: ResolvedMetricsOptions;
     openapi: ResolvedOpenApiOptions;
     telemetry: ResolvedTelemetryOptions;
+    /**
+     * The environment the application declared, carried through so the bootstrap
+     * helper classifies the runtime from the same two inputs the resolver did.
+     * Absent when the application declared none.
+     */
+    environment?: string;
 }
 
 /** Non-option extras accepted by `forRoot` / `forRootAsync`. */

package/dist/index.d.ts

@@ -273,6 +273,28 @@ interface BymaxCoreModuleOptions {
     openapi?: OpenApiOptions;
     /** Trace correlation. Default: disabled. */
     telemetry?: TelemetryOptions;
+    /**
+     * The environment this deployment is running in, for the features that must
+     * never exist outside development — today, the OpenAPI document and its UI.
+     *
+     * **`NODE_ENV` always wins.** This is consulted only when the process
+     * declares nothing: `NODE_ENV` unset, or set to whitespace. It cannot make a
+     * runtime that identified itself as production serve the document, and no
+     * value here overrides one there.
+     *
+     * Set it when your application validates its own environment variable — an
+     * `APP_ENV` your config schema parses — and does not also set `NODE_ENV`.
+     * Without it, that deployment is classified as production because absence was
+     * the only evidence available, and the document is refused in an environment
+     * that never asked for the refusal.
+     *
+     * Recognized non-production values are `development` and `test`, compared
+     * case-insensitively and ignoring surrounding whitespace. Anything else,
+     * including an unrecognized name, is production.
+     *
+     * @example 'development'
+     */
+    environment?: string;
 }
 /** Fully-resolved envelope options. */
 interface ResolvedEnvelopeOptions {
@@ -334,9 +356,9 @@ interface ResolvedOpenApiOptions {
 }
 /**
  * The effective, defaults-applied configuration exposed under
- * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present;
- * the only optional field is `timing.slowRequestThresholdMs`, which has no
- * default and is absent unless the consumer sets it.
+ * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present.
+ * Two fields have no default and are absent unless the consumer supplies them:
+ * `timing.slowRequestThresholdMs`, and `environment`.
  */
 interface ResolvedCoreOptions {
     envelope: ResolvedEnvelopeOptions;
@@ -345,6 +367,12 @@ interface ResolvedCoreOptions {
     metrics: ResolvedMetricsOptions;
     openapi: ResolvedOpenApiOptions;
     telemetry: ResolvedTelemetryOptions;
+    /**
+     * The environment the application declared, carried through so the bootstrap
+     * helper classifies the runtime from the same two inputs the resolver did.
+     * Absent when the application declared none.
+     */
+    environment?: string;
 }
 
 /** Non-option extras accepted by `forRoot` / `forRootAsync`. */

package/dist/index.mjs

@@ -28,6 +28,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/core.options.ts
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
@@ -90,9 +97,9 @@ function cloneServers(raw) {
     (server) => server.description === void 0 ? { url: server.url } : { url: server.url, description: server.description }
   );
 }
-function resolveOpenApi(raw) {
+function resolveOpenApi(raw, declaredEnvironment) {
   const requested = raw?.enabled ?? false;
-  const production = isProductionRuntime();
+  const production = isProductionRuntime(runtimeEnvironmentName(declaredEnvironment));
   return {
     enabled: requested && !production,
     suppressedInProduction: requested && production,
@@ -129,8 +136,12 @@ function normalizeCoreOptions(raw) {
     timing: resolveTiming(raw?.timing),
     health: resolveHealth(raw?.health),
     metrics: resolveMetrics(raw?.metrics),
-    openapi: resolveOpenApi(raw?.openapi),
-    telemetry: resolveTelemetry(raw?.telemetry)
+    openapi: resolveOpenApi(raw?.openapi, raw?.environment),
+    telemetry: resolveTelemetry(raw?.telemetry),
+    // Spread rather than assigned so an application that declared nothing has
+    // no `environment` member at all, matching every other optional member on
+    // this snapshot under `exactOptionalPropertyTypes`.
+    ...raw?.environment === void 0 ? {} : { environment: raw.environment }
   });
 }
 normalizeCoreOptions();

package/dist/openapi/index.cjs

@@ -16,6 +16,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/discovery.ts
 function labelFor(className, token) {
@@ -653,7 +660,7 @@ async function applyBymaxOpenApi(app) {
   const logger = new common.Logger("BymaxCoreModule");
   const resolved = resolveCoreOptions(app);
   const options = resolved.openapi;
-  if (isProductionRuntime()) {
+  if (isProductionRuntime(runtimeEnvironmentName(resolved.environment))) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
         'openapi.enabled was requested but the OpenAPI document is never served in production. Set NODE_ENV to "development" or "test" to serve it.'

package/dist/openapi/index.mjs

@@ -14,6 +14,13 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   }
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
+function runtimeEnvironmentName(declared) {
+  const fromProcess = process.env["NODE_ENV"];
+  if (fromProcess !== void 0 && fromProcess.trim() !== "") {
+    return fromProcess;
+  }
+  return declared;
+}
 
 // src/discovery.ts
 function labelFor(className, token) {
@@ -651,7 +658,7 @@ async function applyBymaxOpenApi(app) {
   const logger = new Logger("BymaxCoreModule");
   const resolved = resolveCoreOptions(app);
   const options = resolved.openapi;
-  if (isProductionRuntime()) {
+  if (isProductionRuntime(runtimeEnvironmentName(resolved.environment))) {
     if (options.suppressedInProduction || options.enabled) {
       logger.warn(
         'openapi.enabled was requested but the OpenAPI document is never served in production. Set NODE_ENV to "development" or "test" to serve it.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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",