@blamejs/core 0.8.42 → 0.8.49

package/lib/dual-control.js

@@ -1,65 +1,34 @@
 "use strict";
 /**
- * dual-control — two-person-rule primitive for destructive operations.
+ * @module b.dualControl
+ * @nav    Identity
+ * @title  Dual Control
  *
- * b.breakGlass already gates a single-actor step-up (TOTP / passkey
- * proof from the SAME actor performing the unseal). dual-control
- * raises the bar to "two distinct named actors must approve before
- * the operation runs" — the standard control for destructive actions
- * in compliance-sensitive domains (HIPAA admin actions, PCI key
- * rotation, financial close, T+1 settlement, etc.).
+ * @intro
+ *   M-of-N approval workflow for destructive operations (eraseHard,
+ *   key rotation, etc.). b.breakGlass gates a single-actor step-up
+ *   (TOTP / passkey proof from the SAME actor performing the
+ *   unseal); dual-control raises the bar to "two distinct named
+ *   actors must approve before the operation runs" — the standard
+ *   control for HIPAA admin actions, PCI key rotation, financial
+ *   close, T+1 settlement, and similar compliance-sensitive flows.
  *
- *   var approvals = b.dualControl.create({
- *     namespace: "wiki.destructive",
- *     audit:     b.audit,
- *     ttlMs:     C.TIME.minutes(15),     // grant expires after this; default 15m
- *     minApprovers: 2,                    // dual = 2; quorum can be larger
- *     forbidSelfApprove: true,            // requester cannot also approve; default true
- *   });
- *
- *   // Step 1: requester opens the request
- *   var req1 = await approvals.request({
- *     action:      "<your-domain>.<verb>",   // e.g. operator picks a stable name
- *     resource:    { kind: "user.bulk", id: "older-than-30d" },
- *     requestedBy: actor1,                // operator-shaped { id, email, ... }
- *     reason:      "GDPR sweep; quarter-close",
- *     req:         req,                   // for actor-context capture
- *   });
- *   // → { grantId, status: "pending", needs: 2, approvedBy: [actor1.id], expiresAt: ... }
- *
- *   // Step 2: a DIFFERENT actor approves
- *   var req2 = await approvals.approve({
- *     grantId:    req1.grantId,
- *     approver:   actor2,
- *     reason:     "verified ticket #4421",
- *     req:        req,
- *   });
- *   // → { grantId, status: "approved", approvedBy: [actor1.id, actor2.id] }
- *
- *   // Step 3: code that performs the destructive op consumes the grant
- *   var grant = await approvals.consume(req1.grantId, { req });
- *   if (!grant.ready) throw new Error("not approved or already consumed");
- *   // ... perform users.purge ...
- *
- * Audit posture:
- *   - Every state transition emits to b.audit:
- *       dual.grant.requested  (status pending)
- *       dual.grant.approved   (each approval; metadata.approverCount)
- *       dual.grant.denied     (operator-callable revoke())
- *       dual.grant.consumed   (the destructive op ran)
- *       dual.grant.expired    (TTL hit before approve+consume)
- *   - Each event carries the grant ID + the actor 5 W's so a compliance
- *     reviewer can reconstruct the chain.
+ *   Every state transition emits an audit row:
+ *   `dual.grant.requested` / `dual.grant.approved` /
+ *   `dual.grant.denied` / `dual.grant.consumed` /
+ *   `dual.grant.expired` / `dual.grant.cancelled`. Each event
+ *   carries the grant ID and the actor 5 W's so a compliance
+ *   reviewer can reconstruct the chain.
  *
- * Storage: the grants live in a b.cache instance the operator passes
- * in (memory backend → per-process; cluster backend → shared across
- * nodes). The cache TTL bounds grant freshness automatically.
+ *   Grants live in a b.cache instance the operator wires in (memory
+ *   backend → per-process; cluster backend → shared across nodes).
+ *   The cache TTL bounds grant freshness automatically. Optional
+ *   cooling-off lock (`consumeLockMs`) defends against rapid-burst
+ *   compromise of requester+approver. Optional `approverRoles`
+ *   restricts approval to actors carrying a named role.
  *
- * Validation:
- *   - create() opts: throw at boot on bad shape
- *   - request() / approve() / consume() / revoke(): throw on missing
- *     required args, return { error } on policy denials (already
- *     consumed, expired, self-approval, etc.)
+ * @card
+ *   M-of-N approval workflow for destructive operations (eraseHard, key rotation, etc.).
  */
 var lazyRequire = require("./lazy-require");
 var crypto = require("./crypto");
