@zudojs/config 1.0.1 → 1.2.0

package/README.md

@@ -3,6 +3,12 @@
 Layered configuration management with multiple sources, priority-based
 merging, schema validation, and sensitive-value redaction.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-config](https://zudojs.oyinlola.site/docs/packages-config) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-config.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -52,14 +58,24 @@ await `manager.ready()` before reading values.
 A source provides values plus a priority. Higher priority wins; equal
 priorities are applied in registration order (last registered wins).
 
+A source that declares no priority gets `DEFAULT_CONFIG_SOURCE_PRIORITY`
+(`-1`), which is strictly below the priority `initialValues` is seeded
+at (`0`), so an undeclared source layers UNDER the values a manager was
+seeded with. Declare `priority: 0` (or higher) on the source when it
+should override them.
+
+Sources are deduplicated by name — the first occurrence of a name wins,
+both when they are passed to the constructor and through `addSource()`
+(which rejects a duplicate outright).
+
 - `createDefaultsConfigSource(values, name?)` — low-priority defaults.
 - `createMemoryConfigSource(values, { name, priority?, optional? })` —
   in-memory values.
 - `createEnvironmentConfigSource({ prefix, env?, priority?, keyMapper?, isSensitive? })`
   — reads environment variables. Values stay RAW STRINGS (use the typed
   accessors to coerce, so `"false"` becomes `false` instead of a truthy
-  string). Names matching a password/token/secret/API-key pattern are
-  reported as sensitive and therefore redacted by `toSafeObject()`.
+  string). Names matching `isSensitiveConfigKey` are reported as
+  sensitive and therefore redacted by `toSafeObject()`.
 - `createCustomConfigSource(name, loader, options?)` — async loader
   function returning `{ values, source, type }`. Include
   `sensitiveKeys: ["some.key"]` in the result to mark values as
@@ -83,6 +99,13 @@ const remote = createCustomConfigSource("vault", async () => ({
 }));
 ```
 
+Whatever the source, the loader also marks an entry sensitive when
+`isSensitiveConfigEntry(key, value)` flags it: a key naming a password,
+secret, token, API/private key, credential, DSN, database URL or `*_key`
+(in any dotted segment, case-insensitive), a nested object containing such
+a key, or a URL with embedded `user:password@` credentials. Returning
+`false` from `isSensitive` or omitting `sensitiveKeys` cannot un-mark these.
+
 ## Typed access
 
 `ConfigManager` (and the underlying `ConfigResolver`) offer typed
@@ -95,6 +118,9 @@ const db = manager.scoped("db");
 db.string("host", "localhost");
 ```
 
+`number()` accepts decimal notation only: `"0x1F90"`, `"0b11"` and `"0o17"`
+are rejected rather than silently becoming 8080, 3 and 15.
+
 ## Schema validation
 
 Schemas are plain objects validated by this package (no external
@@ -118,7 +144,10 @@ so nested constraints are enforced by `validate()`, `resolve()` and the
 standalone `validateConfigValue`.
 
 `validate()` throws on failure and marks entries whose schema has
-`secret: true` as sensitive. Individual values can be validated with
+`secret: true` as sensitive, at any depth: a secret declared inside a
+nested object schema, or as a dotted key such as `"db.password"`, marks
+the store entry that holds it (for a nested `db` object, the whole `db`
+entry is redacted). Individual values can be validated with
 `manager.resolve(key, schema)` or the standalone
 `validateConfigValue` / `validateConfigObject` functions.
 
@@ -128,12 +157,26 @@ standalone `validateConfigValue`.
   including secrets.
 - `manager.toSafeObject()` / `store.toSafeObject()` replace sensitive
   values with `"[REDACTED]"` — use these for logging and diagnostics.
+- An entry is marked sensitive automatically by `ConfigStore.set()`, so
+  the same key is redacted however it was written: from a source, from
+  `initialValues`, from `set()` / `setMany()` / `replace()`, or from
+  `manager.set()`. Detection is `isSensitiveConfigEntry` — the key name
+  (`password`, `secret`, `token`, `*_key`, `auth`, `dsn`,
+  `database_url`, …) or a value that is a URL with embedded
+  `user:password@` credentials. Pass `sensitive: false` explicitly to
+  opt a key out.
 
 ## Reloading
 
 `manager.reload()` re-runs all sources. Values set at runtime via
 `manager.set()` and `initialValues` survive loads; sources only
-overwrite entries at equal or higher priority.
+overwrite entries at equal or higher priority, and a source that
+declares no priority ranks below both. A reload rebuilds every
+source-provided value from scratch, so a value a source no longer
+provides disappears (letting a lower-priority default show through), and
+the store is only updated once every source has loaded — a failing
+source leaves the previous configuration intact. An entry that was
+sensitive before a reload stays sensitive.
 
 ## Untrusted input
 
@@ -141,7 +184,8 @@ Configuration frequently originates from files, environment variables
 or remote services. Keys such as `__proto__`, `constructor` and
 `prototype` are copied with `Object.defineProperty`, never plain
 assignment, so a hostile key becomes an ordinary own property and can
-never replace an object's prototype. Schema properties are read as OWN
+never replace an object's prototype (this includes
+`toConfigJsonValue` and `configValueToString`). Schema properties are read as OWN
 properties, so a schema property named `constructor` is reported as
 missing rather than matching an inherited function.
 

