@bymax-one/nest-config 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -11,6 +11,115 @@ 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
+two `./internal` declaration files, by the JSDoc noted below; `README.md` and `CHANGELOG.md`;
+and `package.json`, by its `version` field alone. Verified by hashing every file in the
+published `1.1.2` tarball against this build.
+
+### Documentation
+
+- **How to report the failure is documented, because the two obvious ways are not
+  equivalent.** `onValidationError` said what the hook is and nothing about logging what it
+  hands you, which left the choice at the call site with no way to know the cost. `code` and
+  `issues` are the only two own enumerable properties of `BymaxConfigValidationError`,
+  while `name`, `message` and `stack` are non-enumerable as on any `Error`. That splits the
+  outcome three ways by representation: an error object keeps everything when the serializer
+  extracts the standard fields and copies the own enumerables, which are two separate steps; `error.stack` keeps the report and drops `code` and `issues`;
+  and a plain `JSON.stringify(error)` keeps `code` and `issues` and drops the report.
+  Which representation reaches the sink is decided by the logging call, and that call is
+  library-specific — Pino serializes an error only as the merging object or under `err`,
+  and drops it entirely when it is passed as a trailing argument. The machine-readable half is the easy one to
+  lose, precisely because the report keeps arriving — `code` separates a configuration
+  failure from any other boot failure, and `issues` is what an alert keys on per variable.
+
+  Wrapping the error as a `cause` also keeps all of it, wherever the serializer walks the
+  chain the same way. Measured against `@bymax-one/nest-logger` 1.2.7 and 1.2.9 rather
+  than assumed: a fifteen-issue report crosses the chain with every issue and the full multi-line
+  `message` intact.
+
+  Versions 1.2.6 through 1.2.9 carry a defect the README states in full: handed this error
+  **directly**, the redactor dropped the whole `err` field, leaving `_redactionFailed: true`
+  and no report at all. The trigger was `issues` rather than `code`, and the property
+  definition rather than freezing: this error is not frozen — it defines `code` and `issues`
+  as non-writable, non-configurable own properties and freezes the issue list, while the
+  instance stays extensible. Only the locked object property failed, because the redactor's
+  clone inherited the locked descriptors and redefining a non-configurable property fails
+  exactly when the value differs, which a structurally copied object does and an identical
+  string does not.
+
+  **Fixed upstream in `1.3.0`**, measured against the published package rather than taken on
+  report: a real failure logged directly now arrives with `type, message, stack, code,
+issues`, the full issue array and the multi-line report intact, and this error is left
+  untouched. On an affected version the workaround stands, and it is something a consumer
+  writes: a `catch` receives this error unchanged, since the module rethrows the instance it
+  caught, so wrapping is an explicit `new Error(message, { cause: error })`.
+
+  The rule also covers the call site where this failure usually lands: a `catch` in
+  `main.ts` runs before any logging module is registered, so it reports through
+  `console.error`. Node's inspector appends an error's own enumerables after the stack,
+  so `console.error(message, error)` prints the report, the `code` and the expanded `issues`, while
+  `console.error(message, error.stack)` prints the report alone — the same split, one layer
+  earlier.
+
+  The same fact is now stated on `BymaxConfigValidationError` itself, so it reaches a
+  consumer through the published types and not only through the README.
+
 ## [1.1.2] - 2026-08-14
 
 **Documentation only.** `dist/` is byte-identical to `1.1.1`, verified by hashing every file in
