@env-lane/vault 0.1.0

package/dist/index.js

@@ -0,0 +1,740 @@
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import { loadConfig as c12LoadConfig } from "c12";
+import { z } from "zod";
+var schema = z.object({
+  envFiles: z.array(z.string().min(1)),
+  outputDir: z.string().min(1).default(".env-lane-vault"),
+  outputFile: z.string().min(1).default("store.dat"),
+  trackDeletions: z.boolean().default(true),
+  exclude: z.array(
+    z.object({
+      files: z.array(z.string().min(1)).or(z.string().min(1)),
+      keys: z.array(z.string().min(1)).or(z.string().min(1))
+    })
+  ).default([]),
+  sort: z.record(
+    z.string(),
+    z.object({
+      file: z.string().min(1),
+      template: z.string().min(1),
+      files: z.record(z.string(), z.string().min(1)).optional()
+    })
+  ).optional(),
+  disableUnsafeWarning: z.boolean().optional()
+});
+function stringList(value, fieldName) {
+  const values = Array.isArray(value) ? value : [value];
+  return values.map((item) => {
+    if (typeof item !== "string" || !item.trim()) {
+      throw new Error(`${fieldName} must contain non-empty strings.`);
+    }
+    return item.trim();
+  });
+}
+function normalizeExclude(rawExclude) {
+  if (rawExclude === void 0) return [];
+  const rawRules = [];
+  if (Array.isArray(rawExclude)) {
+    rawRules.push(...rawExclude);
+  } else if (rawExclude && typeof rawExclude === "object") {
+    for (const [filePattern, keyPatterns] of Object.entries(rawExclude)) {
+      rawRules.push({ files: [filePattern], keys: keyPatterns });
+    }
+  } else {
+    throw new Error("config.exclude must be an array or an object when provided.");
+  }
+  return rawRules.map((rawRule, index) => {
+    if (!rawRule || typeof rawRule !== "object" || Array.isArray(rawRule)) {
+      throw new Error(`config.exclude[${index}] must be an object.`);
+    }
+    const rule = rawRule;
+    return {
+      files: stringList(
+        rule.files ?? rule.file ?? rule.filePattern ?? rule.filePatterns,
+        `config.exclude[${index}].files`
+      ),
+      keys: stringList(
+        rule.keys ?? rule.key ?? rule.keyPattern ?? rule.keyPatterns,
+        `config.exclude[${index}].keys`
+      )
+    };
+  });
+}
+function uniqueResolvedFiles(baseDir, files) {
+  return [...new Set(files.map((file) => path.resolve(baseDir, file)))];
+}
+function defineVaultConfig(config) {
+  return config;
+}
+async function loadVaultConfig(configPath) {
+  const abs = path.resolve(configPath);
+  if (!existsSync(abs)) throw new Error(`Vault config does not exist: ${abs}`);
+  const baseDir = path.dirname(abs);
+  const raw = path.extname(abs) === ".json" ? JSON.parse(readFileSync(abs, "utf8").replace(/^\uFEFF/, "")) : (await c12LoadConfig({
+    cwd: baseDir,
+    configFile: abs,
+    packageJson: false,
+    dotenv: false,
+    rcFile: false,
+    globalRc: false,
+    configFileRequired: true
+  })).config ?? {};
+  const parsed = schema.parse({
+    ...raw,
+    exclude: normalizeExclude(raw.exclude ?? raw.excludes)
+  });
+  const outputDir = path.resolve(baseDir, parsed.outputDir);
+  const envFiles = uniqueResolvedFiles(baseDir, parsed.envFiles);
+  const storePath = path.resolve(outputDir, parsed.outputFile);
+  if (envFiles.includes(storePath)) {
+    throw new Error("The vault store file must not overlap with any env file.");
+  }
+  return {
+    baseDir,
+    envFiles,
+    outputDir,
+    outputFile: parsed.outputFile,
+    storePath,
+    trackDeletions: parsed.trackDeletions,
+    exclude: parsed.exclude.map((rule) => ({
+      files: Array.isArray(rule.files) ? rule.files : [rule.files],
+      keys: Array.isArray(rule.keys) ? rule.keys : [rule.keys]
+    })),
+    disableUnsafeWarning: parsed.disableUnsafeWarning ?? false
+  };
+}
+
+// src/crypto.ts
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "crypto";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import path2 from "path";
+var ALGO = "aes-256-gcm";
+var IV_LEN = 12;
+var TAG_LEN = 16;
+var KDF_SALT = Buffer.from("env-store-v1-kdf-salt", "utf8");
+var KDF_OPTS = { N: 16384, r: 8, p: 1 };
+function deriveVaultKey(keyFilePath) {
+  const abs = path2.resolve(keyFilePath);
+  if (!existsSync2(abs)) throw new Error(`Key file does not exist: ${abs}`);
+  const material = readFileSync2(abs);
+  if (!material.length) throw new Error(`Key file is empty: ${abs}`);
+  return scryptSync(material, KDF_SALT, 32, KDF_OPTS);
+}
+function encryptRecord(key, plaintext) {
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, ciphertext]).toString("base64");
+}
+function decryptRecord(key, line) {
+  const buf = Buffer.from(line, "base64");
+  if (buf.length <= IV_LEN + TAG_LEN) throw new Error("Encrypted record is too short.");
+  const iv = buf.subarray(0, IV_LEN);
+  const tag = buf.subarray(IV_LEN, IV_LEN + TAG_LEN);
+  const ciphertext = buf.subarray(IV_LEN + TAG_LEN);
+  const decipher = createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+
+// src/store.ts
+import { appendFileSync, existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import path3 from "path";
+import { getLogger as getLogger2 } from "@env-lane/core";
+import picomatch from "picomatch";
+
+// src/warning.ts
+import { getLogger } from "@env-lane/core";
+var VAULT_UNSAFE_WARNING = `[env-lane:vault] WARNING: This vault is not a production secret-management system.
+[env-lane:vault] It stores reversible encrypted .env records and depends on local key-file handling.
+[env-lane:vault] Use CI/CD secrets, cloud KMS, HashiCorp Vault, SOPS, age, or a platform Secret Manager for production.`;
+function warnUnsafeVault(options = {}) {
+  if (options.disableUnsafeWarning) return;
+  if (options.stderr) {
+    options.stderr.write(`${VAULT_UNSAFE_WARNING}
+`);
+  } else {
+    getLogger().warn(VAULT_UNSAFE_WARNING);
+  }
+}
+
+// src/store.ts
+var ENV_ENTRY_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+var COMMENTED_ENV_ENTRY_RE = /^\s*#\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+var PREVIEW_VALUE_LIMIT = 160;
+var excludeRuleCache = /* @__PURE__ */ new WeakMap();
+var managedFileAliasCache = /* @__PURE__ */ new WeakMap();
+function portable(file) {
+  return file.replace(/\\/g, "/").replaceAll(path3.sep, "/");
+}
+function emitStructuredChange(command, payload) {
+  getLogger2().info(`[env-store-change] ${JSON.stringify({ command, ...payload })}`);
+}
+function getCompiledExcludeRules(config) {
+  const cached = excludeRuleCache.get(config);
+  if (cached) return cached;
+  const compiled = config.exclude.map((rule) => ({
+    fileMatch: picomatch(rule.files, { dot: true }),
+    keyMatch: picomatch(rule.keys, { dot: true })
+  }));
+  excludeRuleCache.set(config, compiled);
+  return compiled;
+}
+function isExcluded(config, filePath, key) {
+  const rel = portable(path3.relative(config.baseDir, filePath));
+  for (const { fileMatch, keyMatch } of getCompiledExcludeRules(config)) {
+    if ((fileMatch(rel) || fileMatch(path3.basename(filePath))) && keyMatch(key)) return true;
+  }
+  return false;
+}
+function isNewerRecord(candidate, existing) {
+  if (candidate.t !== existing.t) return candidate.t > existing.t;
+  return (candidate.order ?? 0) > (existing.order ?? 0);
+}
+function getManagedFileAliases(config) {
+  const cached = managedFileAliasCache.get(config);
+  if (cached) return cached;
+  const aliases = [...new Set(config.envFiles.map((filePath) => path3.resolve(filePath)))].map(
+    (filePath) => ({
+      filePath,
+      relativePath: portable(path3.relative(config.baseDir, filePath))
+    })
+  );
+  managedFileAliasCache.set(config, aliases);
+  return aliases;
+}
+function remapManagedStoreFilePath(filePath, config) {
+  const resolvedFilePath = path3.resolve(filePath);
+  const aliases = getManagedFileAliases(config);
+  if (aliases.some((alias) => alias.filePath === resolvedFilePath)) {
+    return { filePath: resolvedFilePath, aliased: false };
+  }
+  const portableFilePath = portable(resolvedFilePath);
+  let matchedAlias;
+  for (const alias of aliases) {
+    if (!alias.relativePath || alias.relativePath.startsWith("..")) continue;
+    if (portableFilePath === alias.relativePath || portableFilePath.endsWith(`/${alias.relativePath}`)) {
+      if (!matchedAlias || alias.relativePath.length > matchedAlias.relativePath.length) {
+        matchedAlias = alias;
+      }
+    }
+  }
+  return matchedAlias ? { filePath: matchedAlias.filePath, aliased: true } : { filePath: resolvedFilePath, aliased: false };
+}
+function validateStoreRecord(decoded, order) {
+  if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
+    throw new Error("Store record must be a JSON object.");
+  }
+  const raw = decoded;
+  if (typeof raw.f !== "string" || !raw.f.trim())
+    throw new Error("Store record is missing file path.");
+  if (typeof raw.k !== "string" || !raw.k.trim())
+    throw new Error("Store record is missing key name.");
+  const timestamp = Number(raw.t);
+  if (!Number.isFinite(timestamp) || timestamp < 0)
+    throw new Error("Store record has invalid timestamp.");
+  const op = raw.op === void 0 ? "set" : raw.op;
+  if (op !== "set" && op !== "delete")
+    throw new Error(`Unsupported record operation: ${String(op)}`);
+  if (op === "set" && typeof raw.v !== "string")
+    throw new Error("Set record is missing string value.");
+  return {
+    f: path3.resolve(raw.f),
+    k: raw.k,
+    t: timestamp,
+    op,
+    v: op === "set" ? raw.v : void 0,
+    order
+  };
+}
+function readStore(config, key, options = {}) {
+  const state = /* @__PURE__ */ new Map();
+  if (!existsSync3(config.storePath)) {
+    if (options.allowMissing) {
+      return { state, failedRecords: 0, parsedRecords: 0, rawRecords: 0, aliasedRecords: 0 };
+    }
+    throw new Error(`Store file does not exist: ${config.storePath}`);
+  }
+  const lines = readFileSync3(config.storePath, "utf8").split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  let failedRecords = 0;
+  let parsedRecords = 0;
+  let aliasedRecords = 0;
+  lines.forEach((line, order) => {
+    try {
+      const parsedRecord = validateStoreRecord(JSON.parse(decryptRecord(key, line)), order);
+      const remapped = remapManagedStoreFilePath(parsedRecord.f, config);
+      const record = remapped.aliased ? { ...parsedRecord, f: remapped.filePath } : parsedRecord;
+      if (remapped.aliased) aliasedRecords++;
+      const perFile = state.get(record.f) ?? /* @__PURE__ */ new Map();
+      const existing = perFile.get(record.k);
+      if (!existing || isNewerRecord(record, existing)) perFile.set(record.k, record);
+      state.set(record.f, perFile);
+      parsedRecords++;
+    } catch {
+      failedRecords++;
+    }
+  });
+  if (lines.length > 0 && parsedRecords === 0) {
+    throw new Error(`No readable vault records found in ${config.storePath}. Check the key file.`);
+  }
+  if (failedRecords > 0 && !options.ignoreCorruptRecords) {
+    throw new Error(
+      `Vault store contains ${failedRecords} unreadable record(s) in ${config.storePath}. Refusing to continue from partial state; pass ignoreCorruptRecords only after inspecting the store.`
+    );
+  }
+  return { state, failedRecords, parsedRecords, rawRecords: lines.length, aliasedRecords };
+}
+function append(config, key, record) {
+  mkdirSync(path3.dirname(config.storePath), { recursive: true });
+  appendFileSync(config.storePath, `${encryptRecord(key, JSON.stringify(record))}
+`, "utf8");
+}
+function createEmptyDocument() {
+  return { hasBom: false, eol: "\n", hasFinalNewline: true, lines: [] };
+}
+function createTextDocument(content) {
+  const hasBom = content.startsWith("\uFEFF");
+  const raw = hasBom ? content.slice(1) : content;
+  const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+  const hasFinalNewline = raw.length > 0 && /\r?\n$/.test(raw);
+  let lines = raw.length > 0 ? raw.split(/\r\n|\n/) : [];
+  if (hasFinalNewline && lines.at(-1) === "") lines = lines.slice(0, -1);
+  return { hasBom, eol, hasFinalNewline, lines };
+}
+function renderTextDocument(document, lines) {
+  const body = lines.join(document.eol);
+  const withNewline = lines.length > 0 && document.hasFinalNewline ? `${body}${document.eol}` : body;
+  return document.hasBom ? `\uFEFF${withNewline}` : withNewline;
+}
+function parseEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return { kind: "empty", rawLine: line };
+  if (trimmed.startsWith("#")) {
+    const commentedEntryMatch = line.match(COMMENTED_ENV_ENTRY_RE);
+    if (commentedEntryMatch) {
+      const eqIdx2 = line.indexOf("=");
+      return {
+        kind: "commented-entry",
+        rawLine: line,
+        key: commentedEntryMatch[1],
+        prefix: line.slice(0, eqIdx2 + 1),
+        rawValue: line.slice(eqIdx2 + 1)
+      };
+    }
+    return { kind: "comment", rawLine: line };
+  }
+  const eqIdx = line.indexOf("=");
+  if (eqIdx < 0) return { kind: "invalid", rawLine: line, reason: "missing equals sign" };
+  const match = line.match(ENV_ENTRY_RE);
+  if (!match) return { kind: "invalid", rawLine: line, reason: "invalid env key" };
+  return {
+    kind: "entry",
+    rawLine: line,
+    key: match[1],
+    prefix: line.slice(0, eqIdx + 1),
+    rawValue: line.slice(eqIdx + 1)
+  };
+}
+function loadEnvDocument(filePath) {
+  const fileExists = existsSync3(filePath);
+  const document = fileExists ? createTextDocument(readFileSync3(filePath, "utf8")) : createEmptyDocument();
+  const parsedLines = document.lines.map((line, index) => ({
+    lineNumber: index + 1,
+    ...parseEnvLine(line)
+  }));
+  const currentMap = /* @__PURE__ */ new Map();
+  const occurrencesMap = /* @__PURE__ */ new Map();
+  let invalidLineCount = 0;
+  let shadowedEntryCount = 0;
+  for (const line of parsedLines) {
+    if (line.kind === "entry") {
+      const occurrences = occurrencesMap.get(line.key) ?? [];
+      occurrences.push({ value: line.rawValue, prefix: line.prefix, lineNumber: line.lineNumber });
+      occurrencesMap.set(line.key, occurrences);
+      if (currentMap.has(line.key)) shadowedEntryCount++;
+      currentMap.set(line.key, { value: line.rawValue });
+    } else if (line.kind === "invalid") {
+      invalidLineCount++;
+    }
+  }
+  return {
+    exists: fileExists,
+    document,
+    parsedLines,
+    currentMap,
+    occurrencesMap,
+    invalidLineCount,
+    shadowedEntryCount
+  };
+}
+function desiredRecordsForFile(config, filePath, state) {
+  const desired = /* @__PURE__ */ new Map();
+  let excludedRecordsIgnored = 0;
+  for (const record of state.get(filePath)?.values() ?? []) {
+    if (isExcluded(config, filePath, record.k)) {
+      excludedRecordsIgnored++;
+      continue;
+    }
+    desired.set(record.k, record);
+  }
+  return { desired, excludedRecordsIgnored };
+}
+function formatPreviewValue(value) {
+  const escaped = value.replace(/\\/g, "\\\\").replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(/"/g, '\\"');
+  const quoted = `"${escaped}"`;
+  if (quoted.length <= PREVIEW_VALUE_LIMIT) return quoted;
+  return `"${escaped.slice(0, PREVIEW_VALUE_LIMIT - 24)}"... (${value.length} chars)`;
+}
+function formatPreviewValues(values, occurrenceCount) {
+  const uniqueValues = [...new Set(values)];
+  const valuePreview = uniqueValues.length === 1 ? formatPreviewValue(uniqueValues[0]) : `[${uniqueValues.map(formatPreviewValue).join(", ")}]`;
+  return occurrenceCount > 1 ? `${valuePreview} (${occurrenceCount} occurrences)` : valuePreview;
+}
+function buildRestorePlanFromState(config, store) {
+  const files = [];
+  const summary = {
+    add: 0,
+    modify: 0,
+    delete: 0,
+    identical: 0,
+    filesWithChanges: 0
+  };
+  const managedFiles = new Set(config.envFiles);
+  const unmanagedStoreFiles = [...store.state.keys()].filter(
+    (filePath) => !managedFiles.has(filePath)
+  );
+  let excludedRecordsIgnored = 0;
+  for (const filePath of config.envFiles) {
+    const { desired, excludedRecordsIgnored: fileExcludedRecordsIgnored } = desiredRecordsForFile(
+      config,
+      filePath,
+      store.state
+    );
+    excludedRecordsIgnored += fileExcludedRecordsIgnored;
+    const envDoc = loadEnvDocument(filePath);
+    const entries = [];
+    for (const record of desired.values()) {
+      const occurrences = envDoc.occurrencesMap.get(record.k) ?? [];
+      const currentValues = occurrences.map((item) => item.value);
+      let action;
+      if (record.op === "delete") action = occurrences.length === 0 ? "identical" : "delete";
+      else if (occurrences.length === 0) action = "add";
+      else action = currentValues.every((value) => value === record.v) ? "identical" : "modify";
+      summary[action]++;
+      entries.push({
+        filePath,
+        key: record.k,
+        action,
+        currentValues,
+        occurrenceCount: occurrences.length,
+        nextValue: record.op === "set" ? record.v : void 0
+      });
+    }
+    entries.sort((left, right) => left.key.localeCompare(right.key));
+    const changed = entries.some((entry) => entry.action !== "identical");
+    if (changed) summary.filesWithChanges++;
+    files.push({ filePath, entries, changed });
+  }
+  return {
+    storePath: config.storePath,
+    files,
+    summary,
+    failedRecords: store.failedRecords,
+    parsedRecords: store.parsedRecords,
+    rawRecords: store.rawRecords,
+    aliasedRecords: store.aliasedRecords,
+    unmanagedStoreFiles,
+    excludedRecordsIgnored
+  };
+}
+function printRestorePreview(plan) {
+  const logger = getLogger2();
+  logger.log("[env-lane:vault] Restore preview:");
+  if (plan.summary.filesWithChanges === 0) {
+    logger.log("[env-lane:vault] No file changes detected.");
+    logger.log(`[env-lane:vault] Skipped identical key-value pairs: ${plan.summary.identical}`);
+    return;
+  }
+  for (const file of plan.files) {
+    const changedEntries = file.entries.filter((entry) => entry.action !== "identical");
+    if (changedEntries.length === 0) continue;
+    logger.log(`
+[env-lane:vault] File: ${file.filePath}`);
+    for (const entry of changedEntries) {
+      if (entry.action === "add") {
+        logger.log(`  ADD ${entry.key}=${formatPreviewValue(entry.nextValue ?? "")}`);
+      } else if (entry.action === "modify") {
+        logger.log(
+          `  MODIFY ${entry.key}: ${formatPreviewValues(entry.currentValues, entry.occurrenceCount)} -> ${formatPreviewValue(entry.nextValue ?? "")}`
+        );
+      } else {
+        logger.log(
+          `  DELETE ${entry.key}: ${formatPreviewValues(entry.currentValues, entry.occurrenceCount)}`
+        );
+      }
+    }
+  }
+  logger.log("");
+  logger.log(
+    `[env-lane:vault] Summary: ${plan.summary.modify} modify, ${plan.summary.add} add, ${plan.summary.delete} delete, ${plan.summary.identical} identical skipped`
+  );
+}
+async function confirmRestore(options = {}) {
+  const logger = getLogger2();
+  if (options.dryRun) return false;
+  if (options.autoApprove) {
+    logger.log("[env-lane:vault] Auto-approved restore.");
+    return true;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      "Restore confirmation requires an interactive terminal. Re-run with --yes to apply or --dry-run to preview."
+    );
+  }
+  logger.write("[env-lane:vault] Press y to apply restore, any other key to cancel: ");
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const cleanup = () => {
+      stdin.off("data", onData);
+      stdin.pause();
+      if (typeof stdin.setRawMode === "function") stdin.setRawMode(false);
+    };
+    const onData = (chunk) => {
+      cleanup();
+      logger.write("\n");
+      const input = String(chunk);
+      if (input === "") {
+        resolve(false);
+        return;
+      }
+      resolve(
+        input.replace(/[\r\n]+/g, "").trim().toLowerCase() === "y"
+      );
+    };
+    stdin.resume();
+    if (typeof stdin.setRawMode === "function") stdin.setRawMode(true);
+    stdin.once("data", onData);
+  });
+}
+function applyRestoreFile(config, filePath, state) {
+  const { desired } = desiredRecordsForFile(config, filePath, state);
+  const envDoc = loadEnvDocument(filePath);
+  const seenKeys = /* @__PURE__ */ new Set();
+  const nextLines = [];
+  for (const line of envDoc.parsedLines) {
+    if (line.kind !== "entry") {
+      nextLines.push(line.rawLine);
+      continue;
+    }
+    const desiredRecord = desired.get(line.key);
+    if (!desiredRecord) {
+      nextLines.push(line.rawLine);
+      continue;
+    }
+    seenKeys.add(line.key);
+    if (desiredRecord.op === "delete") continue;
+    nextLines.push(`${line.prefix}${desiredRecord.v ?? ""}`);
+  }
+  const additions = [...desired.entries()].filter(([key, record]) => record.op === "set" && !seenKeys.has(key)).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+  for (const [key, record] of additions) nextLines.push(`${key}=${record.v ?? ""}`);
+  const current = envDoc.exists ? renderTextDocument(envDoc.document, envDoc.document.lines) : "";
+  const next = renderTextDocument(envDoc.document, nextLines);
+  if (current === next) return false;
+  mkdirSync(path3.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, next, "utf8");
+  return true;
+}
+async function encryptEnvFiles(configPath, keyFilePath, options = {}) {
+  const config = await loadVaultConfig(configPath);
+  warnUnsafeVault({
+    disableUnsafeWarning: options.disableUnsafeWarning ?? config.disableUnsafeWarning
+  });
+  const key = deriveVaultKey(keyFilePath);
+  const store = readStore(config, key, {
+    allowMissing: true,
+    ignoreCorruptRecords: options.ignoreCorruptRecords
+  });
+  const state = store.state;
+  let setRecordsWritten = 0;
+  let deleteRecordsWritten = 0;
+  let skippedUnchanged = 0;
+  let excludedEntriesIgnored = 0;
+  let missingFilesSkipped = 0;
+  let invalidLinesIgnored = 0;
+  let shadowedEntriesIgnored = 0;
+  for (const filePath of config.envFiles) {
+    if (!existsSync3(filePath)) {
+      missingFilesSkipped++;
+      continue;
+    }
+    const envDoc = loadEnvDocument(filePath);
+    const prev = state.get(filePath) ?? /* @__PURE__ */ new Map();
+    const current = /* @__PURE__ */ new Map();
+    for (const [keyName, { value }] of envDoc.currentMap) {
+      if (isExcluded(config, filePath, keyName)) {
+        excludedEntriesIgnored++;
+        continue;
+      }
+      current.set(keyName, value);
+      const old = prev.get(keyName);
+      if (old?.op === "set" && old.v === value) {
+        skippedUnchanged++;
+        continue;
+      }
+      append(config, key, { f: filePath, k: keyName, v: value, op: "set", t: Date.now() });
+      emitStructuredChange("encrypt", {
+        action: old?.op === "set" ? "update" : "set",
+        filePath: portable(filePath),
+        key: keyName
+      });
+      setRecordsWritten++;
+    }
+    if (config.trackDeletions) {
+      for (const [keyName, old] of prev.entries()) {
+        if (isExcluded(config, filePath, keyName)) continue;
+        if (old.op === "set" && !current.has(keyName)) {
+          append(config, key, { f: filePath, k: keyName, op: "delete", t: Date.now() });
+          emitStructuredChange("encrypt", {
+            action: "delete",
+            filePath: portable(filePath),
+            key: keyName
+          });
+          deleteRecordsWritten++;
+        }
+      }
+    }
+    invalidLinesIgnored += envDoc.invalidLineCount;
+    shadowedEntriesIgnored += envDoc.shadowedEntryCount;
+  }
+  return {
+    storePath: config.storePath,
+    setRecordsWritten,
+    deleteRecordsWritten,
+    skippedUnchanged,
+    excludedEntriesIgnored,
+    missingFilesSkipped,
+    invalidLinesIgnored,
+    shadowedEntriesIgnored,
+    rawRecords: store.rawRecords,
+    parsedRecords: store.parsedRecords,
+    failedRecords: store.failedRecords,
+    aliasedRecords: store.aliasedRecords
+  };
+}
+async function buildRestorePlan(configPath, keyFilePath, options = {}) {
+  const config = await loadVaultConfig(configPath);
+  warnUnsafeVault({
+    disableUnsafeWarning: options.disableUnsafeWarning ?? config.disableUnsafeWarning
+  });
+  const key = deriveVaultKey(keyFilePath);
+  return buildRestorePlanFromState(
+    config,
+    readStore(config, key, { ignoreCorruptRecords: options.ignoreCorruptRecords })
+  );
+}
+async function decryptEnvFiles(configPath, keyFilePath, options = {}) {
+  const config = await loadVaultConfig(configPath);
+  warnUnsafeVault({
+    disableUnsafeWarning: options.disableUnsafeWarning ?? config.disableUnsafeWarning
+  });
+  const key = deriveVaultKey(keyFilePath);
+  const store = readStore(config, key, { ignoreCorruptRecords: options.ignoreCorruptRecords });
+  const plan = buildRestorePlanFromState(config, store);
+  printRestorePreview(plan);
+  const logger = getLogger2();
+  if (plan.failedRecords > 0) {
+    logger.warn(
+      `[env-lane:vault] Warning: skipped ${plan.failedRecords} unreadable store record(s).`
+    );
+  }
+  if (plan.aliasedRecords > 0) {
+    logger.log(
+      `[env-lane:vault] Remapped ${plan.aliasedRecords} store record(s) from previous checkout paths to current env files.`
+    );
+  }
+  if (plan.unmanagedStoreFiles.length > 0) {
+    logger.warn(
+      `[env-lane:vault] Warning: ignored ${plan.unmanagedStoreFiles.length} store file(s) not listed in config.envFiles.`
+    );
+  }
+  if (plan.excludedRecordsIgnored > 0) {
+    logger.log(
+      `[env-lane:vault] Ignored ${plan.excludedRecordsIgnored} excluded store record(s) during restore.`
+    );
+  }
+  const results = [];
+  if (plan.summary.filesWithChanges === 0 || options.dryRun) {
+    for (const file of plan.files) {
+      results.push({
+        filePath: file.filePath,
+        keys: file.entries.filter((entry) => entry.action !== "delete").length,
+        changed: file.changed,
+        entries: file.entries
+      });
+    }
+    return { ...plan, applied: false, filesWritten: 0, results };
+  }
+  const confirmed = await confirmRestore(options);
+  if (!confirmed) {
+    logger.log("[env-lane:vault] Restore cancelled. No files were changed.");
+    for (const file of plan.files) {
+      results.push({
+        filePath: file.filePath,
+        keys: file.entries.filter((entry) => entry.action !== "delete").length,
+        changed: file.changed,
+        entries: file.entries
+      });
+    }
+    return { ...plan, applied: false, filesWritten: 0, results };
+  }
+  let filesWritten = 0;
+  for (const file of plan.files) {
+    if (!file.changed) {
+      results.push({
+        filePath: file.filePath,
+        keys: file.entries.filter((entry) => entry.action !== "delete").length,
+        changed: false,
+        entries: file.entries
+      });
+      continue;
+    }
+    const changed = applyRestoreFile(config, file.filePath, store.state);
+    if (changed) {
+      filesWritten++;
+      for (const entry of file.entries.filter((item) => item.action !== "identical")) {
+        emitStructuredChange("decrypt", {
+          action: entry.action,
+          filePath: portable(file.filePath),
+          key: entry.key
+        });
+      }
+      emitStructuredChange("decrypt", { action: "write-file", filePath: portable(file.filePath) });
+    }
+    results.push({
+      filePath: file.filePath,
+      keys: file.entries.filter((entry) => entry.action !== "delete").length,
+      changed,
+      entries: file.entries
+    });
+  }
+  return { ...plan, applied: filesWritten > 0, filesWritten, results };
+}
+async function runVault(configPath, keyFilePath, mode, options = {}) {
+  return mode === "encrypt" ? encryptEnvFiles(configPath, keyFilePath, options) : decryptEnvFiles(configPath, keyFilePath, options);
+}
+export {
+  VAULT_UNSAFE_WARNING,
+  buildRestorePlan,
+  decryptEnvFiles,
+  decryptRecord,
+  defineVaultConfig,
+  deriveVaultKey,
+  encryptEnvFiles,
+  encryptRecord,
+  loadVaultConfig,
+  runVault,
+  warnUnsafeVault
+};