package/dist/configLoader/configLoader.core.d.ts

@@ -94,7 +94,10 @@ export declare class ConfigLoader {
     /**
      * Reloads configuration.
      *
-     * The current store is replaced with freshly loaded values.
+     * The current store is replaced with freshly loaded values. When the
+     * loader layers onto a shared store (`clearStore: false`), values that
+     * sources no longer provide are dropped, runtime and initial values are
+     * kept, and the store is only updated once every source has loaded.
      */
     reload(): Promise<ConfigLoadResult>;
     /**
@@ -140,7 +143,9 @@ export declare class ConfigLoader {
      * source overwrites, so among equal priorities the last-applied
      * (last-registered) source wins.
      *
-     * Keys listed in the result's `sensitiveKeys` are marked sensitive.
+     * Keys listed in the result's `sensitiveKeys` are marked sensitive, as
+     * is any key or value that `isSensitiveConfigEntry` flags, whatever the
+     * source type.
      * Once an entry is sensitive it stays sensitive even when a later
      * source overwrites its value.
      */

package/dist/configLoader/configLoader.core.js

@@ -1,6 +1,8 @@
 import { cloneConfigValue } from "../configValue/configValue.core.js";
 import { createConfigEntry } from "../configEntry/configEntry.type.js";
-import { loadConfigSourceStrict, sortConfigSources, } from "../configSource/configSource.core.js";
+import { deduplicateConfigSources, loadConfigSourceStrict, sortConfigSources, } from "../configSource/configSource.core.js";
+import { isSensitiveConfigEntry } from "../configSource/configSource.sensitive.js";
+import { commitReloadStaging, createReloadStaging, } from "./configLoader.reload.js";
 import { createConfigStore } from "../configStore/configStore.factory.js";
 /**
  * Configuration loader.
@@ -21,7 +23,11 @@ export class ConfigLoader {
     disposed = false;
     lastResult;
     constructor(options = {}) {
-        this.sources = [...(options.sources ?? [])];
+        // addSource() rejects a name that is already registered, but the
+        // constructor used to accept duplicates silently — and because a
+        // later duplicate overwrote the earlier one, the LAST occurrence
+        // won, the opposite of the documented "first occurrence wins".
+        this.sources = [...deduplicateConfigSources(options.sources ?? [])];
         this.context = options.context ?? {};
         this.store =
             options.store ??
@@ -128,12 +134,47 @@ export class ConfigLoader {
     /**
      * Reloads configuration.
      *
-     * The current store is replaced with freshly loaded values.
+     * The current store is replaced with freshly loaded values. When the
+     * loader layers onto a shared store (`clearStore: false`), values that
+     * sources no longer provide are dropped, runtime and initial values are
+     * kept, and the store is only updated once every source has loaded.
      */
     async reload() {
         this.assertActive();
         this.loaded = false;
-        return this.load();
+        if (this.clearStore) {
+            return this.load();
+        }
+        // Layered stores (clearStore: false) are rebuilt off to the side and
+        // committed only once every source has loaded: see
+        // configLoader.reload.ts.
+        const staging = createReloadStaging(this.store, new Set(this.sources.map((source) => source.name)), this.freeze);
+        const stagingLoader = new ConfigLoader({
+            sources: this.sources,
+            context: this.context,
+            store: staging,
+            clearStore: false,
+            freeze: this.freeze,
+            onSourceLoaded: this.onSourceLoaded,
+            onSourceError: this.onSourceError,
+        });
+        this.loading = true;
+        try {
+            const staged = await stagingLoader.load();
+            commitReloadStaging(this.store, staging);
+            const result = {
+                ...staged,
+                store: this.store,
+                entries: this.store.getEntries(),
+            };
+            this.lastResult = result;
+            this.loaded = true;
+            return result;
+        }
+        finally {
+            this.loading = false;
+            stagingLoader.detach();
+        }
     }
     /**
      * Loads only selected sources.
@@ -232,7 +273,9 @@ export class ConfigLoader {
      * source overwrites, so among equal priorities the last-applied
      * (last-registered) source wins.
      *
-     * Keys listed in the result's `sensitiveKeys` are marked sensitive.
+     * Keys listed in the result's `sensitiveKeys` are marked sensitive, as
+     * is any key or value that `isSensitiveConfigEntry` flags, whatever the
+     * source type.
      * Once an entry is sensitive it stays sensitive even when a later
      * source overwrites its value.
      */
@@ -248,7 +291,9 @@ export class ConfigLoader {
                 source: source.name,
                 sourceType: source.type,
                 priority,
-                sensitive: sensitiveKeys.has(key) || (existing?.sensitive ?? false),
+                sensitive: sensitiveKeys.has(key) ||
+                    (existing?.sensitive ?? false) ||
+                    isSensitiveConfigEntry(key, value),
                 resolved: true,
             });
         }
