@pawells/config-provider-env 3.0.0-rc1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phillip Aaron Wells
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# @pawells/config-provider-env
+
+[![CI](https://github.com/PhillipAWells/config/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/config/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@pawells/config-provider-env)](https://www.npmjs.com/package/@pawells/config-provider-env)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+## Description
+
+`@pawells/config-provider-env` is a configuration provider for `@pawells/config` that loads settings from `process.env` and an optional `.env` file. Values in the dotenv file overwrite `process.env` for the same key. Environment variable strings are parsed to their native JavaScript types (numbers, booleans, arrays, `null`) before being handed to `ConfigManager` for schema validation.
+
+The provider also supports writing configuration back to disk (`Save`), making it suitable for generating `.env.example` templates and snapshotting live values.
+
+See the [workspace README](../../README.md) for an end-to-end quick start. See [CHANGELOG.md](../../CHANGELOG.md) for version history.
+
+## Requirements
+
+- Node.js `>=22.0.0`
+- `@pawells/config` (peer dependency, installed as a direct dependency via `workspace:*` in the monorepo)
+
+## Installation
+
+```sh
+yarn add @pawells/config-provider-env @pawells/config
+```
+
+All packages are ESM-only (`"type": "module"`).
+
+## Quick Start
+
+```typescript
+import { ConfigManager, RegisterConfigSchema, Secret } from '@pawells/config';
+import { ConfigEnvironmentProvider } from '@pawells/config-provider-env';
+import { z } from 'zod';
+
+// Register the provider BEFORE importing any schema modules.
+// The factory method creates, registers, and returns the provider instance.
+const envProvider = await ConfigEnvironmentProvider.Register({ path: '.env' });
+
+// Define a schema — provider values are already available.
+const AppConfig = RegisterConfigSchema('App', z.object({
+    HOST: z.string().min(1).default('localhost'),
+    PORT: z.coerce.number().int().positive().default(3000),
+    API_KEY: Secret(z.string().min(1)).default(''),
+}));
+
+// Read typed values.
+const host = AppConfig.Get('HOST'); // string
+const port = AppConfig.Get('PORT'); // number
+
+// Generate .env.example — defaults written; secrets blank.
+await ConfigManager.Save(envProvider, { path: '.env.example' });
+
+// Snapshot current runtime values — secrets included.
+await ConfigManager.Save(envProvider, { path: '.env.snapshot', useCurrentValues: true });
+```
+
+## API Reference
+
+### `ConfigEnvironmentProvider`
+
+An async configuration provider that extends `ConfigProvider` from `@pawells/config`.
+
+#### `static Register(options?)`
+
+Convenience factory: creates a `ConfigEnvironmentProvider` instance, registers it with `ConfigManager`, and returns it.
+
+```typescript
+static async Register(
+    options?: Partial<TConfigENVProviderOptions>
+): Promise<ConfigEnvironmentProvider>
+```
+
+Unspecified options use schema defaults (`name: 'environment'`, `path: <cwd>/.env`).
+
+```typescript
+// Register with all defaults
+const provider = await ConfigEnvironmentProvider.Register();
+
+// Register with a custom path
+const provider = await ConfigEnvironmentProvider.Register({
+    path: '.env.production'
+});
+```
+
+#### Constructor
+
+```typescript
+new ConfigEnvironmentProvider(options: TConfigENVProviderOptions)
+```
+
+After constructing, pass the instance to `ConfigManager.RegisterProvider` manually if you need the instance before registration:
+
+```typescript
+import { ConfigManager } from '@pawells/config';
+import { ConfigEnvironmentProvider } from '@pawells/config-provider-env';
+
+const provider = new ConfigEnvironmentProvider({ name: 'env', path: '.env' });
+await ConfigManager.RegisterProvider(provider);
+```
+
+#### `Load()`
+
+```typescript
+async Load(): Promise<Record<string, unknown>>
+```
+
+Loads configuration from `process.env` and optionally the `.env` file at `options.path`:
+
+1. All entries in `process.env` are read first.
+2. If `options.path` is set, the dotenv file is parsed and its entries overwrite `process.env` values for the same key.
+3. All string values are passed through an internal parser that converts JSON-encoded booleans, numbers, arrays, and `null` to their native JavaScript types. Plain strings are returned unchanged.
+4. If the dotenv file is absent (`ENOENT`), it is silently skipped — only `process.env` is returned.
+5. Security exceptions (symlink path, path-traversal sequence) are propagated as errors.
+
+```typescript
+// .env: APP_PORT=8080
+// process.env: APP_HOST=prod.example.com
+const values = await provider.Load();
+// → { APP_HOST: 'prod.example.com', APP_PORT: 8080 }
+```
+
+**Throws** `ConfigError` when the dotenv path is a symlink or contains a `..` traversal sequence.
+
+#### `Save(entries, options?)`
+
+```typescript
+async Save(
+    entries: readonly ConfigSaveEntry[],
+    options?: TConfigENVProviderSaveOptions
+): Promise<void>
+```
+
+Writes configuration entries to a `.env`-format file. Call via `ConfigManager.Save` rather than directly.
+
+**Template mode** (`useCurrentValues: false`, the default):
+- Each entry is written as `KEY=<default value>`.
+- Entries where `entry.isSecret` is `true` are written as `KEY=` (blank value), regardless of their default.
+- This is suitable for generating `.env.example` files safe to commit.
+
+**Current-values mode** (`useCurrentValues: true`):
+- All entries including secrets are written with their live resolved values.
+- Use for runtime snapshots or debugging.
+
+If a Zod `.describe()` annotation is present on the field, it is emitted as a `# comment` line immediately before the key.
+
+```typescript
+// Template output in .env.example:
+// # Server port
+// APP_PORT=3000
+// # API key
+// APP_API_KEY=
+```
+
+**Options:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `path` | `string` (optional) | `this.options.path` | Output file path; overrides the constructor path if provided. |
+| `useCurrentValues` | `boolean` (optional) | `false` | `false` = registered defaults, secrets blank; `true` = live resolved values. |
+
+---
+
+### Options types
+
+#### `TConfigENVProviderOptions`
+
+```typescript
+type TConfigENVProviderOptions = {
+    name: string  // Default: 'environment'
+    path: string  // Default: <cwd>/.env; '..' sequences are rejected
+}
+```
+
+Validated by `CONFIG_ENV_PROVIDER_OPTIONS_SCHEMA`.
+
+#### `TConfigENVProviderSaveOptions`
+
+```typescript
+type TConfigENVProviderSaveOptions = {
+    path?: string            // Overrides constructor path if provided; '..' sequences are rejected
+    useCurrentValues?: boolean  // Default: false
+}
+```
+
+Validated by `CONFIG_ENV_PROVIDER_SAVE_OPTIONS_SCHEMA`.
+
+---
+
+### Assertion and validation utilities
+
+| Export | Description |
+|---|---|
+| `CONFIG_ENV_PROVIDER_OPTIONS_SCHEMA` | Zod schema for `TConfigENVProviderOptions` |
+| `AssertConfigENVProviderOptions(options)` | Asserts conformance; throws `ZodError` otherwise |
+| `ValidateConfigENVProviderOptions(options)` | Returns `true` if valid; `false` otherwise |
+| `CONFIG_ENV_PROVIDER_SAVE_OPTIONS_SCHEMA` | Zod schema for `TConfigENVProviderSaveOptions` |
+| `AssertConfigENVProviderSaveOptions(options)` | Asserts conformance; throws `ZodError` otherwise |
+| `ValidateConfigENVProviderSaveOptions(options)` | Returns `true` if valid; `false` otherwise |
+
+---
+
+### Security
+
+- **Symlink rejection** — The dotenv path is checked; if it resolves to a symlink, `Load()` throws a `ConfigError`.
+- **Path-traversal protection** — Any path containing `..` is rejected by the options schema at construction time and at save time.
+
+## License
+
+MIT — See [LICENSE](../../LICENSE) for details.

package/dist/env-utils.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Intelligently parses an environment variable string to its native JavaScript type.
+ *
+ * Attempts `JSON.parse()` to convert encoded booleans (`'true'`), numbers (`'42'`),
+ * arrays (`'["a","b"]'`), and `null` to their native JavaScript equivalents.
+ * Falls back to returning the original string unchanged if JSON parsing fails.
+ * Uses a fast-path optimization to skip `JSON.parse()` for plain strings.
+ *
+ * @param envVarValue - Raw string value read from `process.env`
+ * @returns Parsed value; a native JS type if JSON-parseable, otherwise the original string
+ *
+ * @remarks
+ * The string `"null"` is parsed by `JSON.parse()` and returns the JavaScript `null` value
+ * (not the string `"null"`). Schemas that expect a string will reject this value via `safeParse()`.
+ *
+ * @example
+ * ```typescript
+ * ParseEnvVarValue('true')        // → true (boolean)
+ * ParseEnvVarValue('42')          // → 42 (number)
+ * ParseEnvVarValue('["a","b"]')   // → ['a', 'b'] (string[])
+ * ParseEnvVarValue('hello world') // → 'hello world' (string, unchanged)
+ * ```
+ */
+export declare function ParseEnvVarValue(envVarValue: string): unknown;
+/**
+ * Parses a `.env` file from disk into a flat key/value record.
+ *
+ * Processing rules (applied per line):
+ * - Lines beginning with `#` (after trimming whitespace) are treated as comments and skipped
+ * - Blank lines are skipped
+ * - Lines containing `=` are split on the first `=`; the key is trimmed; the value is trimmed
+ *   and surrounding single- or double-quotes are stripped if present
+ * - Inline comments (e.g. `KEY=value # comment`) are stripped from unquoted values
+ * - Lines without `=` are skipped
+ * - Windows-style `\r\n` line endings are normalized automatically
+ * - Paths containing `..` traversal sequences are rejected for security
+ * - Symbolic links are not permitted for security (both final component and parent directories)
+ *
+ * @param path - Path to the `.env` file to read
+ * @returns A promise resolving to a record mapping each key to its raw string value
+ * @throws {ConfigError} When the path contains `..` directory traversal sequences
+ * @throws {ConfigError} When the path is a symbolic link (final component or parent directory)
+ * @throws {Error} If the file cannot be read (e.g. not found, permission denied)
+ *
+ * @remarks
+ * Parent directories are canonicalized via realpath to detect symlinked ancestor directories.
+ * The final path component is checked via O_NOFOLLOW for atomic symlink rejection.
+ * Inline comments must be preceded by a space to be recognized (e.g., `KEY=value # comment`).
+ * A `#` that is not preceded by a space is treated as part of the value.
+ *
+ * @example
+ * ```typescript
+ * // .env contents:
+ * // # Database configuration
+ * // HOST=localhost
+ * // PORT=3000
+ * // SECRET="my-token"
+ * const values = await ParseDotEnvFileAsync('./.env');
+ * // → { HOST: 'localhost', PORT: '3000', SECRET: 'my-token' }
+ * ```
+ */
+export declare function ParseDotEnvFileAsync(path: string): Promise<Record<string, string>>;
+/**
+ * Serializes a configuration value to its `.env` string representation.
+ *
+ * Conversion rules:
+ * - `null` or `undefined` → `''` (blank)
+ * - Arrays → JSON-stringified (e.g. `["a","b"]`)
+ * - Plain objects → JSON-stringified
+ * - `Date` → ISO 8601 string
+ * - All other values → `String(value)`
+ *
+ * @param value - The configuration value to serialize
+ * @returns The serialized string ready for inclusion in a `.env` file
+ *
+ * @example
+ * ```typescript
+ * SerializeConfigValue('hello')          // → 'hello'
+ * SerializeConfigValue(42)               // → '42'
+ * SerializeConfigValue(true)             // → 'true'
+ * SerializeConfigValue(['a', 'b'])       // → '["a","b"]'
+ * SerializeConfigValue({ key: 'value' }) // → '{"key":"value"}'
+ * SerializeConfigValue(new Date('2024-01-01T00:00:00.000Z'))
+ * // → '2024-01-01T00:00:00.000Z'
+ * SerializeConfigValue(null)             // → ''
+ * SerializeConfigValue(undefined)        // → ''
+ * ```
+ */
+export declare function SerializeConfigValue(value: unknown): string;
+//# sourceMappingURL=env-utils.d.ts.map

package/dist/env-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-utils.d.ts","sourceRoot":"","sources":["../src/env-utils.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAqB7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA8ExF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAM3D"}

package/dist/env-utils.js

@@ -0,0 +1,185 @@
+import { promises as fs, constants as fsConstants } from 'node:fs';
+import { normalize, dirname, basename, join } from 'node:path';
+import { ConfigError } from '@pawells/config';
+/**
+ * Intelligently parses an environment variable string to its native JavaScript type.
+ *
+ * Attempts `JSON.parse()` to convert encoded booleans (`'true'`), numbers (`'42'`),
+ * arrays (`'["a","b"]'`), and `null` to their native JavaScript equivalents.
+ * Falls back to returning the original string unchanged if JSON parsing fails.
+ * Uses a fast-path optimization to skip `JSON.parse()` for plain strings.
+ *
+ * @param envVarValue - Raw string value read from `process.env`
+ * @returns Parsed value; a native JS type if JSON-parseable, otherwise the original string
+ *
+ * @remarks
+ * The string `"null"` is parsed by `JSON.parse()` and returns the JavaScript `null` value
+ * (not the string `"null"`). Schemas that expect a string will reject this value via `safeParse()`.
+ *
+ * @example
+ * ```typescript
+ * ParseEnvVarValue('true')        // → true (boolean)
+ * ParseEnvVarValue('42')          // → 42 (number)
+ * ParseEnvVarValue('["a","b"]')   // → ['a', 'b'] (string[])
+ * ParseEnvVarValue('hello world') // → 'hello world' (string, unchanged)
+ * ```
+ */
+export function ParseEnvVarValue(envVarValue) {
+    // Fast path: skip JSON.parse for plain strings that cannot be valid JSON
+    const firstChar = envVarValue[0];
+    if (firstChar !== '{'
+        && firstChar !== '['
+        && firstChar !== '"'
+        && envVarValue !== 'true'
+        && envVarValue !== 'false'
+        && envVarValue !== 'null'
+        && !/^-?\d/.test(envVarValue)) {
+        return envVarValue;
+    }
+    try {
+        return JSON.parse(envVarValue);
+    }
+    catch {
+        return envVarValue;
+    }
+}
+/**
+ * Parses a `.env` file from disk into a flat key/value record.
+ *
+ * Processing rules (applied per line):
+ * - Lines beginning with `#` (after trimming whitespace) are treated as comments and skipped
+ * - Blank lines are skipped
+ * - Lines containing `=` are split on the first `=`; the key is trimmed; the value is trimmed
+ *   and surrounding single- or double-quotes are stripped if present
+ * - Inline comments (e.g. `KEY=value # comment`) are stripped from unquoted values
+ * - Lines without `=` are skipped
+ * - Windows-style `\r\n` line endings are normalized automatically
+ * - Paths containing `..` traversal sequences are rejected for security
+ * - Symbolic links are not permitted for security (both final component and parent directories)
+ *
+ * @param path - Path to the `.env` file to read
+ * @returns A promise resolving to a record mapping each key to its raw string value
+ * @throws {ConfigError} When the path contains `..` directory traversal sequences
+ * @throws {ConfigError} When the path is a symbolic link (final component or parent directory)
+ * @throws {Error} If the file cannot be read (e.g. not found, permission denied)
+ *
+ * @remarks
+ * Parent directories are canonicalized via realpath to detect symlinked ancestor directories.
+ * The final path component is checked via O_NOFOLLOW for atomic symlink rejection.
+ * Inline comments must be preceded by a space to be recognized (e.g., `KEY=value # comment`).
+ * A `#` that is not preceded by a space is treated as part of the value.
+ *
+ * @example
+ * ```typescript
+ * // .env contents:
+ * // # Database configuration
+ * // HOST=localhost
+ * // PORT=3000
+ * // SECRET="my-token"
+ * const values = await ParseDotEnvFileAsync('./.env');
+ * // → { HOST: 'localhost', PORT: '3000', SECRET: 'my-token' }
+ * ```
+ */
+export async function ParseDotEnvFileAsync(path) {
+    if (normalize(path).includes('..'))
+        throw new ConfigError(`Path traversal sequences ("..") are not permitted. Received: "${path}"`);
+    try {
+        // Canonicalize parent directory to detect symlinked ancestors
+        const realParent = await fs.realpath(dirname(path));
+        const safePath = join(realParent, basename(path));
+        // Open file with O_NOFOLLOW to reject symlink final component atomically
+        const filehandle = await fs.open(safePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        let raw;
+        try {
+            const buffer = await filehandle.readFile();
+            raw = buffer.toString('utf-8');
+        }
+        finally {
+            await filehandle.close();
+        }
+        const result = {};
+        for (const rawLine of raw.split('\n')) {
+            const line = rawLine.replace(/\r$/, '').trim();
+            if (line === '' || line.startsWith('#'))
+                continue;
+            const eqIdx = line.indexOf('=');
+            if (eqIdx === -1)
+                continue;
+            const key = line.slice(0, eqIdx).trim();
+            let value = line.slice(eqIdx + 1).trim();
+            if ((value.startsWith('"') && value.endsWith('"'))
+                || (value.startsWith('\'') && value.endsWith('\''))) {
+                value = value.slice(1, -1);
+            }
+            else {
+                // Strip inline # comments (only if value is not quoted)
+                const commentIdx = value.indexOf(' #');
+                if (commentIdx !== -1) {
+                    value = value.slice(0, commentIdx).trim();
+                }
+            }
+            if (key !== '') {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        // If it's already a ConfigError, rethrow it
+        if (error instanceof ConfigError) {
+            throw error;
+        }
+        // Check error codes from fs.open and realpath
+        const errorCode = error instanceof Error ? error.code : undefined;
+        // ELOOP (Linux) or ENOTDIR (macOS) indicate symlink in final component
+        if (errorCode === 'ELOOP' || errorCode === 'ENOTDIR') {
+            throw new ConfigError('Symlink paths are not permitted.');
+        }
+        // Check if it's ENOENT (file not found) — allow optional dotenv files to return empty
+        const isNotFound = errorCode === 'ENOENT';
+        // If file is missing, return empty config (dotenv files are optional by nature)
+        if (isNotFound) {
+            return {};
+        }
+        // All other errors (permission, etc.) are rethrown
+        throw error;
+    }
+}
+/**
+ * Serializes a configuration value to its `.env` string representation.
+ *
+ * Conversion rules:
+ * - `null` or `undefined` → `''` (blank)
+ * - Arrays → JSON-stringified (e.g. `["a","b"]`)
+ * - Plain objects → JSON-stringified
+ * - `Date` → ISO 8601 string
+ * - All other values → `String(value)`
+ *
+ * @param value - The configuration value to serialize
+ * @returns The serialized string ready for inclusion in a `.env` file
+ *
+ * @example
+ * ```typescript
+ * SerializeConfigValue('hello')          // → 'hello'
+ * SerializeConfigValue(42)               // → '42'
+ * SerializeConfigValue(true)             // → 'true'
+ * SerializeConfigValue(['a', 'b'])       // → '["a","b"]'
+ * SerializeConfigValue({ key: 'value' }) // → '{"key":"value"}'
+ * SerializeConfigValue(new Date('2024-01-01T00:00:00.000Z'))
+ * // → '2024-01-01T00:00:00.000Z'
+ * SerializeConfigValue(null)             // → ''
+ * SerializeConfigValue(undefined)        // → ''
+ * ```
+ */
+export function SerializeConfigValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return JSON.stringify(value);
+    if (value !== null && typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+//# sourceMappingURL=env-utils.js.map

package/dist/env-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-utils.js","sourceRoot":"","sources":["../src/env-utils.ts"],"names":[],"mappings":"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"}

package/dist/environment-provider.d.ts

@@ -0,0 +1,226 @@
+import { z } from 'zod/v4';
+import { ConfigProvider, type ConfigSaveEntry } from '@pawells/config';
+/**
+ * Zod schema for validating ConfigEnvironmentProvider constructor options.
+ *
+ * @remarks
+ * This schema extends the base {@link CONFIG_PROVIDER_OPTIONS_SCHEMA} with environment-specific fields:
+ * - `name`: Unique provider identifier (default: `'environment'`)
+ * - `path`: Path to the `.env` file to load (default: `.env` in current working directory);
+ *   paths containing `..` directory traversal sequences are rejected for security
+ */
+export declare const CONFIG_ENV_PROVIDER_OPTIONS_SCHEMA: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    path: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Runtime type extracted from {@link CONFIG_ENV_PROVIDER_OPTIONS_SCHEMA}.
+ *
+ * @example
+ * ```typescript
+ * const options: TConfigENVProviderOptions = {
+ *   name: 'my-env',
+ *   path: '.env.local'
+ * };
+ * ```
+ */
+export type TConfigENVProviderOptions = z.infer<typeof CONFIG_ENV_PROVIDER_OPTIONS_SCHEMA>;
+/**
+ * Asserts that a value conforms to {@link TConfigENVProviderOptions}.
+ *
+ * @param options - The value to validate
+ * @throws {ZodError} When validation fails
+ *
+ * @example
+ * ```typescript
+ * AssertConfigENVProviderOptions(userInput);
+ * // If no error, userInput is safely typed as TConfigENVProviderOptions
+ * ```
+ */
+export declare function AssertConfigENVProviderOptions(options: unknown): asserts options is TConfigENVProviderOptions;
+/**
+ * Validates whether a value conforms to {@link TConfigENVProviderOptions}.
+ *
+ * @param options - The value to validate
+ * @returns `true` if valid; `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (ValidateConfigENVProviderOptions(userInput)) {
+ *   // userInput is valid
+ * }
+ * ```
+ */
+export declare function ValidateConfigENVProviderOptions(options: unknown): boolean;
+/**
+ * Zod schema for validating ConfigEnvironmentProvider Save options.
+ *
+ * @remarks
+ * Extends the base {@link CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA} with:
+ * - `path`: Optional output file path; overrides constructor path if provided
+ */
+export declare const CONFIG_ENV_PROVIDER_SAVE_OPTIONS_SCHEMA: z.ZodObject<{
+    useCurrentValues: z.ZodOptional<z.ZodBoolean>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Runtime type extracted from {@link CONFIG_ENV_PROVIDER_SAVE_OPTIONS_SCHEMA}.
+ *
+ * @example
+ * ```typescript
+ * const options: TConfigENVProviderSaveOptions = {
+ *   path: '.env.example',
+ *   useCurrentValues: false
+ * };
+ * ```
+ */
+export type TConfigENVProviderSaveOptions = z.infer<typeof CONFIG_ENV_PROVIDER_SAVE_OPTIONS_SCHEMA>;
+/**
+ * Asserts that a value conforms to {@link TConfigENVProviderSaveOptions}.
+ *
+ * @param options - The value to validate
+ * @throws {ZodError} When validation fails
+ */
+export declare function AssertConfigENVProviderSaveOptions(options: unknown): asserts options is TConfigENVProviderSaveOptions;
+/**
+ * Validates whether a value conforms to {@link TConfigENVProviderSaveOptions}.
+ *
+ * @param options - The value to validate
+ * @returns `true` if valid; `false` otherwise
+ */
+export declare function ValidateConfigENVProviderSaveOptions(options: unknown): boolean;
+/**
+ * Configuration provider for environment variables and `.env` files.
+ *
+ * Loads configuration from `process.env` and an optional `.env` file. This provider
+ * implements the {@link ConfigProvider} interface, supporting both {@link Load} and
+ * {@link Save} operations. It is suitable for development environments and containerized
+ * deployments where configuration is typically provided via environment variables.
+ *
+ * @example
+ * ```typescript
+ * // Register with defaults
+ * const provider = await ConfigEnvironmentProvider.Register();
+ *
+ * // Register with custom path
+ * const provider = await ConfigEnvironmentProvider.Register({
+ *   path: '.env.production'
+ * });
+ *
+ * // Or instantiate directly
+ * const provider = new ConfigEnvironmentProvider({
+ *   name: 'app-env',
+ *   path: '.env'
+ * });
+ * await ConfigManager.RegisterProvider(provider);
+ * ```
+ */
+export declare class ConfigEnvironmentProvider extends ConfigProvider<TConfigENVProviderOptions, unknown, TConfigENVProviderSaveOptions> {
+    /**
+     * Initialize a configuration provider that loads from environment variables and a `.env` file.
+     *
+     * @param options - Provider configuration object with `name` and optional `path`
+     * @param options.name - Unique provider name (default: `'environment'`)
+     * @param options.path - Path to the `.env` file to load (default: `.env` in current working directory)
+     *
+     * @example
+     * ```typescript
+     * const provider = new ConfigEnvironmentProvider({
+     *   name: 'my-env-provider',
+     *   path: './.env.local'
+     * });
+     * ```
+     */
+    constructor(options: TConfigENVProviderOptions);
+    /**
+     * Load configuration values from `process.env` and, optionally, a `.env` file.
+     *
+     * Reads all entries in `process.env` first, then (if `options.path` is set)
+     * reads the dotenv file and overwrites any overlapping keys. All values are passed
+     * through {@link ParseEnvVarValue} before being returned.
+     *
+     * If the dotenv file is missing or cannot be read due to permission errors or other
+     * file system issues, the file is silently skipped and only environment variables are
+     * returned. The dotenv file is optional and its absence or read failure does not prevent
+     * configuration loading.
+     *
+     * Security rejections (symlink detection, path traversal) are propagated as errors.
+     *
+     * @returns A record of fully-qualified config key names to their parsed values
+     * @throws {ConfigError} When the dotenv path is a symlink or contains path traversal sequences
+     *
+     * @example
+     * ```typescript
+     * // process.env = { KEYCLOAK_HOST: 'prod.example.com' }
+     * // .env        = { KEYCLOAK_HOST: 'localhost', KEYCLOAK_PORT: '8080' }
+     * const provider = new ConfigEnvironmentProvider({
+     *   name: 'env',
+     *   path: '.env'
+     * });
+     * const config = await provider.Load();
+     * // → { KEYCLOAK_HOST: 'localhost', KEYCLOAK_PORT: 8080 }
+     * ```
+     */
+    Load(): Promise<Record<string, unknown>>;
+    /**
+     * Save configuration values to a `.env`-format file.
+     *
+     * In template mode (`useCurrentValues: false`, the default), each entry is
+     * written using its registered default value. Secret fields (where
+     * `entry.isSecret` is `true`) are always written with a blank value in
+     * template mode, regardless of their default — making this suitable for
+     * generating `.env.example` files.
+     *
+     * In current-values mode (`useCurrentValues: true`), the live resolved value
+     * is used for every field including secrets — suitable for snapshotting the
+     * active runtime configuration.
+     *
+     * If a field carries a description (from a Zod `.describe()` annotation) it
+     * is emitted as a `# comment` line immediately before the key–value pair.
+     *
+     * @param entries - All registered config entries supplied by {@link ConfigManager.Save}
+     * @param options - Save options
+     * @param options.path - Output file path; overrides `this.options.path` if provided
+     * @param options.useCurrentValues - When `true`, emit current live values; when `false` (default), emit registered defaults
+     *
+     * @example
+     * ```typescript
+     * const provider = new ConfigEnvironmentProvider({
+     *   name: 'env',
+     *   path: '.env'
+     * });
+     *
+     * // Generate a .env.example template (secrets blank)
+     * await ConfigManager.Save(provider, { path: '.env.example' });
+     *
+     * // Snapshot current runtime config (secrets included)
+     * await ConfigManager.Save(provider, {
+     *   path: '.env.snapshot',
+     *   useCurrentValues: true,
+     * });
+     * ```
+     */
+    Save(entries: readonly ConfigSaveEntry[], options?: TConfigENVProviderSaveOptions): Promise<void>;
+    /**
+     * Creates a ConfigEnvironmentProvider instance and registers it with ConfigManager.
+     *
+     * This is a convenience factory method that combines instantiation and registration in one call.
+     * Unspecified options use their schema defaults (`name: 'environment'`, `path: '.env'` in cwd).
+     *
+     * @param options - Optional partial provider configuration; unspecified fields use schema defaults
+     * @returns A promise resolving to the registered provider instance
+     *
+     * @example
+     * ```typescript
+     * // Register with all defaults
+     * const provider = await ConfigEnvironmentProvider.Register();
+     *
+     * // Register with custom path
+     * const provider = await ConfigEnvironmentProvider.Register({
+     *   path: '.env.production'
+     * });
+     * ```
+     */
+    static Register(options?: Partial<TConfigENVProviderOptions>): Promise<ConfigEnvironmentProvider>;
+}
+//# sourceMappingURL=environment-provider.d.ts.map

package/dist/environment-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-provider.d.ts","sourceRoot":"","sources":["../src/environment-provider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAuE,KAAK,eAAe,EAA8B,MAAM,iBAAiB,CAAC;AAGxK;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC;;;iBAK7C,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE3F;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,yBAAyB,CAE7G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAQ1E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uCAAuC;;;iBAIlD,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC;AAEpG;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,6BAA6B,CAErH;AAED;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAQ9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,yBAAyB,EAAE,OAAO,EAAE,6BAA6B,CAAC;IAC/H;;;;;;;;;;;;;;OAcG;gBACS,OAAO,EAAE,yBAAyB;IAK9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACU,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IA6BrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACU,IAAI,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,EAAE,OAAO,CAAC,EAAE,6BAA6B,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB9G;;;;;;;;;;;;;;;;;;;OAmBG;WACiB,QAAQ,CAAC,OAAO,GAAE,OAAO,CAAC,yBAAyB,CAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;CAKlH"}

package/dist/environment-provider.js

@@ -0,0 +1,278 @@
+import { promises as FS } from 'node:fs';
+import * as PATH from 'node:path';
+import { z } from 'zod/v4';
+import { ConfigProvider, CONFIG_PROVIDER_OPTIONS_SCHEMA, CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA, ConfigManager, ConfigError } from '@pawells/config';
+import { ParseEnvVarValue, ParseDotEnvFileAsync, SerializeConfigValue } from './env-utils.js';
+/**
+ * Zod schema for validating ConfigEnvironmentProvider constructor options.
+ *
+ * @remarks
+ * This schema extends the base {@link CONFIG_PROVIDER_OPTIONS_SCHEMA} with environment-specific fields:
+ * - `name`: Unique provider identifier (default: `'environment'`)
+ * - `path`: Path to the `.env` file to load (default: `.env` in current working directory);
+ *   paths containing `..` directory traversal sequences are rejected for security
+ */
+export const CONFIG_ENV_PROVIDER_OPTIONS_SCHEMA = CONFIG_PROVIDER_OPTIONS_SCHEMA.extend({
+    name: z.string().min(1).default('environment'),
+    path: z.string().min(1).default(PATH.join(process.cwd(), '.env')).refine((path) => !PATH.normalize(path).includes('..'), {
+        message: 'Path traversal sequences ("..") are not permitted.'
+    })
+});
+/**
+ * Asserts that a value conforms to {@link TConfigENVProviderOptions}.
+ *
+ * @param options - The value to validate
+ * @throws {ZodError} When validation fails
+ *
+ * @example
+ * ```typescript
+ * AssertConfigENVProviderOptions(userInput);
+ * // If no error, userInput is safely typed as TConfigENVProviderOptions
+ * ```
+ */
+export function AssertConfigENVProviderOptions(options) {
+    CONFIG_ENV_PROVIDER_OPTIONS_SCHEMA.parse(options);
+}
+/**
+ * Validates whether a value conforms to {@link TConfigENVProviderOptions}.
+ *
+ * @param options - The value to validate
+ * @returns `true` if valid; `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (ValidateConfigENVProviderOptions(userInput)) {
+ *   // userInput is valid
+ * }
+ * ```
+ */
+export function ValidateConfigENVProviderOptions(options) {
+    try {
+        AssertConfigENVProviderOptions(options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Zod schema for validating ConfigEnvironmentProvider Save options.
+ *
+ * @remarks
+ * Extends the base {@link CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA} with:
+ * - `path`: Optional output file path; overrides constructor path if provided
+ */
+export const CONFIG_ENV_PROVIDER_SAVE_OPTIONS_SCHEMA = CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA.extend({
+    path: z.string().min(1).refine((path) => !PATH.normalize(path).includes('..'), {
+        message: 'Path traversal sequences ("..") are not permitted.'
+    }).optional()
+});
+/**
+ * Asserts that a value conforms to {@link TConfigENVProviderSaveOptions}.
+ *
+ * @param options - The value to validate
+ * @throws {ZodError} When validation fails
+ */
+export function AssertConfigENVProviderSaveOptions(options) {
+    CONFIG_ENV_PROVIDER_SAVE_OPTIONS_SCHEMA.parse(options);
+}
+/**
+ * Validates whether a value conforms to {@link TConfigENVProviderSaveOptions}.
+ *
+ * @param options - The value to validate
+ * @returns `true` if valid; `false` otherwise
+ */
+export function ValidateConfigENVProviderSaveOptions(options) {
+    try {
+        AssertConfigENVProviderSaveOptions(options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Configuration provider for environment variables and `.env` files.
+ *
+ * Loads configuration from `process.env` and an optional `.env` file. This provider
+ * implements the {@link ConfigProvider} interface, supporting both {@link Load} and
+ * {@link Save} operations. It is suitable for development environments and containerized
+ * deployments where configuration is typically provided via environment variables.
+ *
+ * @example
+ * ```typescript
+ * // Register with defaults
+ * const provider = await ConfigEnvironmentProvider.Register();
+ *
+ * // Register with custom path
+ * const provider = await ConfigEnvironmentProvider.Register({
+ *   path: '.env.production'
+ * });
+ *
+ * // Or instantiate directly
+ * const provider = new ConfigEnvironmentProvider({
+ *   name: 'app-env',
+ *   path: '.env'
+ * });
+ * await ConfigManager.RegisterProvider(provider);
+ * ```
+ */
+export class ConfigEnvironmentProvider extends ConfigProvider {
+    /**
+     * Initialize a configuration provider that loads from environment variables and a `.env` file.
+     *
+     * @param options - Provider configuration object with `name` and optional `path`
+     * @param options.name - Unique provider name (default: `'environment'`)
+     * @param options.path - Path to the `.env` file to load (default: `.env` in current working directory)
+     *
+     * @example
+     * ```typescript
+     * const provider = new ConfigEnvironmentProvider({
+     *   name: 'my-env-provider',
+     *   path: './.env.local'
+     * });
+     * ```
+     */
+    constructor(options) {
+        super(options);
+        AssertConfigENVProviderOptions(options);
+    }
+    /**
+     * Load configuration values from `process.env` and, optionally, a `.env` file.
+     *
+     * Reads all entries in `process.env` first, then (if `options.path` is set)
+     * reads the dotenv file and overwrites any overlapping keys. All values are passed
+     * through {@link ParseEnvVarValue} before being returned.
+     *
+     * If the dotenv file is missing or cannot be read due to permission errors or other
+     * file system issues, the file is silently skipped and only environment variables are
+     * returned. The dotenv file is optional and its absence or read failure does not prevent
+     * configuration loading.
+     *
+     * Security rejections (symlink detection, path traversal) are propagated as errors.
+     *
+     * @returns A record of fully-qualified config key names to their parsed values
+     * @throws {ConfigError} When the dotenv path is a symlink or contains path traversal sequences
+     *
+     * @example
+     * ```typescript
+     * // process.env = { KEYCLOAK_HOST: 'prod.example.com' }
+     * // .env        = { KEYCLOAK_HOST: 'localhost', KEYCLOAK_PORT: '8080' }
+     * const provider = new ConfigEnvironmentProvider({
+     *   name: 'env',
+     *   path: '.env'
+     * });
+     * const config = await provider.Load();
+     * // → { KEYCLOAK_HOST: 'localhost', KEYCLOAK_PORT: 8080 }
+     * ```
+     */
+    async Load() {
+        const result = {};
+        for (const [key, value] of Object.entries(process.env)) {
+            if (value !== undefined) {
+                result[key] = ParseEnvVarValue(value);
+            }
+        }
+        if (this.options.path !== undefined) {
+            try {
+                const dotenv = await ParseDotEnvFileAsync(this.options.path);
+                for (const [key, value] of Object.entries(dotenv)) {
+                    result[key] = ParseEnvVarValue(value);
+                }
+            }
+            catch (error) {
+                // Re-throw ConfigError (security rejections: symlink, path traversal)
+                if (error instanceof ConfigError) {
+                    throw error;
+                }
+                // Silently skip other file errors (ENOENT, EACCES, etc.);
+                // dotenv is optional and fallback uses process.env values already collected
+            }
+        }
+        return result;
+    }
+    /**
+     * Save configuration values to a `.env`-format file.
+     *
+     * In template mode (`useCurrentValues: false`, the default), each entry is
+     * written using its registered default value. Secret fields (where
+     * `entry.isSecret` is `true`) are always written with a blank value in
+     * template mode, regardless of their default — making this suitable for
+     * generating `.env.example` files.
+     *
+     * In current-values mode (`useCurrentValues: true`), the live resolved value
+     * is used for every field including secrets — suitable for snapshotting the
+     * active runtime configuration.
+     *
+     * If a field carries a description (from a Zod `.describe()` annotation) it
+     * is emitted as a `# comment` line immediately before the key–value pair.
+     *
+     * @param entries - All registered config entries supplied by {@link ConfigManager.Save}
+     * @param options - Save options
+     * @param options.path - Output file path; overrides `this.options.path` if provided
+     * @param options.useCurrentValues - When `true`, emit current live values; when `false` (default), emit registered defaults
+     *
+     * @example
+     * ```typescript
+     * const provider = new ConfigEnvironmentProvider({
+     *   name: 'env',
+     *   path: '.env'
+     * });
+     *
+     * // Generate a .env.example template (secrets blank)
+     * await ConfigManager.Save(provider, { path: '.env.example' });
+     *
+     * // Snapshot current runtime config (secrets included)
+     * await ConfigManager.Save(provider, {
+     *   path: '.env.snapshot',
+     *   useCurrentValues: true,
+     * });
+     * ```
+     */
+    async Save(entries, options) {
+        if (options !== undefined)
+            AssertConfigENVProviderSaveOptions(options);
+        const useCurrentValues = options?.useCurrentValues ?? false;
+        const path = options?.path ?? this.options.path;
+        const lines = [];
+        for (const entry of entries) {
+            if (entry.description !== undefined) {
+                const safeDescription = entry.description.replace(/[\r\n]/g, ' ').replace(/#/g, '(hash)');
+                lines.push(`# ${safeDescription}`);
+            }
+            if (!useCurrentValues && entry.isSecret) {
+                lines.push(`${entry.key}=`);
+            }
+            else {
+                lines.push(`${entry.key}=${SerializeConfigValue(entry.value)}`);
+            }
+        }
+        await FS.writeFile(path, lines.join('\n'), 'utf-8');
+    }
+    /**
+     * Creates a ConfigEnvironmentProvider instance and registers it with ConfigManager.
+     *
+     * This is a convenience factory method that combines instantiation and registration in one call.
+     * Unspecified options use their schema defaults (`name: 'environment'`, `path: '.env'` in cwd).
+     *
+     * @param options - Optional partial provider configuration; unspecified fields use schema defaults
+     * @returns A promise resolving to the registered provider instance
+     *
+     * @example
+     * ```typescript
+     * // Register with all defaults
+     * const provider = await ConfigEnvironmentProvider.Register();
+     *
+     * // Register with custom path
+     * const provider = await ConfigEnvironmentProvider.Register({
+     *   path: '.env.production'
+     * });
+     * ```
+     */
+    static async Register(options = {}) {
+        const provider = new ConfigEnvironmentProvider(CONFIG_ENV_PROVIDER_OPTIONS_SCHEMA.parse(options));
+        await ConfigManager.RegisterProvider(provider);
+        return provider;
+    }
+}
+//# sourceMappingURL=environment-provider.js.map

package/dist/environment-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-provider.js","sourceRoot":"","sources":["../src/environment-provider.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './environment-provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './environment-provider.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@pawells/config-provider-env",
+	"displayName": "Config ENV Provider",
+	"version": "3.0.0-rc1",
+	"description": "Environment variable and dotenv file configuration provider for @pawells/config",
+	"keywords": [
+		"config",
+		"configuration",
+		"environment",
+		"environment-variables",
+		"dotenv",
+		"typescript",
+		"nodejs"
+	],
+	"license": "MIT",
+	"author": {
+		"name": "Phillip Aaron Wells",
+		"email": "69355326+PhillipAWells@users.noreply.github.com"
+	},
+	"homepage": "https://github.com/PhillipAWells/config",
+	"bugs": {
+		"url": "https://github.com/PhillipAWells/config/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/PhillipAWells/config.git",
+		"directory": "packages/config-provider-env"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/PhillipAWells"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"type": "module",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"local": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"!**/*.tsbuildinfo",
+		"LICENSE"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"test:coverage": "yarn nx test config-provider-env -- --coverage"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@pawells/config": "workspace:*",
+		"tslib": "^2.8.1",
+		"zod": "^4.4.3"
+	}
+}