@@ -264,4 +373,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.1.0]: https://github.com/bymaxone/nest-config/compare/v1.0.3...v1.1.0
 [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
-[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.1.2...HEAD
+[1.1.3]: https://github.com/bymaxone/nest-config/compare/v1.1.2...v1.1.3
+[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.
@@ -327,6 +388,83 @@ export interface ConfigIssue {
 error's own `code`) and `ConfigIssueCode` (each issue's `code`); see the
 error catalog below for every value.
 
+### Reporting the failure
+
+`onValidationError` receives `ReadonlyArray<ConfigIssue>` — four string fields per
+issue, JSON-serializable, with no error to unwrap. Every description this package
+generates is value-free, so it can go straight into a log as structured data. The
+exception is the one described above: a `custom` message written by your own schema
+is printed as written, so if one of yours interpolates a value, reviewing it before
+it reaches a log is the schema author's job, not this package's.
+
+If you also log the thrown error from a bootstrap `catch`, how you pass it decides
+what survives. `code` and `issues` are the **only two own enumerable properties** of
+`BymaxConfigValidationError`; `name`, `message` and `stack` are non-enumerable, as
+on any `Error`. That splits the outcome three ways — all three measured:
+
+| Which representation reaches the sink                                                                   | The report (`message`) | `code` and `issues` |
+| ------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------- |
+| the error object, read by a serializer that extracts the standard fields **and** copies own enumerables | ✅                     | ✅                  |
+| `error.stack`                                                                                           | ✅ inside the string   | ❌                  |
+| `JSON.stringify(error)`, `{ ...error }`                                                                 | ❌                     | ✅                  |
+
+Recognizing an `Error` is not enough on its own: extracting `name`, `message` and
+`stack` is what preserves the report, and copying the own enumerables is a separate
+step that preserves `code` and `issues`. A serializer that does only the second is
+the third row — `code` and `issues` and no report at all — so if you build the log
+record by hand, add `message` explicitly.
+
+**Which representation the sink sees is decided by your logging call, and that call
+is library-specific.** These are measured, not assumed:
+
+```typescript
+console.error('configuration invalid', error) // report, code and issues
+pino.error({ err: error }, 'configuration invalid') // report, code and issues
+pino.error('configuration invalid', error) // the error is dropped entirely
+
+// @bymax-one/nest-logger 1.2.6-1.2.9: wrap it, explicitly (see the note below)
+nestLogger.error('BOOT_FAILED', new Error('bootstrap failed', { cause: error }))
+```
+
+Pino only applies error serialization when the error is the merging object or sits
+under `err`; passed as a trailing argument it is treated as an interpolation value,
+and nothing about the failure reaches the entry.
+
+> [!NOTE]
+> **`@bymax-one/nest-logger` 1.2.6 through 1.2.9 dropped this error when it was logged
+> directly.** Its redactor left `_redactionFailed: true` and no `err` field at all —
+> no report, no `code`, no `issues`. The trigger was the definition rather than any
+> freezing: this error defines `code` and `issues` as non-writable, non-configurable
+> own properties, and the redactor's clone inherited those descriptors, so rewriting
+> the object-valued one with a walked copy failed. A locked scalar was unaffected,
+> which is why `code` alone never reproduced it.
+>
+> Fixed in **1.3.0**, measured rather than taken on report: a real failure logged
+> directly now arrives with `type, message, stack, code, issues`, the full issue array
+> and the report intact, and this error is left untouched. Measured affected: 1.2.6, 1.2.7
+> and 1.2.9 — 1.2.8 was never published, and on 1.2.2 and earlier this call shape does not
+> attach the error at all, so the defect does not arise there in this form. On an affected
+> version, wrap it — a `catch` receives this error unchanged, since the
+> module rethrows the instance it caught, so wrapping is an explicit
+> `new Error(message, { cause: error })` rather than a side effect of catching. A
+> lockfile pinned below 1.3.0 does not pick the fix up from an ordinary install, so the
+> update has to be deliberate.
+
+Wrapping the error as the `cause` of an error you construct keeps all of it wherever the
+serializer walks the chain — measured against `@bymax-one/nest-logger` 1.2.7 and
+1.2.9, where a fifteen-issue report crosses the chain with `code`, every issue and
+the full multi-line `message` intact.
+
+Before any logger exists — which is where this failure usually lands, since a `catch`
+in `main.ts` runs before the logging module is registered — `console.error` is the
+reporter, and Node's inspector prints the stack and then appends the own enumerables.
+So `console.error(message, error)` shows the report, the `code` and the expanded
+`issues` list, while `console.error(message, error.stack)` shows the report alone.
+
+Losing the machine-readable half is easy to miss precisely because the report keeps
+arriving: `code` is what separates a configuration failure from any other boot
+failure, and `issues` is what an alert or a dashboard keys on per variable.
+
 ### Injection tokens
 
 `BYMAX_CONFIG` and `BYMAX_CONFIG_OPTIONS` are module-local `Symbol` tokens,
@@ -595,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

@@ -167,6 +167,10 @@ interface ConfigIssue {
  * constraints, never their received values — except where a schema author's own
  * `custom` message says otherwise, as described on {@link ConfigIssue}.
  *
+ * `code` and `issues` are its only own enumerable properties, so a structured
+ * logger that copies own enumerables keeps both; passing `error.stack` instead of
+ * the error keeps neither.
+ *
  * @example
  * ```typescript
  * try {
@@ -236,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;
 }
@@ -558,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

@@ -167,6 +167,10 @@ interface ConfigIssue {
  * constraints, never their received values — except where a schema author's own
  * `custom` message says otherwise, as described on {@link ConfigIssue}.
  *
+ * `code` and `issues` are its only own enumerable properties, so a structured
+ * logger that copies own enumerables keeps both; passing `error.stack` instead of
+ * the error keeps neither.
+ *
  * @example
  * ```typescript
  * try {
@@ -236,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;
 }
@@ -558,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.2",
+  "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",