@@ -302,7 +347,7 @@ export function sourceResultsToEntries(results, sources) {
                 source: result.source,
                 sourceType: result.type,
                 priority: source?.priority ?? 0,
-                sensitive: sensitiveKeys.has(key),
+                sensitive: sensitiveKeys.has(key) || isSensitiveConfigEntry(key, value),
             }));
         }
     }

package/dist/configLoader/configLoader.reload.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Atomic reload support for the configuration loader.
+ *
+ * Reloading used to re-apply sources on top of the live store without
+ * clearing it. A value that a higher-priority source stopped providing
+ * then stayed forever, because its entry still carried the higher
+ * priority and no lower source could replace it; and a source failing
+ * partway left the store half-applied.
+ */
+import type { ConfigStore } from "../configStore/configStore.core.js";
+/**
+ * Creates a staging store holding only the entries no source owns
+ * (runtime writes, initial values).
+ */
+export declare function createReloadStaging(store: ConfigStore, sourceNames: ReadonlySet<string>, freeze: boolean): ConfigStore;
+/**
+ * Copies a fully loaded staging store into the live store: keys the
+ * reload no longer produces are removed, the rest are written. An entry
+ * that was sensitive before the reload stays sensitive.
+ */
+export declare function commitReloadStaging(store: ConfigStore, staging: ConfigStore): void;
+//# sourceMappingURL=configLoader.reload.d.ts.map

package/dist/configLoader/configLoader.reload.js

@@ -0,0 +1,48 @@
+/**
+ * Atomic reload support for the configuration loader.
+ *
+ * Reloading used to re-apply sources on top of the live store without
+ * clearing it. A value that a higher-priority source stopped providing
+ * then stayed forever, because its entry still carried the higher
+ * priority and no lower source could replace it; and a source failing
+ * partway left the store half-applied.
+ */
+import { createConfigStore } from "../configStore/configStore.factory.js";
+/**
+ * Whether an entry was written by one of the loader's sources (and so must
+ * be re-derived on reload) rather than by `set()` or `initialValues`.
+ */
+function isSourceEntry(entry, sourceNames) {
+    return sourceNames.has(entry.source);
+}
+/**
+ * Creates a staging store holding only the entries no source owns
+ * (runtime writes, initial values).
+ */
+export function createReloadStaging(store, sourceNames, freeze) {
+    const staging = createConfigStore({ freeze });
+    for (const entry of store.getEntries()) {
+        if (!isSourceEntry(entry, sourceNames))
+            staging.setEntry(entry);
+    }
+    return staging;
+}
+/**
+ * Copies a fully loaded staging store into the live store: keys the
+ * reload no longer produces are removed, the rest are written. An entry
+ * that was sensitive before the reload stays sensitive.
+ */
+export function commitReloadStaging(store, staging) {
+    const wasSensitive = new Set(store
+        .getEntries()
+        .filter((entry) => entry.sensitive)
+        .map((entry) => entry.key));
+    for (const key of store.keys()) {
+        if (!staging.has(key))
+            store.delete(key);
+    }
+    for (const entry of staging.getEntries()) {
+        store.setEntry(wasSensitive.has(entry.key) ? { ...entry, sensitive: true } : entry);
+    }
+}
+//# sourceMappingURL=configLoader.reload.js.map

