@blamejs/core 0.14.26 → 0.15.0

package/lib/api-key.js

@@ -43,6 +43,7 @@ var cluster = require("./cluster");
 var cryptoField = require("./crypto-field");
 var requestHelpers = require("./request-helpers");
 var validateOpts = require("./validate-opts");
+var sql = require("./sql");
 var C = require("./constants");
 var numericChecks = require("./numeric-checks");
 var { ApiKeyError } = require("./framework-error");
@@ -53,16 +54,28 @@ function _emitEvent(n, v, l) { observability().safeEvent(n, v, l || {}); }
 
 var _err = ApiKeyError.factory;
 
-var TABLE   = "_blamejs_api_keys";
-// Pre-quoted form for SQL interpolation. Defense-in-depth: even though
-// our constant is bare-identifier-shaped, every interpolation site uses
-// the wrapped form so a future rename to a reserved-word or
-// whitespace-bearing name would still resolve correctly.
-var Q_TABLE = '"' + TABLE + '"';
-
-// Column order used for INSERT — kept as a constant so the placeholders
-// list and the values list stay in sync. Must match _blamejs_api_keys'
-// schema in db.js (single-node) and framework-schema.js (cluster mode).
+// Logical framework table name. Self-mapped in LOCAL_TO_EXTERNAL, so it is
+// passed BARE to b.sql: clusterStorage.execute rewrites it to the configured
+// prefix and placeholderizes the `?` markers, so one query text runs against
+// the local SQLite single-node backend and the operator's external DB in
+// cluster mode.
+var TABLE   = "_blamejs_api_keys";   // allow:hand-rolled-sql — bare logical name, passed to b.sql for clusterStorage rewrite
+
+// b.sql opts for every _blamejs_api_keys statement: thread the ACTIVE backend
+// dialect (clusterStorage.dialect() — "sqlite" single-node, "postgres" |
+// "mysql" in cluster mode) so the emitted identifier quoting + dialect idioms
+// match the backend the SQL dispatches to. Defaulting to "sqlite" works on
+// Postgres only by accident (both double-quote identifiers) and emits the
+// wrong quoting on MySQL, so this is the canonical resolver threaded into
+// b.sql. clusterStorage.execute still rewrites the bare table name +
+// translates `?` placeholders at dispatch; this controls only the builder-
+// side quoting + idiom selection. The table name stays BARE (no quoteName)
+// so clusterStorage's prefix rewrite still fires.
+function _sqlOpts() { return { dialect: clusterStorage.dialect() }; }
+
+// Column order used for INSERT — kept as a constant so the column list and
+// the row object stay in sync. Must match _blamejs_api_keys' schema in
+// db.js (single-node) and framework-schema.js (cluster mode).
 var COLS = [
   "id", "namespace", "ownerId", "ownerIdHash", "secretHash",
   "secondarySecretHash", "secondaryExpiresAt",
@@ -305,10 +318,11 @@ function create(opts) {
     );
   }
 
