@blamejs/core 0.4.1

package/lib/vault/index.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * Vault — sealed keystore for the framework's encryption keys.
+ *
+ * Holds the ML-KEM-1024 + P-384 hybrid keypair used by every other framework
+ * subsystem that calls vault.seal() / vault.unseal() (db field encryption,
+ * session storage, audit log signing, etc.). Keys never leave the process
+ * after init() in any decrypted form except via the vault.seal/unseal API.
+ *
+ * Modes (default is 'wrapped' — highest-security; 'plaintext' is opt-out
+ * with explicit boot warning per the framework's modernity stance):
+ *
+ *   wrapped    — vault.key.sealed file, passphrase-derived AEAD wrap (lib/vault-wrap.js).
+ *                Argon2id → SHAKE256 → XChaCha20-Poly1305. Default.
+ *   plaintext  — vault.key file (JSON, mode 0o600). For development only.
+ *                Emits console.warn at boot. Opt-out only.
+ *
+ * Two-API contract (sync seal/unseal, async init):
+ *
+ *   await vault.init({ dataDir, mode? })   ← call once at app bootstrap
+ *   vault.seal(value)                      ← sync, post-init
+ *   vault.unseal(value)                    ← sync, post-init
+ *
+ * Why two APIs: seal/unseal have hundreds of call sites across a typical app,
+ * many at module-require time. Making them async would require an invasive
+ * refactor of every consumer. Instead, the bootstrap awaits init() once, then
+ * everything runs synchronously against the in-process key cache.
+ *
+ * Sealed-value format: "vault:" prefix + base64 envelope from lib/crypto.js.
+ * Old envelopes always remain readable (envelope versioning); new writes use
+ * the active KEM/CIPHER/KDF.
+ */
+var fs = require("fs");
+var path = require("path");
+var atomicFile = require("../atomic-file");
+var C = require("../constants");
+var { generateEncryptionKeyPair, encrypt, decrypt } = require("../crypto");
+var { boot } = require("../log");
+var safeBuffer = require("../safe-buffer");
+var safeJson = require("../safe-json");
+var observability = require("../observability");
+var vaultPassphraseSource = require("./passphrase-source");
+var vaultWrap = require("./wrap");
+
+var VAULT_PREFIX = C.VAULT_PREFIX;
+
+// Module-local cache populated by init().
+var keys = null;
+var initialized = false;
+// Passphrase retained post-init (best-effort) for operations that need it
+// later — vault rotation, backup re-wrap. Already in JS heap during unwrap;
+// retaining doesn't change the threat model meaningfully.
+var currentPassphrase = null;
+// Resolved paths (set by init based on dataDir option)
+var paths = null;
+var currentMode = null;
+
+var log = boot("vault");
+
+function resolvePaths(dataDir) {
+  return {
+    dataDir:    dataDir,
+    plaintext:  path.join(dataDir, "vault.key"),
+    sealed:     path.join(dataDir, "vault.key.sealed"),
+  };
+}
+
+// ---- Init dispatch ----
+
+async function init(opts) {
+  if (initialized) return;
+  opts = opts || {};
+
+  if (!opts.dataDir) {
+    throw new Error("vault.init({ dataDir }) is required");
+  }
+
+  var mode = (opts.mode || "wrapped").toLowerCase();
+  if (mode !== "wrapped" && mode !== "plaintext") {
+    throw new Error("vault.init: mode must be 'wrapped' or 'plaintext', got: " + opts.mode);
+  }
+  currentMode = mode;
+  paths = resolvePaths(opts.dataDir);
+
+  if (!fs.existsSync(paths.dataDir)) {
+    fs.mkdirSync(paths.dataDir, { recursive: true });
+  }
+
+  // Sweep tmp files left behind by a previously-crashed write
+  atomicFile.cleanOrphans(paths.sealed);
+  atomicFile.cleanOrphans(paths.plaintext);
+
+  var hasPlaintext = fs.existsSync(paths.plaintext);
+  var hasSealed    = fs.existsSync(paths.sealed);
+
+  // Refuse to guess when both files coexist
+  if (hasPlaintext && hasSealed) {
+    log.error("FATAL: both vault.key and vault.key.sealed exist in " + paths.dataDir);
+    log.error("Delete the one you do NOT want to keep, then restart.");
+    process.exit(1);
+  }
+
+  // Mode-vs-state mismatches
+  if (hasSealed && mode === "plaintext") {
+    log.error("FATAL: vault.key.sealed exists but vault.init({ mode: 'plaintext' }) was requested.");
+    log.error("Either run with mode: 'wrapped', or remove the sealed file (after migration).");
+    process.exit(1);
+  }
+  if (hasPlaintext && mode === "wrapped") {
+    log.error("FATAL: vault.key (plaintext) exists but vault.init({ mode: 'wrapped' }) was requested.");
+    log.error("Either run with mode: 'plaintext', or migrate the key to a wrapped form.");
+    process.exit(1);
+  }
+
+  if (mode === "wrapped") {
+    if (hasSealed) await initWrapped();
+    else await initFirstRunWrapped();
+  } else {
+    // mode === "plaintext"
+    log.warn("WARNING: running in PLAINTEXT mode — vault.key is unprotected on disk.");
+    log.warn("         Use mode: 'wrapped' (default) for any deployment that holds real data.");
+    log.warn("         See https://github.com/blamejs/blamejs#vault-modes for details.");
+    initPlaintext();
+  }
+
+  initialized = true;
+}
+
+function initPlaintext() {
+  if (fs.existsSync(paths.plaintext)) {
+    var loaded;
+    try {
+      loaded = safeJson.parse(atomicFile.readSync(paths.plaintext), {
+        schema: {
+          type: "object",
+          required: ["publicKey", "privateKey", "ecPublicKey", "ecPrivateKey"],
+          properties: {
+            publicKey:    { type: "string" },
+            privateKey:   { type: "string" },
+            ecPublicKey:  { type: "string" },
+            ecPrivateKey: { type: "string" },
+          },
+        },
+      });
+    } catch (e) {
+      log.error("FATAL: vault.key corrupted, unreadable, or schema-invalid at " + paths.plaintext + " — " + e.message);
+      log.error("All sealed data requires the original key. Restore from backup, then restart.");
+      process.exit(1);
+    }
+    keys = loaded;
+    return;
+  }
+  // First run, plaintext mode
+  keys = generateEncryptionKeyPair();
+  atomicFile.writeSync(paths.plaintext, JSON.stringify(keys, null, 2), { fileMode: 0o600 });
+  log("plaintext vault keypair generated at " + paths.plaintext);
+}
+
+async function initWrapped() {
+  log("unsealing vault.key.sealed...");
+  var sealedBytes;
+  try {
+    sealedBytes = atomicFile.readSync(paths.sealed);
+  } catch (e) {
+    log.error("FATAL: cannot read " + paths.sealed + ": " + e.message);
+    process.exit(1);
+  }
+
+  var passphrase;
+  try {
+    passphrase = await vaultPassphraseSource.getPassphrase({ prompt: "Vault passphrase: " });
+  } catch (e) {
+    log.error("FATAL: " + e.message);
+    process.exit(1);
+  }
+
+  var plaintextJson;
+  var plaintextBuf;
+  try {
+    plaintextBuf = await vaultWrap.unwrap(sealedBytes, passphrase);
+    plaintextJson = plaintextBuf.toString("utf8");
+  } catch (e) {
+    log.error("FATAL: passphrase rejected or sealed file corrupted (" + e.message + ")");
+    process.exit(1);
+  } finally {
+    // The Buffer holding the unwrapped key JSON is no longer needed once
+    // toString has copied the bytes into plaintextJson. The string itself
+    // is referenced by the JSON parser below; can't be zeroed (V8 strings
+    // are GC-managed). secureZero on the Buffer at least removes one
+    // copy of the secret from the heap.
+    if (plaintextBuf) safeBuffer.secureZero(plaintextBuf);
+  }
+  currentPassphrase = passphrase;
+
+  try {
+    keys = safeJson.parse(plaintextJson, {
+      schema: {
+        type: "object",
+        required: ["publicKey", "privateKey", "ecPublicKey", "ecPrivateKey"],
+        properties: {
+          publicKey:    { type: "string" },
+          privateKey:   { type: "string" },
+          ecPublicKey:  { type: "string" },
+          ecPrivateKey: { type: "string" },
+        },
+      },
+    });
+  } catch (e) {
+    log.error("FATAL: unwrapped vault key invalid: " + e.message);
+    process.exit(1);
+  }
+  log("unsealed successfully.");
+}
+
+async function initFirstRunWrapped() {
+  log("first run with mode: 'wrapped' — generating wrapped keypair...");
+
+  var passphrase;
+  try {
+    passphrase = await vaultPassphraseSource.getPassphrase({
+      prompt: "Choose a vault passphrase (loss = data loss, store it safely): ",
+    });
+  } catch (e) {
+    log.error("FATAL: " + e.message);
+    process.exit(1);
+  }
+  currentPassphrase = passphrase;
+
+  keys = generateEncryptionKeyPair();
+  var plaintextJson = JSON.stringify(keys, null, 2);
+  var sealed;
+  try {
+    sealed = await vaultWrap.wrap(plaintextJson, passphrase);
+  } catch (e) {
+    log.error("FATAL: failed to wrap new vault key: " + e.message);
+    process.exit(1);
+  }
+
+  // Atomic write via the framework's atomic-file primitive (temp + fsync +
+  // rename + dir fsync — same flow this code used to inline manually).
+  atomicFile.writeSync(paths.sealed, sealed, { fileMode: 0o600 });
+
+  log("generated and sealed new vault keypair (ML-KEM-1024 + P-384 hybrid)");
+}
+
+// ---- Sync API — operates against the populated cache ----
+
+function _requireInit() {
+  if (!initialized) {
+    throw new Error("vault.init() must be awaited before vault.seal/unseal/getKeysJson");
+  }
+}
+
+function seal(plaintext) {
+  if (!plaintext) return plaintext;
+  if (String(plaintext).startsWith(VAULT_PREFIX)) return plaintext;
+  _requireInit();
+  return observability.tap("vault.seal", null, function () {
+    return VAULT_PREFIX + encrypt(String(plaintext), keys);
+  });
+}
+
+function unseal(value) {
+  if (!value || !String(value).startsWith(VAULT_PREFIX)) return value;
+  _requireInit();
+  return observability.tap("vault.unseal", null, function () {
+    var payload = String(value).substring(VAULT_PREFIX.length);
+    return decrypt(payload, keys);
+  });
+}
+
+function getKeysJson() {
+  _requireInit();
+  return JSON.stringify(keys, null, 2);
+}
+
+function getCurrentPassphrase() {
+  return currentPassphrase;
+}
+
+function getMode() {
+  return currentMode;
+}
+
+module.exports = {
+  init:                  init,
+  seal:                  seal,
+  unseal:                unseal,
+  getKeysJson:           getKeysJson,
+  getCurrentPassphrase:  getCurrentPassphrase,
+  getMode:               getMode,
+  // Testing helpers — not part of the public contract
+  _resetForTest:         function () {
+    if (currentPassphrase) safeBuffer.secureZero(currentPassphrase);
+    keys = null; initialized = false; currentPassphrase = null; paths = null; currentMode = null;
+  },
+  _getKeysForTest:       function () { return keys; },
+  _getPathsForTest:      function () { return paths; },
+};

package/lib/vault/passphrase-ops.js

@@ -0,0 +1,311 @@
+"use strict";
+/**
+ * vault-passphrase-ops — seal / unseal / rotate the vault's passphrase wrap.
+ *
+ * Operator workflows the framework needs to support without forcing
+ * everyone through a CLI: turn a plaintext vault.key into a passphrase-
+ * wrapped vault.key.sealed (seal), the reverse (unseal), or change the
+ * passphrase on an already-sealed file (rotate). Crash-safe: each
+ * operation goes through .tmp + fsync + atomic rename so a power-loss
+ * mid-operation leaves either the OLD file or the NEW file intact, never
+ * a half-written one.
+ *
+ *   var ops = b.vaultPassphraseOps;
+ *
+ *   var pre = ops.preflightSealable({ dataDir });
+ *   // → { ok: true } or { ok: false, reason: "..." }
+ *
+ *   await ops.seal({ dataDir, passphrase, keepPlaintext: false });
+ *   // → { sealedPath, plaintextDeleted }
+ *
+ *   await ops.unseal({ dataDir, passphrase });
+ *   // → { plaintextPath }
+ *
+ *   await ops.rotate({ dataDir, oldPassphrase, newPassphrase });
+ *   // → { sealedPath }
+ *
+ * Filenames the framework looks at (relative to dataDir):
+ *   vault.key            — plaintext keypair JSON
+ *   vault.key.sealed     — passphrase-wrapped keypair (Argon2id +
+ *                           XChaCha20-Poly1305, see lib/vault-wrap.js)
+ *
+ * Round-trip verification: every seal/unseal re-reads the .tmp it just
+ * wrote and confirms the bytes match before the atomic rename. If the
+ * filesystem reordered or corrupted the write, the operation aborts
+ * with the original file untouched.
+ */
+
+var fs = require("fs");
+var path = require("path");
+var atomicFile = require("../atomic-file");
+var vaultWrap = require("./wrap");
+var { defineClass } = require("../framework-error");
+
+var VaultPassphraseError = defineClass("VaultPassphraseError", { alwaysPermanent: true });
+
+var PLAINTEXT_NAME = "vault.key";
+var SEALED_NAME    = "vault.key.sealed";
+
+function _paths(dataDir) {
+  return {
+    plaintext:     path.join(dataDir, PLAINTEXT_NAME),
+    plaintextTmp:  path.join(dataDir, PLAINTEXT_NAME + ".tmp"),
+    sealed:        path.join(dataDir, SEALED_NAME),
+    sealedTmp:     path.join(dataDir, SEALED_NAME + ".tmp"),
+  };
+}
+
+function _requireDataDir(opts) {
+  if (!opts || typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw new VaultPassphraseError("vault-passphrase/no-datadir",
+      "opts.dataDir is required (path to the framework data directory)");
+  }
+  if (!fs.existsSync(opts.dataDir)) {
+    throw new VaultPassphraseError("vault-passphrase/no-datadir",
+      "opts.dataDir does not exist: " + opts.dataDir);
+  }
+}
+
+function _requirePassphrase(opts, fieldName) {
+  var name = fieldName || "passphrase";
+  if (!opts || !Buffer.isBuffer(opts[name])) {
+    throw new VaultPassphraseError("vault-passphrase/no-passphrase",
+      "opts." + name + " is required and must be a Buffer (the operator passphrase bytes)");
+  }
+}
+
+// fsync-by-path semantic: open then sync then close. atomicFile.fsync
+// expects an already-open fd; this wrapper opens the file we just
+// wrote, flushes its contents, and closes — the right shape when we
+// don't have the original write fd around.
+function _fsyncPath(p) {
+  try {
+    var fd = fs.openSync(p, "r+");
+    try { atomicFile.fsync(fd); } finally { fs.closeSync(fd); }
+  } catch (_e) { /* best-effort across filesystems */ }
+}
+
+// ---- Pre-flight checks (no side effects) ----
+
+function preflightSealable(opts) {
+  _requireDataDir(opts);
+  var p = _paths(opts.dataDir);
+  if (!fs.existsSync(p.plaintext)) {
+    return { ok: false, reason: "plaintext " + PLAINTEXT_NAME + " does not exist — nothing to seal" };
+  }
+  if (fs.existsSync(p.sealed)) {
+    return { ok: false, reason: SEALED_NAME + " already exists; refusing to overwrite" };
+  }
+  if (fs.existsSync(p.sealedTmp)) {
+    return { ok: false, reason: "stale " + SEALED_NAME + ".tmp from a previous crash; remove it manually after verifying the directory state" };
+  }
+  return { ok: true };
+}
+
+function preflightUnsealable(opts) {
+  _requireDataDir(opts);
+  var p = _paths(opts.dataDir);
+  if (!fs.existsSync(p.sealed)) {
+    return { ok: false, reason: SEALED_NAME + " does not exist — nothing to unseal" };
+  }
+  if (fs.existsSync(p.plaintext)) {
+    return { ok: false, reason: "plaintext " + PLAINTEXT_NAME + " already exists; refusing to overwrite" };
+  }
+  if (fs.existsSync(p.plaintextTmp)) {
+    return { ok: false, reason: "stale " + PLAINTEXT_NAME + ".tmp from a previous crash; remove it manually after verifying the directory state" };
+  }
+  return { ok: true };
+}
+
+function preflightRotatable(opts) {
+  _requireDataDir(opts);
+  var p = _paths(opts.dataDir);
+  if (!fs.existsSync(p.sealed)) {
+    return { ok: false, reason: SEALED_NAME + " does not exist — rotate has nothing to operate on" };
+  }
+  if (fs.existsSync(p.sealedTmp)) {
+    return { ok: false, reason: "stale " + SEALED_NAME + ".tmp from a previous crash; remove it manually after verifying the directory state" };
+  }
+  return { ok: true };
+}
+
+// ---- Seal: plaintext vault.key → vault.key.sealed ----
+
+async function seal(opts) {
+  _requireDataDir(opts);
+  _requirePassphrase(opts, "passphrase");
+  var pre = preflightSealable(opts);
+  if (!pre.ok) {
+    throw new VaultPassphraseError("vault-passphrase/preflight-failed", pre.reason);
+  }
+  var p = _paths(opts.dataDir);
+  var keepPlaintext = !!opts.keepPlaintext;
+
+  var plainBytes = fs.readFileSync(p.plaintext);
+  var sealedBytes = await vaultWrap.wrap(plainBytes, opts.passphrase);
+
+  // Step 1: write sealed.tmp + fsync
+  fs.writeFileSync(p.sealedTmp, sealedBytes, { mode: 0o600 });
+  _fsyncPath(p.sealedTmp);
+  atomicFile.fsyncDir(opts.dataDir);
+
+  // Step 2: round-trip verify the .tmp before committing the rename
+  var verifyBytes = fs.readFileSync(p.sealedTmp);
+  var unwrapped;
+  try {
+    unwrapped = await vaultWrap.unwrap(verifyBytes, opts.passphrase);
+  } catch (e) {
+    try { fs.unlinkSync(p.sealedTmp); } catch (_e) { /* cleanup */ }
+    throw new VaultPassphraseError("vault-passphrase/verify-failed",
+      "round-trip verification of sealed file failed: " + ((e && e.message) || String(e)) +
+      " — original " + PLAINTEXT_NAME + " is UNCHANGED");
+  }
+  if (Buffer.compare(unwrapped, plainBytes) !== 0) {
+    try { fs.unlinkSync(p.sealedTmp); } catch (_e) { /* cleanup */ }
+    throw new VaultPassphraseError("vault-passphrase/verify-mismatch",
+      "round-trip produced different bytes than the original — original " + PLAINTEXT_NAME +
+      " is UNCHANGED. Filesystem may be faulty.");
+  }
+
+  // Step 3: atomic rename sealed.tmp → sealed
+  fs.renameSync(p.sealedTmp, p.sealed);
+  atomicFile.fsyncDir(opts.dataDir);
+
+  // Step 4: delete plaintext (unless keepPlaintext)
+  if (!keepPlaintext) {
+    fs.unlinkSync(p.plaintext);
+    atomicFile.fsyncDir(opts.dataDir);
+  }
+
+  return {
+    sealedPath:       p.sealed,
+    plaintextDeleted: !keepPlaintext,
+  };
+}
+
+// ---- Unseal: vault.key.sealed → plaintext vault.key ----
+
+async function unseal(opts) {
+  _requireDataDir(opts);
+  _requirePassphrase(opts, "passphrase");
+  var pre = preflightUnsealable(opts);
+  if (!pre.ok) {
+    throw new VaultPassphraseError("vault-passphrase/preflight-failed", pre.reason);
+  }
+  var p = _paths(opts.dataDir);
+
+  var sealedBytes = fs.readFileSync(p.sealed);
+  var plainBytes;
+  try {
+    plainBytes = await vaultWrap.unwrap(sealedBytes, opts.passphrase);
+  } catch (e) {
+    throw new VaultPassphraseError("vault-passphrase/passphrase-rejected",
+      "passphrase rejected: " + ((e && e.message) || String(e)) +
+      " — " + SEALED_NAME + " is UNCHANGED");
+  }
+
+  // Step 1: write plaintext.tmp + fsync
+  fs.writeFileSync(p.plaintextTmp, plainBytes, { mode: 0o600 });
+  _fsyncPath(p.plaintextTmp);
+  atomicFile.fsyncDir(opts.dataDir);
+
+  // Step 2: round-trip sanity — re-read tmp and verify
+  var verifyBytes = fs.readFileSync(p.plaintextTmp);
+  if (Buffer.compare(verifyBytes, plainBytes) !== 0) {
+    try { fs.unlinkSync(p.plaintextTmp); } catch (_e) { /* cleanup */ }
+    throw new VaultPassphraseError("vault-passphrase/verify-mismatch",
+      "plaintext.tmp re-read differs from in-memory bytes — filesystem may be faulty. " +
+      SEALED_NAME + " is UNCHANGED");
+  }
+
+  // Step 3: atomic rename plaintext.tmp → plaintext
+  fs.renameSync(p.plaintextTmp, p.plaintext);
+  atomicFile.fsyncDir(opts.dataDir);
+
+  // Step 4: delete sealed file
+  fs.unlinkSync(p.sealed);
+  atomicFile.fsyncDir(opts.dataDir);
+
+  return { plaintextPath: p.plaintext };
+}
+
+// ---- Rotate: change passphrase on an already-sealed file ----
+//
+// Implemented as unwrap-with-old + wrap-with-new + atomic-rename. The
+// underlying vault keypair bytes are unchanged — only the passphrase
+// wrapping (Argon2id KDF + XChaCha20-Poly1305 nonce/key) rotates.
+
+async function rotate(opts) {
+  _requireDataDir(opts);
+  _requirePassphrase(opts, "oldPassphrase");
+  _requirePassphrase(opts, "newPassphrase");
+  var pre = preflightRotatable(opts);
+  if (!pre.ok) {
+    throw new VaultPassphraseError("vault-passphrase/preflight-failed", pre.reason);
+  }
+  var p = _paths(opts.dataDir);
+
+  var sealedBytes = fs.readFileSync(p.sealed);
+  var plainBytes;
+  try {
+    plainBytes = await vaultWrap.unwrap(sealedBytes, opts.oldPassphrase);
+  } catch (e) {
+    throw new VaultPassphraseError("vault-passphrase/passphrase-rejected",
+      "old passphrase rejected: " + ((e && e.message) || String(e)) +
+      " — " + SEALED_NAME + " is UNCHANGED");
+  }
+  var newSealedBytes = await vaultWrap.wrap(plainBytes, opts.newPassphrase);
+
+  // Step 1: write new sealed.tmp + fsync
+  fs.writeFileSync(p.sealedTmp, newSealedBytes, { mode: 0o600 });
+  _fsyncPath(p.sealedTmp);
+  atomicFile.fsyncDir(opts.dataDir);
+
+  // Step 2: round-trip verify with NEW passphrase, AND assert unwrap
+  // with the OLD passphrase fails — otherwise the rotation didn't take.
+  var verifyBytes = fs.readFileSync(p.sealedTmp);
+  var verifyPlain;
+  try { verifyPlain = await vaultWrap.unwrap(verifyBytes, opts.newPassphrase); }
+  catch (e) {
+    try { fs.unlinkSync(p.sealedTmp); } catch (_e) { /* cleanup */ }
+    throw new VaultPassphraseError("vault-passphrase/verify-failed",
+      "round-trip with new passphrase failed: " + ((e && e.message) || String(e)) +
+      " — " + SEALED_NAME + " is UNCHANGED");
+  }
+  if (Buffer.compare(verifyPlain, plainBytes) !== 0) {
+    try { fs.unlinkSync(p.sealedTmp); } catch (_e) { /* cleanup */ }
+    throw new VaultPassphraseError("vault-passphrase/verify-mismatch",
+      "rotated sealed file decrypts under new passphrase but to different bytes — " +
+      SEALED_NAME + " is UNCHANGED. Filesystem may be faulty.");
+  }
+  // Best-effort regression check: the same bytes must NOT unwrap under
+  // the old passphrase. If they do, the wrap library handed back the
+  // input unchanged — refuse to commit.
+  try {
+    await vaultWrap.unwrap(verifyBytes, opts.oldPassphrase);
+    try { fs.unlinkSync(p.sealedTmp); } catch (_e) { /* cleanup */ }
+    throw new VaultPassphraseError("vault-passphrase/rotate-noop",
+      "old passphrase still unwraps the new sealed bytes — rotation did not take effect");
+  } catch (e) {
+    if (e && e.code === "vault-passphrase/rotate-noop") throw e;
+    // any other error means old passphrase fails on new sealed → expected
+  }
+
+  // Step 3: atomic rename — swap in the new sealed file
+  fs.renameSync(p.sealedTmp, p.sealed);
+  atomicFile.fsyncDir(opts.dataDir);
+
+  return { sealedPath: p.sealed };
+}
+
+module.exports = {
+  preflightSealable:    preflightSealable,
+  preflightUnsealable:  preflightUnsealable,
+  preflightRotatable:   preflightRotatable,
+  seal:                 seal,
+  unseal:               unseal,
+  rotate:               rotate,
+  VaultPassphraseError: VaultPassphraseError,
+  PLAINTEXT_NAME:       PLAINTEXT_NAME,
+  SEALED_NAME:          SEALED_NAME,
+};