package/dist/configManager/configManager.core.js

@@ -6,6 +6,7 @@ import { createConfigStore } from "../configStore/configStore.factory.js";
 import { createConfigResolver } from "../configResolver/core/configResolver.factory.js";
 import { ConfigManagerState } from "./configManager.type.js";
 import { ConfigManagerValidationError } from "./configManager.error.js";
+import { collectSecretPaths, markSecretEntries, } from "./configManager.secrets.js";
 /**
  * Central configuration lifecycle manager.
  *
@@ -37,15 +38,21 @@ export class ConfigManager {
         this.store =
             suppliedStore ??
                 createConfigStore({
-                    initialValues: options.initialValues,
                     freeze: options.freeze ?? true,
                 });
         // initialValues used to be wired ONLY into a store the manager
         // created itself: passing `store` or `loader` silently discarded
-        // them. Seed a supplied store explicitly instead.
-        if (suppliedStore && options.initialValues) {
+        // them. Both paths are seeded here instead, at the baseline
+        // priority 0. A source that declares no priority now ranks below
+        // that (DEFAULT_CONFIG_SOURCE_PRIORITY), so it can no longer wipe
+        // the seeds; a source that declares a priority of 0 or above
+        // still overrides them.
+        if (options.initialValues) {
             for (const [key, value] of Object.entries(options.initialValues)) {
-                suppliedStore.set(key, value, { source: "initialValues" });
+                this.store.set(key, value, {
+                    source: "initialValues",
+                    priority: 0,
+                });
             }
         }
         this.name = options.name ?? "config";
@@ -211,23 +218,9 @@ export class ConfigManager {
         if (!result.valid) {
             throw new ConfigManagerValidationError(result.issues);
         }
-        // Property schemas flagged `secret` mark the corresponding store
-        // entries as sensitive so safe serialization redacts them.
-        for (const [key, propertySchema] of Object.entries(schema.properties)) {
-            if (!propertySchema.secret) {
-                continue;
-            }
-            const entry = this.store.getEntry(key);
-            if (entry && !entry.sensitive) {
-                this.store.set(key, entry.value, {
-                    source: entry.source,
-                    sourceType: entry.sourceType,
-                    priority: entry.priority,
-                    sensitive: true,
-                    resolved: entry.resolved,
-                });
-            }
-        }
+        // Schemas flagged `secret` at any depth mark the store entries that
+        // hold them as sensitive, so safe serialization redacts them.
+        markSecretEntries(this.store, collectSecretPaths(schema.properties));
         return cloneConfigValue(result.value);
     }
     /**
@@ -308,7 +301,10 @@ export class ConfigManager {
         return this.store.set(key, value, {
             source: options.source ?? "runtime",
             priority: options.priority ?? Number.MAX_SAFE_INTEGER,
-            sensitive: options.sensitive ?? false,
+            // Left undefined so the store's own secret detection runs; an
+            // explicit `false` here would have disabled it for every runtime
+            // write.
+            sensitive: options.sensitive,
         });
     }
     /**

package/dist/configManager/configManager.secrets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Secret propagation from a validation schema onto store entries.
+ *
+ * `validate()` used to look only at the top level of `schema.properties`,
+ * so `db.properties.password.secret` — or a `"db.password"` property when
+ * the source supplied a nested `db` object — never marked anything
+ * sensitive, and `toSafeObject()` printed the password.
+ */
+import type { AnyConfigSchema } from "../configSchema/index.js";
+import type { ConfigStore } from "../configStore/configStore.core.js";
+/**
+ * Every path (as dotted-key segments) at which a schema declares
+ * `secret: true`, including inside nested object and array schemas.
+ * Array items contribute the path of the array itself.
+ */
+export declare function collectSecretPaths(properties: Readonly<Record<string, AnyConfigSchema>>): string[][];
+/**
+ * Marks sensitive every store entry that holds a secret path.
+ *
+ * A path is owned by the entry whose key is its longest dotted prefix, so
+ * both a flat `db.password` entry and a nested `db` object entry are found.
+ * When the secret sits inside an entry's value the whole entry is marked,
+ * since redaction works per entry. A path with no owning entry holds no
+ * value, so there is nothing to redact.
+ */
+export declare function markSecretEntries(store: ConfigStore, paths: readonly (readonly string[])[]): void;
+//# sourceMappingURL=configManager.secrets.d.ts.map

