@bymax-one/nest-config 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -11,6 +11,60 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-09-04
+
+### Added
+
+- **A namespace can declare itself open, so `strict` is usable next to a library that
+  reads its own environment.** `strict` claims a declared namespace's entire variable
+  prefix: a namespace named `otel` rejects the OpenTelemetry SDK's own
+  `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_TRACES_SAMPLER`, and one named `redis` rejects a
+  `REDIS_PORT` only a compose file reads. A prefix matching no declared namespace
+  (`POSTGRES_*` with no `postgres` namespace) is never inspected, so the failure lands
+  hardest exactly where a schema shares a prefix with another program — which is the common
+  case. `OTEL_` is an open standard; a consumer cannot rename around it.
+
+  `z.object({ ... }).meta({ open: true })` on the namespace waives unknown-key detection
+  for the remainder of that prefix. The waiver is narrow by construction: declared leaves
+  stay bound and validated (an open `otel` still reads and coerces `OTEL_ENABLED`), it
+  applies per namespace rather than per schema, and a more specific closed namespace still
+  claims its own variables (`otelExporter` beside an open `otel` still reports
+  `OTEL_EXPORTER_TYPO`). Only the literal `true` opens a namespace.
+
+  **The cost is stated rather than designed away:** an open namespace cannot distinguish a
+  foreign variable from a misspelled local one, so a typo of `OTEL_ENABLED` passes and the
+  leaf falls back to its default. The two cases are indistinguishable by name. Open the
+  namespaces whose prefix genuinely belongs to another program, and leave the rest closed.
+
+  Filtering the foreign names out of `source` is not an equivalent workaround and is worse
+  in a way that is easy to miss: removing `OTEL_*` from the source also unbinds the declared
+  `OTEL_ENABLED`, whose `.default()` then manufactures a plausible value while the variable
+  silently stops being read.
+
+### Security
+
+- **Development-only advisories cleared; the published package was never affected.** Eight
+  advisories landed against transitive development dependencies across this cycle:
+  `browserslist` (GHSA-73wf-gq98-2v4g, GHSA-c83g-rgw3-j3cx, CVSS 7.5 each), `fast-uri`
+  (GHSA-5jgf-p345-68v8, GHSA-jqff-g426-hqxp — host confusion; GHSA-f65p-4m7j-42xc,
+  GHSA-fph4-wmhf-6fwf — server-side request forgery; CVSS 7.5 each) and `qs`
+  (GHSA-4mjr-xmp4-gh2g, GHSA-x5fp-wj9c-mxmx, CVSS 6.3 each). All three are reached through
+  the mutation-testing and commit-tooling chains, none is a runtime dependency, and this
+  package ships `dist` alone — so no consumer resolved a vulnerable version through it.
+
+  Recorded here rather than omitted as internal because a consumer reading an advisory feed
+  needs to know whether a library in their tree pulled one in, and "it did not" is an answer
+  only the maintainer can give. The floors now sit above every affected range and the
+  lockfile resolves `browserslist@4.28.8`, `fast-uri@3.1.6` and `qs@6.16.0`.
+
+### Documentation
+
+- **`strict` now documents what it claims before you enable it.** The option read as an
+  unambiguous improvement and gave no warning that a declared namespace claims its whole
+  prefix — the behaviour was measured by a consumer only after enabling it broke a boot on
+  five correct variables. The API reference gains a `Strict mode and shared prefixes`
+  section covering the claim, the open-namespace opt-out, and its cost.
+
 ## [1.1.3] - 2026-08-18
 
 **Documentation.** The runtime bundles are byte-identical to `1.1.2`. Five files differ: the
@@ -320,4 +374,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.1.1]: https://github.com/bymaxone/nest-config/compare/v1.1.0...v1.1.1
 [1.1.2]: https://github.com/bymaxone/nest-config/compare/v1.1.1...v1.1.2
 [1.1.3]: https://github.com/bymaxone/nest-config/compare/v1.1.2...v1.1.3
