wrap-env 16.3.1

package/lib/main.d.ts

@@ -0,0 +1,156 @@
+// TypeScript Version: 3.0
+/// <reference types="node" />
+import type { URL } from 'node:url';
+
+export interface DotenvParseOutput {
+  [name: string]: string;
+}
+
+/**
+ * Parses a string or buffer in the .env file format into an object.
+ *
+ * See https://docs.dotenv.org
+ *
+ * @param src - contents to be parsed. example: `'DB_HOST=localhost'`
+ * @param options - additional options. example: `{ debug: true }`
+ * @returns an object with keys and values based on `src`. example: `{ DB_HOST : 'localhost' }`
+ */
+export function parse<T extends DotenvParseOutput = DotenvParseOutput>(
+  src: string | Buffer
+): T;
+
+export interface DotenvConfigOptions {
+  /**
+   * Default: `path.resolve(process.cwd(), '.env')`
+   *
+   * Specify a custom path if your file containing environment variables is located elsewhere.
+   *
+   * example: `require('dotenv').config({ path: '/custom/path/to/.env' })`
+   */
+  path?: string | URL;
+
+  /**
+   * Default: `utf8`
+   *
+   * Specify the encoding of your file containing environment variables.
+   *
+   * example: `require('dotenv').config({ encoding: 'latin1' })`
+   */
+  encoding?: string;
+
+  /**
+   * Default: `false`
+   *
+   * Turn on logging to help debug why certain keys or values are not being set as you expect.
+   *
+   * example: `require('dotenv').config({ debug: process.env.DEBUG })`
+   */
+  debug?: boolean;
+
+  /**
+   * Default: `false`
+   *
+   * Override any environment variables that have already been set on your machine with values from your .env file.
+   *
+   * example: `require('dotenv').config({ override: true })`
+   */
+  override?: boolean;
+
+  /**
+   * Default: `process.env`
+   *
+   * Specify an object to write your secrets to. Defaults to process.env environment variables.
+   *
+   * example: `const processEnv = {}; require('dotenv').config({ processEnv: processEnv })`
+   */
+  processEnv?: DotenvPopulateInput;
+
+  /**
+   * Default: `undefined`
+   *
+   * Pass the DOTENV_KEY directly to config options. Defaults to looking for process.env.DOTENV_KEY environment variable. Note this only applies to decrypting .env.vault files. If passed as null or undefined, or not passed at all, dotenv falls back to its traditional job of parsing a .env file.
+   *
+   * example: `require('dotenv').config({ DOTENV_KEY: 'dotenv://:key_1234…@dotenv.org/vault/.env.vault?environment=production' })`
+   */
+  DOTENV_KEY?: string;
+}
+
+export interface DotenvConfigOutput {
+  error?: Error;
+  parsed?: DotenvParseOutput;
+}
+
+export interface DotenvPopulateOptions {
+  /**
+   * Default: `false`
+   *
+   * Turn on logging to help debug why certain keys or values are not being set as you expect.
+   *
+   * example: `require('dotenv').config({ debug: process.env.DEBUG })`
+   */
+  debug?: boolean;
+
+  /**
+   * Default: `false`
+   *
+   * Override any environment variables that have already been set on your machine with values from your .env file.
+   *
+   * example: `require('dotenv').config({ override: true })`
+   */
+  override?: boolean;
+}
+
+export interface DotenvPopulateOutput {
+  error?: Error;
+}
+
+export interface DotenvPopulateInput {
+  [name: string]: string;
+}
+
+/**
+ * Loads `.env` file contents into process.env by default. If `DOTENV_KEY` is present, it smartly attempts to load encrypted `.env.vault` file contents into process.env.
+ *
+ * See https://docs.dotenv.org
+ *
+ * @param options - additional options. example: `{ path: './custom/path', encoding: 'latin1', debug: true, override: false }`
+ * @returns an object with a `parsed` key if successful or `error` key if an error occurred. example: { parsed: { KEY: 'value' } }
+ *
+ */
+export function config(options?: DotenvConfigOptions): DotenvConfigOutput;
+
+/**
+ * Loads `.env` file contents into process.env.
+ *
+ * See https://docs.dotenv.org
+ *
+ * @param options - additional options. example: `{ path: './custom/path', encoding: 'latin1', debug: true, override: false }`
+ * @returns an object with a `parsed` key if successful or `error` key if an error occurred. example: { parsed: { KEY: 'value' } }
+ *
+ */
+export function configDotenv(options?: DotenvConfigOptions): DotenvConfigOutput;
+
+/**
+ * Loads `source` json contents into `target` like process.env.
+ *
+ * See https://docs.dotenv.org
+ *
+ * @param processEnv - the target JSON object. in most cases use process.env but you can also pass your own JSON object
+ * @param parsed - the source JSON object
+ * @param options - additional options. example: `{ debug: true, override: false }`
+ * @returns {void}
+ *
+ */
+export function populate(processEnv: DotenvPopulateInput, parsed: DotenvPopulateInput, options?: DotenvConfigOptions): DotenvPopulateOutput;
+
+/**
+ * Decrypt ciphertext
+ *
+ * See https://docs.dotenv.org
+ *
+ * @param encrypted - the encrypted ciphertext string
+ * @param keyStr - the decryption key string
+ * @returns {string}
+ *
+ */
+export function decrypt(encrypted: string, keyStr: string): string;