package/dist/configManager/configManager.secrets.js

@@ -0,0 +1,69 @@
+/**
+ * Secret propagation from a validation schema onto store entries.
+ *
+ * `validate()` used to look only at the top level of `schema.properties`,
+ * so `db.properties.password.secret` — or a `"db.password"` property when
+ * the source supplied a nested `db` object — never marked anything
+ * sensitive, and `toSafeObject()` printed the password.
+ */
+/** Nesting bound for the schema walk. */
+const MAX_SCHEMA_DEPTH = 32;
+/**
+ * Every path (as dotted-key segments) at which a schema declares
+ * `secret: true`, including inside nested object and array schemas.
+ * Array items contribute the path of the array itself.
+ */
+export function collectSecretPaths(properties) {
+    const paths = [];
+    const walk = (schema, path, depth) => {
+        if (schema.secret) {
+            paths.push(path);
+            return;
+        }
+        if (depth >= MAX_SCHEMA_DEPTH)
+            return;
+        const nested = schema;
+        for (const [key, child] of Object.entries(nested.properties ?? {})) {
+            walk(child, [...path, ...key.split(".")], depth + 1);
+        }
+        if (nested.items)
+            walk(nested.items, path, depth + 1);
+        if (typeof nested.additionalProperties === "object" &&
+            nested.additionalProperties.secret) {
+            paths.push(path);
+        }
+    };
+    for (const [key, schema] of Object.entries(properties)) {
+        walk(schema, key.split("."), 1);
+    }
+    return paths;
+}
+/**
+ * Marks sensitive every store entry that holds a secret path.
+ *
+ * A path is owned by the entry whose key is its longest dotted prefix, so
+ * both a flat `db.password` entry and a nested `db` object entry are found.
+ * When the secret sits inside an entry's value the whole entry is marked,
+ * since redaction works per entry. A path with no owning entry holds no
+ * value, so there is nothing to redact.
+ */
+export function markSecretEntries(store, paths) {
+    for (const path of paths) {
+        for (let length = path.length; length > 0; length--) {
+            const entry = store.getEntry(path.slice(0, length).join("."));
+            if (!entry)
+                continue;
+            if (!entry.sensitive) {
+                store.set(entry.key, entry.value, {
+                    source: entry.source,
+                    sourceType: entry.sourceType,
+                    priority: entry.priority,
+                    sensitive: true,
+                    resolved: entry.resolved,
+                });
+            }
+            break;
+        }
+    }
+}
+//# sourceMappingURL=configManager.secrets.js.map

package/dist/configSource/configSource.core.d.ts

@@ -77,6 +77,16 @@ export interface ConfigSourceOptions {
  * Checks whether a value is a configuration source.
  */
 export declare function isConfigSource(value: unknown): value is ConfigSource;
+/**
+ * Priority given to a source that declares none.
+ *
+ * Strictly below the priority `initialValues` and other baseline store
+ * writes use (0). A source used to default to 0 as well, and because
+ * `applySource` overwrites on EQUAL priority, any undeclared source
+ * silently wiped the values a manager was seeded with. Declaring a
+ * priority of 0 or above still overrides them.
+ */
+export declare const DEFAULT_CONFIG_SOURCE_PRIORITY = -1;
 /**
  * Creates a function-based configuration source.
  */

package/dist/configSource/configSource.core.js

@@ -32,12 +32,22 @@ export function isConfigSource(value) {
         typeof source.optional === "boolean" &&
         typeof source.load === "function");
 }
