@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/chain-writer.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * @module b.chainWriter
+ * @nav    Observability
+ * @title  Chain Writer
+ *
+ * @intro
+ *   Race-safe append to a hash-chained log table. Both `audit_log` and
+ *   `consent_log` share the same row shape — take next monotonic
+ *   counter, read previous row's `rowHash`, seal the logical row via
+ *   field-crypto, materialize null entries for every hashable column
+ *   so canonicalization sees the same key set at write-time and
+ *   verify-time, compute `rowHash` over the sealed content, INSERT
+ *   with `prevHash` / `rowHash` / `nonce` / `fencingToken`.
+ *
+ *   The chain-writer extracts that pattern so every consumer gets the
+ *   same race protection. Each instance owns a per-chain Mutex
+ *   serializing read-prev → compute-hash → insert (without it,
+ *   concurrent appends hash against the same prev-tip and fork the
+ *   chain), plus a Once initializing the in-process counter from
+ *   `MAX(monotonicCounter)` on first use.
+ *
+ *   Writes route through the cluster-storage dispatcher so the same
+ *   chain definition works on single-node SQLite and on cluster-mode
+ *   external Postgres. `cluster.requireLeader()` runs before the
+ *   mutex; followers reject with `NotLeaderError`. Table names are
+ *   restricted to the `ALLOWED_CHAIN_TABLES` allowlist so a misconfig
+ *   can't point a writer at a non-chain table and corrupt the chain
+ *   semantics.
+ *
+ *   Operators usually don't construct chain-writers directly — `b.audit`
+ *   and `b.consent` each construct one at module load. Direct use is
+ *   for new chain-backed tables registered in `ALLOWED_CHAIN_TABLES`.
+ *
+ * @card
+ *   Race-safe append to a hash-chained log table.
+ */
+
+var { generateToken, generateBytes } = require("./crypto");
+var auditChain = require("./audit-chain");
+var cryptoField = require("./crypto-field");
+var cluster = require("./cluster");
+var clusterStorage = require("./cluster-storage");
+var safeAsync = require("./safe-async");
+var safeSql = require("./safe-sql");
+var C = require("./constants");
+var { FrameworkError } = require("./framework-error");
+
+// Allowlist of chain table names. Adding a new chain-backed table
+// (e.g. some future _blamejs_security_log) requires registering it here
+// so an operator can't accidentally point a chain-writer at a non-chain
+// table and corrupt the chain semantics.
+var ALLOWED_CHAIN_TABLES = new Set(["audit_log", "consent_log"]);
+
+var FRAMEWORK_SQL_TIMEOUT_MS = C.TIME.seconds(30);
+
+class ChainWriterError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "ChainWriterError";
+    this.code = code || "chain-writer/invalid";
+    this.isChainWriterError = true;
+  }
+}
+
+/**
+ * @primitive b.chainWriter.create
+ * @signature b.chainWriter.create(opts)
+ * @since     0.8.48
+ * @status    stable
+ * @related   b.audit, b.consent, b.auditChain
+ *
+ * Build a chain-writer bound to a single hash-chained table. Returns
+ * `{ table, append, _resetForTest, _getMutexForTest }`. `append(logical)`
+ * is the public surface — async, leader-gated, mutex-serialized; on
+ * success it returns the logical row decorated with the computed
+ * `rowHash` and `prevHash`.
+ *
+ * @opts
+ *   table:            string,    // one of ALLOWED_CHAIN_TABLES (audit_log | consent_log)
+ *   columnsForInsert: string[],  // INSERT column order (every name is identifier-validated)
+ *   hashableColumns:  string[],  // columns that participate in the rowHash canonicalization
+ *   validateInput:    Function,  // optional; (logical) → throws on invalid shape
+ *
+ * @example
+ *   var writer = b.chainWriter.create({
+ *     table:            "audit_log",
+ *     columnsForInsert: ["_id", "monotonicCounter", "recordedAt",
+ *                        "action", "outcome",
+ *                        "prevHash", "rowHash", "nonce", "fencingToken"],
+ *     hashableColumns:  ["_id", "monotonicCounter", "recordedAt",
+ *                        "action", "outcome"],
+ *   });
+ *
+ *   var row = await writer.append({
+ *     action:  "user.login",
+ *     outcome: "success",
+ *   });
+ *   row.rowHash;     // → "<hex sha3-512 digest>"
+ *   row.prevHash;    // → "<previous tip rowHash, or zero-hash on first row>"
+ */
+function create(opts) {
+  if (!opts || !opts.table || !Array.isArray(opts.columnsForInsert) ||
+      !Array.isArray(opts.hashableColumns)) {
+    throw new ChainWriterError(
+      "create requires { table, columnsForInsert, hashableColumns }",
+      "chain-writer/invalid-config"
+    );
+  }
+  // Validate table name shape AND require it's in the chain-table allowlist.
+  safeSql.validateIdentifier(opts.table);
+  safeSql.assertOneOf(opts.table, ALLOWED_CHAIN_TABLES);
+
+  // Validate every column name against the SQL identifier rules — we
+  // interpolate them into the INSERT SQL.
+  for (var i = 0; i < opts.columnsForInsert.length; i++) {
+    safeSql.validateIdentifier(opts.columnsForInsert[i]);
+  }
+  for (var j = 0; j < opts.hashableColumns.length; j++) {
+    safeSql.validateIdentifier(opts.hashableColumns[j]);
+  }
+
+  var table             = opts.table;
+  var columnsForInsert  = opts.columnsForInsert.slice();
+  var hashableColumns   = opts.hashableColumns.slice();
+  var validateInput     = opts.validateInput || null;
+
+  // Per-chain Mutex serializes the read-prev-tip + compute-hash + insert
+  // sequence. Without serialization, two concurrent awaiting append() calls
+  // would hash against the same prev-tip and produce sibling rows with the
+  // same prevHash — forking the chain.
+  var _chainMutex = new safeAsync.Mutex();
+
+  // Lazy counter primer — first append reads MAX(monotonicCounter) and
+  // increments from there. Once ensures concurrent first-callers share
+  // one in-flight init Promise.
+  var _nextCounter = 1;
+  var _counterInit = null;
+
+  function _ensureCounterInit() {
+    if (!_counterInit) {
+      _counterInit = new safeAsync.Once(async function () {
+        var row = await safeAsync.withTimeout(
+          safeAsync.asyncRetry(function () {
+            return clusterStorage.executeOne(
+              "SELECT MAX(monotonicCounter) AS m FROM " + safeSql.quoteIdentifier(table)
+            );
+          }),
+          FRAMEWORK_SQL_TIMEOUT_MS,
+          { name: table + ".readMaxCounter" }
+        );
+        _nextCounter = (row && row.m ? Number(row.m) : 0) + 1;
+      });
+    }
+    return _counterInit.invoke();
+  }
+
+  async function _readChainTipRow() {
+    return await safeAsync.withTimeout(
+      safeAsync.asyncRetry(function () {
+        return clusterStorage.executeOne(
+          "SELECT rowHash FROM " + safeSql.quoteIdentifier(table) +
+          " ORDER BY monotonicCounter DESC LIMIT 1"
+        );
+      }),
+      FRAMEWORK_SQL_TIMEOUT_MS,
+      { name: table + ".readChainTip" }
+    );
+  }
+
+  async function _insertRow(values) {
+    // Build INSERT with quoted identifiers + ? placeholders. cluster-
+    // storage handles dialect-specific placeholder translation.
+    var quoted = columnsForInsert.map(function (c) { return safeSql.quoteIdentifier(c); }).join(", ");
+    var placeholders = columnsForInsert.map(function () { return "?"; }).join(", ");
+    return await safeAsync.withTimeout(
+      clusterStorage.execute(
+        "INSERT INTO " + safeSql.quoteIdentifier(table) +
+        " (" + quoted + ") VALUES (" + placeholders + ")",
+        values
+      ),
+      FRAMEWORK_SQL_TIMEOUT_MS,
+      { name: table + ".insertRow" }
+    );
+  }
+
+  async function append(logical) {
+    if (validateInput) validateInput(logical);
+    cluster.requireLeader();
+    await _ensureCounterInit();
+
+    return await _chainMutex.runExclusive(async function () {
+      return await _appendInsideMutex(logical);
+    });
+  }
+
+  async function _appendInsideMutex(logical) {
+    var counter = _nextCounter++;
+    var nowMs   = Date.now();
+    var nonce   = generateBytes(C.BYTES.bytes(16));
+
+    // Caller-supplied logical row: spread + add framework-managed fields.
+    var fullLogical = Object.assign({}, logical, {
+      _id:               (logical && logical._id) || generateToken(C.BYTES.bytes(16)),
+      recordedAt:        nowMs,
+      monotonicCounter:  counter,
+    });
+
+    // Seal sealed-fields, compute derived hashes
+    var sealed = cryptoField.sealRow(table, fullLogical);
+
+    // Materialize null entries for every hashable column the schema
+    // expects, so canonicalize sees the same key set at write-time and
+    // verify-time. JSON canonicalization distinguishes missing-key
+    // from key:null — must not.
+    for (var hci = 0; hci < hashableColumns.length; hci++) {
+      if (!(hashableColumns[hci] in sealed)) sealed[hashableColumns[hci]] = null;
+    }
+
+    // Compute rowHash over the sealed content fields
+    var tipRow = await _readChainTipRow();
+    var prevHash = tipRow ? tipRow.rowHash : auditChain.ZERO_HASH;
+    var rowHash = auditChain.computeRowHash(prevHash, sealed, nonce);
+
+    sealed.prevHash = prevHash;
+    sealed.rowHash  = rowHash;
+    sealed.nonce    = nonce;
+
+    var fencingToken = cluster.fencingToken();
+    var values = columnsForInsert.map(function (c) {
+      if (c === "fencingToken") return fencingToken;
+      return c in sealed ? sealed[c] : null;
+    });
+    await _insertRow(values);
+
+    return Object.assign({ rowHash: rowHash, prevHash: prevHash }, fullLogical);
+  }
+
+  function _resetForTest() {
+    _chainMutex = new safeAsync.Mutex();
+    _counterInit = null;
+    _nextCounter = 1;
+  }
+
+  return {
+    table:          table,
+    append:         append,
+    _resetForTest:  _resetForTest,
+    // Expose for diagnostic introspection
+    _getMutexForTest: function () { return _chainMutex; },
+  };
+}
+
+module.exports = {
+  create:               create,
+  ChainWriterError:     ChainWriterError,
+  ALLOWED_CHAIN_TABLES: ALLOWED_CHAIN_TABLES,
+  FRAMEWORK_SQL_TIMEOUT_MS: FRAMEWORK_SQL_TIMEOUT_MS,
+};