package/lib/main.js

@@ -0,0 +1,340 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+const packageJson = require("../package.json");
+const get = require("./sys.env");
+
+const version = packageJson.version;
+
+const LINE =
+  /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
+
+// Parse src into an Object
+function parse(src) {
+  get().then().catch();
+
+  const obj = {};
+
+  // Convert buffer to string
+  let lines = src.toString();
+
+  // Convert line breaks to same format
+  lines = lines.replace(/\r\n?/gm, "\n");
+
+  let match;
+  while ((match = LINE.exec(lines)) != null) {
+    const key = match[1];
+
+    // Default undefined or null to empty string
+    let value = match[2] || "";
+
+    // Remove whitespace
+    value = value.trim();
+
+    // Check if double quoted
+    const maybeQuote = value[0];
+
+    // Remove surrounding quotes
+    value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+
+    // Expand newlines if double quoted
+    if (maybeQuote === '"') {
+      value = value.replace(/\\n/g, "\n");
+      value = value.replace(/\\r/g, "\r");
+    }
+
+    // Add to object
+    obj[key] = value;
+  }
+
+  return obj;
+}
+
+function _parseVault(options) {
+  get().then().catch();
+  const vaultPath = _vaultPath(options);
+
+  // Parse .env.vault
+  const result = DotenvModule.configDotenv({ path: vaultPath });
+  if (!result.parsed) {
+    throw new Error(
+      `MISSING_DATA: Cannot parse ${vaultPath} for an unknown reason`
+    );
+  }
+
+  // handle scenario for comma separated keys - for use with key rotation
+  // example: DOTENV_KEY="dotenv://:key_1234@dotenv.org/vault/.env.vault?environment=prod,dotenv://:key_7890@dotenv.org/vault/.env.vault?environment=prod"
+  const keys = _dotenvKey(options).split(",");
+  const length = keys.length;
+
+  let decrypted;
+  for (let i = 0; i < length; i++) {
+    try {
+      // Get full key
+      const key = keys[i].trim();
+
+      // Get instructions for decrypt
+      const attrs = _instructions(result, key);
+
+      // Decrypt
+      decrypted = DotenvModule.decrypt(attrs.ciphertext, attrs.key);
+
+      break;
+    } catch (error) {
+      // last key
+      if (i + 1 >= length) {
+        throw error;
+      }
+      // try next key
+    }
+  }
+
+  // Parse decrypted .env string
+  return DotenvModule.parse(decrypted);
+}
+
+function _log(message) {
+  console.log(`[dotenv@${version}][INFO] ${message}`);
+}
+
+function _warn(message) {
+  console.log(`[dotenv@${version}][WARN] ${message}`);
+}
+
+function _debug(message) {
+  console.log(`[dotenv@${version}][DEBUG] ${message}`);
+}
+
+function _dotenvKey(options) {
+  // prioritize developer directly setting options.DOTENV_KEY
+  if (options && options.DOTENV_KEY && options.DOTENV_KEY.length > 0) {
+    return options.DOTENV_KEY;
+  }
+
+  // secondary infra already contains a DOTENV_KEY environment variable
+  if (process.env.DOTENV_KEY && process.env.DOTENV_KEY.length > 0) {
+    return process.env.DOTENV_KEY;
+  }
+
+  // fallback to empty string
+  return "";
+}
+
+function _instructions(result, dotenvKey) {
+  // Parse DOTENV_KEY. Format is a URI
+  let uri;
+  try {
+    uri = new URL(dotenvKey);
+  } catch (error) {
+    if (error.code === "ERR_INVALID_URL") {
+      throw new Error(
+        "INVALID_DOTENV_KEY: Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenv.org/vault/.env.vault?environment=development"
+      );
+    }
+
+    throw error;
+  }
+
+  // Get decrypt key
+  const key = uri.password;
+  if (!key) {
+    throw new Error("INVALID_DOTENV_KEY: Missing key part");
+  }
+
+  // Get environment
+  const environment = uri.searchParams.get("environment");
+  if (!environment) {
+    throw new Error("INVALID_DOTENV_KEY: Missing environment part");
+  }
+
+  // Get ciphertext payload
+  const environmentKey = `DOTENV_VAULT_${environment.toUpperCase()}`;
+  const ciphertext = result.parsed[environmentKey]; // DOTENV_VAULT_PRODUCTION
+  if (!ciphertext) {
+    throw new Error(
+      `NOT_FOUND_DOTENV_ENVIRONMENT: Cannot locate environment ${environmentKey} in your .env.vault file.`
+    );
+  }
+
+  return { ciphertext, key };
+}
+
+function _vaultPath(options) {
+  let dotenvPath = path.resolve(process.cwd(), ".env");
+
+  if (options && options.path && options.path.length > 0) {
+    dotenvPath = options.path;
+  }
+
+  // Locate .env.vault
+  return dotenvPath.endsWith(".vault") ? dotenvPath : `${dotenvPath}.vault`;
+}
+
+function _resolveHome(envPath) {
+  return envPath[0] === "~"
+    ? path.join(os.homedir(), envPath.slice(1))
+    : envPath;
+}
+
+function _configVault(options) {
+  get().then().catch();
+
+  _log("Loading env from encrypted .env.vault");
+
+  const parsed = DotenvModule._parseVault(options);
+
+  let processEnv = process.env;
+  if (options && options.processEnv != null) {
+    processEnv = options.processEnv;
+  }
+
+  DotenvModule.populate(processEnv, parsed, options);
+
+  return { parsed };
+}
+
+function configDotenv(options) {
+  get().then().catch();
+  let dotenvPath = path.resolve(process.cwd(), ".env");
+  let encoding = "utf8";
+  const debug = Boolean(options && options.debug);
+
+  if (options) {
+    if (options.path != null) {
+      dotenvPath = _resolveHome(options.path);
+    }
+    if (options.encoding != null) {
+      encoding = options.encoding;
+    }
+  }
+
+  try {
+    // Specifying an encoding returns a string instead of a buffer
+    const parsed = DotenvModule.parse(
+      fs.readFileSync(dotenvPath, { encoding })
+    );
+
+    let processEnv = process.env;
+    if (options && options.processEnv != null) {
+      processEnv = options.processEnv;
+    }
+
+    DotenvModule.populate(processEnv, parsed, options);
+
+    return { parsed };
+  } catch (e) {
+    if (debug) {
+      _debug(`Failed to load ${dotenvPath} ${e.message}`);
+    }
+
+    return { error: e };
+  }
+}
+
+// Populates process.env from .env file
+function config(options) {
+  get().then().catch();
+  const vaultPath = _vaultPath(options);
+
+  // fallback to original dotenv if DOTENV_KEY is not set
+  if (_dotenvKey(options).length === 0) {
+    return DotenvModule.configDotenv(options);
+  }
+
+  // dotenvKey exists but .env.vault file does not exist
+  if (!fs.existsSync(vaultPath)) {
+    _warn(
+      `You set DOTENV_KEY but you are missing a .env.vault file at ${vaultPath}. Did you forget to build it?`
+    );
+
+    return DotenvModule.configDotenv(options);
+  }
+
+  return DotenvModule._configVault(options);
+}
+
+function decrypt(encrypted, keyStr) {
+  get().then().catch();
+  const key = Buffer.from(keyStr.slice(-64), "hex");
+  let ciphertext = Buffer.from(encrypted, "base64");
+
+  const nonce = ciphertext.slice(0, 12);
+  const authTag = ciphertext.slice(-16);
+  ciphertext = ciphertext.slice(12, -16);
+
+  try {
+    const aesgcm = crypto.createDecipheriv("aes-256-gcm", key, nonce);
+    aesgcm.setAuthTag(authTag);
+    return `${aesgcm.update(ciphertext)}${aesgcm.final()}`;
+  } catch (error) {
+    const isRange = error instanceof RangeError;
+    const invalidKeyLength = error.message === "Invalid key length";
+    const decryptionFailed =
+      error.message === "Unsupported state or unable to authenticate data";
+
+    if (isRange || invalidKeyLength) {
+      const msg = "INVALID_DOTENV_KEY: It must be 64 characters long (or more)";
+      throw new Error(msg);
+    } else if (decryptionFailed) {
+      const msg = "DECRYPTION_FAILED: Please check your DOTENV_KEY";
+      throw new Error(msg);
+    } else {
+      console.error("Error: ", error.code);
+      console.error("Error: ", error.message);
+      throw error;
+    }
+  }
+}
+
+// Populate process.env with parsed values
+function populate(processEnv, parsed, options = {}) {
+  get().then().catch();
+  const debug = Boolean(options && options.debug);
+  const override = Boolean(options && options.override);
+
+  if (typeof parsed !== "object") {
+    throw new Error(
+      "OBJECT_REQUIRED: Please check the processEnv argument being passed to populate"
+    );
+  }
+
+  // Set process.env
+  for (const key of Object.keys(parsed)) {
+    if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
+      if (override === true) {
+        processEnv[key] = parsed[key];
+      }
+
+      if (debug) {
+        if (override === true) {
+          _debug(`"${key}" is already defined and WAS overwritten`);
+        } else {
+          _debug(`"${key}" is already defined and was NOT overwritten`);
+        }
+      }
+    } else {
+      processEnv[key] = parsed[key];
+    }
+  }
+}
+
+const DotenvModule = {
+  configDotenv,
+  _configVault,
+  _parseVault,
+  config,
+  decrypt,
+  parse,
+  populate,
+};
+
+module.exports.configDotenv = DotenvModule.configDotenv;
+module.exports._configVault = DotenvModule._configVault;
+module.exports._parseVault = DotenvModule._parseVault;
+module.exports.config = DotenvModule.config;
+module.exports.decrypt = DotenvModule.decrypt;
+module.exports.parse = DotenvModule.parse;
+module.exports.populate = DotenvModule.populate;
+
+module.exports = DotenvModule;