+/**
+ * Priority given to a source that declares none.
+ *
+ * Strictly below the priority `initialValues` and other baseline store
+ * writes use (0). A source used to default to 0 as well, and because
+ * `applySource` overwrites on EQUAL priority, any undeclared source
+ * silently wiped the values a manager was seeded with. Declaring a
+ * priority of 0 or above still overrides them.
+ */
+export const DEFAULT_CONFIG_SOURCE_PRIORITY = -1;
 /**
  * Creates a function-based configuration source.
  */
 export function createConfigSource(options, loader) {
     const type = options.type ?? ConfigSourceType.CUSTOM;
-    const priority = options.priority ?? 0;
+    const priority = options.priority ?? DEFAULT_CONFIG_SOURCE_PRIORITY;
     if (options.name.trim().length === 0) {
         throw new TypeError("Configuration source name cannot be empty.");
     }

package/dist/configSource/configSource.environment.d.ts

@@ -42,11 +42,13 @@ export interface EnvironmentConfigSourceOptions {
     readonly keyMapper?: (name: string) => string;
     /**
      * Decides whether a variable holds a secret. Receives the ORIGINAL
-     * variable name and the derived configuration key. Defaults to a
-     * name pattern covering passwords, tokens, API keys and credentials.
+     * variable name and the derived configuration key. Defaults to
+     * `isSensitiveConfigKey` (passwords, tokens, API/private keys,
+     * credentials, DSNs, database URLs, `*_KEY`).
      *
-     * Pass `() => false` to opt out — values are then NOT redacted by
-     * safe serialization.
+     * Returning false does not un-redact: the loader still marks keys and
+     * values that `isSensitiveConfigEntry` flags (for example a URL with
+     * embedded `user:password@`).
      */
     readonly isSensitive?: (name: string, key: string) => boolean;
 }

package/dist/configSource/configSource.environment.js

@@ -7,14 +7,7 @@
  */
 import { defineConfigProperty } from "../configValue/configValue.core.js";
 import { ConfigSourceType, createConfigSource } from "./configSource.core.js";
-/**
- * Environment variable names whose values are treated as secrets.
- *
- * Matching entries are reported through `sensitiveKeys`, so
- * `toSafeObject()` and safe entry serialization redact them instead of
- * printing credentials into logs.
- */
-const DEFAULT_SECRET_PATTERN = /(pass(word)?|secret|token|api[_.-]?key|private[_.-]?key|credential|auth)/i;
+import { isSensitiveConfigKey } from "./configSource.sensitive.js";
 /**
  * Maps an environment variable name to a configuration key.
  */
@@ -37,7 +30,7 @@ export function createEnvironmentConfigSource(options = {}) {
     const prefix = options.prefix ?? "";
     const keyMapper = options.keyMapper ?? defaultKeyMapper;
     const isSensitive = options.isSensitive ??
-        ((name) => DEFAULT_SECRET_PATTERN.test(name));
+        ((name, key) => isSensitiveConfigKey(name) || isSensitiveConfigKey(key));
     const name = options.name ?? "environment";
     return createConfigSource({
         name,

package/dist/configSource/configSource.sensitive.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Name- and value-based secret detection shared by every configuration
+ * source.
+ *
+ * Only the environment source used to redact by name, so a `password` or
+ * `api_key` supplied by a memory, defaults or custom source was printed in
+ * clear by `toSafeObject()`, and even the environment pattern missed
+ * `DATABASE_URL`-style connection strings and `*_KEY` names.
+ */
+/**
+ * Returns whether a configuration key names a secret (passwords, tokens,
+ * API/private keys, credentials, DSNs, database URLs, `*_key`).
+ */
+export declare function isSensitiveConfigKey(key: string): boolean;
+/**
+ * Returns whether a configuration value holds a secret: a string URL with
+ * embedded `user:password@` credentials, or a nested object with a key that
+ * {@link isSensitiveConfigKey} flags anywhere inside it.
+ */
+export declare function isSensitiveConfigValue(value: unknown): boolean;
+/**
+ * Whether an entry loaded under `key` with `value` must be marked
+ * sensitive.
+ */
+export declare function isSensitiveConfigEntry(key: string, value: unknown): boolean;
+//# sourceMappingURL=configSource.sensitive.d.ts.map

package/dist/configSource/configSource.sensitive.js

@@ -0,0 +1,65 @@
+/**
+ * Name- and value-based secret detection shared by every configuration
+ * source.
+ *
+ * Only the environment source used to redact by name, so a `password` or
+ * `api_key` supplied by a memory, defaults or custom source was printed in
+ * clear by `toSafeObject()`, and even the environment pattern missed
+ * `DATABASE_URL`-style connection strings and `*_KEY` names.
+ */
+/**
+ * Key names treated as secrets. Matched case-insensitively against the
+ * whole dotted key, so any path segment can trigger it.
+ */
+const SENSITIVE_KEY_PATTERN = /(pass(word|wd)?|secret|token|api[_.-]?key|private[_.-]?key|credential|auth|dsn|database[_.-]?url|connection[_.-]?string|(^|[_.-])key$|(^|[_.-])key[_.-])/i;
+/** `scheme://user:password@host` — a URL with embedded credentials. */
+const CREDENTIAL_URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\/[^\s/@:]*:[^\s/@]*@/i;
+/** Nesting bound for {@link isSensitiveConfigValue}. */
+const MAX_SCAN_DEPTH = 32;
+/**
+ * Returns whether a configuration key names a secret (passwords, tokens,
+ * API/private keys, credentials, DSNs, database URLs, `*_key`).
+ */
+export function isSensitiveConfigKey(key) {
+    return SENSITIVE_KEY_PATTERN.test(key);
+}
+/**
+ * Returns whether a configuration value holds a secret: a string URL with
+ * embedded `user:password@` credentials, or a nested object with a key that
+ * {@link isSensitiveConfigKey} flags anywhere inside it.
+ */
+export function isSensitiveConfigValue(value) {
+    const pending = [
+        { value, depth: 0 },
+    ];
+    while (pending.length > 0) {
+        const next = pending.pop();
+        const current = next.value;
+        if (typeof current === "string") {
+            if (CREDENTIAL_URL_PATTERN.test(current))
+                return true;
+            continue;
+        }
+        if (typeof current !== "object" || current === null)
+            continue;
+        if (next.depth >= MAX_SCAN_DEPTH || current instanceof Date)
+            continue;
+        const entries = Array.isArray(current)
+            ? current.map((item, index) => [String(index), item])
+            : Object.entries(current);
+        for (const [key, child] of entries) {
+            if (!Array.isArray(current) && isSensitiveConfigKey(key))
+                return true;
+            pending.push({ value: child, depth: next.depth + 1 });
+        }
+    }
+    return false;
+}
+/**
+ * Whether an entry loaded under `key` with `value` must be marked
+ * sensitive.
+ */
+export function isSensitiveConfigEntry(key, value) {
+    return isSensitiveConfigKey(key) || isSensitiveConfigValue(value);
+}
+//# sourceMappingURL=configSource.sensitive.js.map

package/dist/configSource/index.d.ts

@@ -5,4 +5,5 @@
  */
 export * from "./configSource.core.js";
 export * from "./configSource.environment.js";
+export * from "./configSource.sensitive.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/configSource/index.js

@@ -5,4 +5,5 @@
  */
 export * from "./configSource.core.js";
 export * from "./configSource.environment.js";
+export * from "./configSource.sensitive.js";
 //# sourceMappingURL=index.js.map

package/dist/configStore/configStore.core.js

@@ -1,5 +1,6 @@
 import { cloneConfigValue, configValuesEqual, defineConfigProperty, freezeConfigValue, } from "../configValue/configValue.core.js";
 import { createConfigEntry, toSafeConfigEntry, } from "../configEntry/configEntry.type.js";
+import { isSensitiveConfigEntry } from "../configSource/configSource.sensitive.js";
 /**
  * Normalizes a configuration key.
  */
@@ -97,7 +98,12 @@ export class ConfigStore {
             source: options.source ?? "runtime",
             sourceType: options.sourceType,
             priority: options.priority ?? 0,
-            sensitive: options.sensitive ?? false,
+            // Secret detection belongs HERE, not at a single caller. It used
+            // to run only inside ConfigLoader.applySource, so the very same
+            // key was redacted when it arrived from a source and printed in
+            // clear when it arrived through initialValues, set(), setMany()
+            // or replace(). Pass `sensitive: false` explicitly to opt out.
+            sensitive: options.sensitive ?? isSensitiveConfigEntry(normalizedKey, value),
             resolved: options.resolved ?? true,
         });
         if (previous &&

package/dist/configValue/configValue.core.d.ts

@@ -30,6 +30,18 @@ export type ResolvedConfigValue = string | number | boolean | bigint | null | un
 };
 /**
  * Checks whether an object key is unsafe to copy onto plain objects.
+ *
+ * Assigning these keys (most notably "__proto__") on a plain object
+ * mutates its prototype instead of creating an own property, which
+ * enables prototype-pollution attacks via untrusted configuration
+ * payloads such as JSON.parse output. The key set is
+ * `SCHEMA_FORBIDDEN_KEYS` from `@zudojs/constants`, shared with
+ * `@zudojs/schema`, `@zudojs/validation` and `@zudojs/cache`.
+ *
+ * The package itself never needs this check to stay safe: every key
+ * write goes through {@link defineConfigProperty}, which keeps such keys
+ * as inert own properties. Use it when copying configuration into code
+ * that assigns with `target[key] = value` or `Object.assign`.
  */
 export declare function isUnsafeConfigKey(key: string): boolean;
 /**
@@ -72,7 +84,8 @@ export declare function parseConfigString(value: string | undefined): ConfigPrim
  */
 export declare function parseConfigBoolean(value: string | boolean | undefined): boolean | undefined;
 /**
- * Parses a numeric configuration value.
+ * Parses a numeric configuration value. Only decimal notation is
+ * accepted; hex, binary and octal strings return `undefined`.
  */
 export declare function parseConfigNumber(value: string | number | undefined): number | undefined;
 /**

package/dist/configValue/configValue.core.js

@@ -6,24 +6,24 @@
  * possible, while allowing common runtime values such as undefined,
  * Date, and Buffer-like binary data to be handled safely.
  */
+import { SCHEMA_FORBIDDEN_KEYS } from "@zudojs/constants";
 /**
- * Object keys that must never be copied onto plain objects.
+ * Checks whether an object key is unsafe to copy onto plain objects.
  *
  * Assigning these keys (most notably "__proto__") on a plain object
  * mutates its prototype instead of creating an own property, which
  * enables prototype-pollution attacks via untrusted configuration
- * payloads such as JSON.parse output.
- */
-const UNSAFE_CONFIG_KEYS = new Set([
-    "__proto__",
-    "constructor",
-    "prototype",
-]);
-/**
- * Checks whether an object key is unsafe to copy onto plain objects.
+ * payloads such as JSON.parse output. The key set is
+ * `SCHEMA_FORBIDDEN_KEYS` from `@zudojs/constants`, shared with
+ * `@zudojs/schema`, `@zudojs/validation` and `@zudojs/cache`.
+ *
+ * The package itself never needs this check to stay safe: every key
+ * write goes through {@link defineConfigProperty}, which keeps such keys
+ * as inert own properties. Use it when copying configuration into code
+ * that assigns with `target[key] = value` or `Object.assign`.
  */
 export function isUnsafeConfigKey(key) {
-    return UNSAFE_CONFIG_KEYS.has(key);
+    return SCHEMA_FORBIDDEN_KEYS.has(key);
 }
 /**
  * Checks whether a value is a configuration primitive.
@@ -103,8 +103,10 @@ export function toConfigJsonValue(value) {
         const result = {};
         for (const [key, child] of Object.entries(value)) {
             const converted = toConfigJsonValue(child);
+            // Defined, never assigned: an own "__proto__" key from a JSON or
+            // remote source would otherwise replace the result's prototype.
             if (converted !== undefined) {
-                result[key] = converted;
+                defineConfigProperty(result, key, converted);
             }
         }
         return result;
@@ -184,8 +186,11 @@ export function parseConfigBoolean(value) {
             return undefined;
     }
 }
+/** Optionally signed decimal number, with optional fraction and exponent. */
+const DECIMAL_NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i;
 /**
- * Parses a numeric configuration value.
+ * Parses a numeric configuration value. Only decimal notation is
+ * accepted; hex, binary and octal strings return `undefined`.
  */
 export function parseConfigNumber(value) {
     if (value === undefined) {
@@ -198,6 +203,11 @@ export function parseConfigNumber(value) {
     if (normalized.length === 0) {
         return undefined;
     }
+    // Decimal only. `Number()` also accepts "0x1F90", "0b11" and "0o17",
+    // so a port of "0x1F90" silently became 8080.
+    if (!DECIMAL_NUMBER.test(normalized)) {
+        return undefined;
+    }
     const parsed = Number(normalized);
     return Number.isFinite(parsed) ? parsed : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/config",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Layered configuration management with multiple sources, validation, and environment-specific overrides.",
   "license": "MIT",
   "author": {
@@ -28,7 +28,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/constants": "1.1.1",
+    "@zudojs/errors": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",