@@ -107,6 +76,72 @@ function _actorIdOf(actor) {
   return null;
 }
 
+/**
+ * @primitive b.dualControl.create
+ * @signature b.dualControl.create(opts)
+ * @since     0.8.41
+ * @status    stable
+ * @compliance hipaa, pci-dss, sox-404, dora, soc2
+ * @related   b.breakGlass.policy.set, b.audit, b.cache.create
+ *
+ * Build a dual-control approval workflow bound to a `namespace`.
+ * Returns a handle exposing async `request(args)` (open a pending
+ * grant), `approve(args)` (a different actor approves; quorum
+ * detection is automatic), `cancel(args)` (the requester withdraws),
+ * `revoke(args)` (an admin denies), `consume(grantId, args)` (the
+ * destructive code path single-uses the grant), and `status(grantId)`
+ * for inspection. Every transition audits with the actor 5 W's.
+ * Grant lifecycle is bounded by `ttlMs`; cluster-shared grants need
+ * a cluster-backed cache.
+ *
+ * @opts
+ *   namespace:          string,                          // grant key namespace (required, non-empty)
+ *   cache:              b.cache,                         // b.cache instance — memory or cluster (required)
+ *   audit:              b.audit,                         // optional audit sink (defaults to global b.audit)
+ *   ttlMs:              number,                          // grant lifetime (default 15 minutes)
+ *   minApprovers:       number,                          // approvals required to reach quorum (default 2, ≥2)
+ *   forbidSelfApprove:  boolean,                         // requester cannot approve own grant (default true)
+ *   consumeLockMs:      number,                          // cooling-off ms after final approval (default 0)
+ *   minReasonLength:    number,                          // minimum chars on reason fields (default 0 → off)
+ *   approverRoles:      Array<string>,                   // restrict approve() to actors with one of these roles (default null)
+ *   notify:             function,                        // (event) → void; fired on every transition
+ *
+ * @example
+ *   var approvals = b.dualControl.create({
+ *     namespace:        "users.eraseHard",
+ *     cache:            b.cache.create({ namespace: "dc", backend: "memory" }),
+ *     audit:            b.audit,
+ *     ttlMs:            b.constants.TIME.minutes(15),
+ *     minApprovers:     2,
+ *     consumeLockMs:    b.constants.TIME.minutes(2),
+ *     minReasonLength:  12,
+ *     approverRoles:    ["security:officer", "compliance:officer"],
+ *   });
+ *
+ *   // Step 1: requester opens the grant.
+ *   var opened = await approvals.request({
+ *     action:      "users.eraseHard",
+ *     resource:    { kind: "user", id: "user-42" },
+ *     requestedBy: { id: "alice", roles: ["engineer"] },
+ *     reason:      "GDPR Art. 17 erasure request, ticket SUP-4421",
+ *     req:         req,
+ *   });
+ *   // → { grantId: "dc-<hex>", status: "pending", needs: 2, expiresAt: ... }
+ *
+ *   // Step 2: a different actor approves.
+ *   var approved = await approvals.approve({
+ *     grantId:  opened.grantId,
+ *     approver: { id: "bob", roles: ["security:officer"] },
+ *     reason:   "verified ticket SUP-4421 against subject identity",
+ *     req:      req,
+ *   });
+ *   // → { grantId, status: "approved", approvedBy: ["alice"... wait, no: ["bob"], ... }
+ *
+ *   // Step 3: the destructive code path consumes the grant once.
+ *   var grant = await approvals.consume(opened.grantId, { req: req });
+ *   if (!grant.ready) throw new Error("dual-control: " + grant.reason);
+ *   await b.db.eraseHard("users", { id: "user-42" });
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/events.js

@@ -1,45 +1,36 @@
 "use strict";
 /**
- * events — framework-wide cross-cutting signal bus.
+ * @module b.events
+ * @nav    Other
+ * @title  Events
  *
- * A thin wrapper around Node's EventEmitter, exposed as `b.events`,
- * dedicated to framework-emitted breach-detection and integrity signals.
- * Operators wire listeners to PagerDuty / Opsgenie / a Slack webhook /
- * a notification queue and the framework fires them on the specific
- * high-signal conditions documented in `EVENTS` below.
+ * @intro
+ *   In-process event emitter — namespaced channels, drop-silent on
+ *   unknown listeners, audit on registration. A thin wrapper around
+ *   Node's `EventEmitter` dedicated to framework-emitted breach-
+ *   detection and integrity signals. Operators wire listeners to
+ *   PagerDuty / Opsgenie / a Slack webhook / a notification queue and
+ *   the framework fires them on the specific high-signal conditions
+ *   exported on `EVENTS` (audit chain break, audit checkpoint break,
+ *   audit rollback detected, NTP drift, api-encrypt failure).
  *
- * Why a separate emitter (not Node's built-in EventEmitter directly):
- *   - One bus the framework controls — operators don't have to chase
- *     emit calls across modules to know what's available.
- *   - Best-effort emit semantics: a listener throwing must NOT break
- *     the framework's refuse-to-boot fail-fast. emit() catches and
- *     swallows listener errors.
- *   - Stable event names exported as constants — operators reference
- *     b.events.EVENTS.AUDIT_CHAIN_BREAK rather than typing the string.
- *   - _resetForTest() clears listeners between tests without touching
- *     consumer state.
+ *   Best-effort emit semantics: a listener throwing must NOT break
+ *   the framework's refuse-to-boot fail-fast. `emit()` catches and
+ *   swallows listener errors per-listener so the rest still fire.
+ *   Stable event names live on `b.events.EVENTS` so operators
+ *   reference `b.events.EVENTS.AUDIT_CHAIN_BREAK` rather than typing
+ *   the raw `"audit:chain-break"` string. The default
+ *   10-listener cap is removed — operators routinely wire several
+ *   notify / structured-log / file-flag listeners on the same event.
  *
- * Public API:
- *   b.events.on(name, fn)               register listener
- *   b.events.off(name, fn)              unregister listener
- *   b.events.once(name, fn)             register single-fire listener
- *   b.events.emit(name, payload)        fire (best-effort; listener
- *                                       errors logged + swallowed)
- *   b.events.listenerCount(name)        diagnostic
- *   b.events.EVENTS                     stable name constants
+ *   Listener handlers should keep work synchronous and short. Several
+ *   framework signals lead to `process.exit`, so blocking network
+ *   calls inside a listener would delay the fail-fast path; hand off
+ *   to a queue or write a sync flag-file from the listener and let an
+ *   external watcher do the network call.
  *
- * Example operator wiring (sync — synchronous I/O only inside the handler
- * since process.exit may follow on certain framework signals):
- *
- *   b.events.on(b.events.EVENTS.AUDIT_CHAIN_BREAK, function (info) {
- *     fs.writeFileSync("/var/run/blamejs-chain-break.flag",
- *       JSON.stringify({ at: Date.now(), info: info }));
- *   });
- *
- * For async fan-out (PagerDuty webhook, etc.) the listener should hand
- * off to a queue — synchronous I/O in the listener is safe but blocking
- * network calls would delay the framework's fail-fast path on signals
- * that lead to process.exit.
+ * @card
+ *   In-process event emitter — namespaced channels, drop-silent on unknown listeners, audit on registration.
  */
 
 var nodeEvents = require("node:events");
