@zudojs/config 0.1.0 → 1.0.1

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

@@ -17,16 +17,6 @@ export declare enum ConfigSourceType {
     REMOTE = "remote",
     CUSTOM = "custom"
 }
-/**
- * A single configuration value supplied by a source.
- */
-export interface ConfigSourceEntry {
-    readonly key: string;
-    readonly value: ConfigValue;
-    readonly source: string;
-    readonly priority?: number;
-    readonly sensitive?: boolean;
-}
 /**
  * Context supplied to a configuration source while loading values.
  */
@@ -42,6 +32,13 @@ export interface ConfigSourceResult {
     readonly values: Readonly<Record<string, ConfigValue>>;
     readonly source: string;
     readonly type: ConfigSourceType;
+    /**
+     * Keys within `values` whose entries must be marked sensitive.
+     *
+     * Sensitive entries are redacted by safe serialization paths such
+     * as ConfigStore.toSafeObject() and toSafeConfigEntry().
+     */
+    readonly sensitiveKeys?: readonly string[];
 }
 /**
  * Configuration source contract.
@@ -100,12 +97,21 @@ export declare function createDefaultsConfigSource(values: Readonly<Record<strin
 export declare function createCustomConfigSource(name: string, loader: ConfigSourceLoader, options?: Omit<ConfigSourceOptions, "name" | "type">): FunctionConfigSource;
 /**
  * Normalizes a source result.
+ *
+ * Note on reference semantics: the returned `values` record is a
+ * frozen SHALLOW copy — nested objects and arrays are still shared
+ * with the object the source returned. Consumers that need isolation
+ * (e.g. the loader/store with freeze enabled) clone values before
+ * storing them.
  */
 export declare function normalizeConfigSourceResult(result: ConfigSourceResult, fallbackName: string, fallbackType: ConfigSourceType): ConfigSourceResult;
 /**
  * Sorts configuration sources by priority.
  *
- * Higher-priority sources are returned first.
+ * Higher-priority sources are returned first. Sources with equal
+ * priority keep their REGISTRATION ORDER (the sort is stable), so
+ * among equal priorities the last-registered source is applied last
+ * and wins.
  */
 export declare function sortConfigSources(sources: readonly ConfigSource[]): readonly ConfigSource[];
 /**
@@ -124,6 +130,17 @@ export declare function deduplicateConfigSources(sources: readonly ConfigSource[
  * Optional sources are allowed to fail without preventing startup.
  */
 export declare function loadConfigSource(source: ConfigSource, context?: ConfigSourceContext): Promise<ConfigSourceResult | undefined>;
+/**
+ * Loads a single configuration source WITHOUT swallowing failures.
+ *
+ * An unavailable optional source still resolves to `undefined`, but
+ * every other failure propagates so callers can route it to their own
+ * error handling (ConfigLoader forwards it to `onSourceError`).
+ *
+ * This is the single implementation of the source loading contract;
+ * `loadConfigSource` is the error-swallowing wrapper around it.
+ */
+export declare function loadConfigSourceStrict(source: ConfigSource, context?: ConfigSourceContext): Promise<ConfigSourceResult | undefined>;
 /**
  * Loads multiple configuration sources in priority order.
  */

package/dist/configSource/configSource.core.js