-  function _selectAll() {
-    return "SELECT id, namespace, ownerId, ownerIdHash, secretHash, " +
-           "secondarySecretHash, secondaryExpiresAt, " +
-           "scopes, metadata, createdAt, expiresAt, revokedAt, lastUsedAt, prefix FROM " + Q_TABLE;
+  // Fresh SELECT builder over the full column set. BARE logical table name
+  // (_blamejs_api_keys) — clusterStorage rewrites it to the configured
+  // prefix and placeholderizes. Callers chain the WHERE family + .toSql().
+  function _selectBuilder() {
+    return sql.select(TABLE, _sqlOpts()).columns(COLS);   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
   }
 
   function _scrubRecord(row) {
@@ -369,14 +383,13 @@ function create(opts) {
       lastUsedAt:          null,
       prefix:              prefix,
     });
-    var values = COLS.map(function (c) { return sealed[c]; });
-    var placeholders = COLS.map(function () { return "?"; }).join(", ");
-    var quoted = COLS.map(function (c) { return '"' + c + '"'; }).join(", ");
-
-    await clusterStorage.execute(
-      "INSERT INTO " + Q_TABLE + " (" + quoted + ") VALUES (" + placeholders + ")",
-      values
-    );
+    var insertRow = {};
+    for (var ci = 0; ci < COLS.length; ci++) insertRow[COLS[ci]] = sealed[COLS[ci]];
+    var insertBuilt = sql.insert(TABLE, _sqlOpts())   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+      .columns(COLS)
+      .values(insertRow)
+      .toSql();
+    await clusterStorage.execute(insertBuilt.sql, insertBuilt.params);
 
     _emit("apikey.issue", {
       actor:    _actor(issueOpts, issueOpts.ownerId),
@@ -402,10 +415,8 @@ function create(opts) {
     if (parsed.prefix !== prefix || parsed.namespace !== namespace) return null;
 
     var compositeId = _composedId(namespace, parsed.idHex);
-    var row = await clusterStorage.executeOne(
-      _selectAll() + " WHERE id = ?",
-      [compositeId]
-    );
+    var verifyBuilt = _selectBuilder().where("id", compositeId).toSql();
+    var row = await clusterStorage.executeOne(verifyBuilt.sql, verifyBuilt.params);
     if (!row) {
       if (auditFailures) {
         _emit("apikey.verify", {
@@ -474,10 +485,11 @@ function create(opts) {
 
     if (trackLastUsedAt && cluster.isLeader()) {
       try {
-        await clusterStorage.execute(
-          "UPDATE " + Q_TABLE + " SET lastUsedAt = ? WHERE id = ?",
-          [nowMs, compositeId]
-        );
+        var touchBuilt = sql.update(TABLE, _sqlOpts())   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+          .set({ lastUsedAt: nowMs })
+          .where("id", compositeId)
+          .toSql();
+        await clusterStorage.execute(touchBuilt.sql, touchBuilt.params);
       } catch (_e) { /* best-effort; verify success not blocked by lastUsed update */ }
     }
 
@@ -501,10 +513,12 @@ function create(opts) {
     if (typeof idHex !== "string" || idHex.length === 0) return false;
     var compositeId = _composedId(namespace, idHex);
     var nowMs = clock();
-    var result = await clusterStorage.execute(
-      "UPDATE " + Q_TABLE + " SET revokedAt = ? WHERE id = ? AND revokedAt IS NULL",
-      [nowMs, compositeId]
-    );
+    var revokeBuilt = sql.update(TABLE, _sqlOpts())   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+      .set({ revokedAt: nowMs })
+      .where("id", compositeId)
+      .whereNull("revokedAt")
+      .toSql();
+    var result = await clusterStorage.execute(revokeBuilt.sql, revokeBuilt.params);
     var changed = (result.rowCount || 0) > 0;
     if (changed) {
       _emit("apikey.revoke", {
@@ -542,10 +556,8 @@ function create(opts) {
     }
 
     var compositeId = _composedId(namespace, idHex);
-    var existing = await clusterStorage.executeOne(
-      _selectAll() + " WHERE id = ?",
-      [compositeId]
-    );
+    var rotateSelBuilt = _selectBuilder().where("id", compositeId).toSql();
+    var existing = await clusterStorage.executeOne(rotateSelBuilt.sql, rotateSelBuilt.params);
     if (!existing) {
       throw _err("NOT_FOUND", "apiKey.rotate: id '" + idHex + "' not found in namespace '" + namespace + "'");
     }
@@ -558,19 +570,27 @@ function create(opts) {
 
     if (gracePeriodMs > 0) {
       // Move current hash → secondary slot, install new hash as primary.
-      await clusterStorage.execute(
-        "UPDATE " + Q_TABLE + " SET secretHash = ?, " +
-        "secondarySecretHash = ?, secondaryExpiresAt = ? WHERE id = ?",
-        [newHash, existing.secretHash, nowMs + gracePeriodMs, compositeId]
-      );
+      var graceBuilt = sql.update(TABLE, _sqlOpts())   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+        .set({
+          secretHash:          newHash,
+          secondarySecretHash: existing.secretHash,
+          secondaryExpiresAt:  nowMs + gracePeriodMs,
+        })
+        .where("id", compositeId)
+        .toSql();
+      await clusterStorage.execute(graceBuilt.sql, graceBuilt.params);
     } else {
       // Hard cutover — old secret stops working immediately. Clears
-      // any prior secondary slot too.
-      await clusterStorage.execute(
-        "UPDATE " + Q_TABLE + " SET secretHash = ?, " +
-        "secondarySecretHash = NULL, secondaryExpiresAt = NULL WHERE id = ?",
-        [newHash, compositeId]
-      );
+      // any prior secondary slot too (bound NULL via the set map).
+      var cutoverBuilt = sql.update(TABLE, _sqlOpts())   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+        .set({
+          secretHash:          newHash,
+          secondarySecretHash: null,
+          secondaryExpiresAt:  null,
+        })
+        .where("id", compositeId)
+        .toSql();
+      await clusterStorage.execute(cutoverBuilt.sql, cutoverBuilt.params);
     }
 
     _emit("apikey.rotate", {
@@ -598,17 +618,23 @@ function create(opts) {
     var lookup = cryptoField.lookupHash(TABLE, "ownerId", ownerId);
     if (!lookup) {
       throw _err("MISCONFIGURED",
-        "_blamejs_api_keys schema is missing the ownerIdHash derived hash — framework misconfigured");
+        TABLE + " schema is missing the ownerIdHash derived hash — framework misconfigured");
     }
-    var sql = _selectAll() + " WHERE namespace = ? AND ownerIdHash = ?";
-    var params = [namespace, lookup.value];
-    if (!includeRevoked) sql += " AND revokedAt IS NULL";
+    var listQb = _selectBuilder()
+      .where("namespace", namespace)
+      .where("ownerIdHash", lookup.value);
+    if (!includeRevoked) listQb.whereNull("revokedAt");
     if (!includeExpired) {
-      sql += " AND (expiresAt IS NULL OR expiresAt >= ?)";
-      params.push(clock());
+      var nowForExpiry = clock();
+      // (expiresAt IS NULL OR expiresAt >= now) — an OR group ANDed onto
+      // the chain so the optional clause keeps its own precedence.
+      listQb.whereGroup(function (g) {
+        g.whereNull("expiresAt").orWhereOp("expiresAt", ">=", nowForExpiry);
+      });
     }
-    sql += " ORDER BY createdAt DESC";
-    var rows = await clusterStorage.execute(sql, params);
+    listQb.orderBy("createdAt", "desc");
+    var listBuilt = listQb.toSql();
+    var rows = await clusterStorage.execute(listBuilt.sql, listBuilt.params);
     var list = (rows.rows || []).map(_scrubRecord);
     _emitEvent("apikey.list", 1, { namespace: namespace, count: list.length });
     // Read-access audit: "who listed whose keys at time T" — gated by
@@ -635,10 +661,8 @@ function create(opts) {
   async function getById(idHex, getOpts) {
     if (typeof idHex !== "string" || idHex.length === 0) return null;
     var compositeId = _composedId(namespace, idHex);
-    var row = await clusterStorage.executeOne(
-      _selectAll() + " WHERE id = ?",
-      [compositeId]
-    );
+    var getBuilt = _selectBuilder().where("id", compositeId).toSql();
+    var row = await clusterStorage.executeOne(getBuilt.sql, getBuilt.params);
     var record = _scrubRecord(row);
     _emitEvent("apikey.get", 1,
       { namespace: namespace, found: record !== null });
@@ -659,13 +683,24 @@ function create(opts) {
     // Compliance auditors expect "key X was purged at time T" — a count-
     // only audit is too coarse for forensic reconstruction. Cost is one
     // extra round-trip per purge call which runs on a schedule (not
-    // request-rate), so the cost is irrelevant.
-    var idRows = await clusterStorage.execute(
-      "SELECT id FROM " + Q_TABLE + " WHERE namespace = ? AND " +
-      "((revokedAt IS NOT NULL AND revokedAt < ?) OR " +
-      " (expiresAt IS NOT NULL AND expiresAt < ?))",
-      [namespace, threshold, threshold]
-    );
+    // request-rate), so the cost is irrelevant. The purge predicate
+    // (namespace match + an OR of the two "past-threshold" age groups) is
+    // applied identically to the SELECT and the DELETE via _applyPurgeWhere.
+    function _applyPurgeWhere(qb) {
+      return qb
+        .where("namespace", namespace)
+        .whereGroup(function (g) {
+          g.whereGroup(function (a) {
+            a.whereNotNull("revokedAt").where("revokedAt", "<", threshold);
+          }).orWhereGroup(function (b2) {
+            b2.whereNotNull("expiresAt").where("expiresAt", "<", threshold);
+          });
+        });
+    }
+    var purgeSelBuilt = _applyPurgeWhere(
+      sql.select(TABLE, _sqlOpts()).columns(["id"])   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+    ).toSql();
+    var idRows = await clusterStorage.execute(purgeSelBuilt.sql, purgeSelBuilt.params);
     var purgedCompositeIds = (idRows.rows || []).map(function (r) { return r.id; });
 
     if (purgedCompositeIds.length === 0) {
@@ -673,12 +708,10 @@ function create(opts) {
       return 0;
     }
 
-    var result = await clusterStorage.execute(
-      "DELETE FROM " + Q_TABLE + " WHERE namespace = ? AND " +
-      "((revokedAt IS NOT NULL AND revokedAt < ?) OR " +
-      " (expiresAt IS NOT NULL AND expiresAt < ?))",
-      [namespace, threshold, threshold]
-    );
+    var purgeDelBuilt = _applyPurgeWhere(
+      sql.delete(TABLE, _sqlOpts())   // allow:hand-rolled-sql — bare logical name for clusterStorage rewrite
+    ).toSql();
+    var result = await clusterStorage.execute(purgeDelBuilt.sql, purgeDelBuilt.params);
     var count = result.rowCount || purgedCompositeIds.length;
 
     _emit("apikey.purge", {

package/lib/atomic-file.js

@@ -167,6 +167,30 @@ function fsyncDir(dirPath) {
 function _fsync(fd) { return fsync(fd); }
 function _fsyncDir(dirPath) { return fsyncDir(dirPath); }
 
+// Exclusive, no-follow create of the sibling temp file that every
+// atomic write stages bytes into before the rename. CWE-377
+// (insecure temporary file) / CWE-59 (symlink-following): the legacy
+// "w" flag is O_WRONLY|O_CREAT|O_TRUNC — it happily opens (and
+// truncates, or writes through) a file an attacker pre-created at the
+// temp path, including a symlink pointing at a victim file the process
+// can write but the attacker can't. O_EXCL makes the open fail with
+// EEXIST if anything already exists at tmpPath, so a planted file /
+// symlink / FIFO is refused instead of followed; O_NOFOLLOW rejects a
+// symlink in the final path component on platforms that define it
+// (Windows leaves it undefined, hence the `|| 0`). The temp name
+// already carries a CSPRNG token (generateToken), so EEXIST is a
+// hostile-collision signal, not a benign retry. The fd is returned for
+// the caller to write + fsync; mode is applied at create time so the
+// bytes are never world-readable even briefly.
+function _openExclTemp(tmpPath, fileMode) {
+  return nodeFs.openSync(
+    tmpPath,
+    nodeFs.constants.O_WRONLY | nodeFs.constants.O_CREAT |
+      nodeFs.constants.O_EXCL | (nodeFs.constants.O_NOFOLLOW || 0),
+    fileMode
+  );
+}
+
 /**
  * @primitive b.atomicFile.ensureDir
  * @signature b.atomicFile.ensureDir(dirPath, mode)
@@ -392,6 +416,34 @@ function conflictPath(originalPath, opts) {
  *   );
  *   // → { bytesWritten: 7, hash: "<sha3-512 hex>" }
  */
+// Synchronous bounded sleep (writeSync is a sync primitive, so no await).
+// Uses Atomics.wait on a throwaway shared buffer; falls back to a short spin
+// if SharedArrayBuffer is unavailable.
+function _sleepSync(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); return; }
+  catch (_e) { /* fall through to spin */ }
+  var end = Date.now() + ms;
+  while (Date.now() < end) { /* spin */ }
+}
+
+// Atomic rename with a bounded retry on Windows-transient lock errors. On
+// Windows a rename target is briefly held by AV / the search indexer / a
+// file-sync client (Dropbox, OneDrive), surfacing as EPERM / EACCES / EBUSY
+// even though the freshly-written temp file is fine; the lock clears in a few
+// ms. POSIX rename is atomic and never hits this, so the first attempt
+// succeeds there. Surface the error if it is not transient or persists.
+function _renameWithRetry(from, to) {
+  var delays = [0, 5, 15, 40, 100];
+  for (var i = 0; i < delays.length; i += 1) {
+    if (delays[i] > 0) _sleepSync(delays[i]);
+    try { nodeFs.renameSync(from, to); return; }
+    catch (e) {
+      var transient = e && (e.code === "EPERM" || e.code === "EACCES" || e.code === "EBUSY");
+      if (!transient || i === delays.length - 1) throw e;
+    }
+  }
+}
+
 function writeSync(filepath, data, opts) {
   opts = Object.assign({}, DEFAULTS, opts || {});
   var buf = safeBuffer.toBuffer(data, {
@@ -406,7 +458,7 @@ function writeSync(filepath, data, opts) {
   var tmpPath = filepath + ".tmp-" + generateToken(C.BYTES.bytes(8));
   var renamed = false;
   try {
-    var fd = nodeFs.openSync(tmpPath, "w", opts.fileMode);
+    var fd = _openExclTemp(tmpPath, opts.fileMode);
     try {
       var pos = 0;
       while (pos < buf.length) {
@@ -416,7 +468,7 @@ function writeSync(filepath, data, opts) {
     } finally {
       try { nodeFs.closeSync(fd); } catch (_e) { /* already closed? */ }
     }
-    nodeFs.renameSync(tmpPath, filepath);
+    _renameWithRetry(tmpPath, filepath);
     renamed = true;
     _fsyncDir(dir);
   } finally {
@@ -530,7 +582,7 @@ async function write(filepath, data, opts) {
       var tmpPath = filepath + ".tmp-" + generateToken(C.BYTES.bytes(8));
       var renamed = false;
       try {
-        var fd = nodeFs.openSync(tmpPath, "w", opts.fileMode);
+        var fd = _openExclTemp(tmpPath, opts.fileMode);
         try {
           var pos = 0;
           while (pos < buf.length) {
@@ -659,9 +711,15 @@ function _readSyncCore(filepath, opts) {
   // can't swap the file between size-check and read because the fd
   // is anchored to the original inode. ENOENT surfaces from open()
   // rather than the previous existsSync() pre-check.
+  //
+  // The third argument pins an owner-only mode (0o600). The flag is
+  // read-only ("r" → O_RDONLY, no O_CREAT) so the mode is inert on
+  // disk, but specifying it keeps this open out of the insecure-temp-
+  // file class (CWE-377): the read can never create a world/group-
+  // accessible file even when `filepath` is rooted under a temp dir.
   var fd;
   try {
-    fd = nodeFs.openSync(filepath, "r");
+    fd = nodeFs.openSync(filepath, "r", 0o600);
   } catch (openErr) {
     if (openErr && openErr.code === "ENOENT") {
       var e = new AtomicFileError("file not found: " + filepath, "atomic-file/not-found");

package/lib/audit-chain.js

@@ -35,8 +35,23 @@
  */
 var canonicalJson = require("./canonical-json");
 var C = require("./constants");
+var clusterStorage = require("./cluster-storage");
+var frameworkSchema = require("./framework-schema");
+var sql = require("./sql");
 var { sha3Hash } = require("./crypto");
 
+// b.sql opts for the chain read SQL these primitives compose. The reader
+// (queryAllAsync / queryOneAsync, normally clusterStorage.execute*) rewrites
+// the bare framework table name + translates `?` placeholders at dispatch,
+// but the IDENTIFIER QUOTING + ORDER-BY column reference are baked into the
+// b.sql output at build time — so they must carry the ACTIVE backend dialect
+// (clusterStorage.dialect() — "sqlite" single-node, "postgres" | "mysql" in
+// cluster mode). Defaulting to "sqlite" double-quotes `monotonicCounter`,
+// which MySQL reads as a STRING LITERAL: `ORDER BY '<constant>'` imposes no
+// ordering, so verifyChain walks the rows out of order and falsely reports a
+// chain break. Backtick-quoting on MySQL makes it an identifier again.
+function _sqlOpts() { return { dialect: clusterStorage.dialect() }; }
+
 // SHA3-512 outputs 64 bytes; routed through C.BYTES so the file's byte
 // arithmetic has one source of truth. Hex-encoded width is twice the
 // byte count.
@@ -140,11 +155,20 @@ function computeRowHash(prevHash, rowFields, nonce) {
  *   // → { prevHash: "<128-char hex>", counter: 4217 }
  */
 async function getChainTip(queryOneAsync, tableName) {
-  var row = await queryOneAsync(
-    'SELECT rowHash, monotonicCounter FROM "' + tableName + '" ' +
-    "ORDER BY monotonicCounter DESC LIMIT 1"
-  );
+  // Emit a BARE logical table name — the operator-supplied reader routes
+  // through clusterStorage, which rewrites bare framework names to the
+  // configured-prefix form and placeholderizes. b.sql quotes the camelCase
+  // columns + runs the output validator.
+  var built = sql.select(tableName, _sqlOpts())
+    .columns(["rowHash", "monotonicCounter"])
+    .orderBy("monotonicCounter", "desc")
+    .limit(1)
+    .toSql();
+  var row = await queryOneAsync(built.sql, built.params);
   if (!row) return { prevHash: ZERO_HASH, counter: 0 };
+  // Normalize driver shape (Postgres returns BIGINT monotonicCounter as a
+  // string) so callers get a numeric counter on every backend.
+  frameworkSchema.coerceRow(row);
   return { prevHash: row.rowHash, counter: row.monotonicCounter };
 }
 
@@ -186,10 +210,15 @@ async function verifyChain(queryAllAsync, tableName, opts) {
   if (tableName === "audit_log") {
     var anchor;
     try {
-      anchor = await queryAllAsync(
-        "SELECT lastPurgedCounter, lastPurgedRowHash FROM _blamejs_audit_purge_anchor " +
-        "WHERE scope = 'audit'"
-      );
+      // External-only table whose LOGICAL name IS the `_blamejs_`-prefixed
+      // name (self-mapped in LOCAL_TO_EXTERNAL), passed bare so the reader's
+      // clusterStorage rewrites it; the 'audit' scope binds as a ? param.
+      // allow:hand-rolled-sql — bare logical key.
+      var anchorBuilt = sql.select("_blamejs_audit_purge_anchor", _sqlOpts())   // allow:hand-rolled-sql
+        .columns(["lastPurgedCounter", "lastPurgedRowHash"])
+        .where("scope", "audit")
+        .toSql();
+      anchor = await queryAllAsync(anchorBuilt.sql, anchorBuilt.params);
     } catch (_e) {
       // Anchor table may not exist on a deployment that has never been
       // through a purge. Treat as no anchor.
@@ -201,9 +230,16 @@ async function verifyChain(queryAllAsync, tableName, opts) {
     }
   }
 
-  var rows = await queryAllAsync(
-    'SELECT * FROM "' + tableName + '" ORDER BY monotonicCounter ASC'
-  );
+  var rowsBuilt = sql.select(tableName, _sqlOpts())
+    .orderBy("monotonicCounter", "asc")
+    .toSql();
+  var rows = await queryAllAsync(rowsBuilt.sql, rowsBuilt.params);
+  // Normalize driver shape before hashing: node-postgres returns BIGINT
+  // columns (recordedAt / monotonicCounter) as strings, which would hash
+  // differently from the numbers the chain-writer signed — the chain only
+  // verified on SQLite without this. coerceRow makes the recompute
+  // type-stable across backends (no-op on already-numeric SQLite rows).
+  rows = frameworkSchema.coerceRows(rows);
   if (skipBeforeCounter > 0) {
     rows = rows.filter(function (r) {
       return Number(r.monotonicCounter) > skipBeforeCounter;

package/lib/audit-sign.js

@@ -63,6 +63,7 @@ var nodePath = require("node:path");
 var nodeCrypto = require("node:crypto");
 var atomicFile = require("./atomic-file");
 var { sha3Hash } = require("./crypto");
+var frameworkFiles = require("./framework-files");
 var { defineClass } = require("./framework-error");
 var { boot } = require("./log");
 var safeBuffer = require("./safe-buffer");
@@ -118,11 +119,73 @@ var log = boot("audit-sign");
 function resolvePaths(dataDir) {
   return {
     dataDir:    dataDir,
-    plaintext:  nodePath.join(dataDir, "audit-sign.key"),
-    sealed:     nodePath.join(dataDir, "audit-sign.key.sealed"),
+    plaintext:  nodePath.join(dataDir, frameworkFiles.fileName("auditSignKey")),
+    sealed:     nodePath.join(dataDir, frameworkFiles.fileName("auditSignKey") + ".sealed"),
+    // Unsealed registry of rotated-out PUBLIC keys (public keys are not
+    // secret). It lets verify-time code (b.audit.verifyCheckpoints) resolve
+    // the public key for a checkpoint signed under a now-rotated key WITHOUT
+    // the old passphrase, so a rotation does not strand historical checkpoints.
+    publicHistory: nodePath.join(dataDir, "audit-sign.pubkeys.json"),
   };
 }
 
+// Append a rotated-out public key to the unsealed public-key history. Public
+// keys carry no secret, so storing them in the clear is safe and is what
+// makes passphrase-free historical verification possible. De-duplicated by
+// fingerprint; best-effort (a write failure must not abort the rotation, the
+// sealed private-key history is the durable archive of record).
+function _appendPublicHistory(entry) {
+  if (!paths || !paths.publicHistory) return;
+  var list = [];
+  try {
+    if (nodeFs.existsSync(paths.publicHistory)) {
+      var parsed = safeJson.parse(atomicFile.readSync(paths.publicHistory));
+      if (Array.isArray(parsed)) list = parsed;
+    }
+  } catch (_e) { list = []; }   // corrupt registry — rebuild from this entry
+  for (var i = 0; i < list.length; i += 1) {
+    if (list[i] && list[i].fingerprint === entry.fingerprint) return;   // already recorded
+  }
+  list.push(entry);
+  try {
+    atomicFile.writeSync(paths.publicHistory, JSON.stringify(list, null, 2), { fileMode: 0o600 });
+  } catch (_e) { /* best-effort */ }
+}
+
+/**
+ * @primitive b.auditSign.getPublicKeyByFingerprint
+ * @signature b.auditSign.getPublicKeyByFingerprint(fingerprint)
+ * @since     0.14.29
+ * @status    stable
+ * @related   b.auditSign.getPublicKey, b.auditSign.verify, b.auditSign.rotateSigningKey
+ *
+ * Resolve the audit-signing public key (SPKI PEM) for a fingerprint: the
+ * live key, or a rotated-out key recorded in the unsealed public-key history
+ * that `rotateSigningKey` maintains. Returns `null` when no key matches. Only
+ * public material is consulted, so no passphrase is needed - this is what
+ * lets `b.audit.verifyCheckpoints` verify a checkpoint signed under a
+ * now-rotated key without stranding history.
+ *
+ * @example
+ *   var pem = b.auditSign.getPublicKeyByFingerprint(checkpoint.publicKeyFingerprint);
+ *   // -> "-----BEGIN PUBLIC KEY-----\n..." (or null if the key is unknown)
+ */
+function getPublicKeyByFingerprint(fp) {
+  _requireInit();
+  if (fp === keys.fingerprint) return keys.publicKey;
+  if (!paths || !paths.publicHistory || !nodeFs.existsSync(paths.publicHistory)) return null;
+  var list;
+  try { list = safeJson.parse(atomicFile.readSync(paths.publicHistory)); }
+  catch (_e) { return null; }
+  if (!Array.isArray(list)) return null;
+  for (var i = 0; i < list.length; i += 1) {
+    if (list[i] && list[i].fingerprint === fp && typeof list[i].publicKey === "string") {
+      return list[i].publicKey;
+    }
+  }
+  return null;
+}
+
 function _computeFingerprint(publicKeyPem) {
   return sha3Hash(publicKeyPem);
 }
@@ -677,6 +740,17 @@ async function rotateSigningKey(rotOpts) {
     catch (_e) { /* history copy is best-effort */ }
   }
 
+  // Record the rotated-out PUBLIC key (unsealed) so b.audit.verifyCheckpoints
+  // can verify a checkpoint signed under it after rotation without the old
+  // passphrase. Without this the public key only lives inside the sealed
+  // history archive and verification of pre-rotation checkpoints is stranded.
+  _appendPublicHistory({
+    fingerprint: prevFingerprint,
+    publicKey:   prevPublicKey,
+    algorithm:   prevAlgorithm,
+    rotatedAt:   new Date().toISOString(),
+  });
+
   // Persist the new keypair through the same path as boot — sealed
   // mode re-wraps with the operator's passphrase; plaintext mode
   // writes JSON. We don't accept a passphrase override here; the
@@ -740,6 +814,7 @@ module.exports = {
   reSignAll:                reSignAll,
   getPublicKey:             getPublicKey,
   getPublicKeyFingerprint:  getPublicKeyFingerprint,
+  getPublicKeyByFingerprint: getPublicKeyByFingerprint,
   getMode:                  getMode,
   getAlgorithm:             getAlgorithm,
   DEFAULT_SIGNING_ALG:      DEFAULT_SIGNING_ALG,