dotenv-gad 1.4.2 → 1.6.0

package/dist/schema-loader.js

@@ -4,14 +4,17 @@
  * Deliberately free of CLI-only dependencies (chalk, inquirer) so it can be
  * imported by the Vite plugin without pulling in heavy Node packages.
  *
- * esbuild is required only when loading `.ts` schemas and is imported
+ * esbuild is required only when loading `.ts` schemas in Node.js and is imported
  * lazily via `await import("esbuild")` so the module itself has no
  * top-level dependency on it.
+ *
+ * In Bun, TypeScript files are loaded directly without transpilation.
  */
 import { readFileSync, writeFileSync, unlinkSync, existsSync } from "fs";
 import { dirname, join, resolve } from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { randomBytes } from "crypto";
+import { isBun } from "./runtime.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 async function importModule(filePath) {
     const fileUrl = pathToFileURL(filePath).href;
@@ -23,6 +26,11 @@ async function importModule(filePath) {
     return schema;
 }
 async function loadTsModule(tsFilePath) {
+    // Bun can import TypeScript files directly without transpilation
+    if (isBun()) {
+        return await importModule(tsFilePath);
+    }
+    // Node.js requires transpilation via esbuild
     const tempFile = join(__dirname, `../temp-schema-${randomBytes(8).toString("hex")}.mjs`);
     try {
         const { transformSync } = await import("esbuild");
@@ -32,7 +40,7 @@ async function loadTsModule(tsFilePath) {
             loader: "ts",
             target: "esnext",
         });
-        writeFileSync(tempFile, code);
+        writeFileSync(tempFile, code, { mode: 0o600 });
         return await importModule(tempFile);
     }
     finally {
@@ -45,7 +53,8 @@ async function loadTsModule(tsFilePath) {
  * Loads a schema from a file.
  *
  * Supports `.ts`, `.js`, `.mjs`, `.cjs`, and `.json` formats.
- * TypeScript files are transpiled on-the-fly via esbuild (loaded lazily).
+ * TypeScript files are loaded natively in Bun, or transpiled on-the-fly
+ * via esbuild in Node.js (loaded lazily).
  */
 export async function loadSchema(schemaPath) {
     const absPath = resolve(schemaPath);

package/dist/types/cli/commands/check.d.ts

@@ -1,2 +1,2 @@
 import { Command } from "commander";
-export default function (program: Command): Command;
+export default function (_program: Command): Command;

package/dist/types/cli/commands/decrypt.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function (_program: Command): Command;

package/dist/types/cli/commands/docs.d.ts

@@ -1,2 +1,2 @@
 import { Command } from "commander";
-export default function (program: Command): Command;
+export default function (_program: Command): Command;

package/dist/types/cli/commands/encrypt.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function (_program: Command): Command;

package/dist/types/cli/commands/fix.d.ts

@@ -1,2 +1,2 @@
 import { Command } from "commander";
-export default function (program: Command): Command;
+export default function (_program: Command): Command;

package/dist/types/cli/commands/init.d.ts

@@ -1,2 +1,2 @@
 import { Command } from "commander";
-export default function (program: Command): Command;
+export default function (_program: Command): Command;

package/dist/types/cli/commands/keygen.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function (program: Command): Command;

package/dist/types/cli/commands/rotate.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function (_program: Command): Command;

package/dist/types/cli/commands/status.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function (_program: Command): Command;

package/dist/types/cli/commands/sync.d.ts

@@ -1,2 +1,2 @@
 import { Command } from "commander";
-export default function (program: Command): Command;
+export default function (_program: Command): Command;

package/dist/types/cli/commands/verify.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function (_program: Command): Command;

package/dist/types/crypto.d.ts

@@ -0,0 +1,58 @@
+export interface KeyPair {
+    /** Hex-encoded 44-byte SPKI DER. Store as ENVGAD_PUBLIC_KEY in .env (safe to commit). */
+    publicKeyHex: string;
+    /** Hex-encoded 48-byte PKCS8 DER. Store as ENVGAD_PRIVATE_KEY in .env.keys (never commit). */
+    privateKeyHex: string;
+}
+/**
+ * Generates a new key pair using the X25519 curve.
+ *
+ * @returns An object containing the hex-encoded public and private keys.
+ * The public key is safe to commit to version control (e.g. .env), while the private key
+ * should be kept secret and stored securely (e.g. .env.keys).
+ */
+export declare function generateKeyPair(): KeyPair;
+/**
+ * Encrypts a plaintext string using ChaCha20-Poly1305 authenticated encryption.
+ * The encryption key is derived from the shared secret of the ephemeral key pair
+ * and the recipient's public key using HKDF-SHA256.
+ *
+ * @param plaintext - The plaintext string to encrypt.
+ * @param recipientPublicKeyHex - Hex-encoded 44-byte SPKI DER of the recipient's public key.
+ * @param varName - The name of the environment variable being encrypted.
+ * @returns A wire-format string containing the encrypted ciphertext and
+ *   ephemeral public key information: `encrypted:v1:<base64>`.
+ */
+export declare function encryptEnvValue(plaintext: string, recipientPublicKeyHex: string, varName: string): string;
+/**
+ * Decrypt a wire-format ciphertext produced by {@link encryptEnvValue}.
+ *
+ * @param token - Wire-format string: `encrypted:v1:<base64>`.
+ * @param privateKeyHex - Hex-encoded PKCS8 DER of the recipient's private key (from ENVGAD_PRIVATE_KEY).
+ * @param varName - Schema variable name, must match the one used during encryption (AAD check).
+ * @returns Decrypted plaintext string.
+ * @throws {@link DecryptionFailedError} if the key is wrong, ciphertext is tampered, or AAD mismatches.
+ */
+export declare function decryptEnvValue(token: string, privateKeyHex: string, varName: string): string;
+/**
+ * Returns true if the given value starts with the encrypted value
+ * prefix, and false otherwise.
+ *
+ * The encrypted value prefix is in the format of
+ * `encrypted:v1:<base64-encoded-payload>`.
+ *
+ * @param {string} value the value to check
+ * @returns {boolean} true if the value is an encrypted value, false otherwise
+ */
+export declare function isEncryptedValue(value: string): boolean;
+/**
+ * Loads the ENVGAD_PRIVATE_KEY value from the given path (default: `.env.keys`)
+ * or the ENVGAD_PRIVATE_KEY environment variable if present.
+ * Returns the hex-encoded DER value of the private key if found, or null otherwise.
+ * @param {Object} [options] Optional options.
+ * @param {string} [options.keysPath] Path to the `.env.keys` file (default: `.env.keys`).
+ * @returns {string | null} Hex-encoded DER value of the private key if found, or null otherwise.
+ */
+export declare function loadPrivateKey(options?: {
+    keysPath?: string;
+}): string | null;

package/dist/types/errors.d.ts

@@ -4,21 +4,44 @@ export declare class EnvValidationError extends Error {
     message: string;
     receiveValue?: unknown | undefined;
     constructor(key: string, message: string, receiveValue?: unknown | undefined);
+    static [Symbol.hasInstance](instance: unknown): boolean;
 }
+type ErrorItem = {
+    key: string;
+    message: string;
+    value?: any;
+    rule?: SchemaRule;
+};
 export declare class EnvAggregateError extends Error {
-    errors: {
-        key: string;
-        message: string;
-        value?: any;
-        rule?: SchemaRule;
-    }[];
-    constructor(errors: {
-        key: string;
-        message: string;
-        value?: any;
-        rule?: SchemaRule;
-    }[], message: string);
+    get errors(): ErrorItem[];
+    constructor(errors: ErrorItem[], message: string);
+    static [Symbol.hasInstance](instance: unknown): boolean;
     toString(): string;
 }
 /** @deprecated Use `EnvAggregateError` instead — avoids shadowing the built-in `AggregateError`. */
 export declare const AggregateError: typeof EnvAggregateError;
+/**
+ * Thrown when a required encryption or decryption key is not available.
+ * For encryption: ENVGAD_PUBLIC_KEY missing from .env.
+ * For decryption: ENVGAD_PRIVATE_KEY missing from .env.keys and environment.
+ */
+export declare class EncryptionKeyMissingError extends Error {
+    constructor(context: "encryption" | "decryption");
+}
+/**
+ * Thrown when ChaCha20-Poly1305 authenticated decryption fails.
+ * Common causes: wrong private key, corrupted ciphertext, or AAD mismatch
+ * (ciphertext copied from a different variable).
+ */
+export declare class DecryptionFailedError extends Error {
+    constructor(varName: string);
+}
+/**
+ * Thrown when an encrypted/plaintext value is found but the schema says otherwise.
+ * When `shouldBeEncrypted = true`: schema has `encrypted: true` but value is plaintext.
+ * When `shouldBeEncrypted = false`: value starts with `encrypted:v1:` but schema lacks `encrypted: true`.
+ */
+export declare class EncryptedFieldMismatchError extends Error {
+    constructor(varName: string, shouldBeEncrypted: boolean);
+}
+export {};

package/dist/types/index.d.ts

@@ -1,14 +1,19 @@
 import { EnvValidator } from "./validator.js";
 import { defineSchema, SchemaDefinition, SchemaRule } from "./schema.js";
-import { EnvAggregateError, AggregateError, EnvValidationError } from "./errors.js";
+import { EnvAggregateError, AggregateError, EnvValidationError, EncryptionKeyMissingError, DecryptionFailedError, EncryptedFieldMismatchError } from "./errors.js";
 import { loadEnv, createEnvProxy } from "./utils.js";
 import { composeSchema } from "./compose.js";
 import { ExtractEnv, InferEnv } from "./types.js";
+import { generateKeyPair, encryptEnvValue, decryptEnvValue, isEncryptedValue, loadPrivateKey } from "./crypto.js";
+import type { KeyPair } from "./crypto.js";
+import { isBun, getEnv, getRuntimeName, getRuntimeVersion } from "./runtime.js";
 export { defineSchema, EnvAggregateError, 
 /** @deprecated Use `EnvAggregateError` instead. */
-AggregateError, EnvValidationError, EnvValidator, loadEnv, createEnvProxy, composeSchema, };
-export type { SchemaDefinition, SchemaRule, ExtractEnv, InferEnv };
+AggregateError, EnvValidationError, EncryptionKeyMissingError, DecryptionFailedError, EncryptedFieldMismatchError, EnvValidator, loadEnv, createEnvProxy, composeSchema, generateKeyPair, encryptEnvValue, decryptEnvValue, isEncryptedValue, loadPrivateKey, isBun, getEnv, getRuntimeName, getRuntimeVersion, };
+export type { SchemaDefinition, SchemaRule, ExtractEnv, InferEnv, KeyPair };
 export declare function validateEnv(schema: SchemaDefinition, options?: {
     strict?: boolean;
     path?: string;
+    allowPlaintext?: boolean;
+    keysPath?: string;
 }): Record<string, any>;

package/dist/types/runtime.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Runtime detection and compatibility utilities for Node.js and Bun.
+ *
+ * This module provides utilities to detect the current runtime environment
+ * and offers optimized implementations based on the runtime.
+ */
+/**
+ * Checks if the current runtime is Bun.
+ * @returns true if running in Bun, false otherwise
+ */
+export declare function isBun(): boolean;
+/**
+ * Gets the appropriate environment object for the current runtime.
+ * In Bun, this returns Bun.env, in Node.js it returns process.env.
+ * Both are compatible, but Bun.env may have better performance in Bun.
+ *
+ * @returns The environment variables object
+ */
+export declare function getEnv(): Record<string, string | undefined>;
+/**
+ * Gets the current runtime name for logging/debugging purposes.
+ * @returns "Bun" or "Node.js"
+ */
+export declare function getRuntimeName(): string;
+/**
+ * Gets the runtime version string.
+ * @returns The version of the current runtime
+ */
+export declare function getRuntimeVersion(): string;

package/dist/types/schema-loader.d.ts

@@ -4,15 +4,18 @@
  * Deliberately free of CLI-only dependencies (chalk, inquirer) so it can be
  * imported by the Vite plugin without pulling in heavy Node packages.
  *
- * esbuild is required only when loading `.ts` schemas and is imported
+ * esbuild is required only when loading `.ts` schemas in Node.js and is imported
  * lazily via `await import("esbuild")` so the module itself has no
  * top-level dependency on it.
+ *
+ * In Bun, TypeScript files are loaded directly without transpilation.
  */
 import type { SchemaDefinition } from "./schema.js";
 /**
  * Loads a schema from a file.
  *
  * Supports `.ts`, `.js`, `.mjs`, `.cjs`, and `.json` formats.
- * TypeScript files are transpiled on-the-fly via esbuild (loaded lazily).
+ * TypeScript files are loaded natively in Bun, or transpiled on-the-fly
+ * via esbuild in Node.js (loaded lazily).
  */
 export declare function loadSchema(schemaPath: string): Promise<SchemaDefinition>;

package/dist/types/schema.d.ts

@@ -12,6 +12,13 @@ export interface SchemaRule {
     validate?: (value: any) => boolean;
     transform?: (value: any) => any;
     sensitive?: boolean;
+    /**
+     * When true, the value must be stored encrypted in the .env file using the
+     * dotenv-gad ECIES scheme. The validator will automatically decrypt the value
+     * before type-checking and returning it to the application.
+     * Use `npx dotenv-gad keygen` and `npx dotenv-gad encrypt` to manage keys.
+     */
+    encrypted?: boolean;
     docs?: string;
     enum?: any[];
     regex?: RegExp;

package/dist/types/utils.d.ts

@@ -1,23 +1,34 @@
 import { SchemaDefinition } from "./schema.js";
 import type { InferEnv } from "./types.js";
 /**
- * Loads environment variables from .env file and validates them against
- * the given schema.
+ * Silently reads and parses a .env file without injecting into process.env.
+ * Returns an empty object when the file does not exist (e.g. Vercel, Railway,
+ * Docker — where env vars are already present in process.env).
  *
- * @template S The type of the schema definition.
- * @param {S} schema The schema definition for the environment variables.
- * @param {Object} [options] Optional options for the validation process.
- * @param {boolean} [options.strict] When true, fail on environment variables not present in the schema.
- * @param {boolean} [options.includeRaw] Include raw values in error reports (non-sensitive by default).
- * @param {boolean} [options.includeSensitive] When used with `includeRaw`, will reveal values marked sensitive (use only for local debugging).
- * @param {string} [options.path] Path to the .env file to load (defaults to `.env` in cwd).
- * @returns {InferEnv<S>} The validated environment variables.
+ * In Bun, this uses Bun's optimized file reading when available.
+ */
+export declare function readEnvFile(path?: string): Record<string, string>;
+/**
+ * Loads environment variables from a `.env` file (if present) and validates them
+ * against the provided schema.
+ *
+ * @param schema The schema definition for the environment variables.
+ * @param options Optional options for the validation process.
+ * @param options.strict When true, environment variables not present in the schema will be rejected.
+ * @param options.includeRaw When true, include raw values in error reports (non-sensitive by default).
+ * @param options.includeSensitive When true, include values marked sensitive in error reports (use only for local debugging).
+ * @param options.path Path to the `.env` file (defaults to `.env` in cwd).
+ * @param options.allowPlaintext When true, fields with `encrypted: true` that have plaintext values emit a warning instead of an error.
+ * @param options.keysPath Path to the `.env.keys` file containing ENVGAD_PRIVATE_KEY (default: `.env.keys`).
+ * @returns The validated environment variables, typed according to the schema.
  */
 export declare function loadEnv<S extends SchemaDefinition>(schema: S, options?: {
     strict?: boolean;
     includeRaw?: boolean;
     includeSensitive?: boolean;
     path?: string;
+    allowPlaintext?: boolean;
+    keysPath?: string;
 }): InferEnv<S>;
 /**
  * Create a proxy around the validated environment variables. The proxy will

package/dist/types/validator.d.ts

@@ -2,21 +2,61 @@ import { SchemaDefinition } from "./schema.js";
 export declare class EnvValidator {
     private schema;
     private options?;
+    private static readonly EMAIL_REGEX;
+    private static readonly LOCAL_MAX;
+    private static readonly DOMAIN_MAX;
+    private static readonly DOMAIN_PART_MAX;
     private errors;
     /**
      * Constructs a new EnvValidator instance.
      * @param {SchemaDefinition} schema The schema definition for the environment variables.
      * @param {Object} [options] Optional options for the validation process.
      * @param {boolean} [options.strict] When true, environment variables not present in the schema will be rejected.
+     * @param {boolean} [options.allowPlaintext] When true, fields with `encrypted: true` that have plaintext values emit a warning instead of an error. Useful for gradual migration.
+     * @param {string} [options.keysPath] Path to the `.env.keys` file (default: `.env.keys`).
      */
     constructor(schema: SchemaDefinition, options?: {
         strict?: boolean;
         includeRaw?: boolean;
         includeSensitive?: boolean;
+        allowPlaintext?: boolean;
+        keysPath?: string;
     } | undefined);
+    /** Bundler-safe instanceof — checks the symbol marker, not the class name. */
+    static [Symbol.hasInstance](instance: unknown): boolean;
     validate(env: Record<string, string | undefined>): Record<string, any>;
+    /**
+     * Redacts a value to hide its contents, following these rules:
+     * - If `value` is undefined, returns undefined.
+     * - If `sensitive` is true, returns `"****"`.
+     * - If `value` is not a string, returns the original value.
+     * - If `value` is a string longer than 64 characters, truncates it to 4 characters
+     *   at the start and end, and replaces the middle with `"..."`.
+     * - Otherwise, returns the original string.
+     * @param value The value to redact.
+     * @param sensitive If true, redacts the value to `"****"`.
+     */
     private redactValue;
+    /**
+     * Tries to parse the given value as a JSON object.
+     * Returns `{ ok: true, value: JSON.parse(s) }` if successful,
+     * or `{ ok: false }` if not.
+     * The following conditions will cause the function to return `{ ok: false }`:
+     * - `value` is not a string
+     * - `value` is an empty string
+     * - `value` does not start with one of the following characters: `{`, `[`, `"`, `t`, `f`, `n`, or a digit
+     * - `value` cannot be parsed as a JSON object
+     */
     private tryParseJSON;
     private validateKey;
     private getEffectiveRule;
+    /**
+     * Preprocesses environment variables to detect and handle encrypted values.
+     *   1. Decrypts any encrypted values using the private key.
+     *   2. Checks if any plaintext values are present for fields that should be encrypted.
+     *   3. Flags any env value that looks encrypted but the schema doesn't declare encrypted: true.
+     * @returns An object containing the processed environment variables and a set of keys that were skipped due to errors.
+     */
+    private preprocessEncryption;
+    private validateEmail;
 }

package/dist/utils.js

@@ -1,21 +1,58 @@
-import dotenv from "dotenv";
+import { parse as parseEnv } from "dotenv";
+import { readFileSync, existsSync } from "node:fs";
 import { EnvValidator } from "./validator.js";
+import { isBun, getEnv } from "./runtime.js";
 /**
- * Loads environment variables from .env file and validates them against
- * the given schema.
+ * Silently reads and parses a .env file without injecting into process.env.
+ * Returns an empty object when the file does not exist (e.g. Vercel, Railway,
+ * Docker — where env vars are already present in process.env).
  *
- * @template S The type of the schema definition.
- * @param {S} schema The schema definition for the environment variables.
- * @param {Object} [options] Optional options for the validation process.
- * @param {boolean} [options.strict] When true, fail on environment variables not present in the schema.
- * @param {boolean} [options.includeRaw] Include raw values in error reports (non-sensitive by default).
- * @param {boolean} [options.includeSensitive] When used with `includeRaw`, will reveal values marked sensitive (use only for local debugging).
- * @param {string} [options.path] Path to the .env file to load (defaults to `.env` in cwd).
- * @returns {InferEnv<S>} The validated environment variables.
+ * In Bun, this uses Bun's optimized file reading when available.
+ */
+export function readEnvFile(path) {
+    const filePath = path ?? ".env";
+    if (!existsSync(filePath))
+        return {};
+    try {
+        // Use Bun's file reading when available for better performance
+        let content;
+        if (isBun() && typeof globalThis.Bun?.file === 'function') {
+            // Bun's synchronous text reading
+            const file = globalThis.Bun.file(filePath);
+            content = file.text ? (typeof file.text === 'function' ? file.text() : file.text) : readFileSync(filePath, "utf-8");
+            // Note: Bun.file().text() is async, so fallback to readFileSync for sync operation
+            content = readFileSync(filePath, "utf-8");
+        }
+        else {
+            content = readFileSync(filePath, "utf-8");
+        }
+        return parseEnv(content);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[dotenv-gad] Failed to parse ${filePath}: ${message}`);
+        return {};
+    }
+}
+/**
+ * Loads environment variables from a `.env` file (if present) and validates them
+ * against the provided schema.
+ *
+ * @param schema The schema definition for the environment variables.
+ * @param options Optional options for the validation process.
+ * @param options.strict When true, environment variables not present in the schema will be rejected.
+ * @param options.includeRaw When true, include raw values in error reports (non-sensitive by default).
+ * @param options.includeSensitive When true, include values marked sensitive in error reports (use only for local debugging).
+ * @param options.path Path to the `.env` file (defaults to `.env` in cwd).
+ * @param options.allowPlaintext When true, fields with `encrypted: true` that have plaintext values emit a warning instead of an error.
+ * @param options.keysPath Path to the `.env.keys` file containing ENVGAD_PRIVATE_KEY (default: `.env.keys`).
+ * @returns The validated environment variables, typed according to the schema.
  */
 export function loadEnv(schema, options) {
-    const fileEnv = dotenv.config({ debug: false, path: options?.path }).parsed || {};
-    const env = { ...process.env, ...fileEnv };
+    const fileEnv = readEnvFile(options?.path);
+    // Use runtime-aware environment getter (process.env or Bun.env)
+    const runtimeEnv = getEnv();
+    const env = { ...runtimeEnv, ...fileEnv };
     const validator = new EnvValidator(schema, options);
     return validator.validate(env);
 }