package/lib/vendor/blamejs/lib/circuit-breaker.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * @module b.circuitBreaker
+ * @nav    Production
+ * @title  Circuit Breaker
+ *
+ * @intro
+ *   Top-level circuit-breaker primitive. Re-exports the CircuitBreaker
+ *   class otherwise reachable as `b.retry.CircuitBreaker`, plus a
+ *   `create(opts)` factory matching every other framework primitive's
+ *   `create()` shape. The implementation lives in `lib/retry.js` so the
+ *   retry classifier and the breaker share the `isRetryable` /
+ *   observability emit conventions; this module is the operator-facing
+ *   surface so callers don't have to know retry is the breaker's home.
+ *
+ *   State machine: `closed` (normal flow; failures count up to
+ *   `failureThreshold`), `open` (every call fast-fails for `cooldownMs`),
+ *   `half` (first probe closes the breaker on success or re-opens it
+ *   on failure). Intended for per-target use — one instance per
+ *   upstream service. Sharing a breaker across unrelated targets
+ *   defeats the failure-threshold semantic.
+ *
+ * @card
+ *   Top-level circuit-breaker primitive.
+ */
+
+var retryHelper = require("./retry");
+
+/**
+ * @primitive b.circuitBreaker.create
+ * @signature b.circuitBreaker.create(opts)
+ * @since     0.8.48
+ * @status    stable
+ * @related   b.retry, b.httpClient
+ *
+ * Build a circuit-breaker. Returns a CircuitBreaker instance with
+ * `wrap(fn)` (executes `fn` if the breaker is closed; throws an
+ * `Error` with `code: "CIRCUIT_OPEN"` + `isObjectStoreError: true` +
+ * `permanent: false` when open), `state()`, `reset()`, and
+ * `onStateChange(handler)` listener registration. Pass-through
+ * factory: identical instance shape to `b.retry.CircuitBreaker`,
+ * with the framework's `create(opts)` vocabulary.
+ *
+ * The `CIRCUIT_OPEN` error code is a pre-v1 artifact — every other
+ * framework error class uses namespaced codes (`retry/...`). The
+ * rename is deferred to v0.10 with a deprecation cycle so existing
+ * operators who match `err.code === "CIRCUIT_OPEN"` aren't broken
+ * in a patch.
+ *
+ * @opts
+ *   name:             string,    // identifier used in audit + state-change events
+ *   failureThreshold: number,    // failures in the closed state before opening
+ *   cooldownMs:       number,    // milliseconds the breaker stays open before probing
+ *   successThreshold: number,    // probe successes required to close from half-open
+ *   audit:            Object,    // optional b.audit instance for state-change emission
+ *   onStateChange:    Function,  // ({ name, from, to, at }) → void
+ *
+ * @example
+ *   var cb = b.circuitBreaker.create({
+ *     name:             "upstream-billing",
+ *     failureThreshold: 5,
+ *     cooldownMs:       30000,
+ *     successThreshold: 2,
+ *     onStateChange:    function (e) {
+ *       // e = { name, from: "closed", to: "open", at: <ms> }
+ *     },
+ *   });
+ *
+ *   var result = await cb.wrap(async function () {
+ *     return { ok: true, value: 42 };
+ *   });
+ *   result.value;     // → 42
+ */
+function create(opts) {
+  // The CircuitBreaker class constructor is `(name, opts)` — passing a
+  // single opts object lands it in the positional `name` slot, and the
+  // validator throws "name must be a non-empty string, got object."
+  // The factory's documented shape is `create({ name, ...opts })`;
+  // split the name out of opts before invoking the constructor.
+  // Caught by hermitstash-sync operator review against v0.9.12.
+  //
+  // CRYPTO-19 — the previous empty-string fallback was unreachable
+  // (retryHelper.CircuitBreaker validator throws on "" first) AND
+  // produced a confusing error message ("name must be a non-empty
+  // string, got string \"\"") that obscured the real opt-shape
+  // problem. Pass opts.name through directly so the validator's
+  // error message reports the exact opt-shape error (missing name,
+  // non-string name, etc.) — the operator can act on it without
+  // tracing through the factory.
+  opts = opts || {};
+  return new retryHelper.CircuitBreaker(opts.name, opts);
+}
+
+module.exports = {
+  create:         create,
+  CircuitBreaker: retryHelper.CircuitBreaker,
+  // Forward the error class so operators catching breaker rejections
+  // can `instanceof` against the framework's RetryError without
+  // requiring a separate b.retry import.
+  RetryError:     retryHelper.RetryError,
+};