@@ -78,26 +69,99 @@ var _emitter = new nodeEvents.EventEmitter();
 // sidecar, file flag writer, etc.) and the warning isn't useful here.
 _emitter.setMaxListeners(0);
 
+/**
+ * @primitive b.events.on
+ * @signature b.events.on(name, fn)
+ * @since     0.4.0
+ * @related   b.events.off, b.events.once, b.events.emit
+ *
+ * Register a listener for one of the stable framework event names on
+ * `b.events.EVENTS`. The listener fires every time the framework
+ * emits the named event. Listeners may throw — `emit()` swallows the
+ * throw and logs it so the emit path stays best-effort, but operators
+ * should keep handlers synchronous and short (several framework
+ * signals lead to `process.exit`).
+ *
+ * @example
+ *   b.events.on(b.events.EVENTS.AUDIT_CHAIN_BREAK, function (info) {
+ *     // Sync I/O only — exit may follow.
+ *     require("node:fs").writeFileSync(
+ *       "/var/run/blamejs-chain-break.flag",
+ *       JSON.stringify({ at: Date.now(), info: info })
+ *     );
+ *   });
+ */
 function on(name, fn) {
   _emitter.on(name, fn);
   return _emitter;
 }
 
+/**
+ * @primitive b.events.off
+ * @signature b.events.off(name, fn)
+ * @since     0.4.0
+ * @related   b.events.on, b.events.once
+ *
+ * Remove a previously-registered listener. The function reference
+ * must be the same object passed to `on()` / `once()` — otherwise
+ * Node's emitter silently keeps the listener registered.
+ *
+ * @example
+ *   function onBreak(info) { console.error("audit chain break", info); }
+ *   b.events.on(b.events.EVENTS.AUDIT_CHAIN_BREAK, onBreak);
+ *   // ... later, during teardown:
+ *   b.events.off(b.events.EVENTS.AUDIT_CHAIN_BREAK, onBreak);
+ *   b.events.listenerCount(b.events.EVENTS.AUDIT_CHAIN_BREAK);   // → 0
+ */
 function off(name, fn) {
   _emitter.off(name, fn);
   return _emitter;
 }
 
