@zudojs/config 1.0.0 → 1.1.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
@@ -58,8 +64,8 @@ priorities are applied in registration order (last registered wins).
 - `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 +89,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 +108,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 +134,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.
 
@@ -133,7 +152,12 @@ standalone `validateConfigValue`.
 
 `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. 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 +165,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 { isSensitiveConfigEntry } from "../configSource/configSource.sensitive.js";
+import { commitReloadStaging, createReloadStaging, } from "./configLoader.reload.js";
 import { createConfigStore } from "../configStore/configStore.factory.js";
 /**
  * Configuration loader.
@@ -128,12 +130,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 +269,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 +287,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 +343,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.
  *
@@ -211,23 +212,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);
     }
     /**

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/configSchema/configSchema.validator.js

@@ -124,8 +124,26 @@ function appendCustomValidationResult(result, path, issues) {
     }
     issues.push(result);
 }
+/**
+ * Compiles a string schema pattern for a one-shot `test`.
+ *
+ * A RegExp carrying the `g` or `y` flag keeps `lastIndex` between calls, so
+ * the same schema object alternated between accepting and rejecting an
+ * identical value on successive validations. Both flags are dropped; they
+ * have no meaning for a whole-value match.
+ */
+function compilePattern(pattern) {
+    if (typeof pattern === "string") {
+        return new RegExp(pattern);
+    }
+    const flags = pattern.flags.replace(/[gy]/g, "");
+    return flags === pattern.flags ? pattern : new RegExp(pattern.source, flags);
+}
 /**
  * Built-in schema validation rules.
+ *
+ * Returns a replacement value when a rule rewrote it (an array whose item
+ * schema applied `transform` or `default`), otherwise undefined.
  */
 function validateBuiltInRules(value, schema, context, issues) {
     if (typeof value === "string") {
@@ -139,9 +157,7 @@ function validateBuiltInRules(value, schema, context, issues) {
             issues.push(createConfigValidationIssue(context.path, `Value must contain at most ${stringSchema.maxLength} characters.`, "MAX_LENGTH"));
         }
         if (stringSchema.pattern) {
-            const pattern = typeof stringSchema.pattern === "string"
-                ? new RegExp(stringSchema.pattern)
-                : stringSchema.pattern;
+            const pattern = compilePattern(stringSchema.pattern);
             if (!pattern.test(value)) {
                 issues.push(createConfigValidationIssue(context.path, "Value does not match the required pattern.", "PATTERN"));
             }
@@ -176,6 +192,11 @@ function validateBuiltInRules(value, schema, context, issues) {
             issues.push(createConfigValidationIssue(context.path, `Array must contain at most ${arraySchema.maxItems} items.`, "MAX_ITEMS"));
         }
         if (arraySchema.items) {
+            // Item results used to be consulted for issues only, so an item
+            // schema's `transform` (or `default`) ran and its output was thrown
+            // away: the caller got the untransformed array back as "valid".
+            const rebuilt = [];
+            let allValid = true;
             value.forEach((item, index) => {
                 const result = validateConfigValue(item, arraySchema.items, {
                     path: `${context.path}[${index}]`,
@@ -184,9 +205,15 @@ function validateBuiltInRules(value, schema, context, issues) {
                     key: index,
                 });
                 issues.push(...result.issues);
+                if (!result.valid) {
+                    allValid = false;
+                }
+                rebuilt.push(result.value === undefined ? item : result.value);
             });
+            return allValid ? rebuilt : undefined;
         }
     }
+    return undefined;
 }
 /**
  * Validates a value against a schema.
@@ -239,7 +266,7 @@ export function validateConfigValue(value, schema, context) {
             issues,
         };
     }
-    validateBuiltInRules(value, schema, validationContext, issues);
+    const rewritten = validateBuiltInRules(value, schema, validationContext, issues);
     // An object schema carries `properties` / `additionalProperties`.
     // Those were declared on ConfigObjectSchema but read nowhere in this
     // function, so every nested object schema — including the ones used
@@ -247,7 +274,7 @@ export function validateConfigValue(value, schema, context) {
     // validation unconditionally. Delegate to validateConfigObject so
     // nested constraints are actually enforced.
     const objectSchema = schema;
-    let base = value;
+    let base = rewritten ?? value;
     if (matchesConfigType(value, ConfigValueType.OBJECT) &&
         (objectSchema.properties !== undefined ||
             objectSchema.additionalProperties !== undefined)) {

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/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,8 +1,12 @@
 {
   "name": "@zudojs/config",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Layered configuration management with multiple sources, validation, and environment-specific overrides.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -24,7 +28,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/errors": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",