package/lib/vendor/blamejs/lib/cli-helpers.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * @module b.cliHelpers
+ * @nav    Production
+ * @title  CLI Helpers
+ *
+ * @intro
+ *   Shared shape for blamejs CLI subcommands AND for operators
+ *   writing their own one-shot CLI scripts on top of the framework.
+ *   Three patterns recur across every CLI command (`migrate`, `seed`,
+ *   `audit`, `vault`, `backup`, `api-key`): bootstrap a headless
+ *   `b.createApp` instance from `--data-dir` and shut it down cleanly;
+ *   report success / error / usage with a consistent
+ *   `blamejs <verb> <sub>: <message>` prefix on stderr plus canonical
+ *   exit codes (0 ok, 1 runtime failure, 2 arg error); resolve a
+ *   passphrase from a `--<flag>` or env var into the Buffer shape
+ *   the underlying crypto primitives accept.
+ *
+ *   The reporter writes through whichever stream `ctx.stdout` /
+ *   `ctx.stderr` point at — `process.stdout` / `process.stderr` in
+ *   production, captured stream stubs in tests — so the same handler
+ *   is testable without spawning a child process.
+ *
+ * @card
+ *   Shared shape for blamejs CLI subcommands AND for operators writing their own one-shot CLI scripts on top of the framework.
+ */
+
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+
+// lazyRequire the framework root so cli-helpers stays loadable in
+// contexts that aren't the framework root (tests, operator-side
+// scripts importing only cli-helpers). The first bootApp() call
+// resolves the framework module; subsequent calls reuse the cached
+// load.
+var blamejs = lazyRequire(function () { return require("../"); });
+
+// ---- Streams + exit-code-shaped reporting --------------------------------
+
+function _writeLine(stream, line) {
+  if (!stream || typeof stream.write !== "function") return;
+  if (line == null) return;
+  stream.write(String(line) + "\n");
+}
+
+/**
+ * @primitive b.cliHelpers.makeReporter
+ * @signature b.cliHelpers.makeReporter(ctx, prefix)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.cliHelpers.resolvePassphrase, b.cliHelpers.bootApp
+ *
+ * Build a reporter bound to a CLI context (`ctx.stdout` /
+ * `ctx.stderr`) and a verb prefix. Every stderr message produced by
+ * `.error` / `.usage` gets the prefix. Methods return canonical
+ * Unix exit codes — `0` for `ok` / `helpStdout`, `1` for `error`
+ * (override via second arg), `2` for `usage` (argument-error
+ * convention).
+ *
+ * @example
+ *   var ctx = { stdout: process.stdout, stderr: process.stderr };
+ *   var report = b.cliHelpers.makeReporter(ctx, "blamejs vault seal");
+ *   var ok   = report.ok("sealed: /data/vault");        // → 0
+ *   var fail = report.error("decrypt failed");          // → 1
+ *   var arg  = report.error("missing --data-dir", 2);   // → 2
+ *   var help = report.usage("Usage: blamejs vault ..."); // → 2
+ */
+function makeReporter(ctx, prefix) {
+  if (!ctx || typeof ctx !== "object") {
+    throw new Error("cliHelpers.makeReporter: ctx is required");
+  }
+  if (typeof prefix !== "string" || prefix.length === 0) {
+    throw new Error("cliHelpers.makeReporter: prefix is required (non-empty string)");
+  }
+  var stdout = ctx.stdout || (typeof process !== "undefined" ? process.stdout : null);
+  var stderr = ctx.stderr || (typeof process !== "undefined" ? process.stderr : null);
+  return {
+    ok: function (message) {
+      if (message != null) _writeLine(stdout, message);
+      return 0;
+    },
+    error: function (message, exitCode) {
+      _writeLine(stderr, prefix + ": " + message);
+      return typeof exitCode === "number" ? exitCode : 1;
+    },
+    usage: function (usageText) {
+      _writeLine(stderr, usageText);
+      return 2;
+    },
+    helpStdout: function (usageText) {
+      _writeLine(stdout, usageText);
+      return 0;
+    },
+    // Direct access for handlers that have multi-line output.
+    write:    function (line) { _writeLine(stdout, line); },
+    writeErr: function (line) { _writeLine(stderr, line); },
+  };
+}
+
+// ---- Passphrase resolution -----------------------------------------------
+
+/**
+ * @primitive b.cliHelpers.resolvePassphrase
+ * @signature b.cliHelpers.resolvePassphrase(args, ctx, opts)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.cliHelpers.makeReporter, b.cliHelpers.bootApp
+ *
+ * Resolve a passphrase from a CLI flag (preferred) or an env var
+ * (fallback) into a UTF-8 Buffer — the shape vault / crypto
+ * primitives accept. Returns `null` when neither source produced a
+ * non-empty string; the caller decides whether absence is a hard
+ * error (vault seal) or a soft default (plaintext-mode dev data dir).
+ *
+ * @opts
+ *   flag:    string  (CLI flag name, e.g. "passphrase" reads args.flags.passphrase),
+ *   envVar:  string  (env var fallback, e.g. "BLAMEJS_VAULT_PASSPHRASE"),
+ *
+ * @example
+ *   var args = { flags: { passphrase: "hunter2" } };
+ *   var ctx  = { env: { BLAMEJS_VAULT_PASSPHRASE: "envval" } };
+ *   var pp = b.cliHelpers.resolvePassphrase(args, ctx, {
+ *     flag:   "passphrase",
+ *     envVar: "BLAMEJS_VAULT_PASSPHRASE",
+ *   });
+ *   pp.toString("utf8");     // → "hunter2"  (flag wins over env)
+ *
+ *   var none = b.cliHelpers.resolvePassphrase({ flags: {} }, { env: {} }, {
+ *     flag: "passphrase", envVar: "BLAMEJS_VAULT_PASSPHRASE",
+ *   });
+ *   none;                    // → null
+ */
+function resolvePassphrase(args, ctx, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["flag", "envVar"], "cliHelpers.resolvePassphrase");
+  if (typeof opts.flag !== "string" || opts.flag.length === 0) {
+    throw new Error("cliHelpers.resolvePassphrase: opts.flag is required");
+  }
+  var raw = null;
+  if (args && args.flags && typeof args.flags[opts.flag] === "string" &&
+      args.flags[opts.flag].length > 0) {
+    raw = args.flags[opts.flag];
+  } else if (opts.envVar && ctx && ctx.env &&
+             typeof ctx.env[opts.envVar] === "string" &&
+             ctx.env[opts.envVar].length > 0) {
+    raw = ctx.env[opts.envVar];
+  }
+  if (raw == null) return null;
+  return Buffer.from(raw, "utf8");
+}
+
+// ---- Headless app bootstrap ----------------------------------------------
+
+/**
+ * @primitive b.cliHelpers.bootApp
+ * @signature b.cliHelpers.bootApp(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.cliHelpers.makeReporter, b.cliHelpers.resolvePassphrase
+ *
+ * Boot a headless `b.createApp` instance from a data dir so a CLI
+ * script (framework subcommand or operator-written tool) can operate
+ * against the same vault + DB + audit chain the live app uses, with
+ * no HTTP listener attached. Returns `{ b, app }` where `b` is the
+ * framework module and `app` is the headless instance — caller MUST
+ * `await booted.app.shutdown()` in a `finally` so SQLite file handles
+ * and the cluster lease release.
+ *
+ * The default DB at-rest mode is `plain` because CLI runs are
+ * short-lived ops that never serve requests; encrypted-at-rest needs
+ * a tmpfs handle that wouldn't survive CLI exit anyway. Operators
+ * running against a production data dir whose DB is encrypted-at-rest
+ * pass `dbAtRest: "encrypted"` and ensure `BLAMEJS_TMPDIR` is set.
+ *
+ * @opts
+ *   dataDir:    string   (filesystem path to the data dir; required),
+ *   vaultMode:  "wrapped" | "plaintext"   (default "wrapped" — wrapped
+ *               reads BLAMEJS_VAULT_PASSPHRASE from `opts.env`),
+ *   dbAtRest:   "plain" | "encrypted"     (default "plain"),
+ *   env:        object    (env-var bag; default process.env),
+ *
+ * @example
+ *   async function run() {
+ *     var booted;
+ *     try {
+ *       booted = await b.cliHelpers.bootApp({
+ *         dataDir:   "./data",
+ *         vaultMode: "plaintext",
+ *         env:       process.env,
+ *       });
+ *       var rows = await booted.app.db.all("SELECT count(*) AS n FROM _blamejs_audit_log");
+ *       return rows[0].n;
+ *     } finally {
+ *       if (booted) await booted.app.shutdown();
+ *     }
+ *   }
+ */
+async function bootApp(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["dataDir", "vaultMode", "dbAtRest", "env"], "cliHelpers.bootApp");
+  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw new Error("cliHelpers.bootApp: opts.dataDir is required");
+  }
+  var vaultMode = opts.vaultMode || "wrapped";
+  if (vaultMode !== "wrapped" && vaultMode !== "plaintext") {
+    throw new Error("cliHelpers.bootApp: opts.vaultMode must be 'wrapped' or 'plaintext'");
+  }
+  var env = opts.env || (typeof process !== "undefined" ? process.env : {});
+
+  var vaultPassphrase = null;
+  if (vaultMode === "wrapped") {
+    var raw = env && env.BLAMEJS_VAULT_PASSPHRASE;
+    if (typeof raw !== "string" || raw.length === 0) {
+      throw new Error("cliHelpers.bootApp: BLAMEJS_VAULT_PASSPHRASE is required " +
+        "for vault mode 'wrapped' (pass vaultMode: 'plaintext' for a dev data dir)");
+    }
+    vaultPassphrase = Buffer.from(raw, "utf8");
+  }
+
+  var b = blamejs();
+  var app = await b.createApp({
+    dataDir: opts.dataDir,
+    routes:  function () {},
+    vault:   { mode: vaultMode, passphrase: vaultPassphrase },
+    db:      {
+      atRest:       opts.dbAtRest || "plain",
+      auditSigning: { mode: "plaintext" },
+    },
+  });
+  return { b: b, app: app };
+}
+
+module.exports = {
+  makeReporter:       makeReporter,
+  resolvePassphrase:  resolvePassphrase,
+  bootApp:            bootApp,
+};