-[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.1.3...HEAD
+[1.2.0]: https://github.com/bymaxone/nest-config/compare/v1.1.3...v1.2.0
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.0...HEAD

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/@bymax-one/nest-config"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-config/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
-  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.61%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
+  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.62%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-config"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-config/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
   <a href="https://github.com/bymaxone/nest-config/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -258,6 +258,20 @@ database: z.object({
 })
 ```
 
+A namespace can declare itself **open**, which waives strict unknown-key
+detection for the rest of its prefix. Use it when the prefix is shared with
+another program that reads its own variables — see
+[Strict mode and shared prefixes](#strict-mode-and-shared-prefixes):
+
+```typescript
+// OTEL_ENABLED is read and validated; every other OTEL_* variable belongs to
+// the OpenTelemetry SDK, which reads it natively.
+otel: z.object({ enabled: z.stringbool().default(false) }).meta({ open: true })
+```
+
+Only the literal `true` opens a namespace. Any other value, and any metadata
+without the key, leaves detection in force.
+
 ### `BymaxConfigModule`
 
 | Method                  | Signature                                                         |
@@ -267,12 +281,12 @@ database: z.object({
 
 `BymaxConfigModuleOptions`:
 
-| Field               | Type                                           | Required | Notes                                                                                                                               |
-| ------------------- | ---------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `schema`            | `EnvSchema`                                    | yes      | Produced by `defineEnv`.                                                                                                            |
-| `source`            | `Record<string, string \| undefined>`          | no       | Defaults to `process.env` in the provider factory. Injectable for tests.                                                            |
-| `onValidationError` | `(issues: ReadonlyArray<ConfigIssue>) => void` | no       | Observability hook invoked before the fail-fast throw. Cannot suppress the failure.                                                 |
-| `strict`            | `boolean`                                      | no       | When true, source variables matching a namespace prefix but no declared leaf raise `BYMAX_CONFIG_UNKNOWN_KEY`. Defaults to `false`. |
+| Field               | Type                                           | Required | Notes                                                                                                                                                                                                                            |
+| ------------------- | ---------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`            | `EnvSchema`                                    | yes      | Produced by `defineEnv`.                                                                                                                                                                                                         |
+| `source`            | `Record<string, string \| undefined>`          | no       | Defaults to `process.env` in the provider factory. Injectable for tests.                                                                                                                                                         |
+| `onValidationError` | `(issues: ReadonlyArray<ConfigIssue>) => void` | no       | Observability hook invoked before the fail-fast throw. Cannot suppress the failure.                                                                                                                                              |
+| `strict`            | `boolean`                                      | no       | When true, source variables matching a namespace prefix but no declared leaf raise `BYMAX_CONFIG_UNKNOWN_KEY`. Defaults to `false`. Read [Strict mode and shared prefixes](#strict-mode-and-shared-prefixes) before enabling it. |
 
 `forRootAsync` resolves the source through another provider, for example a
 secrets-manager client composed with `process.env`:
@@ -293,6 +307,53 @@ BymaxConfigModule.forRootAsync({
 `isGlobal` defaults to `true` and can be set to `false` through the standard
 extras when an application intentionally scopes configuration to a submodule.
 
+#### Strict mode and shared prefixes
+
+**A declared namespace claims its entire variable prefix.** Under `strict`, any
+source variable starting with that prefix and matching no declared leaf fails
+the boot — including variables this application never reads because _another
+program_ reads them. A namespace named `otel` claims `OTEL_*`, so the
+OpenTelemetry SDK's own `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_TRACES_SAMPLER`
+are rejected; a namespace named `redis` claims `REDIS_*`, so a `REDIS_PORT` that
+only a compose file reads is rejected too. A prefix matching no declared
+namespace at all (`POSTGRES_*` with no `postgres` namespace) is never inspected,
+which is why the failure lands hardest on schemas that share a prefix with a
+library or a tool — the common case, not the edge one.
+
+Declare such a namespace **open** to waive the check for the remainder of its
+prefix:
+
+```typescript
+export const envSchema = defineEnv({
+  // OTEL_ENABLED is declared, read and validated. Every other OTEL_* variable
+  // is the SDK's, and strict leaves it alone.
+  otel: z.object({ enabled: z.stringbool().default(false) }).meta({ open: true }),
+  database: z.object({ url: z.url() })
+})
+```
+
+What the waiver does and does not do:
+
+- **Declared leaves stay bound.** `OTEL_ENABLED` is still read, coerced and
+  validated. Opening a namespace waives unknown-key detection only; it never
+  weakens the validation the schema does perform.
+- **The waiver is per namespace.** A stray `DATABASE_TYPO` is still reported
+  while `otel` is open. One open namespace does not disable strict mode.
+- **The most specific namespace wins.** If a schema declares both `otel` (open)
+  and `otelExporter` (closed), `OTEL_EXPORTER_TYPO` belongs to `otelExporter`
+  and is still reported.
+
+**The cost, stated plainly:** an open namespace cannot tell a foreign variable
+from a misspelled local one. Under an open `otel`, a typo of `OTEL_ENABLED`
+passes silently and the leaf falls back to its default. No design removes this —
+the two cases are indistinguishable by name — so open the namespaces whose
+prefix genuinely belongs to someone else, and leave the rest closed.
+
+> Filtering the foreign names out of `source` instead is **not** equivalent, and
+> is worse in a way that is easy to miss: removing `OTEL_*` from the source also
+> unbinds the declared `OTEL_ENABLED`, whose `.default()` then manufactures a
+> plausible value while the variable silently stops being read.
+
 ### `ConfigService<TConfig>`
 
 The typed, injectable accessor over the frozen configuration object.
@@ -672,6 +733,10 @@ standard is Jest.
 4. **No multi-source precedence.** One source record per module
    registration. Precedence between layers (defaults, env, secrets) is the
    caller's composition (`{ ...a, ...b }`), kept explicit on purpose.
+5. **An open namespace cannot detect a typo in its own prefix.** A foreign
+   variable and a misspelled local one are indistinguishable by name, so
+   `meta({ open: true })` accepts both. See
+   [Strict mode and shared prefixes](#strict-mode-and-shared-prefixes).
 
 ## 🤝 Contributing
 

package/dist/internal/index.cjs

@@ -125,6 +125,9 @@ function readEnvOverride(leaf) {
   const override = leaf.meta()?.env;
   return typeof override === "string" && override.length > 0 ? override : void 0;
 }
+function readOpenFlag(namespace) {
+  return namespace.meta()?.open === true;
+}
 function deriveVariable(namespace, leafKey) {
   return `${toScreamingSnake(namespace)}_${toScreamingSnake(leafKey)}`;
 }
@@ -137,9 +140,10 @@ function resolveSourceNames(schema) {
   );
 }
 function resolveNamespacePrefixes(schema) {
-  return Object.keys(schema.shape).map((namespace) => ({
+  return Object.entries(schema.shape).map(([namespace, namespaceSchema]) => ({
     namespace,
-    prefix: `${toScreamingSnake(namespace)}_`
+    prefix: `${toScreamingSnake(namespace)}_`,
+    open: readOpenFlag(namespaceSchema)
   }));
 }
 
@@ -240,6 +244,7 @@ function detectUnknownKeys(prefixes, bindings, source) {
     if (source.get(key) === void 0) continue;
     const match = longestMatchingPrefix(prefixes, key);
     if (match === void 0) continue;
+    if (match.open) continue;
     issues.push({
       path: match.namespace,
       variable: key,

package/dist/internal/index.d.cts

@@ -240,6 +240,12 @@ interface BymaxConfigModuleOptions<TSchema extends EnvSchema = EnvSchema> {
     /**
      * When true, source variables that match a declared namespace prefix but no
      * declared leaf produce `BYMAX_CONFIG_UNKNOWN_KEY` issues. Defaults to false.
+     *
+     * The prefix is claimed whole, so a namespace sharing its prefix with another
+     * program (`OTEL_` with an OpenTelemetry SDK, `REDIS_` with a compose file)
+     * would reject that program's variables. Declare such a namespace
+     * `meta({ open: true })` to waive the check for the rest of its prefix while
+     * its own leaves stay bound and validated.
      */
     readonly strict?: boolean;
 }
@@ -562,8 +568,11 @@ declare function createValidatedConfig<TShape extends EnvShape>(options: Omit<By
  * @fileoverview Deterministic mapping between nested config paths and flat
  * environment variable names. Each leaf resolves to exactly one variable:
  * SCREAMING_SNAKE_CASE of the joined path (`database.url` reads `DATABASE_URL`),
- * unless the leaf declares a `meta({ env })` override, which wins. This is an
- * internal module consumed by the validator; it is not part of the public API.
+ * unless the leaf declares a `meta({ env })` override, which wins. It also
+ * resolves the shared prefix of each namespace and whether that namespace
+ * declared `meta({ open: true })`, the two facts strict unknown-key detection
+ * runs on. This is an internal module consumed by the validator; it is not part
+ * of the public API.
  * @layer Utility
  */
 

package/dist/internal/index.d.ts

@@ -240,6 +240,12 @@ interface BymaxConfigModuleOptions<TSchema extends EnvSchema = EnvSchema> {
     /**
      * When true, source variables that match a declared namespace prefix but no
      * declared leaf produce `BYMAX_CONFIG_UNKNOWN_KEY` issues. Defaults to false.
+     *
+     * The prefix is claimed whole, so a namespace sharing its prefix with another
+     * program (`OTEL_` with an OpenTelemetry SDK, `REDIS_` with a compose file)
+     * would reject that program's variables. Declare such a namespace
+     * `meta({ open: true })` to waive the check for the rest of its prefix while
+     * its own leaves stay bound and validated.
      */
     readonly strict?: boolean;
 }
@@ -562,8 +568,11 @@ declare function createValidatedConfig<TShape extends EnvShape>(options: Omit<By
  * @fileoverview Deterministic mapping between nested config paths and flat
  * environment variable names. Each leaf resolves to exactly one variable:
  * SCREAMING_SNAKE_CASE of the joined path (`database.url` reads `DATABASE_URL`),
- * unless the leaf declares a `meta({ env })` override, which wins. This is an
- * internal module consumed by the validator; it is not part of the public API.
+ * unless the leaf declares a `meta({ env })` override, which wins. It also
+ * resolves the shared prefix of each namespace and whether that namespace
+ * declared `meta({ open: true })`, the two facts strict unknown-key detection
+ * runs on. This is an internal module consumed by the validator; it is not part
+ * of the public API.
  * @layer Utility
  */
 

package/dist/internal/index.mjs

@@ -123,6 +123,9 @@ function readEnvOverride(leaf) {
   const override = leaf.meta()?.env;
   return typeof override === "string" && override.length > 0 ? override : void 0;
 }
+function readOpenFlag(namespace) {
+  return namespace.meta()?.open === true;
+}
 function deriveVariable(namespace, leafKey) {
   return `${toScreamingSnake(namespace)}_${toScreamingSnake(leafKey)}`;
 }
@@ -135,9 +138,10 @@ function resolveSourceNames(schema) {
   );
 }
 function resolveNamespacePrefixes(schema) {
-  return Object.keys(schema.shape).map((namespace) => ({
+  return Object.entries(schema.shape).map(([namespace, namespaceSchema]) => ({
     namespace,
-    prefix: `${toScreamingSnake(namespace)}_`
+    prefix: `${toScreamingSnake(namespace)}_`,
+    open: readOpenFlag(namespaceSchema)
   }));
 }
 
@@ -238,6 +242,7 @@ function detectUnknownKeys(prefixes, bindings, source) {
     if (source.get(key) === void 0) continue;
     const match = longestMatchingPrefix(prefixes, key);
     if (match === void 0) continue;
+    if (match.open) continue;
     issues.push({
       path: match.namespace,
       variable: key,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-config",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Typed and validated environment configuration entry point for NestJS 11 applications, built on Zod v4.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -56,16 +56,17 @@
   "scripts": {
     "build": "pnpm clean && tsup",
     "check:exports": "attw --pack . --profile strict",
+    "check:lint-graph": "node scripts/check-lint-graph-rules.mjs",
     "check:mutants": "node scripts/check-mutation-directives.mjs",
     "check:published": "node scripts/check-published-surface.mjs",
     "check:runtime": "node scripts/check-consumer-runtime.mjs",
     "clean": "node -e \"const fs=require('node:fs');for(const d of ['dist','coverage'])fs.rmSync(d,{recursive:true,force:true})\"",
     "dogfood": "node scripts/dogfood-smoke-test.mjs",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "lint": "eslint src scripts",
+    "lint:fix": "eslint src scripts --fix",
     "mutation": "stryker run",
-    "mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
     "mutation:dry-run": "stryker run --dryRunOnly",
+    "mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
     "prepare": "husky",
     "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm check:mutants && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
     "release": "npm publish --provenance --access public",
@@ -86,7 +87,6 @@
       "prettier --write"
     ]
   },
-  "dependencies": {},
   "peerDependencies": {
     "@nestjs/common": "^11.0.16",
     "@nestjs/core": "^11.1.18",
@@ -97,7 +97,7 @@
     "@arethetypeswrong/cli": "^0.18.2",
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
-    "@eslint/js": "^9.39.4",
+    "@eslint/js": "^10.0.1",
     "@nestjs/common": "^11.1.20",
     "@nestjs/core": "^11.1.20",
     "@nestjs/platform-express": "^11.1.20",
@@ -110,10 +110,10 @@
     "@types/node": "^25",
     "@typescript-eslint/eslint-plugin": "^8.59.3",
     "@typescript-eslint/parser": "^8.59.3",
-    "eslint": "^9.39.4",
+    "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-import-resolver-typescript": "^4.4.4",
-    "eslint-plugin-import": "^2.32.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.17.1",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-security": "^4.0.0",
     "globals": "^17.6.0",