dotenv-gad 1.4.2 → 1.6.0

package/dist/validator.js

@@ -1,20 +1,39 @@
-import { EnvAggregateError } from "./errors.js";
+import { EnvAggregateError, EncryptionKeyMissingError } from "./errors.js";
+import { decryptEnvValue, isEncryptedValue, loadPrivateKey } from "./crypto.js";
+import { getEnv } from "./runtime.js";
+import net from "net";
+const kValidator = Symbol.for("dotenv-gad.EnvValidator");
 export class EnvValidator {
     schema;
     options;
+    static EMAIL_REGEX = /^[-!#$%&'*+\/0-9=?A-Z^_a-z`{|}~](\.?[-!#$%&'*+\/0-9=?A-Z^_a-z`{|}~])*@[a-zA-Z0-9](-?\.?[a-zA-Z0-9])*\.[a-zA-Z](-?[a-zA-Z0-9])+$/;
+    static LOCAL_MAX = 64;
+    static DOMAIN_MAX = 255;
+    static DOMAIN_PART_MAX = 63;
     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, options) {
         this.schema = schema;
         this.options = options;
+        Object.defineProperty(this, kValidator, { value: true, enumerable: false });
+    }
+    /** Bundler-safe instanceof — checks the symbol marker, not the class name. */
+    static [Symbol.hasInstance](instance) {
+        return (typeof instance === "object" &&
+            instance !== null &&
+            Object.prototype.hasOwnProperty.call(instance, kValidator));
     }
     validate(env) {
         this.errors = [];
+        // First Decrypt encrypted fields and check for schema/value mismatches.
+        const { processedEnv, skipKeys } = this.preprocessEncryption(env);
         const result = {};
         // Build grouping map for object types that support envPrefix.
         // We'll collect all prefixes first and then make a single pass over env keys
@@ -29,29 +48,31 @@ export class EnvValidator {
                 groupedEnv[k] = {};
             }
         }
-        const envKeys = Object.keys(env);
+        const envKeys = Object.keys(processedEnv);
         for (let i = 0; i < envKeys.length; i++) {
             const eKey = envKeys[i];
             for (let j = 0; j < prefixes.length; j++) {
                 const { key, prefix } = prefixes[j];
                 if (eKey.startsWith(prefix)) {
                     const subKey = eKey.slice(prefix.length);
-                    groupedEnv[key][subKey] = env[eKey];
+                    groupedEnv[key][subKey] = processedEnv[eKey];
                 }
             }
         }
-        // Micro-optimization: avoid creating intermediate arrays from Object.entries
         const schemaKeys = Object.keys(this.schema);
         for (let i = 0; i < schemaKeys.length; i++) {
             const key = schemaKeys[i];
             const rule = this.schema[key];
+            // Keys that already have a preprocessing error (encryption mismatch, decryption failure, etc.) get skipped
+            if (skipKeys.has(key))
+                continue;
             try {
                 // If we have grouped values for this key use them (preferred over JSON string)
                 const valToValidate = groupedEnv[key] && Object.keys(groupedEnv[key]).length > 0
                     ? groupedEnv[key]
-                    : env[key];
+                    : processedEnv[key];
                 // If both grouped and a top-level JSON value exist, prefer grouped and warn
-                if (groupedEnv[key] && Object.keys(groupedEnv[key]).length > 0 && env[key] !== undefined) {
+                if (groupedEnv[key] && Object.keys(groupedEnv[key]).length > 0 && processedEnv[key] !== undefined) {
                     console.warn(`Both prefixed variables and top-level ${key} exist; prefixed vars are used`);
                 }
                 // If strict mode is enabled, and this key has grouped env vars, ensure there are no unexpected subkeys
@@ -77,7 +98,7 @@ export class EnvValidator {
                     // - includeRaw: include raw values for non-sensitive fields
                     // - includeSensitive: when used with includeRaw, include raw sensitive values too (use with caution)
                     let displayedValue;
-                    if (env[key] === undefined) {
+                    if (processedEnv[key] === undefined) {
                         displayedValue = undefined;
                     }
                     else if (this.options?.includeRaw) {
@@ -85,11 +106,11 @@ export class EnvValidator {
                             displayedValue = "****";
                         }
                         else {
-                            displayedValue = env[key];
+                            displayedValue = processedEnv[key];
                         }
                     }
                     else {
-                        displayedValue = this.redactValue(env[key], rule.sensitive);
+                        displayedValue = this.redactValue(processedEnv[key], rule.sensitive);
                     }
                     this.errors.push({
                         key,
@@ -123,7 +144,17 @@ export class EnvValidator {
         }
         return result;
     }
-    // Redact or trim sensitive values for error reporting
+    /**
+     * 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 `"****"`.
+     */
     redactValue(value, sensitive) {
         if (value === undefined)
             return undefined;
@@ -136,8 +167,16 @@ export class EnvValidator {
         }
         return value;
     }
-    // Try to quickly determine if a string *might* be JSON before parsing to avoid
-    // costly exceptions in the hot path for clearly non-JSON values.
+    /**
+     * 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
+     */
     tryParseJSON(value) {
         if (typeof value !== "string")
             return { ok: false };
@@ -162,12 +201,22 @@ export class EnvValidator {
                 throw new Error(`Missing required environment variable`);
             return effectiveRule.default;
         }
+        if (typeof value === "string") {
+            value = value.trim();
+            // Re-check emptiness after trim in case the value was only whitespace
+            if (value === "") {
+                if (effectiveRule.required)
+                    throw new Error(`Missing required environment variable`);
+                return effectiveRule.default;
+            }
+        }
         if (effectiveRule.transform) {
             value = effectiveRule.transform(value);
         }
         switch (effectiveRule.type) {
             case "string":
-                value = String(value).trim();
+                // value is already trimmed above; cast to string for minLength/maxLength checks
+                value = String(value);
                 if (effectiveRule.minLength !== undefined && value.length < effectiveRule.minLength) {
                     throw new Error(`Environment variable ${key} must be at least ${effectiveRule.minLength} characters`);
                 }
@@ -190,10 +239,10 @@ export class EnvValidator {
             case "boolean":
                 if (typeof value === "string") {
                     value = value.toLowerCase();
-                    if (value === "true") {
+                    if (value === "true" || value === "yes" || value === "1" || value === "on") {
                         value = true;
                     }
-                    else if (value === "false") {
+                    else if (value === "false" || value === "no" || value === "0" || value === "off") {
                         value = false;
                     }
                 }
@@ -218,12 +267,12 @@ export class EnvValidator {
                 }
                 break;
             case "email":
-                if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value))) {
+                if (!this.validateEmail(value)) {
                     throw new Error("Must be a valid email");
                 }
                 break;
             case "ip":
-                if (!/^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/.test(String(value))) {
+                if (!net.isIP(value)) {
                     throw new Error("Must be a valid IP address");
                 }
                 break;
@@ -300,9 +349,105 @@ export class EnvValidator {
         }
         return value;
     }
-    getEffectiveRule(key, rule) {
-        const envName = process.env.NODE_ENV || "development";
+    getEffectiveRule(_key, rule) {
+        const runtimeEnv = getEnv();
+        const envName = runtimeEnv.NODE_ENV || "development";
         const envRule = rule.env?.[envName] || {};
         return { ...rule, ...envRule };
     }
+    /**
+     * 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.
+     */
+    preprocessEncryption(env) {
+        const processedEnv = { ...env };
+        const skipKeys = new Set();
+        const encryptedSchemaKeys = Object.keys(this.schema).filter((k) => this.schema[k].encrypted);
+        if (encryptedSchemaKeys.length > 0) {
+            // Only load the private key when at least one value is already encrypted
+            const needsDecryption = encryptedSchemaKeys.some((k) => processedEnv[k] != null && processedEnv[k] !== "" && isEncryptedValue(processedEnv[k]));
+            let privateKeyHex = null;
+            if (needsDecryption) {
+                privateKeyHex = loadPrivateKey({ keysPath: this.options?.keysPath });
+                if (!privateKeyHex) {
+                    throw new EncryptionKeyMissingError("decryption");
+                }
+            }
+            for (const key of encryptedSchemaKeys) {
+                const value = processedEnv[key];
+                if (value == null || value === "")
+                    continue; // handled by required check in main loop
+                if (isEncryptedValue(value)) {
+                    try {
+                        processedEnv[key] = decryptEnvValue(value, privateKeyHex, key);
+                    }
+                    catch (err) {
+                        this.errors.push({
+                            key,
+                            message: err instanceof Error ? err.message : "Decryption failed",
+                            rule: this.schema[key],
+                        });
+                        skipKeys.add(key);
+                    }
+                }
+                else {
+                    // Plaintext value for a field that should be encrypted
+                    if (this.options?.allowPlaintext) {
+                        console.warn(`[dotenv-gad] "${key}" has a plaintext value but schema declares encrypted: true. ` +
+                            "Run: npx dotenv-gad encrypt");
+                    }
+                    else {
+                        this.errors.push({
+                            key,
+                            message: 'Must be encrypted. Run: npx dotenv-gad encrypt',
+                            rule: this.schema[key],
+                        });
+                        skipKeys.add(key);
+                    }
+                }
+            }
+        }
+        // Flag any env value that looks encrypted but the schema doesn't declare encrypted: true
+        for (const [eKey, value] of Object.entries(processedEnv)) {
+            if (skipKeys.has(eKey))
+                continue;
+            if (value && isEncryptedValue(value) && !this.schema[eKey]?.encrypted) {
+                this.errors.push({
+                    key: eKey,
+                    message: "Encrypted value found but schema does not declare encrypted: true",
+                });
+                skipKeys.add(eKey);
+            }
+        }
+        return { processedEnv, skipKeys };
+    }
+    /*
+   * Email validation logic adapted from:
+   * Project: email-validator
+   *  * Repository: https://github.com/manishsaraan/email-validator
+   *
+   * * Adapted to enforce email validation rules more strictly
+   */
+    validateEmail(email) {
+        if (!email)
+            return false;
+        const emailParts = email.split("@");
+        if (emailParts.length !== 2)
+            return false;
+        const [local, domain] = emailParts;
+        if (local.length > EnvValidator.LOCAL_MAX || domain.length > EnvValidator.DOMAIN_MAX)
+            return false;
+        const domainParts = domain.split(".");
+        if (domainParts.some(part => part.length > EnvValidator.DOMAIN_PART_MAX))
+            return false;
+        return EnvValidator.EMAIL_REGEX.test(email);
+    }
 }
+Object.defineProperty(EnvValidator, "name", {
+    value: "EnvValidator",
+    configurable: true,
+    writable: false,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-gad",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "type": "module",
@@ -32,10 +32,12 @@
     "config",
     "type-safe",
     "nodejs",
+    "bun",
     "cli"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
   },
   "exports": {
     ".": {
@@ -63,7 +65,7 @@
   ],
   "author": "Kasim Lyee",
   "license": "MIT",
-  "description": "Environment variable validation and type safety for Node.js and modern JavaScript applications",
+  "description": "Environment variable validation and type safety for Node.js, Bun, and modern JavaScript applications",
   "repository": {
     "type": "git",
     "url": "https://github.com/kasimlyee/dotenv-gad.git"
@@ -96,11 +98,11 @@
     "esbuild": "^0.27.2"
   },
   "dependencies": {
+    "@noble/ciphers": "2.2.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
     "figlet": "^1.10.0",
-    "inquirer": "^13.2.1",
     "ora": "^9.1.0"
   }
 }