+/**
+ * @primitive b.events.once
+ * @signature b.events.once(name, fn)
+ * @since     0.4.0
+ * @related   b.events.on, b.events.emit
+ *
+ * Register a single-fire listener — fires once and auto-removes. The
+ * auto-removal is preserved through `b.events.emit` even though emit
+ * iterates raw listeners directly to keep the best-effort contract.
+ *
+ * @example
+ *   b.events.once(b.events.EVENTS.NTP_DRIFT, function (payload) {
+ *     console.warn("NTP drift detected (first occurrence): " + payload.driftMs + "ms");
+ *   });
+ */
 function once(name, fn) {
   _emitter.once(name, fn);
   return _emitter;
 }
 
-// Best-effort emit. A listener throwing must not propagate — framework
-// callers (e.g. db.init's chain-verify FATAL path) emit immediately
-// before process.exit and can't tolerate a listener crashing the exit
-// path. We log+swallow per-listener errors so the rest of the listeners
-// still fire.
+/**
+ * @primitive b.events.emit
+ * @signature b.events.emit(name, payload)
+ * @since     0.4.0
+ * @related   b.events.on, b.events.once
+ *
+ * Best-effort fire — invokes every registered listener for `name`,
+ * passing `payload`. Listener throws are logged and swallowed
+ * per-listener so the rest of the chain still fires; framework
+ * callers (e.g. `db.init`'s chain-verify FATAL path) emit immediately
+ * before `process.exit` and can't tolerate a listener crashing the
+ * exit path. Returns `true` when at least one listener was registered.
+ *
+ * Operator code rarely emits onto `b.events` directly — the bus is
+ * for framework-emitted signals. Calling `emit()` from operator code
+ * is supported for tests that want to exercise listener wiring.
+ *
+ * @example
+ *   var fired = false;
+ *   b.events.on(b.events.EVENTS.AUDIT_CHAIN_BREAK, function () { fired = true; });
+ *   var hadListener = b.events.emit(b.events.EVENTS.AUDIT_CHAIN_BREAK, { at: 1 });
+ *   hadListener;   // → true
+ *   fired;         // → true
+ */
 function emit(name, payload) {
   // rawListeners returns the wrapper functions including the auto-
   // removing wrapper that once() registers. Calling the wrapper triggers
@@ -116,6 +180,21 @@ function emit(name, payload) {
   return listeners.length > 0;
 }
 
+/**
+ * @primitive b.events.listenerCount
+ * @signature b.events.listenerCount(name)
+ * @since     0.4.0
+ * @related   b.events.on, b.events.off
+ *
+ * Diagnostic — returns the number of listeners registered for `name`.
+ * Useful in tests and during teardown to confirm `off()` removed the
+ * intended listener.
+ *
+ * @example
+ *   b.events.on(b.events.EVENTS.NTP_DRIFT, function () {});
+ *   b.events.on(b.events.EVENTS.NTP_DRIFT, function () {});
+ *   b.events.listenerCount(b.events.EVENTS.NTP_DRIFT);   // → 2
+ */
 function listenerCount(name) {
   return _emitter.listenerCount(name);
 }

package/lib/external-db-migrate.js

@@ -50,12 +50,16 @@
  */
 var path = require("path");
 var atomicFile = require("./atomic-file");
+var canonicalJson = require("./canonical-json");
+var { sha3Hash } = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var migrationFiles = require("./migration-files");
 var numericBounds = require("./numeric-bounds");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
+var auditSign = lazyRequire(function () { return require("./audit-sign"); });
+
 var ExternalDbMigrateError = defineClass("ExternalDbMigrateError", { alwaysPermanent: true });
 
 // Lazy require — external-db imports back into this module via its
@@ -64,10 +68,47 @@ var externalDbModule = lazyRequire(function () { return require("./external-db")
 
 var TRACKING_TABLE = "_blamejs_externaldb_migrations";
 var LOCK_TABLE     = "_blamejs_externaldb_migrations_lock";
+var HISTORY_TABLE  = "_blamejs_schema_version_history";
 // Identifiers wrapped in `"..."` per project convention so a reserved-word
 // or whitespace-bearing name resolves correctly.
 var Q_TRACKING = '"' + TRACKING_TABLE + '"';
 var Q_LOCK     = '"' + LOCK_TABLE + '"';
+var Q_HISTORY  = '"' + HISTORY_TABLE + '"';
+
+// Bytes that get signed for one history row. Stable forever — changing
+// it invalidates every prior signature.
+var HISTORY_SIGNATURE_FORMAT = "blamejs-schema-history-v1";
+
+function _historyPayload(row) {
+  // Canonical JSON keeps the byte stream deterministic across Node
+  // versions / property-insertion order. Order-independent verifiers
+  // recompute the same bytes.
+  var payload =
+    HISTORY_SIGNATURE_FORMAT + "\n" +
+    canonicalJson.stringify({
+      version:                 row.version,
+      ranAt:                   row.ranAt,
+      ranBy:                   row.ranBy,
+      schemaIntrospectionHash: row.schemaIntrospectionHash,
+    });
+  return Buffer.from(payload, "utf8");
+}
+
+// Hash the current schema introspection — operators wiring an opts.
+// schemaIntrospect that returns deterministic bytes get the strict
+// guarantee that a tampered table after-the-fact will not verify. The
+// default introspect just returns the migration name list as a JSON
+// array, which is enough to detect "someone manually altered the
+// migrations table."
+async function _defaultSchemaIntrospect(xdb) {
+  var res = await xdb.query(
+    "SELECT name, appliedAt FROM " + Q_TRACKING +
+    " ORDER BY appliedAt ASC, name ASC",
+    []
+  );
+  var rows = (res && res.rows) || [];
+  return sha3Hash(Buffer.from(canonicalJson.stringify(rows), "utf8"));
+}
 
 // Filename grammar lives in lib/migration-files (shared with the local
 // migrations.js + seeders.js runners). Length capped before the regex
@@ -114,6 +155,42 @@ async function _ensureTrackingTable(xdb) {
   );
 }
 
+async function _ensureHistoryTable(xdb) {
+  // Schema-version history table: append-only record of every migrate.up
+  // wave + signature over (version, ranAt, ranBy, schemaIntrospectionHash).
+  // Signature uses ML-DSA-87 / SLH-DSA-SHAKE-256f via b.auditSign — an
+  // attacker tampering with rows after-the-fact cannot forge a matching
+  // signature without the audit-signing private key.
+  await xdb.query(
+    "CREATE TABLE IF NOT EXISTS " + Q_HISTORY + " (" +
+    "  version                 TEXT NOT NULL," +
+    "  ranAt                   TEXT NOT NULL," +
+    "  ranBy                   TEXT NOT NULL," +
+    "  schemaIntrospectionHash TEXT NOT NULL," +
+    "  signature               TEXT," +
+    "  publicKeyFingerprint    TEXT," +
+    "  PRIMARY KEY (version, ranAt)" +
+    ")",
+    []
+  );
+}
+
+async function _writeHistoryRow(xdb, row) {
+  await xdb.query(
+    "INSERT INTO " + Q_HISTORY +
+    " (version, ranAt, ranBy, schemaIntrospectionHash, signature, publicKeyFingerprint) " +
+    " VALUES ($1, $2, $3, $4, $5, $6)",
+    [
+      row.version,
+      row.ranAt,
+      row.ranBy,
+      row.schemaIntrospectionHash,
+      row.signature,
+      row.publicKeyFingerprint,
+    ]
+  );
+}
+
 async function _ensureLockTable(xdb) {
   await xdb.query(
     "CREATE TABLE IF NOT EXISTS " + Q_LOCK + " (" +
@@ -263,12 +340,23 @@ function _resolveBackendName(opts) {
 
 function create(opts) {
   opts = opts || {};
-  validateOpts(opts, ["dir", "backend", "audit", "staleAfterMs"], "b.externalDb.migrate");
+  validateOpts(opts, [
+    "dir", "backend", "audit", "staleAfterMs",
+    "schemaIntrospect", "ranBy", "signHistory",
+  ], "b.externalDb.migrate");
   validateOpts.requireNonEmptyString(opts.dir, "externalDb.migrate.create: opts.dir (path to migrations directory)", ExternalDbMigrateError, "externaldb-migrate/no-dir");
   validateOpts.optionalFiniteNonNegative(opts.staleAfterMs, "externalDb.migrate: staleAfterMs", ExternalDbMigrateError, "externaldb-migrate/bad-stale");
   validateOpts.auditShape(opts.audit, "externalDb.migrate", ExternalDbMigrateError, "externaldb-migrate/bad-audit");
+  validateOpts.optionalFunction(opts.schemaIntrospect,
+    "externalDb.migrate: schemaIntrospect", ExternalDbMigrateError,
+    "externaldb-migrate/bad-introspect");
   var dir = opts.dir;
   var audit = opts.audit || null;
+  var schemaIntrospect = typeof opts.schemaIntrospect === "function"
+    ? opts.schemaIntrospect : _defaultSchemaIntrospect;
+  var ranBy = typeof opts.ranBy === "string" && opts.ranBy.length > 0
+    ? opts.ranBy : _lockHolderId();
+  var signHistory = opts.signHistory !== false;
 
   function _ctx(backendName) {
     return {
@@ -306,6 +394,7 @@ function create(opts) {
     return await externalDbModule().transaction(async function (xdb) {
       await _ensureTrackingTable(xdb);
       await _ensureLockTable(xdb);
+      await _ensureHistoryTable(xdb);
     }, { backend: backendName }).then(async function () {
       // Acquire the lock OUTSIDE the per-migration transaction so the
       // lock survives across migration boundaries. We use a separate
@@ -345,11 +434,43 @@ function create(opts) {
           try {
             await externalDbModule().transaction(async function (xdb) {
               await mod.up(xdb, ctx);
+              var ranAt = new Date().toISOString();
               await xdb.query(
                 "INSERT INTO " + Q_TRACKING +
                 " (name, description, appliedAt) VALUES ($1, $2, $3)",
-                [file, mod.description || "", new Date().toISOString()]
+                [file, mod.description || "", ranAt]
               );
+              // Schema-version history with signature. Sign post-INSERT
+              // so the introspection hash reflects the row that just
+              // landed. Sign-failure is non-fatal for the migration but
+              // emits a failure audit so the operator chases it down.
+              var historyRow = {
+                version:                 file,
+                ranAt:                   ranAt,
+                ranBy:                   ranBy,
+                schemaIntrospectionHash: await schemaIntrospect(xdb),
+                signature:               null,
+                publicKeyFingerprint:    null,
+              };
+              if (signHistory) {
+                try {
+                  var payload = _historyPayload(historyRow);
+                  var sigBuf = auditSign().sign(payload);
+                  historyRow.signature = sigBuf.toString("base64");
+                  historyRow.publicKeyFingerprint = auditSign().getPublicKeyFingerprint();
+                } catch (sigErr) {
+                  _emit(audit, "migrations.history.sign_failed", "failure",
+                    { migration: file, backend: backendName },
+                    (sigErr && sigErr.message) || String(sigErr));
+                }
+              }
+              await _writeHistoryRow(xdb, historyRow);
+              _emit(audit, "migrations.history.appended", "success", {
+                migration: file,
+                schemaIntrospectionHash: historyRow.schemaIntrospectionHash,
+                signed: historyRow.signature !== null,
+                backend: backendName,
+              }, null);
             }, { backend: backendName });
             _emit(audit, "externaldb.migrate.up", "success",
                   { migration: file, durationMs: Date.now() - t0, backend: backendName }, null);
@@ -452,10 +573,77 @@ function create(opts) {
     }
   }
 
+  // history(opts?) — list every schema-version-history row + verify the
+  // signature on each. Returns:
+  //   [{ version, ranAt, ranBy, schemaIntrospectionHash, signature,
+  //      publicKeyFingerprint, verified: bool, verifyReason: string|null }]
+  //
+  // verify is `true` when the signature decodes + auditSign.verify
+  // returns true against the row's payload; `false` with reason
+  // otherwise (unsigned row / verify-failed / signing key absent /
+  // public-key-fingerprint mismatch).
+  async function history(historyOpts) {
+    historyOpts = historyOpts || {};
+    var backendName = _resolveBackendName(opts);
+    return await externalDbModule().transaction(async function (xdb) {
+      await _ensureHistoryTable(xdb);
+      var res = await xdb.query(
+        "SELECT version, ranAt, ranBy, schemaIntrospectionHash, signature, publicKeyFingerprint " +
+        "FROM " + Q_HISTORY + " ORDER BY ranAt ASC, version ASC",
+        []
+      );
+      var out = [];
+      var rows = (res && res.rows) || [];
+      for (var i = 0; i < rows.length; i++) {
+        var row = rows[i];
+        var verified = false;
+        var verifyReason = null;
+        if (!row.signature) {
+          verifyReason = "row-unsigned";
+        } else {
+          try {
+            var payload = _historyPayload(row);
+            var sigBuf = Buffer.from(row.signature, "base64");
+            var currentFp = auditSign().getPublicKeyFingerprint();
+            if (row.publicKeyFingerprint && row.publicKeyFingerprint !== currentFp) {
+              verifyReason = "public-key-fingerprint-mismatch";
+            } else {
+              verified = !!auditSign().verify(payload, sigBuf);
+              if (!verified) verifyReason = "signature-verify-failed";
+            }
+          } catch (e) {
+            verifyReason = "verify-threw: " + ((e && e.message) || String(e));
+          }
+        }
+        out.push({
+          version:                 row.version,
+          ranAt:                   row.ranAt,
+          ranBy:                   row.ranBy,
+          schemaIntrospectionHash: row.schemaIntrospectionHash,
+          signature:               row.signature,
+          publicKeyFingerprint:    row.publicKeyFingerprint,
+          verified:                verified,
+          verifyReason:            verifyReason,
+        });
+        if (!verified && row.signature) {
+          _emit(audit, "migrations.history.tamper_detected", "denied", {
+            version: row.version, ranAt: row.ranAt, reason: verifyReason,
+            backend: backendName,
+          }, null);
+        }
+      }
+      _emit(audit, "migrations.history.verified", "success", {
+        rowsVerified: out.length, backend: backendName,
+      }, null);
+      return out;
+    }, { backend: backendName });
+  }
+
   return {
     up:       up,
     down:     down,
     status:   status,
+    history:  history,
   };
 }
 
@@ -463,4 +651,6 @@ module.exports = {
   create:                  create,
   ExternalDbMigrateError:  ExternalDbMigrateError,
   TRACKING_TABLE:          TRACKING_TABLE,
+  HISTORY_TABLE:           HISTORY_TABLE,
+  HISTORY_SIGNATURE_FORMAT: HISTORY_SIGNATURE_FORMAT,
 };