@blamejs/core 0.4.1

package/lib/atomic-file.js

@@ -0,0 +1,525 @@
+"use strict";
+/**
+ * Atomic file I/O with integrity verification, retry on transient errors,
+ * and cross-process locking.
+ *
+ * The framework already does atomic writes for vault.key.sealed (lib/vault.js)
+ * and audit.tip (lib/db.js). This module exposes the same primitives for
+ * any caller that needs:
+ *
+ *   - Crash-safe writes via temp + fsync + atomic rename + dir fsync
+ *   - Optional integrity hash (SHA3-512) computed on write, verified on read
+ *   - Retry on EBUSY / EAGAIN / ENFILE with exponential backoff
+ *   - Cross-process locking for read-modify-write sequences
+ *   - JSON convenience wrappers using b.json's security defaults
+ *
+ * The framework's "fail closed" stance applies: a partially-written file
+ * NEVER survives a crash to the caller — either the new contents are
+ * fully on disk (atomic rename succeeded) or the original (or absence)
+ * remains. fsync calls are best-effort across platforms (Windows rejects
+ * directory fsync, etc.); the rename remains atomic at the FS level
+ * regardless.
+ *
+ * Public API:
+ *   atomicFile.write(filepath, data, opts?)        → { bytesWritten, hash? }
+ *   atomicFile.read(filepath, opts?)               → Buffer (or string if encoding)
+ *   atomicFile.readSync(filepath, opts?)           → same, sync (for boot paths)
+ *   atomicFile.writeJson(filepath, value, opts?)   → { bytesWritten, hash? }
+ *   atomicFile.readJson(filepath, opts?)           → parsed value
+ *   atomicFile.copy(src, dst, opts?)               → { bytesWritten, hash? }
+ *   atomicFile.exists(filepath)                    → boolean
+ *   atomicFile.lock(filepath, fn, opts?)           → fn's return value
+ *   atomicFile.AtomicFileError                     → error class
+ */
+var fs = require("fs");
+var path = require("path");
+var { generateToken, sha3Hash } = require("./crypto");
+var safeJson = require("./safe-json");
+var C = require("./constants");
+var safeBuffer = require("./safe-buffer");
+var safeAsync = require("./safe-async");
+var retry = require("./retry");
+var { FrameworkError } = require("./framework-error");
+
+var DEFAULTS = {
+  maxBytes:        C.BYTES.mib(64),     // 64 MiB ceiling on read
+  retryAttempts:   5,
+  retryBaseMs:     50,
+  retryMaxMs:      C.TIME.seconds(2),
+  fileMode:        0o600,
+  computeHash:     false,
+  lockTimeoutMs:   C.TIME.seconds(30),
+  lockPollMs:      50,
+};
+
+class AtomicFileError extends FrameworkError {
+  constructor(message, code) {
+    super(message);
+    this.name = "AtomicFileError";
+    this.code = code || "atomic-file/error";
+    this.isAtomicFileError = true;
+  }
+}
+
+// ---- Retry helper for transient FS errors ----
+//
+// Routes through b.retry.withRetry with an FS-specific classifier — the
+// errnos that mean "try again" on Linux/macOS/Windows file systems differ
+// from the HTTP/network-shaped default classifier. atomic-file's public
+// opts (retryAttempts/retryBaseMs/retryMaxMs) are mapped to the retry
+// primitive's standard names; jitterFactor 0.5 reproduces the original
+// `delay * (0.5 + Math.random()/2)` range of [delay/2, delay].
+
+var TRANSIENT_FS_ERRNOS = new Set(["EBUSY", "EAGAIN", "ENFILE", "EMFILE", "EPERM"]);
+
+function _isFsRetryable(e) {
+  return e != null && TRANSIENT_FS_ERRNOS.has(e.code);
+}
+
+async function _withRetry(fn, opts) {
+  opts = Object.assign({}, DEFAULTS, opts || {});
+  return retry.withRetry(function () { return fn(); }, {
+    maxAttempts:  opts.retryAttempts,
+    baseDelayMs:  opts.retryBaseMs,
+    maxDelayMs:   opts.retryMaxMs,
+    jitterFactor: 0.5,
+    isRetryable:  _isFsRetryable,
+    signal:       opts.signal,
+  });
+}
+
+// ---- Sync helpers (best effort) ----
+//
+// fsync / fsyncDir / ensureDir / copyDirRecursive / pathTimestamp are
+// public surface — they were previously underscore-prefixed, and other
+// modules (vault-passphrase-ops, vault-rotate, backup-bundle, restore-
+// bundle, restore-rollback, bundler) duplicated them inline. Hoisted
+// here so the framework has one shared implementation per concern.
+
+function fsync(fd) {
+  try { fs.fsyncSync(fd); } catch (_e) { /* not all platforms support fsync on every fd type */ }
+}
+
+function fsyncDir(dirPath) {
+  try {
+    var fd = fs.openSync(dirPath, "r");
+    try { fs.fsyncSync(fd); } catch (_e) { /* Windows rejects directory fsync */ }
+    finally { fs.closeSync(fd); }
+  } catch (_e) { /* dir fsync is best-effort across filesystems */ }
+}
+
+// Internal aliases so existing code in this file keeps working
+function _fsync(fd) { return fsync(fd); }
+function _fsyncDir(dirPath) { return fsyncDir(dirPath); }
+
+// ensureDir — mkdirSync with recursive: true and a default mode of
+// 0o700 (owner-only) suitable for framework data directories. Caller
+// passes a different mode for less-restricted dirs.
+function ensureDir(dirPath, mode) {
+  if (typeof dirPath !== "string" || dirPath.length === 0) {
+    throw new AtomicFileError("ensureDir: path must be a non-empty string", "atomic-file/bad-path");
+  }
+  fs.mkdirSync(dirPath, { recursive: true, mode: typeof mode === "number" ? mode : 0o700 });
+  return dirPath;
+}
+
+// copyDirRecursive — synchronous, file-by-file copy that mirrors the
+// source's directory structure. Skips symlinks (operator wanting symlink
+// preservation should use a real archive tool). Refuses to overwrite
+// existing files at dest by default — pass opts.overwrite=true to
+// replace. dest is created with mode 0o700 by default.
+function copyDirRecursive(src, dest, opts) {
+  if (typeof src !== "string" || src.length === 0) {
+    throw new AtomicFileError("copyDirRecursive: src must be a non-empty string", "atomic-file/bad-path");
+  }
+  if (typeof dest !== "string" || dest.length === 0) {
+    throw new AtomicFileError("copyDirRecursive: dest must be a non-empty string", "atomic-file/bad-path");
+  }
+  if (!fs.existsSync(src)) {
+    throw new AtomicFileError("copyDirRecursive: src does not exist: " + src, "atomic-file/missing-src");
+  }
+  opts = opts || {};
+  var dirMode = typeof opts.dirMode === "number" ? opts.dirMode : 0o700;
+  var overwrite = !!opts.overwrite;
+  var copyFlags = overwrite ? 0 : fs.constants.COPYFILE_EXCL;
+
+  ensureDir(dest, dirMode);
+  var entries = fs.readdirSync(src, { withFileTypes: true });
+  var fileCount = 0;
+  var byteCount = 0;
+  for (var i = 0; i < entries.length; i++) {
+    var name = entries[i].name;
+    var s = path.join(src, name);
+    var d = path.join(dest, name);
+    if (entries[i].isDirectory()) {
+      var sub = copyDirRecursive(s, d, opts);
+      fileCount += sub.fileCount;
+      byteCount += sub.byteCount;
+    } else if (entries[i].isFile()) {
+      fs.copyFileSync(s, d, copyFlags);
+      try { byteCount += fs.statSync(d).size; } catch (_e) { /* size best-effort */ }
+      fileCount++;
+    }
+    // Symlinks, sockets, devices: deliberately skipped
+  }
+  return { fileCount: fileCount, byteCount: byteCount };
+}
+
+// pathTimestamp — filesystem-safe ISO-8601 timestamp suitable for use as
+// a directory or file name on every platform. Standard
+// Date.toISOString() embeds ':' and '.' which Windows reserves for
+// drive letters and extension separators. This helper substitutes both
+// with '-' so the result works as a path segment unmodified. String
+// sort still gives chronological order.
+//
+//   atomicFile.pathTimestamp()
+//     → "2026-04-27T14-00-00-123Z"
+//   atomicFile.pathTimestamp(new Date(0))
+//     → "1970-01-01T00-00-00-000Z"
+function pathTimestamp(date) {
+  var d = (date instanceof Date) ? date : new Date();
+  return d.toISOString().replace(/[:.]/g, "-");
+}
+
+// ---- writeSync ----
+// Synchronous atomic write — same temp+fsync+rename+dirfsync flow as
+// async write(), but without the retry loop (which requires awaits).
+// Use this from sync code paths (process exit handlers, module-load-time
+// bootstraps). For everything else, prefer the async write().
+//
+// Transactional guarantee: either the rename completes (new contents fully
+// visible) or the tmp file is removed (no state change). The caller never
+// sees a half-written file at `filepath` and never leaves a tmp orphan
+// from the current call's failure path.
+function writeSync(filepath, data, opts) {
+  opts = Object.assign({}, DEFAULTS, opts || {});
+  var buf = safeBuffer.toBuffer(data, {
+    errorClass: AtomicFileError,
+    typeCode:   "atomic-file/invalid-data",
+    typeMessage: "data must be Buffer, Uint8Array, or string",
+  });
+
+  var dir = path.dirname(filepath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  var tmpPath = filepath + ".tmp-" + generateToken(8);
+  var renamed = false;
+  try {
+    var fd = fs.openSync(tmpPath, "w", opts.fileMode);
+    try {
+      var pos = 0;
+      while (pos < buf.length) {
+        pos += fs.writeSync(fd, buf, pos, buf.length - pos, null);
+      }
+      _fsync(fd);
+    } finally {
+      try { fs.closeSync(fd); } catch (_e) { /* already closed? */ }
+    }
+    fs.renameSync(tmpPath, filepath);
+    renamed = true;
+    _fsyncDir(dir);
+  } finally {
+    if (!renamed) {
+      // Either the write or the rename failed — remove the tmp so the next
+      // boot doesn't see a leaked partial file.
+      try { fs.unlinkSync(tmpPath); } catch (_e) { /* may not exist */ }
+    }
+  }
+
+  return {
+    bytesWritten: buf.length,
+    hash:         opts.computeHash ? sha3Hash(buf) : null,
+  };
+}
+
+// Clean up orphan tmp files left behind by a previously-crashed process.
+// Atomic writes use random tmp names (filepath + ".tmp-" + token), so a
+// crash leaves a file with a name we can't predict on next boot — only
+// glob and prune by age. Default: prune anything older than 5 minutes.
+//
+// Operators should call this at boot for every "important" filepath
+// (vault.key.sealed, audit-sign.key.sealed, db.enc, etc.) BEFORE they
+// start their first atomic write to that path.
+function cleanOrphans(filepath, opts) {
+  opts = opts || {};
+  var olderThanMs = opts.olderThanMs != null ? opts.olderThanMs : C.TIME.minutes(5);
+  var dir = path.dirname(filepath);
+  var basename = path.basename(filepath);
+  var prefix = basename + ".tmp-";
+  var nowMs = Date.now();
+  var removed = 0;
+  var entries = listDir(dir, {
+    filter:      function (name) { return name.startsWith(prefix); },
+    includeStat: true,
+  });
+  for (var i = 0; i < entries.length; i++) {
+    var entry = entries[i];
+    try {
+      if (nowMs - entry.mtimeMs >= olderThanMs) {
+        fs.unlinkSync(entry.fullPath);
+        removed += 1;
+      }
+    } catch (_e) { /* concurrent cleanup or permission — best effort */ }
+  }
+  return removed;
+}
+
+// ---- write ----
+
+async function write(filepath, data, opts) {
+  opts = Object.assign({}, DEFAULTS, opts || {});
+  var buf = safeBuffer.toBuffer(data, {
+    errorClass: AtomicFileError,
+    typeCode:   "atomic-file/invalid-data",
+    typeMessage: "data must be Buffer, Uint8Array, or string",
+  });
+
+  return await _withRetry(function () {
+    return new Promise(function (resolve, reject) {
+      var dir = path.dirname(filepath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      var tmpPath = filepath + ".tmp-" + generateToken(8);
+      var renamed = false;
+      try {
+        var fd = fs.openSync(tmpPath, "w", opts.fileMode);
+        try {
+          var pos = 0;
+          while (pos < buf.length) {
+            pos += fs.writeSync(fd, buf, pos, buf.length - pos, null);
+          }
+          _fsync(fd);
+        } finally {
+          try { fs.closeSync(fd); } catch (_e) { /* already closed? */ }
+        }
+        // Atomic rename — POSIX rename is atomic on the same FS; on Windows,
+        // fs.renameSync uses MoveFileEx with REPLACE_EXISTING.
+        fs.renameSync(tmpPath, filepath);
+        renamed = true;
+        _fsyncDir(dir);
+        var hash = opts.computeHash ? sha3Hash(buf) : null;
+        resolve({ bytesWritten: buf.length, hash: hash });
+      } catch (e) {
+        reject(e);
+      } finally {
+        if (!renamed) {
+          try { fs.unlinkSync(tmpPath); } catch (_e) { /* may not exist */ }
+        }
+      }
+    });
+  }, opts);
+}
+
+// ---- read ----
+
+async function read(filepath, opts) {
+  opts = Object.assign({}, DEFAULTS, opts || {});
+  return await _withRetry(function () {
+    return new Promise(function (resolve, reject) {
+      try { resolve(_readSyncCore(filepath, opts)); }
+      catch (e) { reject(e); }
+    });
+  }, opts);
+}
+
+// Sync variant for callers in module-init / boot paths that can't
+// `await` (vault.initPlaintext, audit-sign._initPlaintext,
+// db._checkRollback, db.loadOrCreateDbKey). Same semantics as
+// async read: size cap, optional integrity-hash verification, ENOENT
+// translation. No retry loop — sync paths can't usefully back off.
+function readSync(filepath, opts) {
+  opts = Object.assign({}, DEFAULTS, opts || {});
+  return _readSyncCore(filepath, opts);
+}
+
+function _readSyncCore(filepath, opts) {
+  if (!fs.existsSync(filepath)) {
+    var e = new AtomicFileError("file not found: " + filepath, "atomic-file/not-found");
+    e.code = "ENOENT";
+    throw e;
+  }
+  var stat = fs.statSync(filepath);
+  if (stat.size > opts.maxBytes) {
+    throw new AtomicFileError(
+      "file size " + stat.size + " > maxBytes " + opts.maxBytes,
+      "atomic-file/too-large"
+    );
+  }
+  var buf = fs.readFileSync(filepath);
+  if (opts.expectedHash) {
+    var actual = sha3Hash(buf);
+    if (actual !== opts.expectedHash) {
+      throw new AtomicFileError(
+        "integrity check failed: expected " + opts.expectedHash + " got " + actual,
+        "atomic-file/integrity"
+      );
+    }
+  }
+  return opts.encoding ? buf.toString(opts.encoding) : buf;
+}
+
+// ---- writeJson / readJson ----
+
+async function writeJson(filepath, value, opts) {
+  opts = opts || {};
+  var serialized = opts.canonical
+    ? safeJson.canonical(value)
+    : safeJson.stringify(value, { indent: opts.indent || 0 });
+  return await write(filepath, serialized, opts);
+}
+
+async function readJson(filepath, opts) {
+  opts = opts || {};
+  var buf = await read(filepath, opts);
+  var input = Buffer.isBuffer(buf) ? buf : Buffer.from(buf, "utf8");
+  return safeJson.parse(input, opts);
+}
+
+// ---- copy ----
+
+async function copy(src, dst, opts) {
+  opts = Object.assign({}, DEFAULTS, opts || {});
+  var srcOpts = Object.assign({}, opts);
+  delete srcOpts.expectedHash;     // hash check applies to dst, not src
+  var buf = await read(src, srcOpts);
+  if (!Buffer.isBuffer(buf)) buf = Buffer.from(buf, "utf8");
+  return await write(dst, buf, opts);
+}
+
+// ---- exists ----
+
+function exists(filepath) {
+  return fs.existsSync(filepath);
+}
+
+// ---- lock (cross-process file mutex) ----
+
+async function lock(filepath, fn, opts) {
+  opts = Object.assign({}, DEFAULTS, opts || {});
+  var lockPath = filepath + ".lock";
+  var deadline = Date.now() + opts.lockTimeoutMs;
+  var fd = null;
+
+  while (Date.now() < deadline) {
+    try {
+      // O_CREAT | O_EXCL — fails if file exists
+      fd = fs.openSync(lockPath, "wx", opts.fileMode);
+      break;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      // Stale lock detection: if the .lock file is older than 5 minutes,
+      // assume the holding process crashed and remove it.
+      try {
+        var stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > C.TIME.minutes(5)) {
+          try { fs.unlinkSync(lockPath); } catch (_e) {}
+          continue;
+        }
+      } catch (_e) { /* stat raced with another process — keep waiting */ }
+      await safeAsync.sleep(opts.lockPollMs, { signal: opts.signal });
+    }
+  }
+  if (fd === null) {
+    throw new AtomicFileError(
+      "lock timeout after " + opts.lockTimeoutMs + "ms on " + filepath,
+      "atomic-file/lock-timeout"
+    );
+  }
+  try {
+    fs.writeSync(fd, Buffer.from(JSON.stringify({
+      pid:        process.pid,
+      acquiredAt: Date.now(),
+    }), "utf8"));
+    _fsync(fd);
+  } catch (_e) { /* lock content best-effort */ }
+
+  try {
+    return await fn();
+  } finally {
+    try { fs.closeSync(fd); } catch (_e) {}
+    try { fs.unlinkSync(lockPath); } catch (_e) {}
+  }
+}
+
+// Single-directory listing primitive. Wraps fs.readdirSync with the
+// optional-stat pattern + missing-dir tolerance + filter that callers
+// across the framework were re-implementing.
+//
+//   opts:
+//     filter:      function(name) => boolean   — name-only predicate
+//     includeStat: bool — adds mtimeMs / sizeBytes / isDirectory /
+//                  isFile per entry (one fs.statSync call each).
+//                  Skip when the caller only needs names — saves a
+//                  syscall per entry.
+//     missingOk:   bool — default true. Returns [] when the dir
+//                  doesn't exist (ENOENT). Other errors throw.
+//
+//   Returns: array of { name, fullPath } (plus stat fields when
+//   includeStat is true). Entries that vanish between readdir and
+//   stat (concurrent cleanup) are silently dropped.
+//
+// For recursive directory walks, callers compose listDir per
+// subdirectory — the primitive doesn't recurse, so callers can apply
+// per-iteration limits / filters / stop conditions cleanly.
+function listDir(dir, opts) {
+  opts = opts || {};
+  var missingOk   = opts.missingOk !== false;
+  var includeStat = opts.includeStat === true;
+  var filter      = typeof opts.filter === "function" ? opts.filter : null;
+
+  var entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (e) {
+    if (missingOk && e.code === "ENOENT") return [];
+    throw new AtomicFileError(
+      "failed to list directory " + dir + ": " + e.message,
+      "atomic-file/list-failed"
+    );
+  }
+
+  var out = [];
+  for (var i = 0; i < entries.length; i++) {
+    var name = entries[i];
+    if (filter && !filter(name)) continue;
+    var fullPath = path.join(dir, name);
+    var entry = { name: name, fullPath: fullPath };
+    if (includeStat) {
+      try {
+        var stat = fs.statSync(fullPath);
+        entry.mtimeMs    = stat.mtimeMs;
+        entry.sizeBytes  = stat.size;
+        entry.isDirectory = stat.isDirectory();
+        entry.isFile     = stat.isFile();
+      } catch (_e) {
+        // Entry vanished between readdir and stat — concurrent cleanup
+        // by another process. Skip silently; caller asked for stat
+        // info that no longer exists.
+        continue;
+      }
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+module.exports = {
+  write:             write,
+  writeSync:         writeSync,
+  read:              read,
+  readSync:          readSync,
+  writeJson:         writeJson,
+  readJson:          readJson,
+  copy:              copy,
+  exists:            exists,
+  lock:              lock,
+  listDir:           listDir,
+  cleanOrphans:      cleanOrphans,
+  // Filesystem hygiene helpers (lifted from inline duplicates across lib/)
+  fsync:             fsync,
+  fsyncDir:          fsyncDir,
+  ensureDir:         ensureDir,
+  copyDirRecursive:  copyDirRecursive,
+  pathTimestamp:     pathTimestamp,
+  AtomicFileError:   AtomicFileError,
+  DEFAULTS:          DEFAULTS,
+};

package/lib/audit-chain.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Audit hash chain — tamper-evidence math.
+ *
+ * Per the compliance spec ("Tamper evidence (the chain + checkpoint signing)"
+ * in the roadmap):
+ *
+ *   rowHash = SHA3-512(
+ *     prevHash || canonicalize(row-fields-except-hash) || nonce
+ *   )
+ *
+ * Each row's prevHash equals the previous row's rowHash (in monotonic-counter
+ * order). The first row uses ZERO_HASH as prevHash. Verification walks the
+ * chain forward; any row whose prevHash doesn't match the running hash, or
+ * whose rowHash recomputes differently, breaks the chain.
+ *
+ * Checkpoint signing (ML-DSA-87 over (atRow || atRowHash)) lives in
+ * lib/audit-sign.js. This module owns the chain hash math only;
+ * verification is O(n) and walks every row at boot.
+ */
+var { sha3Hash } = require("./crypto");
+
+// All-zero SHA3-512 (128 hex chars) — sentinel prevHash for the first row.
+var ZERO_HASH = "0".repeat(128);
+
+// Canonicalize a row for hashing. Excludes the hash/nonce columns themselves
+// and any caller-specified columns. Sorted keys, JSON-encoded values; Buffer
+// values converted to hex for stable byte serialization.
+function canonicalize(row, excludeKeys) {
+  var ex = new Set(excludeKeys || []);
+  var keys = Object.keys(row).filter(function (k) { return !ex.has(k); }).sort();
+  var pairs = {};
+  for (var i = 0; i < keys.length; i++) {
+    var v = row[keys[i]];
+    if (Buffer.isBuffer(v))                    v = v.toString("hex");
+    else if (v instanceof Uint8Array)          v = Buffer.from(v).toString("hex");
+    else if (v === undefined)                  v = null;
+    pairs[keys[i]] = v;
+  }
+  return JSON.stringify(pairs);
+}
+
+// Compute a row's hash given its predecessor's hash, the row's logical fields
+// (already excluding prevHash, rowHash, nonce), and the row's nonce buffer.
+function computeRowHash(prevHash, rowFields, nonce) {
+  if (typeof prevHash !== "string" || prevHash.length !== 128) {
+    throw new Error("prevHash must be a 128-char hex string (SHA3-512); got length " +
+      (prevHash && prevHash.length));
+  }
+  if (!Buffer.isBuffer(nonce) || nonce.length === 0) {
+    throw new Error("nonce must be a non-empty Buffer");
+  }
+  var canonical = canonicalize(rowFields);
+  var input = Buffer.concat([
+    Buffer.from(prevHash, "hex"),
+    Buffer.from(canonical, "utf8"),
+    nonce,
+  ]);
+  return sha3Hash(input);
+}
+
+// Read the current chain tip (last row's rowHash + monotonicCounter) for a
+// given audit table. Async to accommodate operator-supplied external-db
+// drivers; queryOneAsync is `async (sql, params?) → row | null`.
+async function getChainTip(queryOneAsync, tableName) {
+  var row = await queryOneAsync(
+    'SELECT rowHash, monotonicCounter FROM "' + tableName + '" ' +
+    "ORDER BY monotonicCounter DESC LIMIT 1"
+  );
+  if (!row) return { prevHash: ZERO_HASH, counter: 0 };
+  return { prevHash: row.rowHash, counter: row.monotonicCounter };
+}
+
+// Walk the entire chain forward, recomputing each row's hash. Returns an
+// object describing the result; callers decide how to react (refuse-to-boot,
+// log warning, etc.). queryAllAsync is `async (sql, params?) → rows`.
+//
+// audit_log only: if a `_blamejs_audit_purge_anchor` row exists, the walk
+// starts at lastPurgedCounter+1 with prevHash = lastPurgedRowHash. The
+// anchor is written by audit-tools.purge() after a successful archive,
+// and lets the chain math survive deletion of historical rows without
+// the bundle as the source of truth.
+async function verifyChain(queryAllAsync, tableName, opts) {
+  opts = opts || {};
+
+  var prevHash = ZERO_HASH;
+  var skipBeforeCounter = 0;
+  if (tableName === "audit_log") {
+    var anchor;
+    try {
+      anchor = await queryAllAsync(
+        "SELECT lastPurgedCounter, lastPurgedRowHash FROM _blamejs_audit_purge_anchor " +
+        "WHERE scope = 'audit'"
+      );
+    } catch (_e) {
+      // Anchor table may not exist on a deployment that has never been
+      // through a purge. Treat as no anchor.
+      anchor = [];
+    }
+    if (Array.isArray(anchor) && anchor.length > 0) {
+      prevHash = anchor[0].lastPurgedRowHash;
+      skipBeforeCounter = Number(anchor[0].lastPurgedCounter);
+    }
+  }
+
+  var rows = await queryAllAsync(
+    'SELECT * FROM "' + tableName + '" ORDER BY monotonicCounter ASC'
+  );
+  if (skipBeforeCounter > 0) {
+    rows = rows.filter(function (r) {
+      return Number(r.monotonicCounter) > skipBeforeCounter;
+    });
+  }
+
+  if (rows.length === 0) {
+    return { ok: true, table: tableName, rowsVerified: 0, lastHash: prevHash };
+  }
+  for (var i = 0; i < rows.length; i++) {
+    var row = rows[i];
+    if (row.prevHash !== prevHash) {
+      return {
+        ok:           false,
+        table:        tableName,
+        rowsVerified: i,
+        breakAt:      i,
+        breakRowId:   row._id,
+        reason:       "prevHash mismatch",
+        expected:     prevHash,
+        actual:       row.prevHash,
+      };
+    }
+    var fields = Object.assign({}, row);
+    delete fields.prevHash;
+    delete fields.rowHash;
+    delete fields.nonce;
+    // fencingToken is cluster-coordination bookkeeping — orthogonal to
+    // tamper-evidence. Excluded from chain hash inputs so deployments
+    // upgrading from a pre-cluster schema (no fencingToken column) verify
+    // identically before and after the ALTER TABLE.
+    delete fields.fencingToken;
+    var nonceBuf = Buffer.isBuffer(row.nonce) ? row.nonce : Buffer.from(row.nonce);
+    var computed = computeRowHash(prevHash, fields, nonceBuf);
+    if (computed !== row.rowHash) {
+      return {
+        ok:           false,
+        table:        tableName,
+        rowsVerified: i,
+        breakAt:      i,
+        breakRowId:   row._id,
+        reason:       "rowHash mismatch",
+        expected:     computed,
+        actual:       row.rowHash,
+      };
+    }
+    prevHash = row.rowHash;
+
+    if (opts.maxRows && i >= opts.maxRows - 1) break;
+  }
+  return { ok: true, table: tableName, rowsVerified: rows.length, lastHash: prevHash };
+}
+
+module.exports = {
+  ZERO_HASH:      ZERO_HASH,
+  canonicalize:   canonicalize,
+  computeRowHash: computeRowHash,
+  getChainTip:    getChainTip,
+  verifyChain:    verifyChain,
+};