@saasak/tool-env 1.0.2 → 1.2.0

package/src/core.js

@@ -0,0 +1,491 @@
+import fs from "fs-extra";
+import path from "path";
+import { decrypt, isEncrypted } from "./utils-crypto.js";
+import { buildEnv } from "./utils-env.js";
+import { findMonorepoPackages } from "./utils-pkg.js";
+
+/**
+ * @typedef {Object.<string, string>} EnvRecord
+ * Key-value pairs of environment variable name to value
+ */
+
+/**
+ * @typedef {Object} LoadOptions
+ * @property {string} [targetEnv] - Target environment (e.g. 'dev', 'production')
+ * @property {string} [secret] - Secret for decryption (or file://path to read from file)
+ * @property {string} [envPath] - Path to env.json file (default: '.env.json')
+ * @property {string} [cwd] - Working directory (default: process.cwd())
+ * @property {boolean} [applyToProcess] - Whether to apply to process.env (default: true)
+ */
+
+/**
+ * @typedef {Object} LoadEnvJsonOptions
+ * @property {string} [secret] - Secret for decryption (or file://path)
+ * @property {string} [targetEnv] - Target environment
+ * @property {string} [envPath] - Path to env.json file (default: '.env.json')
+ * @property {string} [cwd] - Working directory (default: process.cwd())
+ */
+
+/**
+ * @typedef {Object} VerifyResult
+ * @property {boolean} success - Whether verification passed
+ * @property {string|null} [path] - Path to the failed encrypted value
+ * @property {string} [error] - Error message if verification failed
+ */
+
+/** @type {string} */
+const DEFAULT_ENV = "dev";
+
+/**
+ * Environment variables that must never be injected by .env.json content.
+ * These control wrenv's own behavior and must not be overridden.
+ * @type {Set<string>}
+ */
+export const RESERVED_ENV_VARS = new Set([
+	"WRENV_TARGET",
+	"WRENV_SECRET",
+	"TARGET_ENV",
+	"TARGET_SECRET",
+]);
+
+/**
+ * Mapping of environment name aliases to canonical names
+ * Note: 'all' is a special target that writes all environments (write command only)
+ * @type {Object.<string, string>}
+ */
+const targets = {
+	development: "dev",
+	dev: "dev",
+	staging: "preprod",
+	pp: "preprod",
+	preprod: "preprod",
+	prod: "production",
+	production: "production",
+	all: "all",
+};
+
+/**
+ * Mapping of internal environment names to conventional output file names
+ * Used when writing .env files with 'all' target
+ * @type {Object.<string, string>}
+ */
+const outputNames = {
+	dev: "development",
+	preprod: "staging",
+	production: "production",
+};
+
+/**
+ * Get the conventional output file name for an internal environment name
+ * Falls back to the internal name if no mapping exists
+ * @param {string} internalName - Internal environment name (e.g. 'dev', 'preprod')
+ * @returns {string} - Conventional output name (e.g. 'development', 'staging')
+ */
+export function getOutputName(internalName) {
+	return outputNames[internalName] || internalName;
+}
+
+/**
+ * Resolve target environment with fallback chain:
+ * param -> WRENV_TARGET -> TARGET_ENV -> NODE_ENV (mapped) -> 'dev'
+ * @param {string} [targetParam] - Explicit target environment parameter
+ * @returns {string} - Resolved target environment
+ */
+export function resolveTarget(targetParam) {
+	if (targetParam) {
+		return targets[targetParam] || targetParam;
+	}
+
+	const envTarget = process.env.WRENV_TARGET || process.env.TARGET_ENV;
+	if (envTarget) {
+		return targets[envTarget] || envTarget;
+	}
+
+	const nodeEnv = process.env.NODE_ENV;
+	if (nodeEnv && targets[nodeEnv]) {
+		return targets[nodeEnv];
+	}
+
+	return DEFAULT_ENV;
+}
+
+/**
+ * Resolve target environment aliases:
+ * param -> allowedEnvs
+ * @param {string[]} [allowedEnvs] - 4rray of allowed environments to resolve against (e.g. ['dev', 'preprod', 'production'])
+ * @returns {string[]} - Resolved target sliases environment
+ */
+export function resolveTargetAliases(allowedEnvs) {
+	const allowedAliases = allowedEnvs.flatMap((env) =>
+		Object.entries(targets)
+			.find(([_, val]) => val === env)
+			.map(([alias]) => alias),
+	);
+
+	return Array.from(new Set(allowedAliases));
+}
+
+/**
+ * Resolve secret with unified fallback chain:
+ * param (stdin | file:// | file path | literal) -> WRENV_SECRET -> TARGET_SECRET -> null
+ *
+ * If reading from stdin or a file:// path fails, falls back to env vars.
+ * A bare string that is not a readable file is treated as a literal secret.
+ *
+ * @param {string} [secretParam] - Secret source: "stdin", "file://path", file path, or literal string
+ * @returns {string} - Resolved secret or empty string if not provided
+ */
+export function resolveSecret(secretParam) {
+	if (secretParam) {
+		if (secretParam === "stdin") {
+			try {
+				const value = fs.readFileSync(0, "utf8").trim();
+				if (value) return value;
+			} catch (_) {
+				// fall through to env vars
+			}
+		} else if (secretParam.startsWith("file://")) {
+			try {
+				const value = fs.readFileSync(secretParam.slice(7), "utf8").trim();
+				if (value) return value;
+			} catch (_) {
+				// fall through to env vars
+			}
+		} else {
+			try {
+				return fs.readFileSync(secretParam, "utf8").trim();
+			} catch (_) {
+				// Not a readable file path — treat as literal secret string
+				return secretParam;
+			}
+		}
+	}
+
+	return process.env.WRENV_SECRET || process.env.TARGET_SECRET || "";
+}
+
+/**
+ * Parse .env file content into key-value pairs
+ * Supports standard KEY=value format with basic quote handling
+ * @param {string} content - Raw .env file content
+ * @returns {EnvRecord} - Parsed key-value pairs
+ */
+export function parseEnvFile(content) {
+	/** @type {EnvRecord} */
+	const result = {};
+	const lines = content.split("\n");
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+
+		// Skip empty lines and comments
+		if (!trimmed || trimmed.startsWith("#")) {
+			continue;
+		}
+
+		// Find the first = sign
+		const eqIndex = trimmed.indexOf("=");
+		if (eqIndex === -1) {
+			continue;
+		}
+
+		const key = trimmed.slice(0, eqIndex).trim();
+		let value = trimmed.slice(eqIndex + 1).trim();
+
+		// Remove surrounding quotes if present
+		if (
+			(value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"))
+		) {
+			value = value.slice(1, -1);
+		}
+
+		if (key) {
+			result[key] = value;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Find the nearest package.json traversing upward from cwd and return its name (without scope)
+ * @param {string} cwd - Starting directory
+ * @param {string} scope - Package scope (e.g. '@saasak')
+ * @returns {string} - Package name without scope, or 'root' as fallback
+ */
+function findNearestPackageName(cwd, scope) {
+	let currentDir = cwd;
+
+	while (currentDir !== path.dirname(currentDir)) {
+		// Stop at filesystem root
+		const pkgPath = path.join(currentDir, "package.json");
+		if (fs.existsSync(pkgPath)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+				if (pkg.name) {
+					// Return name without scope prefix
+					return pkg.name.replace(`${scope}/`, "");
+				}
+			} catch (e) {
+				// Continue traversing upward
+			}
+		}
+		currentDir = path.dirname(currentDir);
+	}
+
+	return "root"; // fallback
+}
+
+/**
+ * Load .env.local file if it exists
+ * @param {string} [cwd] - Working directory (default: process.cwd())
+ * @returns {EnvRecord} - Local overrides or empty object
+ */
+export function loadLocalOverrides(cwd = process.cwd()) {
+	const localEnvPath = path.join(cwd, ".env.local");
+
+	if (!fs.existsSync(localEnvPath)) {
+		return {};
+	}
+
+	try {
+		const content = fs.readFileSync(localEnvPath, "utf8");
+		return parseEnvFile(content);
+	} catch (error) {
+		return {};
+	}
+}
+
+/**
+ * Find the monorepo root by looking for the env.json file, traversing upward from cwd
+ * @param {string} cwd - Starting directory
+ * @param {string} envPath - Name of the env file (e.g. '.env.json')
+ * @returns {string|null} - Path to monorepo root, or null if not found
+ */
+function findMonorepoRoot(cwd, envPath) {
+	let currentDir = cwd;
+
+	while (currentDir !== path.dirname(currentDir)) {
+		const envFilePath = path.join(currentDir, envPath);
+		if (fs.existsSync(envFilePath)) {
+			return currentDir;
+		}
+		currentDir = path.dirname(currentDir);
+	}
+
+	return null;
+}
+
+/**
+ * Load environment configuration from env.json file
+ * Automatically detects the current package and returns its specific env vars
+ * @param {LoadEnvJsonOptions} [options] - Options object
+ * @returns {EnvRecord} - Decrypted environment variables for the current package
+ * @throws {Error} - If env file not found or target env not allowed
+ */
+export function loadEnvJson(options = {}) {
+	const {
+		secret: secretParam,
+		targetEnv: targetParam,
+		envPath = ".env.json",
+		cwd = process.cwd(),
+	} = options;
+
+	const secret = resolveSecret(secretParam);
+	const targetEnv = resolveTarget(targetParam);
+
+	// Find the monorepo root (where env.json lives)
+	const monorepoRoot = findMonorepoRoot(cwd, envPath);
+	if (!monorepoRoot) {
+		throw new Error(`No env file found (searched upward from ${cwd})`);
+	}
+
+	const envFile = path.join(monorepoRoot, envPath);
+	const envContent = fs.readFileSync(envFile, "utf8");
+	const env = JSON.parse(envContent);
+
+	const allowedEnvs =
+		env && env.envs && Array.isArray(env.envs) ? env.envs : [DEFAULT_ENV];
+	const resolvedTarget = allowedEnvs.find((e) => e === targetEnv);
+
+	if (!resolvedTarget) {
+		throw new Error(
+			`Target env "${targetEnv}" is not allowed. Allowed: ${allowedEnvs.join(", ")}`,
+		);
+	}
+
+	// Get scope from monorepo root package.json
+	const rootPkgPath = path.join(monorepoRoot, "package.json");
+	let scope = "";
+	/** @type {string[]} */
+	let depsName = ["root"];
+
+	if (fs.existsSync(rootPkgPath)) {
+		try {
+			const rootPkgContent = fs.readFileSync(rootPkgPath, "utf8");
+			const rootPkg = JSON.parse(rootPkgContent);
+			scope = rootPkg.name.split("/")[0];
+
+			const foundPackages = findMonorepoPackages(monorepoRoot, scope);
+			depsName = [
+				...foundPackages.map((pkg) => pkg.name.replace(`${scope}/`, "")),
+				"root",
+			];
+		} catch (error) {
+			// Not a monorepo or error parsing, use default
+		}
+	}
+
+	const allEnvs = buildEnv(secret, resolvedTarget, env, depsName);
+
+	// Find the current package name from nearest package.json
+	const currentPackageName = findNearestPackageName(cwd, scope);
+
+	// Return env for current package (with fallback to root)
+	return allEnvs[currentPackageName] || allEnvs.root || {};
+}
+
+/**
+ * Main load function - loads env.json and applies .env.local overrides
+ * Applies values to process.env and returns the final config object
+ * @param {LoadOptions} [options] - Options object
+ * @returns {EnvRecord} - Final environment configuration
+ * @throws {Error} - If env file not found or target env not allowed
+ * @example
+ * // Basic usage - loads from cwd, applies to process.env
+ * const config = load();
+ *
+ * @example
+ * // With options
+ * const config = load({
+ *   targetEnv: 'production',
+ *   secret: 'file://./secret.txt',
+ *   applyToProcess: false
+ * });
+ */
+export function load(options = {}) {
+	const {
+		targetEnv,
+		secret,
+		envPath,
+		cwd = process.cwd(),
+		applyToProcess = true,
+	} = options;
+
+	// Resolve target first to determine if we're in dev mode
+	const resolvedTarget = resolveTarget(targetEnv);
+
+	// Load env.json config
+	const envConfig = loadEnvJson({
+		secret,
+		targetEnv: resolvedTarget,
+		envPath,
+		cwd,
+	});
+
+	// Load .env.local overrides only in dev mode (security: prevent local overrides in production)
+	const localOverrides =
+		resolvedTarget === "dev" ? loadLocalOverrides(cwd) : {};
+
+	// Merge: env.json values, then .env.local overrides (local takes precedence)
+	// Note: .env.local only overrides env.json values, not existing process.env
+	/** @type {EnvRecord} */
+	const finalConfig = { ...envConfig };
+
+	for (const [key, value] of Object.entries(localOverrides)) {
+		if (Object.prototype.hasOwnProperty.call(envConfig, key)) {
+			finalConfig[key] = value;
+		}
+	}
+
+	// - Reserved vars (WRENV_*, TARGET_*) are never injected
+	// - NODE_ENV is only injected if not already set
+	for (const key of RESERVED_ENV_VARS) {
+		delete finalConfig[key];
+	}
+	if (process.env.NODE_ENV) {
+		delete finalConfig.NODE_ENV;
+	}
+
+	// Apply to process.env if requested
+	if (applyToProcess) {
+		for (const [key, value] of Object.entries(finalConfig)) {
+			process.env[key] = value;
+		}
+	}
+
+	return finalConfig;
+}
+
+/**
+ * @typedef {Object} EncryptedValueInfo
+ * @property {string} path - Path to the encrypted value (e.g. 'variables.API_KEY.dev')
+ * @property {string} value - The encrypted value
+ */
+
+/**
+ * Verify that all encrypted values in the env can be decrypted with the provided secret
+ * This prevents mixed-encryption scenarios where different passwords are used
+ * @param {Object} env - The env configuration object (parsed env.json)
+ * @param {string} secret - The secret to use for decryption (already resolved, not file:// path)
+ * @returns {VerifyResult} - Verification result with success status
+ */
+export function verifyCanDecrypt(env, secret) {
+	/** @type {EncryptedValueInfo[]} */
+	const encryptedValues = [];
+
+	if (!secret) {
+		return { success: false, path: null, error: "No secret provided" };
+	}
+
+	// Collect all encrypted values from variables
+	if (env.variables) {
+		for (const [varName, varValue] of Object.entries(env.variables)) {
+			for (const [envKey, envVal] of Object.entries(varValue)) {
+				if (typeof envVal === "string" && isEncrypted(envVal)) {
+					encryptedValues.push({
+						path: `variables.${varName}.${envKey}`,
+						value: envVal,
+					});
+				}
+			}
+		}
+	}
+
+	// Collect all encrypted values from overrides
+	if (env.overrides) {
+		for (const [pkgName, pkgOverrides] of Object.entries(env.overrides)) {
+			for (const [varName, varValue] of Object.entries(pkgOverrides)) {
+				for (const [envKey, envVal] of Object.entries(varValue)) {
+					if (typeof envVal === "string" && isEncrypted(envVal)) {
+						encryptedValues.push({
+							path: `overrides.${pkgName}.${varName}.${envKey}`,
+							value: envVal,
+						});
+					}
+				}
+			}
+		}
+	}
+
+	// If no encrypted values exist, verification passes (first-time encryption)
+	if (encryptedValues.length === 0) {
+		return { success: true };
+	}
+
+	// Try to decrypt each encrypted value
+	for (const { path, value } of encryptedValues) {
+		try {
+			decrypt(value, secret);
+		} catch (error) {
+			return {
+				success: false,
+				path,
+				error: error.message,
+			};
+		}
+	}
+
+	return { success: true };
+}

package/src/index.d.ts

@@ -0,0 +1,82 @@
+/** Key-value pairs of environment variable name to value */
+export type EnvRecord = Record<string, string>;
+
+export interface LoadOptions {
+  /** Target environment (e.g. 'dev', 'preprod', 'production') */
+  targetEnv?: string;
+  /** Secret for decryption: "stdin", "file://path", file path, or literal string */
+  secret?: string;
+  /** Path to env.json file (default: '.env.json') */
+  envPath?: string;
+  /** Working directory (default: process.cwd()) */
+  cwd?: string;
+  /** Whether to apply resolved vars to process.env (default: true) */
+  applyToProcess?: boolean;
+}
+
+/**
+ * Load environment variables from .env.json with optional .env.local overrides.
+ * By default, applies resolved variables to process.env.
+ */
+export function load(options?: LoadOptions): EnvRecord;
+
+/**
+ * Load environment configuration from .env.json without .env.local overrides.
+ */
+export function loadEnvJson(options?: {
+  secret?: string;
+  targetEnv?: string;
+  envPath?: string;
+  cwd?: string;
+}): EnvRecord;
+
+/** Load .env.local overrides if the file exists */
+export function loadLocalOverrides(cwd?: string): EnvRecord;
+
+/** Parse .env file content into key-value pairs */
+export function parseEnvFile(content: string): EnvRecord;
+
+/**
+ * Resolve target environment with fallback chain:
+ * param -> WRENV_TARGET -> TARGET_ENV -> NODE_ENV (mapped) -> 'dev'
+ */
+export function resolveTarget(targetParam?: string): string;
+
+/**
+ * Resolve secret with fallback chain:
+ * param (stdin | file:// | file path | literal) -> WRENV_SECRET -> TARGET_SECRET -> ''
+ */
+export function resolveSecret(secretParam?: string): string;
+
+/** Get the conventional output file name for an internal environment name */
+export function getOutputName(internalName: string): string;
+
+/** Verify that all encrypted values can be decrypted with the provided secret */
+export function verifyCanDecrypt(env: object, secret: string): {
+  success: boolean;
+  path?: string | null;
+  error?: string;
+};
+
+/** Encrypt a plaintext value with the given secret */
+export function encrypt(value: string, secret: string): string;
+
+/** Decrypt an encrypted value with the given secret */
+export function decrypt(value: string, secret: string): string;
+
+/** Check if a value is encrypted */
+export function isEncrypted(value: string): boolean;
+
+/** Build environment variables for all packages from an env config */
+export function buildEnv(
+  secret: string,
+  target: string,
+  env: object,
+  names: string[],
+): Record<string, EnvRecord>;
+
+/** Find all packages in a monorepo */
+export function findMonorepoPackages(
+  root: string,
+  scope: string,
+): Array<{ name: string; dir: string }>;

package/src/index.js

@@ -0,0 +1,42 @@
+/**
+ * @saasak/tool-env - Environment variable management for monorepos
+ * 
+ * Main module exports for programmatic usage.
+ * 
+ * @example
+ * // Basic usage - load env vars and apply to process.env
+ * import { load } from '@saasak/tool-env';
+ * const config = load();
+ * 
+ * @example
+ * // Load with specific options
+ * import { load } from '@saasak/tool-env';
+ * const config = load({
+ *   targetEnv: 'production',
+ *   secret: 'file://./secret.txt',
+ *   applyToProcess: false
+ * });
+ * 
+ * @module @saasak/tool-env
+ */
+
+// Core functions for loading and resolving environment configuration
+export { 
+	load, 
+	loadEnvJson, 
+	loadLocalOverrides, 
+	parseEnvFile,
+	resolveTarget, 
+	resolveSecret,
+	verifyCanDecrypt,
+	getOutputName
+} from './core.js';
+
+// Re-export crypto utilities for encryption/decryption
+export { encrypt, decrypt, isEncrypted } from './utils-crypto.js';
+
+// Re-export env building utilities
+export { buildEnv } from './utils-env.js';
+
+// Re-export package utilities
+export { findMonorepoPackages } from './utils-pkg.js';

package/src/utils-crypto.js

@@ -3,18 +3,29 @@ import crypto from 'crypto';
 // Constants for AES-256-GCM encryption
 // GCM provides authenticated encryption (confidentiality + integrity)
 // Using 256-bit keys for strong security
+
+/** @type {string} */
 const ENCRYPTION_PREFIX = '$enc$';
+/** @type {string} */
 const ALGORITHM = 'aes-256-gcm';
-const IV_LENGTH = 16; // 128 bits
-const SALT_LENGTH = 64; // 512 bits
-const TAG_LENGTH = 16; // 128 bits
-const KEY_LENGTH = 32; // 256 bits
-const ITERATIONS = 100000; // PBKDF2 iterations
+/** @type {number} 128 bits */
+const IV_LENGTH = 16;
+/** @type {number} 512 bits */
+const SALT_LENGTH = 64;
+/** @type {number} 128 bits */
+const TAG_LENGTH = 16;
+/** @type {number} 256 bits */
+const KEY_LENGTH = 32;
+/** @type {number} PBKDF2 iterations */
+const ITERATIONS = 100000;
 
 /**
  * Derive a 256-bit key from a secret using PBKDF2
  * This ensures consistent key generation from variable-length secrets
  * and adds computational cost to prevent brute-force attacks
+ * @param {string} secret - The secret passphrase
+ * @param {Buffer} salt - Random salt for key derivation
+ * @returns {Buffer} - Derived 256-bit key
  */
 function deriveKey(secret, salt) {
 	return crypto.pbkdf2Sync(secret, salt, ITERATIONS, KEY_LENGTH, 'sha256');
@@ -24,6 +35,9 @@ function deriveKey(secret, salt) {
  * Encrypt a string value using AES-256-GCM
  * Returns a string with format: $enc$<base64(salt+iv+ciphertext+tag)>
  * Each encryption uses a unique salt and IV, so the same plaintext produces different ciphertexts
+ * @param {string} plaintext - The string to encrypt
+ * @param {string} secret - The secret passphrase for encryption
+ * @returns {string} - Encrypted string with $enc$ prefix, or original value if empty
  */
 export function encrypt(plaintext, secret) {
 	if (!plaintext) return plaintext;
@@ -50,6 +64,10 @@ export function encrypt(plaintext, secret) {
  * Decrypt an encrypted string
  * Strips the prefix and decodes the base64 payload
  * GCM authentication tag ensures the data hasn't been tampered with
+ * @param {string} encrypted - The encrypted string (with $enc$ prefix)
+ * @param {string} secret - The secret passphrase for decryption
+ * @returns {string} - Decrypted plaintext, or original value if not encrypted
+ * @throws {Error} - If decryption fails (wrong secret or corrupted data)
  */
 export function decrypt(encrypted, secret) {
 	if (!encrypted || !isEncrypted(encrypted)) {
@@ -83,8 +101,9 @@ export function decrypt(encrypted, secret) {
 /**
  * Check if a string is encrypted by looking for the prefix
  * This allows the system to detect encrypted values without attempting decryption
+ * @param {unknown} value - The value to check
+ * @returns {boolean} - True if the value is an encrypted string
  */
 export function isEncrypted(value) {
 	return typeof value === 'string' && value.startsWith(ENCRYPTION_PREFIX);
 }
-