dotenv-gad 1.4.1 → 1.5.0

package/README.md

@@ -1,17 +1,22 @@
 # dotenv-gad
 
 [![npm version](https://badge.fury.io/js/dotenv-gad.svg)](https://badge.fury.io/js/dotenv-gad)
+[![CI](https://github.com/kasimlyee/dotenv-gad/actions/workflows/ci.yml/badge.svg)](https://github.com/kasimlyee/dotenv-gad/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-first--class-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Docs](https://img.shields.io/badge/docs-latest-blue?style=flat-square)](https://kasimlyee.github.io/dotenv-gad/)
+[![npm downloads](https://img.shields.io/npm/dm/dotenv-gad.svg)](https://www.npmjs.com/package/dotenv-gad)
 
 **dotenv-gad** is an environment variable validation library that brings type safety, schema validation, and runtime checks to your Node.js and JavaScript applications. It works with any environment variable source — `.env` files, platform dashboards (Vercel, Railway, Docker), CI/CD pipelines, or `process.env` directly.
 
 - Type-safe environment variables with full IntelliSense
 - Schema validation (string, number, boolean, url, email, ip, port, json, array, object)
+- **At-rest encryption** —  transparent decrypt at runtime
 - Schema composition for modular configs
 - Automatic documentation and `.env.example` generation
 - First-class TypeScript support
-- CLI tooling (check, sync, types, init, fix, docs)
+- CLI tooling (check, sync, types, init, fix, docs, keygen, encrypt, decrypt, rotate, verify, status)
 - Sensitive value management and redaction
 - Vite plugin with client-safe filtering and HMR
 
@@ -66,18 +71,25 @@ Full documentation is available at [kasimlyee.github.io/dotenv-gad](https://kasi
 
 ## CLI Commands
 
-| Command | Description                        |
-| ------- | ---------------------------------- |
-| `check` | Validate .env against schema       |
-| `sync`  | Generate/update .env.example       |
-| `types` | Generate env.d.ts TypeScript types |
-| `init`  | Create starter schema              |
-| `fix`   | Fixes environment issues           |
-| `docs`  | Generates .env documentation       |
+| Command   | Description                                      |
+| --------- | ------------------------------------------------ |
+| `check`   | Validate .env against schema                     |
+| `sync`    | Generate/update .env.example                     |
+| `types`   | Generate env.d.ts TypeScript types               |
+| `init`    | Create starter schema                            |
+| `fix`     | Fix environment issues interactively             |
+| `docs`    | Generate .env documentation                      |
+| `keygen`  | Generate an X25519 key pair for encryption       |
+| `encrypt` | Encrypt plaintext values for `encrypted:true` fields |
+| `decrypt` | Print or write back decrypted values             |
+| `rotate`  | Rotate keys: decrypt → new pair → re-encrypt     |
+| `status`  | Show encryption status of each schema field      |
+| `verify`  | Dry-run: confirm all encrypted values decrypt    |
 
 ```bash
 npx dotenv-gad check
-npx dotenv-gad types
+npx dotenv-gad keygen
+npx dotenv-gad encrypt
 ```
 
 ## Vite Plugin
@@ -174,6 +186,35 @@ const schema = composeSchema(baseSchema, dbSchema);
 }
 ```
 
+### At-rest Encryption
+
+Store secrets as encrypted ciphertext in `.env` using asymmetric X25519 + ChaCha20-Poly1305. Only `.env.keys` (gitignored) can decrypt them.
+
+**1. Mark fields as encrypted:**
+
+```typescript
+export default defineSchema({
+  DATABASE_URL: { type: 'string', required: true, sensitive: true, encrypted: true },
+  API_SECRET:   { type: 'string', required: true, sensitive: true, encrypted: true },
+});
+```
+
+**2. Generate keys and encrypt:**
+
+```bash
+npx dotenv-gad keygen    # writes ENVGAD_PUBLIC_KEY to .env, creates .env.keys
+npx dotenv-gad encrypt   # replaces plaintext secrets with encrypted:v1:… tokens
+```
+
+**3. `loadEnv` decrypts transparently at runtime:**
+
+```typescript
+const env = loadEnv(schema); // reads .env.keys, decrypts, validates — all in one step
+console.log(env.DATABASE_URL); // "postgres://user:pass@host/db"
+```
+
+Your `.env` (with encrypted values and the public key) is now safe to commit. See the [Encryption guide](https://kasimlyee.github.io/dotenv-gad/guide/encryption) for key rotation, CI/CD setup, and security details.
+
 ### Grouping / Namespaced Envs
 
 Group related variables into a single validated object:

package/dist/cli/commands/check.js

@@ -2,13 +2,15 @@ import { Command } from "commander";
 import chalk from "chalk";
 import ora from "ora";
 import { validateEnv } from "../../index.js";
-import { EnvAggregateError } from "../../errors.js";
+import { EnvAggregateError, EncryptionKeyMissingError } from "../../errors.js";
 import { loadSchema } from "./utils.js";
-export default function (program) {
+export default function (_program) {
     return new Command("check")
         .description("Validate .env against schema")
         .option("--strict", "Fail on extra env vars not in schema")
         .option("--fix", "Attempt to fix errors interactively")
+        .option("--keys <file>", "Path to .env.keys file for decrypting encrypted fields", ".env.keys")
+        .option("--allow-plaintext", "Warn instead of error when encrypted fields have plaintext values")
         .action(async (option, command) => {
         const rootOpts = command.parent.opts();
         const spinner = ora("Validating environment...").start();
@@ -17,6 +19,8 @@ export default function (program) {
             const env = validateEnv(schema, {
                 strict: option.strict,
                 path: rootOpts.env,
+                keysPath: option.keys,
+                allowPlaintext: option.allowPlaintext,
             });
             spinner.succeed(chalk.green("Environment validation passed!"));
             console.log(chalk.dim(`Found ${Object.keys(env).length} valid variables`));
@@ -33,6 +37,10 @@ export default function (program) {
                 });
                 process.exit(1);
             }
+            else if (error instanceof EncryptionKeyMissingError) {
+                console.error(chalk.red(`\n✗ ${error.message}`));
+                process.exit(1);
+            }
             else {
                 console.error(chalk.red("Unexpected error:"), error);
                 process.exit(2);

package/dist/cli/commands/decrypt.js

@@ -0,0 +1,126 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { createInterface } from "node:readline/promises";
+import { readFileSync, writeFileSync } from "node:fs";
+import dotenv from "dotenv";
+import { decryptEnvValue, isEncryptedValue, loadPrivateKey } from "../../crypto.js";
+import { EncryptionKeyMissingError } from "../../errors.js";
+import { loadSchema } from "./utils.js";
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(question);
+        return answer.trim().toLowerCase() === "y";
+    }
+    finally {
+        rl.close();
+    }
+}
+export default function (_program) {
+    return new Command("decrypt")
+        .description("Decrypt encrypted values and print them to stdout (or write back with --write)")
+        .option("--keys <file>", "Path to the .env.keys private key file", ".env.keys")
+        .option("--write", "Write decrypted values back to the .env file (requires confirmation)")
+        .action(async (opts, command) => {
+        const rootOpts = command.parent.opts();
+        const envPath = rootOpts.env ?? ".env";
+        const schemaPath = rootOpts.schema ?? "env.schema.ts";
+        const keysPath = opts.keys;
+        const spinner = ora("Loading schema…").start();
+        try {
+            const schema = await loadSchema(schemaPath);
+            const encryptedFields = Object.keys(schema).filter((k) => schema[k].encrypted === true);
+            if (encryptedFields.length === 0) {
+                spinner.info(chalk.dim("No fields with encrypted: true found in schema."));
+                return;
+            }
+            spinner.text = `Reading ${envPath}…`;
+            let envContent;
+            try {
+                envContent = readFileSync(envPath, "utf8");
+            }
+            catch {
+                spinner.fail(chalk.red(`Cannot read ${envPath}`));
+                process.exit(1);
+            }
+            const parsed = dotenv.parse(envContent);
+            spinner.text = "Loading private key…";
+            const privateKeyHex = loadPrivateKey({ keysPath });
+            if (!privateKeyHex) {
+                spinner.fail(chalk.red("Private key not found.\n" +
+                    `  Checked: ${keysPath} and ENVGAD_PRIVATE_KEY env var\n` +
+                    "  Obtain .env.keys from your team or set ENVGAD_PRIVATE_KEY"));
+                process.exit(1);
+            }
+            spinner.text = `Decrypting ${encryptedFields.length} field(s)…`;
+            const decrypted = {};
+            const errors = [];
+            for (const key of encryptedFields) {
+                const value = parsed[key];
+                if (value == null || value === "")
+                    continue;
+                if (!isEncryptedValue(value)) {
+                    console.warn(chalk.yellow(`  ⚠  ${key}: value is not encrypted (skipping)`));
+                    continue;
+                }
+                try {
+                    decrypted[key] = decryptEnvValue(value, privateKeyHex, key);
+                }
+                catch (err) {
+                    errors.push({
+                        key,
+                        message: err instanceof Error ? err.message : "Decryption failed",
+                    });
+                }
+            }
+            spinner.stop();
+            if (errors.length > 0) {
+                for (const { key, message } of errors) {
+                    console.error(`  ${chalk.red("✗")} ${chalk.bold(key)}: ${message}`);
+                }
+            }
+            const decryptedKeys = Object.keys(decrypted);
+            if (decryptedKeys.length === 0) {
+                console.log(chalk.dim("No encrypted values found to decrypt."));
+                return;
+            }
+            if (!opts.write) {
+                // Default: safe stdout output
+                console.log(chalk.bold("\n# Decrypted values (stdout only — not written to file):"));
+                for (const [key, value] of Object.entries(decrypted)) {
+                    console.log(`${key}=${value}`);
+                }
+                console.log(chalk.dim(`\n${decryptedKeys.length} value(s) printed. ` +
+                    "Use --write to update the .env file."));
+                return;
+            }
+            // --write mode: confirm before overwriting
+            console.log(chalk.yellow(`\n⚠  About to write ${decryptedKeys.length} decrypted value(s) to ${envPath}.`) +
+                chalk.dim("\n   This replaces encrypted values with plaintext.\n" +
+                    "   DO NOT commit these changes to git!\n"));
+            const ok = await confirm("   Continue? (y/N): ");
+            if (!ok) {
+                console.log(chalk.dim("\nAborted."));
+                return;
+            }
+            const replaceRegexes = Object.fromEntries(Object.keys(decrypted).map((k) => [k, new RegExp(`^(${k}\\s*=).*$`, "m")]));
+            let updatedContent = envContent;
+            for (const [key, value] of Object.entries(decrypted)) {
+                updatedContent = updatedContent.replace(replaceRegexes[key], `$1${value}`);
+            }
+            writeFileSync(envPath, updatedContent);
+            console.log(`\n${chalk.green("✓")} ${decryptedKeys.length} value(s) written to ${chalk.bold(envPath)}\n` +
+                chalk.yellow("⚠  Remember: DO NOT commit these decrypted values!"));
+        }
+        catch (error) {
+            spinner.stop();
+            if (error instanceof EncryptionKeyMissingError) {
+                console.error(chalk.red(`\n✗ ${error.message}`));
+                process.exit(1);
+            }
+            console.error(chalk.red("\nUnexpected error:"), error);
+            process.exit(2);
+        }
+    });
+}

package/dist/cli/commands/docs.js

@@ -1,10 +1,10 @@
 import { Command } from "commander";
 import { loadSchema } from "./utils.js";
 import { writeFileSync } from "fs";
-export default function (program) {
+export default function (_program) {
     return new Command("docs")
         .description("Generate Markdown documentation")
-        .action(async (program, command) => {
+        .action(async (_program, command) => {
         const schema = await loadSchema(command.parent.opts().schema);
         let md = `# Environment Variables\n\n`;
         Object.entries(schema).forEach(([key, rule]) => {

package/dist/cli/commands/encrypt.js

@@ -0,0 +1,94 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import dotenv from "dotenv";
+import { encryptEnvValue, isEncryptedValue } from "../../crypto.js";
+import { EncryptionKeyMissingError } from "../../errors.js";
+import { loadSchema } from "./utils.js";
+export default function (_program) {
+    return new Command("encrypt")
+        .description("Encrypt plaintext values for fields marked encrypted: true in the schema")
+        .action(async (_opts, command) => {
+        const rootOpts = command.parent.opts();
+        const envPath = rootOpts.env ?? ".env";
+        const schemaPath = rootOpts.schema ?? "env.schema.ts";
+        const spinner = ora("Loading schema…").start();
+        try {
+            const schema = await loadSchema(schemaPath);
+            const encryptedFields = Object.keys(schema).filter((k) => schema[k].encrypted === true);
+            if (encryptedFields.length === 0) {
+                spinner.info(chalk.dim("No fields with encrypted: true found in schema. Nothing to do."));
+                return;
+            }
+            spinner.text = `Reading ${envPath}…`;
+            let envContent;
+            try {
+                envContent = readFileSync(envPath, "utf8");
+            }
+            catch {
+                spinner.fail(chalk.red(`Cannot read ${envPath}`));
+                process.exit(1);
+            }
+            const parsed = dotenv.parse(envContent);
+            const publicKeyHex = parsed.ENVGAD_PUBLIC_KEY;
+            if (!publicKeyHex) {
+                spinner.fail(chalk.red(`ENVGAD_PUBLIC_KEY not found in ${envPath}.\n` +
+                    "  Run: " +
+                    chalk.cyan("npx dotenv-gad keygen")));
+                process.exit(1);
+            }
+            spinner.text = `Encrypting ${encryptedFields.length} field(s)…`;
+            const keyRegex = (k) => new RegExp(`^(${k}\\s*=).*$`, "m");
+            const replaceRegexes = Object.fromEntries(encryptedFields.map((k) => [k, keyRegex(k)]));
+            let updatedContent = envContent;
+            let encryptedCount = 0;
+            const results = [];
+            for (const key of encryptedFields) {
+                const value = parsed[key];
+                if (value == null || value === "") {
+                    results.push({ key, status: "missing" });
+                    continue;
+                }
+                if (isEncryptedValue(value)) {
+                    results.push({ key, status: "skipped" });
+                    continue;
+                }
+                const encrypted = encryptEnvValue(value, publicKeyHex, key);
+                updatedContent = updatedContent.replace(replaceRegexes[key], `$1${encrypted}`);
+                results.push({ key, status: "encrypted" });
+                encryptedCount++;
+            }
+            spinner.stop();
+            for (const { key, status } of results) {
+                if (status === "encrypted") {
+                    console.log(`  ${chalk.green("✓")} ${chalk.bold(key)}: encrypted`);
+                }
+                else if (status === "skipped") {
+                    console.log(`  ${chalk.dim("⊘")} ${chalk.dim(key + ": already encrypted (skipped)")}`);
+                }
+                else {
+                    console.log(`  ${chalk.dim("⊘")} ${chalk.dim(key + ": not present in .env (skipped)")}`);
+                }
+            }
+            if (encryptedCount > 0) {
+                copyFileSync(envPath, `${envPath}.bak`);
+                writeFileSync(envPath, updatedContent);
+                console.log(`\n${chalk.green("✓")} ${encryptedCount} field(s) encrypted in ${chalk.bold(envPath)}\n` +
+                    chalk.dim(`  Backup saved to ${envPath}.bak`));
+            }
+            else {
+                console.log(chalk.dim("\nNo fields needed encryption."));
+            }
+        }
+        catch (error) {
+            spinner.stop();
+            if (error instanceof EncryptionKeyMissingError) {
+                console.error(chalk.red(`\n✗ ${error.message}`));
+                process.exit(1);
+            }
+            console.error(chalk.red("\nUnexpected error:"), error);
+            process.exit(2);
+        }
+    });
+}

package/dist/cli/commands/fix.js

@@ -1,13 +1,23 @@
 import { Command } from "commander";
 import chalk from "chalk";
-import inquirer from "inquirer";
+import { createInterface } from "node:readline/promises";
 import { loadSchema, applyFix } from "./utils.js";
 import { validateEnv } from "../../index.js";
 import { EnvAggregateError } from "../../errors.js";
-export default function (program) {
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(question);
+        return answer.trim().toLowerCase() === "y";
+    }
+    finally {
+        rl.close();
+    }
+}
+export default function (_program) {
     return new Command("fix")
         .description("Interactively fix environment issues")
-        .action(async (options, command) => {
+        .action(async (_options, command) => {
         const rootOpts = command.parent.opts();
         const schema = await loadSchema(rootOpts.schema);
         const envPath = rootOpts.env || ".env";
@@ -26,19 +36,13 @@ export default function (program) {
                         console.log(chalk.dim(`    ${e.rule.docs}`));
                     }
                 });
-                const { confirmed } = await inquirer.prompt({
-                    type: "confirm",
-                    name: "confirmed",
-                    message: `\nWould you like to fix these issues interactively?`,
-                    default: true,
-                });
-                if (confirmed) {
-                    // Convert errors array to issues object format expected by applyFix
+                const ok = await confirm(chalk.bold("\nWould you like to fix these issues interactively? (y/N): "));
+                if (ok) {
                     const issues = {};
                     error.errors.forEach((e) => {
                         issues[e.key] = { value: e.value, key: e.key };
                     });
-                    await applyFix(issues, schema, rootOpts.env || ".env");
+                    await applyFix(issues, schema, envPath);
                 }
                 else {
                     console.log(chalk.dim("\nFix cancelled."));

package/dist/cli/commands/init.js

@@ -2,11 +2,18 @@ import { Command } from "commander";
 import chalk from "chalk";
 import ora from "ora";
 import { writeFileSync, existsSync } from "fs";
-import inquirer from "inquirer";
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-export default function (program) {
+import { createInterface } from "node:readline/promises";
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(question);
+        return answer.trim().toLowerCase() === "y";
+    }
+    finally {
+        rl.close();
+    }
+}
+export default function (_program) {
     return new Command("init")
         .description("Initialize new schema file")
         .option("--force", "Overwrite existing files")
@@ -15,14 +22,12 @@ export default function (program) {
         const schemaPath = rootOpts.schema;
         if (existsSync(schemaPath)) {
             if (!options.force) {
-                const { overwrite } = await inquirer.prompt({
-                    type: "confirm",
-                    name: "overwrite",
-                    message: "Schema file already exists. Overwrite?",
-                    default: false,
-                });
-                if (!overwrite)
+                const ok = await confirm(chalk.yellow(`Schema file "${schemaPath}" already exists. Overwrite? (y/N): `));
+                if (!ok) {
+                    console.log(chalk.dim("\nAborted."));
                     process.exit(0);
+                }
+                console.log();
             }
         }
         const spinner = ora("Creating new schema...").start();

package/dist/cli/commands/keygen.js

@@ -0,0 +1,97 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { createInterface } from "node:readline/promises";
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { generateKeyPair } from "../../crypto.js";
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(question);
+        return answer.trim().toLowerCase() === "y";
+    }
+    finally {
+        rl.close();
+    }
+}
+export default function (program) {
+    return new Command("keygen")
+        .description("Generate an X25519 key pair for schema-based encryption")
+        .option("--keys <file>", "Path to write the private key file", ".env.keys")
+        .option("-f, --force", "Overwrite existing keys without confirmation")
+        .action(async (opts, command) => {
+        const rootOpts = command.parent.opts();
+        const envPath = rootOpts.env ?? ".env";
+        const keysPath = opts.keys;
+        // Warn and confirm if keys already exist (unless --force)
+        const envContent = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+        const hasExistingPublicKey = /^ENVGAD_PUBLIC_KEY=/m.test(envContent);
+        const hasExistingKeysFile = existsSync(keysPath);
+        if ((hasExistingPublicKey || hasExistingKeysFile) && !opts.force) {
+            console.log(chalk.yellow("\n⚠  Existing keys detected:") +
+                (hasExistingPublicKey
+                    ? chalk.dim(`\n   ENVGAD_PUBLIC_KEY found in ${envPath}`)
+                    : "") +
+                (hasExistingKeysFile
+                    ? chalk.dim(`\n   ${keysPath} already exists`)
+                    : "") +
+                chalk.yellow("\n\n   Generating new keys invalidates all existing encrypted values.\n" +
+                    "   Use 'npx dotenv-gad rotate' for safe key rotation.\n"));
+            const ok = await confirm("   Generate new keys anyway? (y/N): ");
+            if (!ok) {
+                console.log(chalk.dim("\nAborted."));
+                return;
+            }
+            console.log();
+        }
+        const spinner = ora("Generating X25519 key pair…").start();
+        const { publicKeyHex, privateKeyHex } = generateKeyPair();
+        // Update or append public key in .env
+        let newEnvContent;
+        if (hasExistingPublicKey) {
+            newEnvContent = envContent.replace(/^ENVGAD_PUBLIC_KEY=.*$/m, `ENVGAD_PUBLIC_KEY=${publicKeyHex}`);
+        }
+        else {
+            const sep = envContent.length > 0 && !envContent.endsWith("\n") ? "\n" : "";
+            newEnvContent =
+                envContent +
+                    `${sep}\n# dotenv-gad encryption public key (safe to commit)\n` +
+                    `ENVGAD_PUBLIC_KEY=${publicKeyHex}\n`;
+        }
+        writeFileSync(envPath, newEnvContent);
+        // Write private key to .env.keys (restricted permissions on Unix)
+        writeFileSync(keysPath, "# KEEP THIS FILE SECRET — DO NOT COMMIT TO GIT\n" +
+            "# Share securely via 1Password, Vault, or a secure channel\n" +
+            `ENVGAD_PRIVATE_KEY=${privateKeyHex}\n`, { mode: 0o600 });
+        // Ensure .env.keys is listed in .gitignore
+        const gitignorePath = ".gitignore";
+        const gitignoreContent = existsSync(gitignorePath)
+            ? readFileSync(gitignorePath, "utf8")
+            : "";
+        if (!gitignoreContent.includes(keysPath)) {
+            const sep = gitignoreContent.length > 0 && !gitignoreContent.endsWith("\n") ? "\n" : "";
+            appendFileSync(gitignorePath, `${sep}\n# dotenv-gad encryption keys\n${keysPath}\n`);
+        }
+        spinner.succeed(chalk.green("Key pair generated!"));
+        console.log("\n" +
+            chalk.bold("Public key") +
+            chalk.dim(` → ${envPath}`) +
+            `\n  ${chalk.cyan(`ENVGAD_PUBLIC_KEY=${publicKeyHex}`)}\n` +
+            "\n" +
+            chalk.bold("Private key") +
+            chalk.dim(` → ${keysPath}`) +
+            `\n  ${chalk.cyan(`ENVGAD_PRIVATE_KEY=${privateKeyHex}`)}\n` +
+            "\n" +
+            chalk.yellow("⚠  Remember:\n") +
+            chalk.dim(`  • ${keysPath} is gitignored — never commit it\n`) +
+            chalk.dim("  • Share it securely with team members\n") +
+            chalk.dim("  • For CI/CD, set ENVGAD_PRIVATE_KEY as an environment secret\n") +
+            "\n" +
+            chalk.bold("Next steps:\n") +
+            chalk.dim("  1. Add ") +
+            chalk.cyan("encrypted: true") +
+            chalk.dim(" to sensitive fields in your schema\n") +
+            chalk.dim("  2. Run: ") +
+            chalk.cyan("npx dotenv-gad encrypt"));
+    });
+}