dotenv-gad 1.4.2 → 1.6.0

package/dist/crypto.js

@@ -0,0 +1,165 @@
+import { createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from "node:crypto";
+import { chacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { existsSync, readFileSync } from "node:fs";
+import { DecryptionFailedError } from "./errors.js";
+import { getEnv } from "./runtime.js";
+const SPKI_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
+const RAW_KEY_LENGTH = 32;
+const NONCE_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+const PROTOCOL_PREFIX = "encrypted:";
+const ENCRYPTION_VERSION = "v1";
+const HKDF_INFO = Buffer.from("dotenv-gad:v1");
+const HKDF_SALT = Buffer.alloc(0);
+const AAD_PREFIX = "dotenv-gad:v1:";
+const PRIVATE_KEY_HEX_LENGTH = 96;
+const PUBLIC_KEY_HEX_LENGTH = 88;
+/**
+ * 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 function generateKeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync("x25519", {
+        publicKeyEncoding: { type: "spki", format: "der" },
+        privateKeyEncoding: { type: "pkcs8", format: "der" },
+    });
+    return {
+        publicKeyHex: publicKey.toString("hex"),
+        privateKeyHex: privateKey.toString("hex"),
+    };
+}
+/**
+ * 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 function encryptEnvValue(plaintext, recipientPublicKeyHex, varName) {
+    if (!/^[a-fA-F0-9]+$/.test(recipientPublicKeyHex) || recipientPublicKeyHex.length !== PUBLIC_KEY_HEX_LENGTH) {
+        throw new Error(`Invalid ENVGAD_PUBLIC_KEY format (expected ${PUBLIC_KEY_HEX_LENGTH}-char hex-encoded SPKI DER, got ${recipientPublicKeyHex.length} chars)`);
+    }
+    const recipientSpki = Buffer.from(recipientPublicKeyHex, "hex");
+    const { publicKeyHex: ephPubHex, privateKeyHex: ephPrivHex } = generateKeyPair();
+    const ephSpki = Buffer.from(ephPubHex, "hex");
+    const ephPkcs8 = Buffer.from(ephPrivHex, "hex");
+    const sharedSecret = diffieHellman({
+        privateKey: createPrivateKey({ key: ephPkcs8, format: "der", type: "pkcs8" }),
+        publicKey: createPublicKey({ key: recipientSpki, format: "der", type: "spki" }),
+    });
+    const encKey = Buffer.from(hkdfSync("sha256", sharedSecret, HKDF_SALT, HKDF_INFO, 32));
+    const nonce = randomBytes(NONCE_LENGTH);
+    const aad = Buffer.from(`${AAD_PREFIX}${varName}`);
+    const cipher = chacha20poly1305(encKey, nonce, aad);
+    // encrypt() returns ciphertext || 16-byte auth tag concatenated
+    const encrypted = cipher.encrypt(Buffer.from(plaintext, "utf8"));
+    const rawEphPubKey = ephSpki.subarray(SPKI_PREFIX.length);
+    const payload = Buffer.concat([rawEphPubKey, nonce, encrypted]);
+    return `${PROTOCOL_PREFIX}${ENCRYPTION_VERSION}:${payload.toString("base64")}`;
+}
+/**
+ * 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 function decryptEnvValue(token, privateKeyHex, varName) {
+    const prefix = `${PROTOCOL_PREFIX}${ENCRYPTION_VERSION}:`;
+    if (!token.startsWith(prefix)) {
+        const versionMatch = token.match(/^encrypted:(\w+):/);
+        if (versionMatch) {
+            throw new Error(`Unsupported encryption version: ${versionMatch[1]}. ` +
+                `This version of dotenv-gad supports: ${ENCRYPTION_VERSION}`);
+        }
+        throw new Error("Invalid encrypted value format");
+    }
+    let payload;
+    try {
+        payload = Buffer.from(token.slice(prefix.length), "base64");
+    }
+    catch {
+        throw new Error("Invalid base64 encoding in encrypted value");
+    }
+    const minLength = RAW_KEY_LENGTH + NONCE_LENGTH + AUTH_TAG_LENGTH;
+    if (payload.length < minLength) {
+        throw new Error(`Encrypted value too short: ${payload.length} bytes (minimum: ${minLength})`);
+    }
+    const rawEphPubKey = payload.subarray(0, RAW_KEY_LENGTH);
+    const nonce = payload.subarray(RAW_KEY_LENGTH, RAW_KEY_LENGTH + NONCE_LENGTH);
+    // rest = ciphertext || 16-byte auth tag (as produced by @noble/ciphers encrypt)
+    const encrypted = payload.subarray(RAW_KEY_LENGTH + NONCE_LENGTH);
+    const ephSpki = Buffer.concat([SPKI_PREFIX, rawEphPubKey]);
+    // ECDH: recipient private × ephemeral public → shared secret
+    const pkcs8 = Buffer.from(privateKeyHex, "hex");
+    const sharedSecret = diffieHellman({
+        privateKey: createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" }),
+        publicKey: createPublicKey({ key: ephSpki, format: "der", type: "spki" }),
+    });
+    // HKDF-SHA256: same derivation as encryption
+    const encKey = Buffer.from(hkdfSync("sha256", sharedSecret, HKDF_SALT, HKDF_INFO, 32));
+    const aad = Buffer.from(`${AAD_PREFIX}${varName}`);
+    const decipher = chacha20poly1305(encKey, nonce, aad);
+    try {
+        const plaintext = decipher.decrypt(encrypted);
+        return Buffer.from(plaintext).toString("utf8");
+    }
+    catch {
+        throw new DecryptionFailedError(varName);
+    }
+}
+/**
+ * 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 function isEncryptedValue(value) {
+    return value.startsWith(`${PROTOCOL_PREFIX}${ENCRYPTION_VERSION}:`);
+}
+/**
+ * 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 function loadPrivateKey(options = {}) {
+    const keysPath = options.keysPath ?? ".env.keys";
+    if (existsSync(keysPath)) {
+        const content = readFileSync(keysPath, "utf8");
+        const match = content.match(/^ENVGAD_PRIVATE_KEY=([a-fA-F0-9]+)/m);
+        if (match) {
+            const key = match[1];
+            if (key.length !== PRIVATE_KEY_HEX_LENGTH) {
+                throw new Error(`Invalid ENVGAD_PRIVATE_KEY in ${keysPath}: expected ${PRIVATE_KEY_HEX_LENGTH}-char hex-encoded PKCS8 DER, got ${key.length} chars`);
+            }
+            return key;
+        }
+    }
+    const runtimeEnv = getEnv();
+    const envKey = runtimeEnv.ENVGAD_PRIVATE_KEY;
+    if (envKey) {
+        // Remove the key from environment after reading for security
+        delete runtimeEnv.ENVGAD_PRIVATE_KEY;
+        if (!/^[a-fA-F0-9]+$/.test(envKey) || envKey.length !== PRIVATE_KEY_HEX_LENGTH) {
+            throw new Error(`Invalid ENVGAD_PRIVATE_KEY format (expected ${PRIVATE_KEY_HEX_LENGTH}-char hex-encoded PKCS8 DER, got ${envKey.length} chars)`);
+        }
+        return envKey;
+    }
+    return null;
+}

package/dist/errors.js

@@ -1,3 +1,5 @@
+const kValidationError = Symbol.for("dotenv-gad.EnvValidationError");
+const kAggregateError = Symbol.for("dotenv-gad.EnvAggregateError");
 export class EnvValidationError extends Error {
     key;
     message;
@@ -8,16 +10,50 @@ export class EnvValidationError extends Error {
         this.message = message;
         this.receiveValue = receiveValue;
         this.name = "EnvValidationError";
+        Object.defineProperty(this, kValidationError, { value: true, enumerable: false });
+    }
+    static [Symbol.hasInstance](instance) {
+        return (typeof instance === "object" &&
+            instance !== null &&
+            Object.prototype.hasOwnProperty.call(instance, kValidationError));
     }
 }
+Object.defineProperty(EnvValidationError, "name", {
+    value: "EnvValidationError",
+    configurable: true,
+    writable: false,
+});
+// WeakMap will store the full errors array completely off the instance, 
+// so Node.js inspect never sees it — no schema internals in logs.
+const errorsMap = new WeakMap();
 export class EnvAggregateError extends Error {
-    errors;
+    get errors() {
+        return errorsMap.get(this);
+    }
     constructor(errors, message) {
-        super(message);
-        this.errors = errors;
+        const summary = errors
+            .map((e) => {
+            let line = `\n  - ${e.key}: ${e.message}`;
+            if (e.value !== undefined)
+                line += ` (received: ${JSON.stringify(e.value)})`;
+            if (e.rule?.docs)
+                line += `\n    hint: ${e.rule.docs}`;
+            return line;
+        })
+            .join("");
+        super(message + summary);
         this.name = "EnvAggregateError";
+        // Store full errors (including rule) off-instance, invisible to Node.js
+        // inspect but fully accessible via the .errors getter in catch blocks.
+        errorsMap.set(this, errors);
+        Object.defineProperty(this, kAggregateError, { value: true, enumerable: false });
         Object.setPrototypeOf(this, EnvAggregateError.prototype);
     }
+    static [Symbol.hasInstance](instance) {
+        return (typeof instance === "object" &&
+            instance !== null &&
+            Object.prototype.hasOwnProperty.call(instance, kAggregateError));
+    }
     toString() {
         const errorList = this.errors
             .map((e) => {
@@ -29,8 +65,60 @@ export class EnvAggregateError extends Error {
             return msg;
         })
             .join("\n");
-        return `${this.message}:\n${errorList}`;
+        return `${this.name}: ${this.message}\n${errorList}`;
     }
 }
+Object.defineProperty(EnvAggregateError, "name", {
+    value: "EnvAggregateError",
+    configurable: true,
+    writable: false,
+});
 /** @deprecated Use `EnvAggregateError` instead — avoids shadowing the built-in `AggregateError`. */
 export const AggregateError = 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 class EncryptionKeyMissingError extends Error {
+    constructor(context) {
+        const message = context === "encryption"
+            ? "Public key not found. Run: npx dotenv-gad keygen"
+            : "Private key not found. Obtain .env.keys from your team or set ENVGAD_PRIVATE_KEY env var. " +
+                "Run: npx dotenv-gad keygen to generate new keys.";
+        super(message);
+        this.name = "EncryptionKeyMissingError";
+        Object.setPrototypeOf(this, EncryptionKeyMissingError.prototype);
+    }
+}
+/**
+ * Thrown when ChaCha20-Poly1305 authenticated decryption fails.
+ * Common causes: wrong private key, corrupted ciphertext, or AAD mismatch
+ * (ciphertext copied from a different variable).
+ */
+export class DecryptionFailedError extends Error {
+    constructor(varName) {
+        super(`Decryption failed for "${varName}". Possible causes:\n` +
+            "  - Wrong private key\n" +
+            "  - Corrupted ciphertext\n" +
+            "  - Ciphertext moved from a different variable (AAD mismatch)");
+        this.name = "DecryptionFailedError";
+        Object.setPrototypeOf(this, DecryptionFailedError.prototype);
+    }
+}
+/**
+ * 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 class EncryptedFieldMismatchError extends Error {
+    constructor(varName, shouldBeEncrypted) {
+        const message = shouldBeEncrypted
+            ? `"${varName}" must be encrypted but received a plaintext value. ` +
+                "Run: npx dotenv-gad encrypt"
+            : `"${varName}" has an encrypted value but schema does not declare encrypted: true`;
+        super(message);
+        this.name = "EncryptedFieldMismatchError";
+        Object.setPrototypeOf(this, EncryptedFieldMismatchError.prototype);
+    }
+}