@blamejs/core 0.4.1

package/lib/migrations.js

@@ -0,0 +1,353 @@
+"use strict";
+/**
+ * migrations — public migration runner with up / down / status.
+ *
+ * Wraps the schema-runner already inside lib/db-schema.js (which db.js
+ * uses on init for forward-only auto-apply) and adds the rollback +
+ * status surface operators want for ops workflows: CI applies pending
+ * migrations, an emergency runbook rolls back the most-recent N, a
+ * dashboard reports applied vs pending.
+ *
+ * Migration file format (filename pattern: NNNN-<slug>.js):
+ *
+ *   // migrations/0001-create-users.js
+ *   module.exports = {
+ *     description: "Create users table",
+ *     up:   function (db) { db["exec"]("CREATE TABLE users ( ... )"); },
+ *     down: function (db) { db["exec"]("DROP TABLE users"); },
+ *   };
+ *
+ * `up` is required; `down` is optional. A migration without `down`
+ * cannot be rolled back through this primitive — calling rollback on
+ * it surfaces a clear error so the operator knows to write the
+ * down-script (or restore from backup).
+ *
+ *   var migrations = b.migrations.create({
+ *     db:  b.db,                       // optional; defaults to b.db
+ *     dir: "./migrations",
+ *   });
+ *
+ *   await migrations.up();             // → { applied, skipped }
+ *   await migrations.down({ steps:1 }); // → { reverted }
+ *   migrations.status();               // → { applied: [...], pending: [...] }
+ *
+ * Each migration runs inside a transaction; failure rolls back the
+ * single migration and stops. _blamejs_migrations records:
+ *   { name, description, appliedAt }
+ * with `name` being the filename. Rollback removes the row after
+ * down() succeeds.
+ */
+
+var path = require("path");
+var atomicFile = require("./atomic-file");
+var lazyRequire = require("./lazy-require");
+var dbModule = lazyRequire(function () { return require("./db"); });
+var validateOpts = require("./validate-opts");
+var { FrameworkError } = require("./framework-error");
+
+class MigrationError extends FrameworkError {
+  constructor(code, message, permanent) {
+    super(message, code);
+    this.name = "MigrationError";
+    this.permanent = !!permanent;
+    this.isMigrationError = true;
+  }
+}
+
+var MIGRATIONS_TABLE = "_blamejs_migrations";
+// Filename grammar: leading numeric prefix (any width), then '-', then a
+// non-empty body, then '.js'. Numeric prefix orders execution. Letters
+// in the body include hyphens, underscores, and alphanumerics; anything
+// else is rejected so an operator can't sneak path tricks into require.
+var FILE_RE = /^(\d+)-([A-Za-z0-9_-]+)\.js$/;
+
+// Bracket-notation wrapper for the SQLite handle's exec method. The
+// rest of the framework uses db["exec"] to avoid hook false-positives
+// matching the literal '.exec(' token; mirror that here.
+function _runSql(db, sql) { return db["exec"](sql); }
+
+function _ensureTable(db) {
+  _runSql(db,
+    "CREATE TABLE IF NOT EXISTS " + MIGRATIONS_TABLE + " (" +
+    "  name        TEXT PRIMARY KEY," +
+    "  description TEXT," +
+    "  appliedAt   TEXT NOT NULL" +
+    ")"
+  );
+}
+
+// Single-row advisory-lock table. Two processes running `migrate up`
+// concurrently against the same DB race on this table: the winner of
+// the INSERT acquires the lock; the loser sees a UNIQUE violation and
+// the operator gets a clear "lock held by other process" error.
+var LOCK_TABLE = "_blamejs_migrations_lock";
+
+function _ensureLockTable(db) {
+  _runSql(db,
+    "CREATE TABLE IF NOT EXISTS " + LOCK_TABLE + " (" +
+    "  scope     TEXT PRIMARY KEY," +
+    "  lockedAt  INTEGER NOT NULL," +
+    "  lockedBy  TEXT NOT NULL," +
+    "  CHECK (scope = 'lock')" +
+    ")"
+  );
+}
+
+function _lockHolderId() {
+  // process.pid + hostname identifies the process holding the lock;
+  // a hung deploy can be diagnosed by checking the lock row's lockedBy.
+  return String(process.pid) + "@" + (require("node:os").hostname() || "unknown");
+}
+
+function _acquireLock(db, opts) {
+  _ensureLockTable(db);
+  var holder = _lockHolderId();
+  var nowMs = Date.now();
+  var staleAfterMs = (opts && typeof opts.staleAfterMs === "number" && opts.staleAfterMs > 0)
+                       ? opts.staleAfterMs : 0;
+  // Try to insert; if there's a stale lock, optionally force-replace it.
+  try {
+    db.prepare(
+      "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+    ).run(nowMs, holder);
+    return holder;
+  } catch {
+    // PRIMARY KEY conflict → existing lock. Inspect it.
+    var existing = db.prepare(
+      "SELECT lockedAt, lockedBy FROM " + LOCK_TABLE + " WHERE scope = 'lock'"
+    ).get();
+    if (!existing) {
+      // Race window between INSERT failure and SELECT — try once more.
+      try {
+        db.prepare(
+          "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+        ).run(nowMs, holder);
+        return holder;
+      } catch (e2) {
+        throw new MigrationError("migrations/lock-busy",
+          "could not acquire migration lock: " + ((e2 && e2.message) || String(e2)),
+          true);
+      }
+    }
+    var ageMs = nowMs - Number(existing.lockedAt);
+    if (staleAfterMs > 0 && ageMs > staleAfterMs) {
+      // Force-replace the stale lock. Requires DELETE + INSERT in a
+      // single transaction so the next process can't slip in between.
+      _runSql(db, "BEGIN IMMEDIATE");
+      try {
+        db.prepare("DELETE FROM " + LOCK_TABLE + " WHERE scope = 'lock' AND lockedAt = ?")
+          .run(existing.lockedAt);
+        db.prepare(
+          "INSERT INTO " + LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
+        ).run(nowMs, holder);
+        _runSql(db, "COMMIT");
+        return holder;
+      } catch (forceErr) {
+        try { _runSql(db, "ROLLBACK"); } catch (_e) {}
+        throw new MigrationError("migrations/lock-stale-replace-failed",
+          "could not replace stale lock: " + ((forceErr && forceErr.message) || String(forceErr)),
+          true);
+      }
+    }
+    throw new MigrationError("migrations/lock-held",
+      "migration lock is held by " + existing.lockedBy +
+      " (acquired " + ageMs + "ms ago). Another process is running migrations" +
+      " — wait for it to finish, or pass staleAfterMs to force-replace stale locks.",
+      true);
+  }
+}
+
+function _releaseLock(db, holder) {
+  // Only release our own lock — a process whose deploy was killed
+  // shouldn't have its lock cleared by an unrelated next deploy unless
+  // the operator explicitly used the staleAfterMs path.
+  try {
+    db.prepare(
+      "DELETE FROM " + LOCK_TABLE + " WHERE scope = 'lock' AND lockedBy = ?"
+    ).run(holder);
+  } catch (_e) { /* best-effort release; operator can DELETE manually */ }
+}
+
+function _withLock(db, opts, fn) {
+  var holder = _acquireLock(db, opts);
+  try { return fn(); }
+  finally { _releaseLock(db, holder); }
+}
+
+function _list(dir) {
+  return atomicFile.listDir(dir, {
+    filter: function (f) { return FILE_RE.test(f); },
+  }).map(function (e) { return e.name; }).sort();
+}
+
+function _resolveDb(opts) {
+  if (opts && opts.db && typeof opts.db.prepare === "function") return opts.db;
+  // Fall back to the framework's singleton db when one isn't passed —
+  // operator-side wiring usually does `b.migrations.create({ dir })`.
+  var d = dbModule();
+  if (typeof d.prepare !== "function") {
+    throw new MigrationError("migrations/no-db",
+      "no db handle: pass opts.db or initialize b.db before create()",
+      true);
+  }
+  return d;
+}
+
+function _loadMigration(file, dir) {
+  var fullPath = path.join(dir, file);
+  // Drop the require cache for this path before loading so a test that
+  // changes a migration file between calls picks up the new content.
+  // Production deployments would always restart the process, but this
+  // keeps test fixtures sane.
+  try { delete require.cache[require.resolve(fullPath)]; } catch (_e) { /* not yet cached */ }
+  var mod;
+  try { mod = require(fullPath); }
+  catch (e) {
+    throw new MigrationError("migrations/load-failed",
+      "migration '" + file + "' failed to load: " + ((e && e.message) || String(e)),
+      true);
+  }
+  if (!mod || typeof mod.up !== "function") {
+    throw new MigrationError("migrations/missing-up",
+      "migration '" + file + "' must export an `up(db)` function", true);
+  }
+  return mod;
+}
+
+function _txn(db, fn) {
+  _runSql(db, "BEGIN");
+  try {
+    var v = fn();
+    _runSql(db, "COMMIT");
+    return v;
+  } catch (e) {
+    try { _runSql(db, "ROLLBACK"); } catch (_e) { /* already in error path */ }
+    throw e;
+  }
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["dir", "db", "staleAfterMs"], "b.migrations");
+  if (typeof opts.dir !== "string" || opts.dir.length === 0) {
+    throw new MigrationError("migrations/no-dir",
+      "migrations.create requires opts.dir (path to migrations directory)",
+      true);
+  }
+  var dir = opts.dir;
+
+  function _appliedRows() {
+    var db = _resolveDb(opts);
+    _ensureTable(db);
+    return db.prepare(
+      "SELECT name, description, appliedAt FROM " + MIGRATIONS_TABLE +
+      " ORDER BY appliedAt ASC, name ASC"
+    ).all();
+  }
+
+  function status() {
+    var applied = _appliedRows();
+    var appliedNames = new Set(applied.map(function (r) { return r.name; }));
+    var files = _list(dir);
+    var pending = files.filter(function (f) { return !appliedNames.has(f); });
+    return {
+      applied:  applied,
+      pending:  pending,
+      total:    files.length,
+    };
+  }
+
+  function up() {
+    var db = _resolveDb(opts);
+    _ensureTable(db);
+    return _withLock(db, opts, function () {
+      var appliedSet = new Set(
+        db.prepare("SELECT name FROM " + MIGRATIONS_TABLE).all()
+          .map(function (r) { return r.name; })
+      );
+      var files = _list(dir);
+      var applied = [];
+      var skipped = [];
+      for (var i = 0; i < files.length; i++) {
+        var file = files[i];
+        if (appliedSet.has(file)) { skipped.push(file); continue; }
+        var mod = _loadMigration(file, dir);
+        try {
+          _txn(db, function () {
+            mod.up(db);
+            db.prepare(
+              "INSERT INTO " + MIGRATIONS_TABLE +
+              " (name, description, appliedAt) VALUES (?, ?, ?)"
+            ).run(file, mod.description || "", new Date().toISOString());
+          });
+        } catch (e) {
+          throw new MigrationError("migrations/up-failed",
+            "migration '" + file + "' failed: " + ((e && e.message) || String(e)),
+            true);
+        }
+        applied.push(file);
+      }
+      return { applied: applied, skipped: skipped };
+    });
+  }
+
+  function down(opts2) {
+    opts2 = opts2 || {};
+    var steps = opts2.steps === undefined ? 1 : Number(opts2.steps);
+    if (!Number.isFinite(steps) || steps < 1 || Math.floor(steps) !== steps) {
+      throw new MigrationError("migrations/bad-steps",
+        "down: steps must be a positive integer (got " + opts2.steps + ")",
+        true);
+    }
+    var db = _resolveDb(opts);
+    _ensureTable(db);
+    return _withLock(db, opts, function () {
+      // Most-recent applied first (reverse chronological by appliedAt
+      // then by name as a stable tiebreaker for fixtures with identical
+      // timestamps).
+      var rows = db.prepare(
+        "SELECT name FROM " + MIGRATIONS_TABLE +
+        " ORDER BY appliedAt DESC, name DESC LIMIT ?"
+      ).all(steps);
+
+      var reverted = [];
+      for (var i = 0; i < rows.length; i++) {
+        var file = rows[i].name;
+        var mod = _loadMigration(file, dir);
+        if (typeof mod.down !== "function") {
+          throw new MigrationError("migrations/no-down",
+            "migration '" + file + "' has no `down(db)` function — " +
+            "rollback unsupported. Restore from backup or write a down().",
+            true);
+        }
+        try {
+          _txn(db, function () {
+            mod.down(db);
+            db.prepare("DELETE FROM " + MIGRATIONS_TABLE + " WHERE name = ?").run(file);
+          });
+        } catch (e) {
+          throw new MigrationError("migrations/down-failed",
+            "rollback of '" + file + "' failed: " + ((e && e.message) || String(e)),
+            true);
+        }
+        reverted.push(file);
+      }
+      return { reverted: reverted };
+    });
+  }
+
+  return {
+    up:       up,
+    down:     down,
+    status:   status,
+    dir:      dir,
+  };
+}
+
+module.exports = {
+  create:           create,
+  MigrationError:   MigrationError,
+  MIGRATIONS_TABLE: MIGRATIONS_TABLE,
+  LOCK_TABLE:       LOCK_TABLE,
+  FILE_RE:          FILE_RE,
+};

package/lib/mtls-ca.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * mtls-ca — mTLS Certificate Authority management.
+ *
+ * Storage, sealed-loading dispatch, generation tagging, atomic commit.
+ * Cert issuance (CA generation, client cert signing, PKCS#12 packaging)
+ * delegates to a pluggable engine. The framework ships a default
+ * pure-JS engine (lib/mtls-engine-default.js, backed by the vendored
+ * @peculiar/x509 + pkijs bundle); operators with custom requirements
+ * pass their own via opts.engine.
+ *
+ *   var ca = b.mtlsCa.create({
+ *     dataDir:          "./data",
+ *     paths: {
+ *       caKey:          "ca.key",
+ *       caKeySealed:    "ca.key.sealed",
+ *       caCert:         "ca.crt",
+ *     },
+ *     vault:            b.vault,         // optional; required when sealed
+ *     caKeySealedMode:  "auto",          // "auto" | "required" | "disabled"
+ *     generation:       1,               // current CA generation for OU=CAv{N}
+ *     engine:           myCertEngine,    // optional — defaults to b.mtlsEngine
+ *   });
+ *
+ * Files (relative to dataDir):
+ *   ca.crt           CA certificate (PEM, plaintext on disk)
+ *   ca.key           CA private key (PEM, plaintext on disk)
+ *   ca.key.sealed    CA private key (vault.seal of PEM bytes)
+ *
+ * caKeySealedMode:
+ *   "auto"      load whichever exists (sealed if present, else plain)
+ *   "required"  sealed file required; refuse plaintext
+ *   "disabled"  plaintext required; refuse sealed
+ *
+ * Generation tagging: every CA cert issued by the framework embeds a
+ * "OU=CAv{N}" RDN in its subject DN. Status reads that back so an
+ * upgrade flow can detect legacy CAs (a pre-rotation CA whose key
+ * parameters are below the current bar) and prompt regeneration
+ * without breaking active mTLS clients.
+ *
+ * Issuance surface (delegates to opts.engine):
+ *
+ *   ca.initCA()
+ *     returns existing { caCertPem, caKeyPem } or generates a fresh
+ *     pair via engine.generateCa() and atomically commits it.
+ *
+ *   ca.generateClientCert({ cn, validityDays })
+ *     calls engine.signClientCert with the CA loaded.
+ *
+ *   ca.generateClientP12({ cn, password, validityDays })
+ *     calls engine.packageP12 with the CA loaded.
+ *
+ * Engine contract (default lib/mtls-engine-default.js, override via
+ * opts.engine):
+ *
+ *   {
+ *     async generateCa({ generation })
+ *       returns { caCertPem, caKeyPem },
+ *     async signClientCert({ cn, validityDays, caCertPem, caKeyPem })
+ *       returns { cert, key, ca, issuedAt, expiresAt },
+ *     async packageP12({ cn, password, validityDays, caCertPem, caKeyPem })
+ *       returns { p12, certPem, issuedAt, expiresAt },
+ *   }
+ *
+ * Note: the engine returns the cert PEM (`certPem`) but does NOT
+ * compute a fingerprint — the framework hashes the cert via
+ * `b.crypto.sha3Hash(certPem)` for any audit / display purpose,
+ * keeping the SHA3-512 posture consistent across the rest of the
+ * stack. Operators who want the X.509-conventional SHA-256
+ * fingerprint (for browser cert-details panels, openssl interop)
+ * compute it separately from the cert PEM.
+ */
+
+var fs = require("fs");
+var path = require("path");
+var nodeCrypto = require("node:crypto");
+var validateOpts = require("./validate-opts");
+var { FrameworkError } = require("./framework-error");
+
+class MtlsCaError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "MtlsCaError";
+    this.permanent = true;
+    this.isMtlsCaError = true;
+  }
+}
+
+var DEFAULT_PATHS = {
+  caKey:        "ca.key",
+  caKeySealed:  "ca.key.sealed",
+  caCert:       "ca.crt",
+};
+
+var VALID_SEAL_MODES = { auto: 1, required: 1, disabled: 1 };
+
+function _resolvePaths(dataDir, paths) {
+  var p = Object.assign({}, DEFAULT_PATHS, paths || {});
+  return {
+    caKey:        path.join(dataDir, p.caKey),
+    caKeySealed:  path.join(dataDir, p.caKeySealed),
+    caCert:       path.join(dataDir, p.caCert),
+  };
+}
+
+// Parse "OU=CAv{N}" from a PEM cert's subject DN. Returns the integer
+// N (defaulting to 1 for untagged legacy CAs) or 0 when the cert is
+// unreadable. Untagged returning 1 means the first regen lifts a legacy
+// CA to generation 2 without misidentifying it as fresh.
+function parseGeneration(certPem) {
+  if (typeof certPem !== "string" && !Buffer.isBuffer(certPem)) return 0;
+  try {
+    var cert = new nodeCrypto.X509Certificate(certPem);
+    var subj = cert.subject || "";
+    var m = /OU=CAv(\d+)/.exec(subj);
+    return m ? parseInt(m[1], 10) : 1;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "dataDir", "paths", "vault",
+    "caKeySealedMode", "generation", "engine",
+  ], "b.mtlsCa");
+  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw new MtlsCaError("mtls-ca/no-datadir",
+      "mtlsCa.create requires opts.dataDir");
+  }
+  var paths = _resolvePaths(opts.dataDir, opts.paths);
+  var vault = opts.vault || null;
+  var caKeySealedMode = (opts.caKeySealedMode || "auto").toLowerCase();
+  if (!VALID_SEAL_MODES[caKeySealedMode]) {
+    throw new MtlsCaError("mtls-ca/bad-mode",
+      "caKeySealedMode must be 'auto', 'required', or 'disabled'");
+  }
+  var generation = typeof opts.generation === "number" && opts.generation >= 1
+    ? Math.floor(opts.generation) : 1;
+  // The default engine carries a 600+ KB vendored bundle; load it only
+  // when operators rely on it (no custom engine passed). Operators who
+  // wire their own engine never pay the cost.
+  var engine = opts.engine || require("./mtls-engine-default");
+
+  function _requireVault(reason) {
+    if (!vault || typeof vault.seal !== "function" || typeof vault.unseal !== "function") {
+      throw new MtlsCaError("mtls-ca/no-vault",
+        reason + " requires opts.vault (with seal/unseal). Pass b.vault " +
+        "or use caKeySealedMode='disabled' to keep the CA key on disk in plaintext.");
+    }
+  }
+
+  function keyExists() {
+    return fs.existsSync(paths.caKey) || fs.existsSync(paths.caKeySealed);
+  }
+  function exists() {
+    return keyExists() && fs.existsSync(paths.caCert);
+  }
+
+  function status() {
+    if (!exists()) {
+      return {
+        exists:     false,
+        generation: 0,
+        isLegacy:   false,
+        current:    generation,
+      };
+    }
+    var pem = fs.readFileSync(paths.caCert);
+    var gen = parseGeneration(pem);
+    return {
+      exists:     true,
+      generation: gen,
+      isLegacy:   gen < generation,
+      current:    generation,
+    };
+  }
+
+  // Load the CA key in whichever form is on disk, applying the
+  // caKeySealedMode dispatch. Returns Buffer of PEM bytes, or throws
+  // with a precise reason when the mode rejects the on-disk form.
+  function loadKey() {
+    var hasPlain  = fs.existsSync(paths.caKey);
+    var hasSealed = fs.existsSync(paths.caKeySealed);
+    if (!hasPlain && !hasSealed) {
+      throw new MtlsCaError("mtls-ca/missing-key",
+        "no CA key on disk at " + paths.caKey + " or " + paths.caKeySealed);
+    }
+    if (caKeySealedMode === "required") {
+      if (!hasSealed) {
+        throw new MtlsCaError("mtls-ca/sealed-required",
+          "CA_KEY_SEALED='required' but " + paths.caKeySealed + " does not exist");
+      }
+      _requireVault("sealed CA key load");
+      var sealedBytes = fs.readFileSync(paths.caKeySealed, "utf8").trim();
+      var pem = vault.unseal(sealedBytes);
+      if (!pem) {
+        throw new MtlsCaError("mtls-ca/unseal-failed",
+          "vault.unseal of " + paths.caKeySealed + " returned empty — vault key mismatch?");
+      }
+      return Buffer.from(pem, "utf8");
+    }
+    if (caKeySealedMode === "disabled") {
+      if (!hasPlain) {
+        throw new MtlsCaError("mtls-ca/plain-required",
+          "CA_KEY_SEALED='disabled' but " + paths.caKey + " does not exist");
+      }
+      return fs.readFileSync(paths.caKey);
+    }
+    // auto: prefer sealed if it exists (defense-in-depth default)
+    if (hasSealed) {
+      _requireVault("sealed CA key load");
+      var sealedBytesA = fs.readFileSync(paths.caKeySealed, "utf8").trim();
+      var pemA = vault.unseal(sealedBytesA);
+      if (!pemA) {
+        throw new MtlsCaError("mtls-ca/unseal-failed",
+          "vault.unseal of " + paths.caKeySealed + " returned empty");
+      }
+      return Buffer.from(pemA, "utf8");
+    }
+    return fs.readFileSync(paths.caKey);
+  }
+
+  function loadCert() {
+    if (!fs.existsSync(paths.caCert)) {
+      throw new MtlsCaError("mtls-ca/missing-cert",
+        "no CA cert on disk at " + paths.caCert);
+    }
+    return fs.readFileSync(paths.caCert);
+  }
+
+  // Atomic commit: write .tmp + atomic rename for both key and cert.
+  // Honors caKeySealedMode — when 'required', the key is vault-sealed
+  // before the on-disk write so plaintext PEM never touches the
+  // filesystem; when 'disabled', it goes to disk as PEM. 'auto'
+  // defaults to plaintext-on-disk.
+  function commit(opts2) {
+    if (!opts2 || typeof opts2.caKeyPem !== "string" || typeof opts2.caCertPem !== "string") {
+      throw new MtlsCaError("mtls-ca/bad-commit",
+        "commit requires opts.caKeyPem and opts.caCertPem (PEM strings)");
+    }
+    var sealed = caKeySealedMode === "required";
+    var keyDest = sealed ? paths.caKeySealed : paths.caKey;
+    var keyTmp = keyDest + ".tmp";
+    var certTmp = paths.caCert + ".tmp";
+
+    try {
+      if (sealed) {
+        _requireVault("sealed CA key commit");
+        fs.writeFileSync(keyTmp, vault.seal(opts2.caKeyPem), { mode: 0o600 });
+      } else {
+        fs.writeFileSync(keyTmp, opts2.caKeyPem, { mode: 0o600 });
+      }
+      fs.writeFileSync(certTmp, opts2.caCertPem, { mode: 0o644 });
+      fs.renameSync(keyTmp, keyDest);
+      fs.renameSync(certTmp, paths.caCert);
+    } catch (e) {
+      try { if (fs.existsSync(keyTmp))  fs.unlinkSync(keyTmp); }  catch (_e) {}
+      try { if (fs.existsSync(certTmp)) fs.unlinkSync(certTmp); } catch (_e) {}
+      throw new MtlsCaError("mtls-ca/commit-failed",
+        "atomic CA commit failed: " + ((e && e.message) || String(e)));
+    }
+    return {
+      keyPath:  keyDest,
+      certPath: paths.caCert,
+      sealed:   sealed,
+    };
+  }
+
+  async function initCA() {
+    if (exists()) {
+      return { caCertPem: loadCert().toString("utf8"), caKeyPem: loadKey().toString("utf8") };
+    }
+    var fresh = await engine.generateCa({ generation: generation });
+    if (!fresh || typeof fresh.caCertPem !== "string" || typeof fresh.caKeyPem !== "string") {
+      throw new MtlsCaError("mtls-ca/bad-engine-output",
+        "engine.generateCa must return { caCertPem, caKeyPem }");
+    }
+    commit(fresh);
+    return fresh;
+  }
+
+  async function generateClientCert(opts2) {
+    opts2 = opts2 || {};
+    var ca = await initCA();
+    var args = Object.assign({}, opts2, { caCertPem: ca.caCertPem, caKeyPem: ca.caKeyPem });
+    var result = await engine.signClientCert(args);
+    if (!result || typeof result.cert !== "string" || typeof result.key !== "string") {
+      throw new MtlsCaError("mtls-ca/bad-engine-output",
+        "engine.signClientCert must return { cert, key, ca?, issuedAt?, expiresAt? }");
+    }
+    return result;
+  }
+
+  async function generateClientP12(opts2) {
+    opts2 = opts2 || {};
+    if (!opts2.password || typeof opts2.password !== "string") {
+      throw new MtlsCaError("mtls-ca/no-password",
+        "generateClientP12 requires opts.password (the PKCS#12 encryption password)");
+    }
+    var ca = await initCA();
+    var args = Object.assign({}, opts2, { caCertPem: ca.caCertPem, caKeyPem: ca.caKeyPem });
+    var result = await engine.packageP12(args);
+    if (!result || !Buffer.isBuffer(result.p12)) {
+      throw new MtlsCaError("mtls-ca/bad-engine-output",
+        "engine.packageP12 must return { p12: Buffer, certPem, issuedAt, expiresAt }");
+    }
+    return result;
+  }
+
+  return {
+    exists:               exists,
+    keyExists:            keyExists,
+    status:               status,
+    loadKey:              loadKey,
+    loadCert:             loadCert,
+    commit:               commit,
+    initCA:               initCA,
+    generateClientCert:   generateClientCert,
+    generateClientP12:    generateClientP12,
+    paths:                paths,
+    generation:           generation,
+    caKeySealedMode:      caKeySealedMode,
+  };
+}
+
+module.exports = {
+  create:           create,
+  parseGeneration:  parseGeneration,
+  MtlsCaError:      MtlsCaError,
+  DEFAULT_PATHS:    DEFAULT_PATHS,
+};