@blamejs/core 0.15.12 → 0.15.14

package/lib/audit-chain.js

@@ -38,6 +38,8 @@ var C = require("./constants");
 var clusterStorage = require("./cluster-storage");
 var frameworkSchema = require("./framework-schema");
 var sql = require("./sql");
+var safeSql = require("./safe-sql");
+var safeBuffer = require("./safe-buffer");
 var { sha3Hash } = require("./crypto");
 
 // b.sql opts for the chain read SQL these primitives compose. The reader
@@ -135,7 +137,7 @@ function computeRowHash(prevHash, rowFields, nonce) {
 
 /**
  * @primitive b.auditChain.getChainTip
- * @signature b.auditChain.getChainTip(queryOneAsync, tableName)
+ * @signature b.auditChain.getChainTip(queryOneAsync, tableName, opts?)
  * @since     0.4.0
  * @related   b.auditChain.verifyChain, b.auditChain.computeRowHash
  *
@@ -146,6 +148,14 @@ function computeRowHash(prevHash, rowFields, nonce) {
  * drivers can use any await-able query function of the shape
  * `async (sql, params?) -> row | null`.
  *
+ * Pass `{ chainKey, keyValue }` to scope the tip to one partition of a
+ * multi-chain table (one chain per account / device / tenant) — the tip read
+ * filters `WHERE <chainKey> = ?` with the value bound, never interpolated.
+ *
+ * @opts
+ *   chainKey:  string,   // partition column for a multi-chain table
+ *   keyValue:  any,      // the partition value to scope the tip to (bound)
+ *
  * @example
  *   async function queryOne(sql) {
  *     var rows = await myDriver.query(sql);
@@ -154,16 +164,22 @@ function computeRowHash(prevHash, rowFields, nonce) {
  *   var tip = await b.auditChain.getChainTip(queryOne, "audit_log");
  *   // → { prevHash: "<128-char hex>", counter: 4217 }
  */
-async function getChainTip(queryOneAsync, tableName) {
+async function getChainTip(queryOneAsync, tableName, opts) {
+  opts = opts || {};
   // 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 + runs the output validator. A chainKey scopes the tip to one
+  // partition; the key value binds as a ? placeholder.
+  var q = sql.select(tableName, _sqlOpts())
     .columns(["rowHash", "monotonicCounter"])
     .orderBy("monotonicCounter", "desc")
-    .limit(1)
-    .toSql();
+    .limit(1);
+  if (opts.chainKey) {
+    safeSql.validateIdentifier(opts.chainKey);
+    q = q.where(opts.chainKey, opts.keyValue);
+  }
+  var built = q.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
@@ -192,60 +208,32 @@ async function getChainTip(queryOneAsync, tableName) {
  * after a successful archive and lets the chain math survive deletion
  * of historical rows without the archive bundle as source of truth.
  *
+ * Pass `{ chainKey }` to verify a MULTI-chain table partitioned by a key
+ * column (one chain per account / device / tenant): each key's sub-chain is
+ * walked independently from `ZERO_HASH`, and the first break in any key returns
+ * `{ ok:false, chainKey, breakAt, ... }`. Under `chainKey`, `maxRows` is
+ * per-sub-chain and `maxChains` bounds the partition fan-out, failing closed
+ * when exceeded. The `audit_log` purge-anchor logic is single-chain-only and
+ * is skipped when a `chainKey` is given.
+ *
  * @opts
- *   {
- *     maxRows?: number,   // stop after N rows (default: walk every row)
- *   }
+ *   maxRows:   number,   // stop after N rows per (sub-)chain (default: walk every row)
+ *   chainKey:  string,   // partition column — verify each sub-chain independently
+ *   maxChains: number,   // max partitions to verify under chainKey (default 100000; fails closed)
+ *   from:      number,   // single-chain only: verify rows with monotonicCounter >= from, anchored at the predecessor's rowHash (incremental verify after a known-good checkpoint)
+ *   to:        number,   // single-chain only: verify rows with monotonicCounter <= to
  *
  * @example
  *   async function queryAll(sql) { return await myDriver.query(sql); }
  *   var result = await b.auditChain.verifyChain(queryAll, "audit_log", {});
  *   // → { ok: true, table: "audit_log", rowsVerified: 4217, lastHash: "<hex>" }
  */
-async function verifyChain(queryAllAsync, tableName, opts) {
-  opts = opts || {};
-
-  var prevHash = ZERO_HASH;
-  var skipBeforeCounter = 0;
-  if (tableName === "audit_log") {
-    var anchor;
-    try {
-      // 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.
-      anchor = [];
-    }
-    if (Array.isArray(anchor) && anchor.length > 0) {
-      prevHash = anchor[0].lastPurgedRowHash;
-      skipBeforeCounter = Number(anchor[0].lastPurgedCounter);
-    }
-  }
-
-  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;
-    });
-  }
-
+// Walk one (sub-)chain forward from startPrevHash, recomputing each row's
+// hash. Returns the same { ok, table, rowsVerified, lastHash | breakAt... }
+// shape verifyChain documents. Shared by the single-chain path and each
+// per-key partition.
+function _walkRows(rows, tableName, startPrevHash, opts) {
+  var prevHash = startPrevHash;
   if (rows.length === 0) {
     return { ok: true, table: tableName, rowsVerified: 0, lastHash: prevHash };
   }
@@ -290,7 +278,148 @@ async function verifyChain(queryAllAsync, tableName, opts) {
 
     if (opts.maxRows && i >= opts.maxRows - 1) break;
   }
-  return { ok: true, table: tableName, rowsVerified: rows.length, lastHash: prevHash };
+  // Report the count ACTUALLY walked, not rows.length — under maxRows the walk
+  // stops early, so rows.length would over-report coverage (a caller reading
+  // rowsVerified to judge how much of the chain was checked must see the real
+  // number, not be told the whole table verified when only maxRows did).
+  var verifiedCount = opts.maxRows ? Math.min(rows.length, opts.maxRows) : rows.length;
+  return { ok: true, table: tableName, rowsVerified: verifiedCount, lastHash: prevHash };
+}
+
+async function verifyChain(queryAllAsync, tableName, opts) {
+  opts = opts || {};
+
+  // Multi-chain table: verify each partition independently. Each key's
+  // sub-chain anchors at ZERO_HASH and is walked in monotonic-counter order;
+  // the first break in ANY key returns { ok:false, chainKey, ... }. maxRows is
+  // per-sub-chain; maxChains bounds the partition fan-out (fails closed when
+  // exceeded). The audit_log purge-anchor logic is single-chain-only, so it is
+  // skipped under a chainKey.
+  if (opts.chainKey) {
+    safeSql.validateIdentifier(opts.chainKey);
+    var keysBuilt = sql.select(tableName, _sqlOpts())
+      .distinct()
+      .columns([opts.chainKey])
+      .orderBy(opts.chainKey, "asc")
+      .toSql();
+    // coerce so a Postgres INTEGER/BIGINT chainKey is type-stable in the
+    // reported break-shape and the per-key WHERE bind, matching SQLite.
+    var keyRows = frameworkSchema.coerceRows(await queryAllAsync(keysBuilt.sql, keysBuilt.params));
+    var maxChains = (typeof opts.maxChains === "number" && opts.maxChains > 0) ? opts.maxChains : 100000;   // allow:numeric-opt-Infinity — partition fan-out cap; non-number / <=0 falls back to the default
+    if (keyRows.length > maxChains) {
+      return {
+        ok:           false,
+        table:        tableName,
+        rowsVerified: 0,
+        reason:       "too many chains: " + keyRows.length + " partitions exceeds maxChains " + maxChains,
+      };
+    }
+    var totalVerified = 0;
+    var lastHashByKey = {};
+    for (var ki = 0; ki < keyRows.length; ki++) {
+      var keyValue = keyRows[ki][opts.chainKey];
+      var rowsBuiltK = sql.select(tableName, _sqlOpts())
+        .where(opts.chainKey, keyValue)
+        .orderBy("monotonicCounter", "asc")
+        .toSql();
+      var rowsK = frameworkSchema.coerceRows(await queryAllAsync(rowsBuiltK.sql, rowsBuiltK.params));
+      var resK = _walkRows(rowsK, tableName, ZERO_HASH, opts);
+      if (!resK.ok) { resK.chainKey = keyValue; return resK; }
+      totalVerified += resK.rowsVerified;
+      lastHashByKey[String(keyValue)] = resK.lastHash;
+    }
+    return {
+      ok:           true,
+      table:        tableName,
+      rowsVerified: totalVerified,
+      chains:       keyRows.length,
+      lastHashByKey: lastHashByKey,
+    };
+  }
+
+  var prevHash = ZERO_HASH;
+  var skipBeforeCounter = 0;
+  if (tableName === "audit_log") {
+    var anchor;
+    try {
+      // 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.
+      anchor = [];
+    }
+    if (Array.isArray(anchor) && anchor.length > 0) {
+      var aHash = anchor[0].lastPurgedRowHash;
+      var aCounter = Number(anchor[0].lastPurgedCounter);
+      // A corrupted / tampered purge anchor (non-hex lastPurgedRowHash or a
+      // non-numeric lastPurgedCounter) must fail CLOSED with a clear reason.
+      // Passing a garbage prevHash into _walkRows → computeRowHash would THROW
+      // ("prevHash must be a 128-char hex"), turning a defensive verify into an
+      // uncaught exception; a NaN counter would skip nothing and surface as an
+      // opaque chain-break. Detect it here and return { ok:false }.
+      if (!safeBuffer.isHex(aHash, SHA3_512_HEX_LEN) || !isFinite(aCounter) || aCounter < 0) {
+        return { ok: false, table: tableName, rowsVerified: 0, reason: "corrupted purge anchor" };
+      }
+      prevHash = aHash;
+      skipBeforeCounter = aCounter;
+    }
+  }
+
+  // Incremental verify (b.audit.verify { from, to }): verify only rows whose
+  // monotonicCounter is in [from, to]. `from` must anchor on the rowHash of the
+  // row immediately BEFORE it, so the scoped walk chains correctly — otherwise
+  // the first in-range row's prevHash (= the predecessor's rowHash) wouldn't
+  // match ZERO_HASH and a good chain would falsely report a break.
+  var fromCounter = (opts.from != null && isFinite(Number(opts.from))) ? Number(opts.from) : null;
+  var toCounter   = (opts.to != null && isFinite(Number(opts.to)))   ? Number(opts.to)   : null;
+
+  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);
+
+  // Resolve the incremental-verify anchor: the highest row strictly below
+  // `from` (derived from the already-read rows, no extra query). Raise
+  // skipBeforeCounter to it and adopt its rowHash as the chain anchor.
+  if (fromCounter != null && fromCounter > skipBeforeCounter + 1) {
+    var pred = null;
+    for (var pi = 0; pi < rows.length; pi++) {
+      var pc = Number(rows[pi].monotonicCounter);
+      if (pc < fromCounter && pc > skipBeforeCounter) pred = rows[pi]; else if (pc >= fromCounter) break;
+    }
+    if (pred) {
+      if (!safeBuffer.isHex(pred.rowHash, SHA3_512_HEX_LEN)) {
+        return { ok: false, table: tableName, rowsVerified: 0, reason: "incremental-verify anchor row has a corrupt rowHash" };
+      }
+      prevHash = pred.rowHash;
+      skipBeforeCounter = Math.max(skipBeforeCounter, Number(pred.monotonicCounter));
+    }
+  }
+
+  if (skipBeforeCounter > 0 || toCounter != null) {
+    rows = rows.filter(function (r) {
+      var c = Number(r.monotonicCounter);
+      if (c <= skipBeforeCounter) return false;
+      if (toCounter != null && c > toCounter) return false;
+      return true;
+    });
+  }
+
+  return _walkRows(rows, tableName, prevHash, opts);
 }
 
 module.exports = {

package/lib/audit-daily-review.js

@@ -83,9 +83,15 @@ function _defaultClassify(event) {
 }
 
 function _severityAtLeast(severity, threshold) {
-  var sIdx = SEVERITY_ORDER.indexOf(severity);
   var tIdx = SEVERITY_ORDER.indexOf(threshold);
-  if (sIdx === -1 || tIdx === -1) return false;
+  if (tIdx === -1) return false;   // unknown threshold (validated at config)
+  var sIdx = SEVERITY_ORDER.indexOf(severity);
+  // An UNKNOWN event severity — e.g. a custom classify(event) returning an
+  // unexpected value — must NOT silently drop the event from the review. Fail
+  // SAFE: treat it as meeting the threshold so the operator still sees the
+  // event (and notices their classify mis-returned) rather than missing a
+  // flagged event.
+  if (sIdx === -1) return true;
   return sIdx >= tIdx;
 }
 
@@ -164,20 +170,30 @@ function create(opts) {
     throw _err("auditDailyReview/audit-query-missing",
       "auditDailyReview.create: opts.audit.query must be a function");
   }
-  validateOpts.optionalFunction(opts.notify,
-    "auditDailyReview: notify", AuditDailyReviewError, "auditDailyReview/bad-notify");
-  validateOpts.optionalFunction(opts.classify,
-    "auditDailyReview: classify", AuditDailyReviewError, "auditDailyReview/bad-classify");
-  validateOpts.optionalFunction(opts.now,
-    "auditDailyReview: now", AuditDailyReviewError, "auditDailyReview/bad-now");
-  validateOpts.optionalNonEmptyString(opts.posture,
-    "auditDailyReview: posture", AuditDailyReviewError, "auditDailyReview/bad-posture");
-  validateOpts.optionalNonEmptyString(opts.cron,
-    "auditDailyReview: cron", AuditDailyReviewError, "auditDailyReview/bad-cron");
-  validateOpts.optionalPositiveInt(opts.queryLimit,
-    "auditDailyReview: queryLimit", AuditDailyReviewError, "auditDailyReview/bad-querylimit");
-  validateOpts.optionalPositiveInt(opts.historyLimit,
-    "auditDailyReview: historyLimit", AuditDailyReviewError, "auditDailyReview/bad-historylimit");
+  validateOpts.shape(opts, {
+    audit:        { methods: ["query", "safeEmit"] },
+    notify:       { rule: "optional-function",     code: "auditDailyReview/bad-notify" },
+    classify:     { rule: "optional-function",     code: "auditDailyReview/bad-classify" },
+    now:          { rule: "optional-function",     code: "auditDailyReview/bad-now" },
+    posture:      { rule: "optional-string",       code: "auditDailyReview/bad-posture" },
+    cron:         { rule: "optional-string",       code: "auditDailyReview/bad-cron" },
+    severityThreshold: { rule: "optional-string",  code: "auditDailyReview/bad-severity" },
+    queryLimit:   { rule: "optional-positive-int", code: "auditDailyReview/bad-querylimit" },
+    historyLimit: { rule: "optional-positive-int", code: "auditDailyReview/bad-historylimit" },
+    // lookbackHours — positive finite number (hours, not bytes). Bespoke
+    // check preserves the auditDailyReview/bad-lookback code the message
+    // below depends on; a positive-int token would reject fractional hours.
+    lookbackHours: function (value, label) {
+      if (value === undefined || value === null) return;
+      if (typeof value !== "number" || !isFinite(value) || value <= 0) {
+        throw _err("auditDailyReview/bad-lookback",
+          "auditDailyReview.create: lookbackHours must be a positive finite number");
+      }
+    },
+  }, "auditDailyReview", AuditDailyReviewError, "auditDailyReview/bad-opts",
+     // scheduler is forwarded to the b.scheduler instance at start() and not
+     // validated locally at create-time (start() requires it on its own).
+     { allow: ["scheduler"] });
 
   // lookbackHours — default 24 per PCI DSS 4.0 daily cadence. Caller can
   // pass weekly / monthly via larger numbers.
@@ -237,6 +253,10 @@ function create(opts) {
         from:  fromMs,
         to:    startedAt,
         limit: queryLimit,
+        // Newest-first: if the window holds more than queryLimit events, keep
+        // the MOST RECENT (the actionable ones) — an ascending+limit query would
+        // keep the oldest and silently drop the newest from the review.
+        order: "desc",
       });
     } catch (e) {
       _emit("audit.daily_review.failed", {

package/lib/audit-emit.js

@@ -0,0 +1,82 @@
+"use strict";
+
+// audit-emit — the stateless drop-silent audit emitter with a metadata-first,
+// success-default signature `(action, metadata, outcome?)`. Many primitives —
+// the mail servers and DAV bridge, the A2A task store, the compliance posture
+// tracker, the MCP tool registry, the idempotency-key middleware — emit audit
+// events where the per-event detail (metadata) is almost always supplied and
+// the outcome is almost always "this happened", so they pass metadata second
+// and let outcome default to "success". They route through the drop-silent
+// audit.safeEmit so a misbehaving sink never crashes the request. Unlike
+// b.audit.namespaced (gated, action-prefixed, outcome-first), this is ungated
+// and passes the action verbatim — matching what each of them hand-rolled.
+//
+// This module self-lazy-requires audit so a consumer can `require("./audit-emit")`
+// at the top of the file without re-introducing the audit load cycle that the
+// per-file `lazyRequire(() => require("./audit"))` was guarding against.
+
+var lazyRequire = require("./lazy-require");
+var audit = lazyRequire(function () { return require("./audit"); });
+
+// emit(action, metadata, outcome?) — drop-silent audit emit. `outcome` defaults
+// to "success"; `metadata` defaults to `{}`.
+function emit(action, metadata, outcome) {
+  try {
+    audit().safeEmit({
+      action:   action,
+      outcome:  outcome || "success",
+      metadata: metadata || {},
+    });
+  } catch (_e) { /* drop-silent — audit best-effort */ }
+}
+
+// emitToSink(opts, action, outcome, metadata) — drop-silent audit emit to an
+// OPERATOR-SUPPLIED sink threaded through `opts.audit`, the no-op-when-absent
+// variant the archive reader / tar-reader / writer share verbatim: forward the
+// event only when `opts.audit` exposes a `safeEmit`, otherwise stay silent.
+// Distinct from emit() (which targets the framework's GLOBAL audit()) — here the
+// caller carries the sink in opts, so a reader/writer with no audit configured
+// emits nothing. (Callers whose payload carries extra top-level fields — e.g.
+// http-client's `resource` — keep their own wrapper; this is the bare
+// action/outcome/metadata shape.)
+function emitToSink(opts, action, outcome, metadata) {
+  if (!opts || !opts.audit || typeof opts.audit.safeEmit !== "function") return;
+  try {
+    opts.audit.safeEmit({ action: action, outcome: outcome, metadata: metadata });
+  } catch (_e) { /* drop-silent — operator audit sink must never crash the caller */ }
+}
+
+// gatedReasonEmitter({ audit, sink?, extra? }) — build a gated drop-silent
+// emitter `(action, info, outcome)` that records a structured top-level `reason`
+// (hoisted from `info.reason`) alongside the audit metadata. The gated +
+// reason-hoisting sibling of emit() / b.audit.namespaced, for the primitives
+// (backup / restore / scheduler / config-drift / legal-hold) that emit a reason
+// the audit chain surfaces as a first-class field. `audit` is the gate flag
+// (false disables); `sink` is an optional operator-supplied audit target (the
+// no-op-without-safeEmit guard the hand-rolled `auditInstance || audit()`
+// pattern carried); `extra(info)` optionally returns more top-level event
+// fields (e.g. legal-hold's `resource`). Routes through b.audit.namespaced, so
+// the same redaction + drop-silent guarantees apply.
+function gatedReasonEmitter(opts) {
+  opts = opts || {};
+  var ns = audit().namespaced(null, { audit: opts.audit, sink: opts.sink });
+  var extra = typeof opts.extra === "function" ? opts.extra : null;
+  return function (action, info, outcome) {
+    var fields = { reason: (info && info.reason) || null };
+    if (extra) {
+      var more = extra(info);
+      if (more) {
+        for (var k in more) {
+          if (Object.prototype.hasOwnProperty.call(more, k)) fields[k] = more[k];
+        }
+      }
+    }
+    ns(action, outcome, info, fields);
+  };
+}
+
+module.exports = {
+  emit:               emit,
+  emitToSink:         emitToSink,
+  gatedReasonEmitter: gatedReasonEmitter,
+};