@@ -99,6 +99,12 @@ export function createCustomConfigSource(name, loader, options = {}) {
 }
 /**
  * Normalizes a source result.
+ *
+ * Note on reference semantics: the returned `values` record is a
+ * frozen SHALLOW copy — nested objects and arrays are still shared
+ * with the object the source returned. Consumers that need isolation
+ * (e.g. the loader/store with freeze enabled) clone values before
+ * storing them.
  */
 export function normalizeConfigSourceResult(result, fallbackName, fallbackType) {
     if (!result || typeof result !== "object") {
@@ -115,20 +121,23 @@ export function normalizeConfigSourceResult(result, fallbackName, fallbackType)
         values: Object.freeze({
             ...result.values,
         }),
+        ...(result.sensitiveKeys
+            ? { sensitiveKeys: Object.freeze([...result.sensitiveKeys]) }
+            : {}),
     });
 }
 /**
  * Sorts configuration sources by priority.
  *
- * Higher-priority sources are returned first.
+ * Higher-priority sources are returned first. Sources with equal
+ * priority keep their REGISTRATION ORDER (the sort is stable), so
+ * among equal priorities the last-registered source is applied last
+ * and wins.
  */
 export function sortConfigSources(sources) {
-    return [...sources].sort((left, right) => {
-        if (right.priority !== left.priority) {
-            return right.priority - left.priority;
-        }
-        return left.name.localeCompare(right.name);
-    });
+    // Array.prototype.sort is stable, so equal priorities preserve the
+    // original registration order.
+    return [...sources].sort((left, right) => right.priority - left.priority);
 }
 /**
  * Finds a source by name.
@@ -160,16 +169,7 @@ export function deduplicateConfigSources(sources) {
  */
 export async function loadConfigSource(source, context = {}) {
     try {
-        if (source.isAvailable) {
-            const available = await source.isAvailable(context);
-            if (!available) {
-                if (source.optional) {
-                    return undefined;
-                }
-                throw new Error(`Configuration source "${source.name}" is unavailable.`);
-            }
-        }
-        return await source.load(context);
+        return await loadConfigSourceStrict(source, context);
     }
     catch (error) {
         if (source.optional) {
@@ -178,6 +178,32 @@ export async function loadConfigSource(source, context = {}) {
         throw error;
     }
 }
+/**
+ * Loads a single configuration source WITHOUT swallowing failures.
+ *
+ * An unavailable optional source still resolves to `undefined`, but
+ * every other failure propagates so callers can route it to their own
+ * error handling (ConfigLoader forwards it to `onSourceError`).
+ *
+ * This is the single implementation of the source loading contract;
+ * `loadConfigSource` is the error-swallowing wrapper around it.
+ */
+export async function loadConfigSourceStrict(source, context = {}) {
+    if (source.isAvailable) {
+        const available = await source.isAvailable(context);
+        if (!available) {
+            if (source.optional) {
+                return undefined;
+            }
+            throw new Error(`Configuration source "${source.name}" is unavailable.`);
+        }
+    }
+    const result = await source.load(context);
+    if (!result || typeof result !== "object") {
+        throw new Error(`Configuration source "${source.name}" returned an invalid result.`);
+    }
+    return result;
+}
 /**
  * Loads multiple configuration sources in priority order.
  */

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

@@ -0,0 +1,66 @@
+/**
+ * Environment-variable configuration source.
+ *
+ * ConfigSourceType.ENVIRONMENT existed from the first release but no
+ * implementation ever shipped, so the documented "environment-specific
+ * settings" use case had to be hand-rolled by every consumer.
+ */
+import type { ConfigSource } from "./configSource.core.js";
+/**
+ * Options for the environment configuration source.
+ */
+export interface EnvironmentConfigSourceOptions {
+    /**
+     * Only variables starting with this prefix are read. The prefix is
+     * removed from the resulting configuration key. When omitted, every
+     * variable is read — rarely what an application wants.
+     */
+    readonly prefix?: string;
+    /**
+     * Source name (default "environment").
+     */
+    readonly name?: string;
+    /**
+     * Source priority (default 100, above in-memory defaults).
+     */
+    readonly priority?: number;
+    /**
+     * Whether load failures are tolerated (default false).
+     */
+    readonly optional?: boolean;
+    /**
+     * Variable map to read. Defaults to `process.env`.
+     */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Overrides the default variable-name to configuration-key mapping.
+     * Receives the name with `prefix` already removed.
+     *
+     * The default lowercases the name and maps "__" to "." so
+     * `APP__DB__HOST` becomes `db.host` under the prefix `APP__`.
+     */
+    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.
+     *
+     * Pass `() => false` to opt out — values are then NOT redacted by
+     * safe serialization.
+     */
+    readonly isSensitive?: (name: string, key: string) => boolean;
+}
+/**
+ * Creates a configuration source backed by environment variables.
+ *
+ * Values are returned as RAW STRINGS: no boolean or numeric inference
+ * happens here, because guessing types from strings is how `"false"`
+ * ends up truthy. Use the typed accessors (`manager.number(key)`,
+ * `manager.boolean(key)`) which coerce explicitly and reject values
+ * that do not parse.
+ *
+ * Variables whose value is `undefined` are skipped; a variable set to
+ * the empty string is kept, since "set but empty" is meaningful.
+ */
+export declare function createEnvironmentConfigSource(options?: EnvironmentConfigSourceOptions): ConfigSource;
+//# sourceMappingURL=configSource.environment.d.ts.map

package/dist/configSource/configSource.environment.js

@@ -0,0 +1,75 @@
+/**
+ * Environment-variable configuration source.
+ *
+ * ConfigSourceType.ENVIRONMENT existed from the first release but no
+ * implementation ever shipped, so the documented "environment-specific
+ * settings" use case had to be hand-rolled by every consumer.
+ */
+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;
+/**
+ * Maps an environment variable name to a configuration key.
+ */
+function defaultKeyMapper(name) {
+    return name.toLowerCase().split("__").join(".");
+}
+/**
+ * Creates a configuration source backed by environment variables.
+ *
+ * Values are returned as RAW STRINGS: no boolean or numeric inference
+ * happens here, because guessing types from strings is how `"false"`
+ * ends up truthy. Use the typed accessors (`manager.number(key)`,
+ * `manager.boolean(key)`) which coerce explicitly and reject values
+ * that do not parse.
+ *
+ * Variables whose value is `undefined` are skipped; a variable set to
+ * the empty string is kept, since "set but empty" is meaningful.
+ */
+export function createEnvironmentConfigSource(options = {}) {
+    const prefix = options.prefix ?? "";
+    const keyMapper = options.keyMapper ?? defaultKeyMapper;
+    const isSensitive = options.isSensitive ??
+        ((name) => DEFAULT_SECRET_PATTERN.test(name));
+    const name = options.name ?? "environment";
+    return createConfigSource({
+        name,
+        type: ConfigSourceType.ENVIRONMENT,
+        priority: options.priority ?? 100,
+        optional: options.optional ?? false,
+    }, () => {
+        const env = options.env ?? process.env;
+        const values = {};
+        const sensitiveKeys = [];
+        for (const [variable, raw] of Object.entries(env)) {
+            if (raw === undefined) {
+                continue;
+            }
+            if (prefix.length > 0 && !variable.startsWith(prefix)) {
+                continue;
+            }
+            const key = keyMapper(variable.slice(prefix.length));
+            if (key.length === 0) {
+                continue;
+            }
+            defineConfigProperty(values, key, raw);
+            if (isSensitive(variable, key)) {
+                sensitiveKeys.push(key);
+            }
+        }
+        return {
+            source: name,
+            type: ConfigSourceType.ENVIRONMENT,
+            values,
+            sensitiveKeys,
+        };
+    });
+}
+//# sourceMappingURL=configSource.environment.js.map

package/dist/configSource/index.d.ts

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

package/dist/configSource/index.js

@@ -4,4 +4,5 @@
  * Configuration source abstractions and implementations.
  */
 export * from "./configSource.core.js";
+export * from "./configSource.environment.js";
 //# sourceMappingURL=index.js.map

package/dist/configStore/configStore.core.d.ts

@@ -87,8 +87,23 @@ export declare class ConfigStore {
     values(): readonly ConfigValue[];
     /**
      * Returns a plain object containing all configuration values.
+     *
+     * WARNING: values are returned RAW — sensitive entries are NOT
+     * redacted. Use toSafeObject() for logging or diagnostics.
+     *
+     * The returned object is a defensive snapshot: when the store does
+     * not freeze values, each value is deep-cloned so later mutations
+     * of the snapshot never affect the store (and vice versa). Frozen
+     * stores share their (immutable) values directly.
      */
     toObject(): Readonly<Record<string, ConfigValue>>;
+    /**
+     * Returns a plain object with sensitive values redacted.
+     *
+     * Entries marked sensitive are replaced with "[REDACTED]". This is
+     * the safe counterpart to toObject() for logging and diagnostics.
+     */
+    toSafeObject(): Readonly<Record<string, ConfigValue>>;
     /**
      * Returns entries matching a prefix.
      */

package/dist/configStore/configStore.core.js

@@ -1,5 +1,5 @@
-import { cloneConfigValue, configValuesEqual, freezeConfigValue, } from "../configValue/configValue.core.js";
-import { createConfigEntry } from "../configEntry/configEntry.type.js";
+import { cloneConfigValue, configValuesEqual, defineConfigProperty, freezeConfigValue, } from "../configValue/configValue.core.js";
+import { createConfigEntry, toSafeConfigEntry, } from "../configEntry/configEntry.type.js";
 /**
  * Normalizes a configuration key.
  */
@@ -107,7 +107,9 @@ export class ConfigStore {
             previous.priority === entry.priority &&
             previous.sensitive === entry.sensitive &&
             previous.resolved === entry.resolved) {
-            return entry;
+            // No-op write: return the entry that is actually stored so
+            // callers always hold a reference to live store state.
+            return previous;
         }
         this.entries.set(normalizedKey, entry);
         this.emitChange({
@@ -199,18 +201,46 @@ export class ConfigStore {
     }
     /**
      * Returns a plain object containing all configuration values.
+     *
+     * WARNING: values are returned RAW — sensitive entries are NOT
+     * redacted. Use toSafeObject() for logging or diagnostics.
+     *
+     * The returned object is a defensive snapshot: when the store does
+     * not freeze values, each value is deep-cloned so later mutations
+     * of the snapshot never affect the store (and vice versa). Frozen
+     * stores share their (immutable) values directly.
      */
     toObject() {
         this.assertActive();
         const result = {};
         for (const entry of this.entries.values()) {
-            result[entry.key] = entry.value;
+            // Keys come from configuration sources and may be hostile
+            // ("__proto__"): define them instead of assigning so they can
+            // never reach an inherited setter.
+            defineConfigProperty(result, entry.key, this.shouldFreeze ? entry.value : cloneConfigValue(entry.value));
         }
         if (this.shouldFreeze) {
             freezeConfigValue(result);
         }
         return result;
     }
+    /**
+     * Returns a plain object with sensitive values redacted.
+     *
+     * Entries marked sensitive are replaced with "[REDACTED]". This is
+     * the safe counterpart to toObject() for logging and diagnostics.
+     */
+    toSafeObject() {
+        this.assertActive();
+        const result = {};
+        for (const entry of this.entries.values()) {
+            const safeEntry = toSafeConfigEntry(entry);
+            defineConfigProperty(result, safeEntry.key, safeEntry.sensitive
+                ? safeEntry.value
+                : cloneConfigValue(safeEntry.value));
+        }
+        return Object.freeze(result);
+    }
     /**
      * Returns entries matching a prefix.
      */
@@ -232,7 +262,7 @@ export class ConfigStore {
                 ? ""
                 : entry.key.slice(normalizedPrefix.length + 1);
             if (key.length > 0) {
-                result[key] = entry.value;
+                defineConfigProperty(result, key, entry.value);
             }
         }
         if (this.shouldFreeze) {

package/dist/configStore/configStore.type.d.ts

@@ -19,6 +19,17 @@ export type ConfigChangeListener = (event: ConfigChangeEvent) => void;
 export interface ConfigStoreOptions {
     readonly initialValues?: Readonly<Record<string, ConfigValue>>;
     readonly entries?: readonly ConfigEntry[];
+    /**
+     * Whether stored values are deep-cloned and deep-frozen on write
+     * (default true).
+     *
+     * When `false`, the store keeps REFERENCES to the exact objects
+     * passed to `set()`: callers can still mutate them afterwards and
+     * those mutations are visible through the store. `get()` likewise
+     * returns the shared reference. Only `toObject()` defends against
+     * this by cloning. Use `freeze: false` only for trusted,
+     * performance-sensitive code that treats values as immutable.
+     */
     readonly freeze?: boolean;
 }
 //# sourceMappingURL=configStore.type.d.ts.map

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

@@ -28,6 +28,10 @@ export type ConfigValue = ConfigPrimitive | Date | ConfigValue[] | {
 export type ResolvedConfigValue = string | number | boolean | bigint | null | undefined | Date | ResolvedConfigValue[] | {
     readonly [key: string]: ResolvedConfigValue;
 };
+/**
+ * Checks whether an object key is unsafe to copy onto plain objects.
+ */
+export declare function isUnsafeConfigKey(key: string): boolean;
 /**
  * Checks whether a value is a configuration primitive.
  */
@@ -84,14 +88,48 @@ export declare function parseConfigDate(value: string | Date | undefined): Date
  *
  * Configuration objects should normally be immutable after
  * resolution to prevent accidental runtime mutation.
+ *
+ * A shallow-frozen container is still traversed so its nested
+ * children are frozen as well. Non-plain objects (class instances)
+ * are returned by reference WITHOUT being frozen — consistent with
+ * cloneConfigValue, which also returns such values by reference.
+ * Values are assumed to be acyclic, as required by ConfigValue.
  */
 export declare function freezeConfigValue<T extends ConfigValue>(value: T): T;
 /**
  * Deeply clones a configuration value.
+ *
+ * Plain objects, arrays, and Dates are copied deeply. Non-plain
+ * objects (class instances) are returned BY REFERENCE — the clone
+ * shares them with the original (freezeConfigValue treats them the
+ * same way and never freezes them). Unsafe keys ("__proto__",
+ * "constructor", "prototype") are copied as own data properties via
+ * Object.defineProperty, so untrusted payloads can never pollute a
+ * prototype through the clone.
  */
 export declare function cloneConfigValue<T extends ConfigValue>(value: T): T;
 /**
  * Compares two configuration values deeply.
  */
 export declare function configValuesEqual(left: ConfigValue, right: ConfigValue): boolean;
+/**
+ * Assigns a key onto a plain object without prototype pollution.
+ *
+ * Plain assignment (`target[key] = value`) invokes inherited setters:
+ * for the key "__proto__" that REPLACES the target's prototype instead
+ * of creating an own property, which both loses the value and lets an
+ * untrusted configuration key mutate object shape. Defining the
+ * property explicitly always creates an own, enumerable data property,
+ * so keys such as "__proto__", "constructor" and "prototype" survive
+ * round-trips without ever reaching a setter.
+ */
+export declare function defineConfigProperty(target: Record<string, ConfigValue>, key: string, value: ConfigValue): void;
+/**
+ * Reads an OWN property from a configuration-shaped object.
+ *
+ * Bracket access would walk the prototype chain, so a schema property
+ * named "constructor" or "toString" would read an inherited function
+ * rather than reporting a missing value.
+ */
+export declare function readOwnConfigProperty(source: Readonly<Record<string, unknown>>, key: string): unknown;
 //# sourceMappingURL=configValue.core.d.ts.map

package/dist/configValue/configValue.core.js

@@ -6,6 +6,25 @@
  * possible, while allowing common runtime values such as undefined,
  * Date, and Buffer-like binary data to be handled safely.
  */
+/**
+ * Object keys that must never be copied 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.
+ */
+export function isUnsafeConfigKey(key) {
+    return UNSAFE_CONFIG_KEYS.has(key);
+}
 /**
  * Checks whether a value is a configuration primitive.
  */
@@ -223,26 +242,43 @@ export function parseConfigDate(value) {
  *
  * Configuration objects should normally be immutable after
  * resolution to prevent accidental runtime mutation.
+ *
+ * A shallow-frozen container is still traversed so its nested
+ * children are frozen as well. Non-plain objects (class instances)
+ * are returned by reference WITHOUT being frozen — consistent with
+ * cloneConfigValue, which also returns such values by reference.
+ * Values are assumed to be acyclic, as required by ConfigValue.
  */
 export function freezeConfigValue(value) {
     if (typeof value !== "object" || value === null) {
         return value;
     }
-    if (Object.isFrozen(value)) {
-        return value;
-    }
     if (value instanceof Date) {
-        return Object.freeze(value);
+        return Object.isFrozen(value) ? value : Object.freeze(value);
+    }
+    if (!Array.isArray(value) && !isConfigObject(value)) {
+        // Non-plain values (class instances) are intentionally left
+        // untouched; they are not valid ConfigValues and callers keep
+        // full ownership of them.
+        return value;
     }
     for (const child of Object.values(value)) {
-        if (isConfigValue(child)) {
+        if (typeof child === "object" && child !== null) {
             freezeConfigValue(child);
         }
     }
-    return Object.freeze(value);
+    return Object.isFrozen(value) ? value : Object.freeze(value);
 }
 /**
  * Deeply clones a configuration value.
+ *
+ * Plain objects, arrays, and Dates are copied deeply. Non-plain
+ * objects (class instances) are returned BY REFERENCE — the clone
+ * shares them with the original (freezeConfigValue treats them the
+ * same way and never freezes them). Unsafe keys ("__proto__",
+ * "constructor", "prototype") are copied as own data properties via
+ * Object.defineProperty, so untrusted payloads can never pollute a
+ * prototype through the clone.
  */
 export function cloneConfigValue(value) {
     if (value === null || value === undefined || typeof value !== "object") {
@@ -257,7 +293,11 @@ export function cloneConfigValue(value) {
     if (isConfigObject(value)) {
         const result = {};
         for (const [key, child] of Object.entries(value)) {
-            result[key] = cloneConfigValue(child);
+            // Unsafe keys ("__proto__" and friends) are preserved as own
+            // data properties rather than assigned: assignment would reach
+            // the inherited "__proto__" setter and mutate the clone's
+            // prototype instead of copying the value.
+            defineConfigProperty(result, key, cloneConfigValue(child));
         }
         return result;
     }
@@ -290,4 +330,35 @@ export function configValuesEqual(left, right) {
     }
     return false;
 }
+/**
+ * Assigns a key onto a plain object without prototype pollution.
+ *
+ * Plain assignment (`target[key] = value`) invokes inherited setters:
+ * for the key "__proto__" that REPLACES the target's prototype instead
+ * of creating an own property, which both loses the value and lets an
+ * untrusted configuration key mutate object shape. Defining the
+ * property explicitly always creates an own, enumerable data property,
+ * so keys such as "__proto__", "constructor" and "prototype" survive
+ * round-trips without ever reaching a setter.
+ */
+export function defineConfigProperty(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+/**
+ * Reads an OWN property from a configuration-shaped object.
+ *
+ * Bracket access would walk the prototype chain, so a schema property
+ * named "constructor" or "toString" would read an inherited function
+ * rather than reporting a missing value.
+ */
+export function readOwnConfigProperty(source, key) {
+    return Object.prototype.hasOwnProperty.call(source, key)
+        ? source[key]
+        : undefined;
+}
 //# sourceMappingURL=configValue.core.js.map