@blamejs/blamejs-shop 0.2.14 → 0.2.17

package/lib/vendor/blamejs/lib/db.js

@@ -132,6 +132,22 @@ var encPath   = null;       // encrypted-at-rest path (null in plain mode)
 var encKey    = null;       // DB encryption key buffer (null in plain mode)
 var encTimer  = null;       // periodic encrypt interval handle
 var atRest    = null;       // 'encrypted' or 'plain'
+// Tmpfs free-space guard (encrypted mode). The working copy lives on a
+// bounded tmpfs (Docker /dev/shm defaults to 64 MiB); if it fills, SQLite
+// hits ENOSPC and corrupts the working copy. A periodic probe refuses
+// growth writes (INSERT/UPDATE/REPLACE) before that happens — fail-clear
+// instead of corrupt-then-recover. DELETE + reads stay available so
+// retention can reclaim space and the app can keep serving.
+var storageProbeTimer = null;  // periodic free-space probe handle
+var writesRefused = false;     // true when free space < minFreeBytes
+var minFreeBytes  = 0;         // refuse growth writes below this (0 = guard off)
+var statfsProbe   = null;      // free-space reader (fs.statfsSync; injectable for tests)
+// The process-exit final-flush handler is registered ONCE at first
+// encrypted init. Re-registering per init() leaked an 'exit' listener on
+// every init/close cycle (MaxListenersExceeded in long test runs / hot
+// reload); the flag makes it idempotent. The handler reads live module
+// state at exit time, so a later re-init is still covered.
+var _exitHandlerRegistered = false;
 var dataDir   = null;
 var initialized = false;
 var dataResidency = null;   // operator's declared region config (validated by storage backends)
@@ -672,13 +688,30 @@ function loadOrCreateDbKey(dataDirPath, keyPathOverride) {
 function decryptToTmp() {
   if (!encPath || !nodeFs.existsSync(encPath)) return;
   // If a plaintext file already exists in tmpfs from a prior process, prefer
-  // the newer mtime (crash recovery — operator's most recent state wins).
+  // the newer mtime (crash recovery — operator's most recent state wins) —
+  // but ONLY if it is a readable SQLite file. A working copy corrupted by
+  // an unclean shutdown or a full tmpfs (e.g. Docker's 64 MiB /dev/shm
+  // default overflowing) would otherwise be kept on every boot, and
+  // db.init's integrity gate would fail identically forever — an
+  // unrecoverable crash loop. When the newer plaintext fails a fast
+  // integrity probe, discard it and fall through to re-decrypt the
+  // last-good db.enc snapshot. db.enc itself is never modified here, so
+  // this only ever rolls back to the persistent encrypted copy; if THAT
+  // is also corrupt, db.init still fails loudly (no silent data loss).
   if (nodeFs.existsSync(dbPath)) {
     var plainStat = nodeFs.statSync(dbPath);
     var encStat = nodeFs.statSync(encPath);
     if (plainStat.mtimeMs > encStat.mtimeMs && plainStat.size > 0) {
-      log("plaintext is newer than encrypted — keeping plaintext (crash recovery)");
-      return;
+      if (_tmpWorkingCopyIsHealthy(dbPath)) {
+        log("plaintext is newer than encrypted — keeping plaintext (crash recovery)");
+        return;
+      }
+      log("newer tmpfs working copy failed its integrity probe (corrupt — likely an " +
+          "unclean shutdown or a full /dev/shm); discarding it and re-decrypting from " +
+          "db.enc (auto-recovery to the last-good encrypted snapshot)");
+      try { nodeFs.unlinkSync(dbPath); }          catch (_e) { /* fall through to overwrite */ }
+      try { nodeFs.unlinkSync(dbPath + "-wal"); } catch (_e) { /* may not exist */ }
+      try { nodeFs.unlinkSync(dbPath + "-shm"); } catch (_e) { /* may not exist */ }
     }
   }
   var packed = nodeFs.readFileSync(encPath);
@@ -696,10 +729,90 @@ function decryptToTmp() {
   }
 }
 
+// Fast "is this a usable SQLite file" probe for the crash-recovery path.
+// Opens the candidate working copy and runs PRAGMA quick_check(1) (far
+// cheaper than full integrity_check — header + page-structure sanity,
+// enough to catch a "database disk image is malformed" / truncated /
+// non-DB file). Any throw (malformed image, not-a-DB) or non-"ok" result
+// is unhealthy. The probe handle is always closed so it never holds the
+// tmpfs file open against the subsequent real open.
+function _tmpWorkingCopyIsHealthy(p) {
+  var probe = null;
+  try {
+    probe = new DatabaseSync(p);
+    var rows = probe.prepare("PRAGMA quick_check(1)").all();
+    return rows.length >= 1 && rows[0] && rows[0].quick_check === "ok";
+  } catch (_e) {
+    return false;
+  } finally {
+    if (probe) { try { probe.close(); } catch (_e2) { /* already gone */ } }
+  }
+}
+
 function _dbEncAad(dir) {
   return Buffer.from("blamejs.db-enc.v1\0" + (dir || ""), "utf8");
 }
 
+// Probe free space on the tmpfs holding the working copy and flip the
+// write-refusal flag. Encrypted mode only (the bounded-tmpfs surface);
+// guard disabled when minFreeBytes is 0. A probe failure leaves the flag
+// unchanged — we never refuse writes on a stat error (that would be a
+// self-inflicted outage). Growth writes (INSERT/UPDATE/REPLACE) are gated
+// by the prepare() wrapper installed in init(); DELETE + reads always pass
+// so retention can reclaim space and the app keeps serving.
+function _probeStorageHeadroom() {
+  if (atRest !== "encrypted" || !minFreeBytes || !dbPath || !statfsProbe) return;
+  var free;
+  try {
+    var st = statfsProbe(nodePath.dirname(dbPath));
+    free = st.bavail * st.bsize;
+    if (!isFinite(free)) return;
+  } catch (_e) { return; }
+  if (free < minFreeBytes && !writesRefused) {
+    writesRefused = true;
+    log.error("storage low: " + free + " bytes free on the tmpfs working-copy mount (< " +
+      minFreeBytes + ") — refusing growth writes (INSERT/UPDATE/REPLACE) until space " +
+      "recovers. Raise shm_size / --shm-size, or let retention prune. DELETE + reads still serve.");
+    try {
+      audit.safeEmit({ action: "db.storage.low", outcome: "failure",
+        metadata: { freeBytes: free, minFreeBytes: minFreeBytes } });
+    } catch (_e2) { /* drop-silent — observability */ }
+  } else if (free >= minFreeBytes && writesRefused) {
+    writesRefused = false;
+    log("storage recovered: " + free + " bytes free — growth writes re-enabled");
+    try {
+      audit.safeEmit({ action: "db.storage.recovered", outcome: "success",
+        metadata: { freeBytes: free } });
+    } catch (_e3) { /* drop-silent */ }
+  }
+}
+
+// Install the growth-write gate on the SQLite handle: shadow prepare() so
+// INSERT/UPDATE/REPLACE statements throw db/storage-low when the tmpfs is
+// critically low, instead of proceeding into an ENOSPC corruption. Reads,
+// DELETE, PRAGMA, and DDL pass through ungated. Called once in init() after
+// schema setup so init's own writes are never gated (writesRefused is false
+// until the first probe anyway).
+function _installWriteGate() {
+  var rawPrepare = database.prepare.bind(database);
+  database.prepare = function (sql) {
+    var stmt = rawPrepare(sql);
+    if (/^\s*(?:INSERT|UPDATE|REPLACE)\b/i.test(sql)) {
+      var rawRun = stmt.run.bind(stmt);
+      stmt.run = function () {
+        if (writesRefused) {
+          throw _dbErr("db/storage-low",
+            "db: refusing write — the encrypted-mode working copy is on a tmpfs with less than " +
+            minFreeBytes + " bytes free (Docker /dev/shm defaults to 64 MiB). Raise shm_size / " +
+            "--shm-size, or let retention prune expired rows. DELETE and reads remain available.");
+        }
+        return rawRun.apply(stmt, arguments);
+      };
+    }
+    return stmt;
+  };
+}
+
 function encryptToDisk() {
   if (!encPath) return;
   // Force WAL checkpoint so the .db file holds all committed transactions.
@@ -878,11 +991,11 @@ async function init(opts) {
     if (!nodeFs.existsSync(tmpDir)) nodeFs.mkdirSync(tmpDir, { recursive: true });
 
     // D-H7 — if the resolved tmpDir is NOT actually tmpfs, the
-    // plaintext DB file lives on persistent storage. statvfs/statfs
-    // isn't in stable Node, but on Linux we can check that tmpDir
-    // resolves under /dev/shm or /run/shm as a heuristic. On other
+    // plaintext DB file lives on persistent storage. We check that tmpDir
+    // resolves under /dev/shm or /run/shm on Linux as a heuristic; on other
     // platforms we warn that the operator must verify tmpfs binding
-    // out-of-band.
+    // out-of-band. (Free-space headroom is enforced separately via
+    // fs.statfsSync in the storage guard below.)
     if (process.platform === "linux") {
       var realTmp = "";
       try { realTmp = nodeFs.realpathSync(tmpDir); } catch (_e) { /* stat best-effort */ }
@@ -904,6 +1017,21 @@ async function init(opts) {
     dbPath  = nodePath.join(tmpDir, "blamejs-" + generateToken(C.BYTES.bytes(16)) + ".db");
     encKey  = loadOrCreateDbKey(dataDir, opts.dbKeyPath);
 
+    // Tmpfs free-space guard. Default headroom is 16 MiB below which growth
+    // writes are refused (fail-clear) before the working copy fills its
+    // bounded tmpfs and corrupts. opts.minFreeBytes tunes it; 0 disables.
+    // opts._statfsForTest injects a free-space reader for tests.
+    if (opts.minFreeBytes !== undefined) {
+      require("./numeric-bounds").requireNonNegativeFiniteIntIfPresent(
+        opts.minFreeBytes, "db.init: opts.minFreeBytes", DbError, "db/bad-min-free-bytes");
+      minFreeBytes = opts.minFreeBytes;
+    } else {
+      minFreeBytes = C.BYTES.mib(16);
+    }
+    statfsProbe = typeof opts._statfsForTest === "function"
+      ? opts._statfsForTest
+      : (typeof nodeFs.statfsSync === "function" ? nodeFs.statfsSync : null);
+
     cleanStaleTmpDbs(tmpDir);
     decryptToTmp();
   } else {
@@ -961,7 +1089,25 @@ async function init(opts) {
   // the freshly-decrypted-into-tmpfs file (<1 second on a typical
   // multi-MB DB) and the result is "ok" or a list of issues.
   if (opts.skipBootIntegrityCheck !== true) {
-    var ic = database.prepare("PRAGMA integrity_check").all();
+    var ic;
+    try {
+      ic = database.prepare("PRAGMA integrity_check").all();
+    } catch (corruptErr) {
+      // SQLite throws "database disk image is malformed" / "file is not a
+      // database" when the file is too corrupt to even run the check.
+      // Translate the raw native error into an actionable one — the most
+      // common operational cause in encrypted mode is a too-small tmpfs.
+      throw new DbError("db/integrity-check-failed",
+        "database is corrupt at boot — SQLite: " +
+        ((corruptErr && corruptErr.message) || String(corruptErr)) + ". " +
+        (atRest === "encrypted"
+          ? "Encrypted mode runs the live DB as a tmpfs working copy (" + dbPath +
+            "); a recurring failure here usually means the tmpfs is too small " +
+            "(Docker's /dev/shm defaults to 64 MiB — raise it via shm_size / " +
+            "--shm-size), or db.enc itself is corrupt (restore <dataDir>/db.enc " +
+            "from backup)."
+          : "Restore the database file (" + dbPath + ") from backup."));
+    }
     var icIssues = ic.map(function (r) { return r && r.integrity_check; })
                      .filter(function (s) { return s && s !== "ok"; });
     if (icIssues.length > 0) {
@@ -1282,12 +1428,30 @@ async function init(opts) {
       }
     }, C.TIME.minutes(5), { name: "db-periodic-encrypt" });
 
+    // Tmpfs free-space guard. Install the growth-write gate now (after all
+    // of init's own writes), then probe on a short interval so the
+    // refuse-writes flag tracks a fast-filling tmpfs (the 5-minute encrypt
+    // cadence is far too coarse to catch a fill in time). The guard is a
+    // no-op when minFreeBytes is 0 or no statfs reader is available.
+    if (minFreeBytes && statfsProbe) {
+      _installWriteGate();
+      _probeStorageHeadroom();   // seed the flag from current free space
+      storageProbeTimer = safeAsync.repeating(_probeStorageHeadroom,
+        C.TIME.seconds(10), { name: "db-storage-probe" });
+    }
+
     // Final encrypt on process exit. We don't try to unlink the plaintext
     // here — the SQLite handle may still be open, and the OS reclaims tmpfs
-    // on reboot anyway. close() does the orderly shutdown.
-    process.on("exit", function () {
-      try { encryptToDisk(); } catch (_e) { /* exit handler — silent */ }
-    });
+    // on reboot anyway. close() does the orderly shutdown. Registered ONCE
+    // (guarded by the module flag) — re-registering per init() leaked an
+    // 'exit' listener on every init/close cycle. The handler reads live
+    // module state, so it still flushes whatever DB is open at exit.
+    if (!_exitHandlerRegistered) {
+      _exitHandlerRegistered = true;
+      process.on("exit", function () {
+        try { if (atRest === "encrypted") encryptToDisk(); } catch (_e) { /* exit handler — silent */ }
+      });
+    }
   }
 
   log("ready (mode: " + atRest + ", path: " + dbPath + ")");
@@ -1924,6 +2088,11 @@ function close() {
     encTimer.stop();
     encTimer = null;
   }
+  if (storageProbeTimer) {
+    storageProbeTimer.stop();
+    storageProbeTimer = null;
+  }
+  writesRefused = false;
   // Drop prepared-statement cache so the underlying Statement handles
   // release ahead of database.close().
   _prepareCache.clear();
@@ -1942,11 +2111,19 @@ function close() {
   // Order: encrypt while the DB is still open (so the file is consistent),
   // then close the SQLite handle (releases the file lock on Windows),
   // THEN unlink the plaintext sidecar files.
-  try { encryptToDisk(); } catch (e) {
-    log.error("close: final encrypt failed: " + e.message);
+  var encryptOk = false;
+  try { encryptToDisk(); encryptOk = true; } catch (e) {
+    log.error("close: final encrypt failed: " + e.message +
+      " — keeping the plaintext working copy so the next boot can recover " +
+      "the latest writes (db.enc still holds the prior snapshot)");
   }
   try { database.close(); } catch (_e) { /* already closed */ }
-  if (atRest === "encrypted") removePlaintextFiles();
+  // Only discard the plaintext working copy once it has been safely
+  // re-encrypted. If the final encrypt failed (full /dev/shm, disk-full),
+  // the working copy is the ONLY carrier of writes since the last periodic
+  // flush — keep it so decryptToTmp's newer-mtime recovery picks it up next
+  // boot (integrity-probed, falling back to db.enc if it is itself corrupt).
+  if (atRest === "encrypted" && encryptOk) removePlaintextFiles();
   database = null;
   initialized = false;
 }
@@ -2440,6 +2617,7 @@ function _cascadeStep(name, ref) {
 // Test helpers — not part of public contract
 function _resetForTest() {
   if (encTimer) { encTimer.stop(); encTimer = null; }
+  if (storageProbeTimer) { storageProbeTimer.stop(); storageProbeTimer = null; }
   try { if (database) database.close(); }
   catch (e) { log.debug("test-reset close failed", { error: e.message }); }
   database = null;
@@ -2448,10 +2626,20 @@ function _resetForTest() {
   encKey = null;
   atRest = null;
   dataDir = null;
+  minFreeBytes = 0;
+  statfsProbe = null;
+  writesRefused = false;
   initialized = false;
   cryptoField.clearForTest();
 }
 
+// Test seam — force a storage-headroom probe synchronously (the production
+// path runs it on a 10s timer) and read the resulting refuse-writes flag.
+function _probeStorageForTest() {
+  _probeStorageHeadroom();
+  return { writesRefused: writesRefused, minFreeBytes: minFreeBytes };
+}
+
 
 /**
  * @primitive b.db.vacuumAfterErase
@@ -3102,6 +3290,8 @@ module.exports = {
     _cascadeStep("redact",      _resetRedact);
     _cascadeStep("external-db", _resetExternalDb);
   },
+  // Test seam for the tmpfs free-space guard — force a probe + read the flag.
+  _probeStorageForTest: _probeStorageForTest,
   // Helper for audit.checkpoint to write the rollback-detection sidecar
   _writeAuditTip: function (tip) {
     if (!dataDir) return;

package/lib/vendor/blamejs/lib/dual-control.js

@@ -301,27 +301,27 @@ function create(opts) {
 
   async function cancel(args) {
     if (!args || typeof args !== "object") throw _err("BAD_ARG", "cancel: args required");
-    var record = await _load(args.grantId);
-    if (!record) return { error: "grant-not-found", grantId: args.grantId };
-    if (record.consumedAt !== null) return { error: "grant-already-consumed", grantId: record.grantId };
-    if (record.revokedAt !== null)  return { error: "grant-revoked", grantId: record.grantId };
-    if (record.cancelledAt !== null) return { error: "grant-already-cancelled", grantId: record.grantId };
     var actorId = _actorIdOf(args.cancelledBy);
-    if (actorId !== record.requestedBy) {
-      // Cancellation by anyone other than the requester is a revoke,
-      // not a cancel. Surface explicitly.
-      return { error: "only-requester-can-cancel", grantId: record.grantId,
-        requestedBy: record.requestedBy };
-    }
-    record.cancelledAt = Date.now();
-    record.cancelledReason = args.reason || null;
-    var ttlRemaining = Math.max(1, record.expiresAt - Date.now());
-    await cache.set(_key(record.grantId), record, { ttlMs: ttlRemaining });
+    var outcome = await cache.update(_key(args.grantId), function (record) {
+      if (!record) return { abort: { response: { error: "grant-not-found", grantId: args.grantId } } };
+      if (record.consumedAt !== null) return { abort: { response: { error: "grant-already-consumed", grantId: record.grantId } } };
+      if (record.revokedAt !== null)  return { abort: { response: { error: "grant-revoked", grantId: record.grantId } } };
+      if (record.cancelledAt !== null) return { abort: { response: { error: "grant-already-cancelled", grantId: record.grantId } } };
+      // Cancellation by anyone other than the requester is a revoke, not a
+      // cancel — surface explicitly.
+      if (actorId !== record.requestedBy) {
+        return { abort: { response: { error: "only-requester-can-cancel", grantId: record.grantId, requestedBy: record.requestedBy } } };
+      }
+      record.cancelledAt = Date.now();
+      record.cancelledReason = args.reason || null;
+      return { value: record, expiresAt: record.expiresAt };
+    }, { ttlMs: ttlMs });
+    if (outcome.aborted) return outcome.aborted.response;
+    var rec = outcome.value;
     _emit("dual.grant.cancelled",
-      { grantId: record.grantId, action: record.action,
-        cancelledBy: actorId, reason: args.reason || null },
+      { grantId: rec.grantId, action: rec.action, cancelledBy: actorId, reason: args.reason || null },
       "success", args.req);
-    return { grantId: record.grantId, status: "cancelled" };
+    return { grantId: rec.grantId, status: "cancelled" };
   }
 
   async function _load(grantId) {
@@ -334,156 +334,152 @@ function create(opts) {
 
   async function approve(args) {
     if (!args || typeof args !== "object") throw _err("BAD_ARG", "approve: args required");
-    var record = await _load(args.grantId);
-    if (!record) {
-      return { error: "grant-not-found", grantId: args.grantId };
-    }
-    if (record.consumedAt !== null) {
-      return { error: "grant-already-consumed", grantId: record.grantId };
-    }
-    if (record.revokedAt !== null) {
-      return { error: "grant-revoked", grantId: record.grantId, revokedReason: record.revokedReason };
-    }
-    if (record.cancelledAt !== null) {
-      return { error: "grant-cancelled", grantId: record.grantId };
-    }
-    if (record.expiresAt < Date.now()) {
-      _emit("dual.grant.expired", { grantId: record.grantId, action: record.action },
-        "failure", args.req);
-      await cache.del(_key(record.grantId));
-      return { error: "grant-expired", grantId: record.grantId };
-    }
     var approverId = _actorIdOf(args.approver);
     if (!approverId) throw _err("BAD_ARG", "approve: args.approver must be an actor with a stable id");
-    if (forbidSelfApprove && approverId === record.requestedBy) {
-      _emit("dual.grant.self_approval_denied",
-        { grantId: record.grantId, action: record.action, approver: approverId },
-        "denied", args.req);
-      return { error: "self-approval-forbidden", grantId: record.grantId };
-    }
-    if (!_approverRoleOk(args.approver)) {
-      _emit("dual.grant.role_denied",
-        { grantId: record.grantId, action: record.action, approver: approverId,
-          requiredRoles: approverRoles,
-          actorRoles: (args.approver && Array.isArray(args.approver.roles)) ? args.approver.roles : [] },
-        "denied", args.req);
-      return { error: "approver-role-required", grantId: record.grantId,
-        requiredRoles: approverRoles };
-    }
-    if (record.approvedBy.indexOf(approverId) !== -1) {
-      return { error: "already-approved-by-this-actor", grantId: record.grantId,
-        approvedBy: record.approvedBy };
-    }
+    // Pre-compute the pure, record-independent checks so the mutator stays
+    // side-effect-free (it may re-run under cluster CAS contention).
+    var roleOk = _approverRoleOk(args.approver);
     var reasonProblem = _checkReason(args.reason, "approve");
-    if (reasonProblem) {
-      return Object.assign({ grantId: record.grantId }, reasonProblem);
-    }
-    record.approvedBy.push(approverId);
-    record.approvalsAt.push(Date.now());
-    record.approvalReasons.push(args.reason || null);
-    if (approverRoles && args.approver && Array.isArray(args.approver.roles)) {
-      // Record which of the required roles satisfied the approval —
-      // useful when an audit reviewer needs to confirm the actor
-      // approved as e.g. their security-officer role and not their
-      // engineer role.
-      var hits = args.approver.roles.filter(function (r) { return approverRoles.indexOf(r) !== -1; });
-      record.approverRoleHits.push(hits);
-    }
-    var status = "pending";
-    if (record.approvedBy.length >= record.minApprovers) {
-      status = "approved";
-      if (record.quorumReachedAt === null) record.quorumReachedAt = Date.now();
+    var roleHits = (approverRoles && args.approver && Array.isArray(args.approver.roles))
+      ? args.approver.roles.filter(function (r) { return approverRoles.indexOf(r) !== -1; })
+      : null;
+
+    // Atomic read-modify-write: the duplicate-approver guard and the
+    // approvedBy append commit together, so two concurrent approvals (or a
+    // retried one) cannot each read a stale snapshot and append the same
+    // approver twice — the quorum-bypass the get/set version allowed.
+    var outcome = await cache.update(_key(args.grantId), function (record) {
+      if (!record) return { abort: { response: { error: "grant-not-found", grantId: args.grantId } } };
+      if (record.consumedAt !== null) return { abort: { response: { error: "grant-already-consumed", grantId: record.grantId } } };
+      if (record.revokedAt !== null) return { abort: { response: { error: "grant-revoked", grantId: record.grantId, revokedReason: record.revokedReason } } };
+      if (record.cancelledAt !== null) return { abort: { response: { error: "grant-cancelled", grantId: record.grantId } } };
+      if (record.expiresAt < Date.now()) {
+        return { abort: { response: { error: "grant-expired", grantId: record.grantId },
+          event: "dual.grant.expired", meta: { grantId: record.grantId, action: record.action }, outcome: "failure" } };
+      }
+      if (forbidSelfApprove && approverId === record.requestedBy) {
+        return { abort: { response: { error: "self-approval-forbidden", grantId: record.grantId },
+          event: "dual.grant.self_approval_denied",
+          meta: { grantId: record.grantId, action: record.action, approver: approverId }, outcome: "denied" } };
+      }
+      if (!roleOk) {
+        return { abort: { response: { error: "approver-role-required", grantId: record.grantId, requiredRoles: approverRoles },
+          event: "dual.grant.role_denied",
+          meta: { grantId: record.grantId, action: record.action, approver: approverId, requiredRoles: approverRoles,
+            actorRoles: (args.approver && Array.isArray(args.approver.roles)) ? args.approver.roles : [] }, outcome: "denied" } };
+      }
+      if (record.approvedBy.indexOf(approverId) !== -1) {
+        return { abort: { response: { error: "already-approved-by-this-actor", grantId: record.grantId, approvedBy: record.approvedBy.slice() } } };
+      }
+      if (reasonProblem) return { abort: { response: Object.assign({ grantId: record.grantId }, reasonProblem) } };
+      record.approvedBy.push(approverId);
+      record.approvalsAt.push(Date.now());
+      record.approvalReasons.push(args.reason || null);
+      // Record which required role satisfied the approval — an audit
+      // reviewer can confirm the actor approved as e.g. security-officer.
+      if (roleHits) record.approverRoleHits.push(roleHits);
+      if (record.approvedBy.length >= record.minApprovers && record.quorumReachedAt === null) {
+        record.quorumReachedAt = Date.now();
+      }
+      return { value: record, expiresAt: record.expiresAt };
+    }, { ttlMs: ttlMs });
+
+    if (outcome.aborted) {
+      var ab = outcome.aborted;
+      if (ab.event) _emit(ab.event, ab.meta, ab.outcome, args.req);
+      return ab.response;
     }
-    var ttlRemaining = Math.max(1, record.expiresAt - Date.now());
-    await cache.set(_key(record.grantId), record, { ttlMs: ttlRemaining });
+    var rec = outcome.value;
+    var status = (rec.approvedBy.length >= rec.minApprovers) ? "approved" : "pending";
+    var consumeUnlockAt = rec.quorumReachedAt !== null ? rec.quorumReachedAt + rec.consumeLockMs : null;
     _emit("dual.grant.approved",
-      { grantId: record.grantId, action: record.action, approver: approverId,
-        approverCount: record.approvedBy.length, needs: record.minApprovers,
-        status: status, reason: args.reason || null,
-        consumeUnlockAt: record.quorumReachedAt !== null
-          ? record.quorumReachedAt + record.consumeLockMs : null },
+      { grantId: rec.grantId, action: rec.action, approver: approverId,
+        approverCount: rec.approvedBy.length, needs: rec.minApprovers,
+        status: status, reason: args.reason || null, consumeUnlockAt: consumeUnlockAt },
       "success", args.req);
     return {
-      grantId:    record.grantId,
+      grantId:    rec.grantId,
       status:     status,
-      approvedBy: record.approvedBy.slice(),
-      needs:      record.minApprovers,
-      expiresAt:  record.expiresAt,
-      consumeUnlockAt: record.quorumReachedAt !== null
-        ? record.quorumReachedAt + record.consumeLockMs : null,
+      approvedBy: rec.approvedBy.slice(),
+      needs:      rec.minApprovers,
+      expiresAt:  rec.expiresAt,
+      consumeUnlockAt: consumeUnlockAt,
     };
   }
 
   async function revoke(args) {
     if (!args || typeof args !== "object") throw _err("BAD_ARG", "revoke: args required");
-    var record = await _load(args.grantId);
-    if (!record) return { error: "grant-not-found", grantId: args.grantId };
-    if (record.consumedAt !== null) {
-      return { error: "grant-already-consumed", grantId: record.grantId };
-    }
-    record.revokedAt = Date.now();
-    record.revokedReason = args.reason || null;
-    var ttlRemaining = Math.max(1, record.expiresAt - Date.now());
-    await cache.set(_key(record.grantId), record, { ttlMs: ttlRemaining });
+    var revokedById = _actorIdOf(args.revokedBy);
+    var outcome = await cache.update(_key(args.grantId), function (record) {
+      if (!record) return { abort: { response: { error: "grant-not-found", grantId: args.grantId } } };
+      if (record.consumedAt !== null) return { abort: { response: { error: "grant-already-consumed", grantId: record.grantId } } };
+      record.revokedAt = Date.now();
+      record.revokedReason = args.reason || null;
+      return { value: record, expiresAt: record.expiresAt };
+    }, { ttlMs: ttlMs });
+    if (outcome.aborted) return outcome.aborted.response;
+    var rec = outcome.value;
     _emit("dual.grant.denied",
-      { grantId: record.grantId, action: record.action,
-        revokedBy: _actorIdOf(args.revokedBy), reason: args.reason || null },
+      { grantId: rec.grantId, action: rec.action, revokedBy: revokedById, reason: args.reason || null },
       "denied", args.req);
-    return { grantId: record.grantId, status: "revoked" };
+    return { grantId: rec.grantId, status: "revoked" };
   }
 
   async function consume(grantId, args) {
     args = args || {};
-    var record = await _load(grantId);
-    if (!record) return { ready: false, reason: "grant-not-found" };
-    if (record.revokedAt !== null) {
-      return { ready: false, reason: "revoked" };
-    }
-    if (record.cancelledAt !== null) {
-      return { ready: false, reason: "cancelled" };
-    }
-    if (record.consumedAt !== null) {
-      return { ready: false, reason: "already-consumed" };
-    }
-    if (record.expiresAt < Date.now()) {
-      _emit("dual.grant.expired", { grantId: record.grantId, action: record.action },
-        "failure", args.req);
-      await cache.del(_key(record.grantId));
-      return { ready: false, reason: "expired" };
-    }
-    if (record.approvedBy.length < record.minApprovers) {
-      return { ready: false, reason: "not-enough-approvers",
-        approvedBy: record.approvedBy.slice(), needs: record.minApprovers };
-    }
-    // Cooling-off lock: ANY approval-quorum-reached grant can't consume
-    // until consumeLockMs has passed since the final approval. Defends
-    // against rapid-burst compromise of requester+approver.
-    if ((record.consumeLockMs || 0) > 0 && record.quorumReachedAt !== null) {
-      var unlockAt = record.quorumReachedAt + record.consumeLockMs;
-      if (Date.now() < unlockAt) {
-        _emit("dual.grant.consume_locked",
-          { grantId: record.grantId, action: record.action,
-            unlockAt: unlockAt, waitMs: unlockAt - Date.now() },
-          "denied", args.req);
-        return { ready: false, reason: "consume-locked", unlockAt: unlockAt,
-          waitMs: unlockAt - Date.now() };
+    // Atomic read-modify-write: the consumedAt check and the consumedAt set
+    // commit together (compare-and-set), so two concurrent consumes cannot
+    // both observe consumedAt === null and both proceed — exactly one wins
+    // and runs the destructive operation. The get/set version let a
+    // single-use grant be consumed twice.
+    var outcome = await cache.update(_key(grantId), function (record) {
+      if (!record) return { abort: { response: { ready: false, reason: "grant-not-found" } } };
+      if (record.revokedAt !== null) return { abort: { response: { ready: false, reason: "revoked" } } };
+      if (record.cancelledAt !== null) return { abort: { response: { ready: false, reason: "cancelled" } } };
+      if (record.consumedAt !== null) return { abort: { response: { ready: false, reason: "already-consumed" } } };
+      if (record.expiresAt < Date.now()) {
+        return { abort: { response: { ready: false, reason: "expired" }, del: true,
+          event: "dual.grant.expired", meta: { grantId: record.grantId, action: record.action }, outcome: "failure" } };
       }
+      if (record.approvedBy.length < record.minApprovers) {
+        return { abort: { response: { ready: false, reason: "not-enough-approvers",
+          approvedBy: record.approvedBy.slice(), needs: record.minApprovers } } };
+      }
+      // Cooling-off lock: a quorum-reached grant can't consume until
+      // consumeLockMs has passed since the final approval — defends against
+      // rapid-burst compromise of requester + approver.
+      if ((record.consumeLockMs || 0) > 0 && record.quorumReachedAt !== null) {
+        var unlockAt = record.quorumReachedAt + record.consumeLockMs;
+        if (Date.now() < unlockAt) {
+          return { abort: { response: { ready: false, reason: "consume-locked", unlockAt: unlockAt, waitMs: unlockAt - Date.now() },
+            event: "dual.grant.consume_locked",
+            meta: { grantId: record.grantId, action: record.action, unlockAt: unlockAt, waitMs: unlockAt - Date.now() }, outcome: "denied" } };
+        }
+      }
+      record.consumedAt = Date.now();
+      return { value: record, expiresAt: record.expiresAt };
+    }, { ttlMs: ttlMs });
+
+    if (outcome.aborted) {
+      var ab = outcome.aborted;
+      if (ab.event) _emit(ab.event, ab.meta, ab.outcome, args.req);
+      if (ab.del) { try { await cache.del(_key(grantId)); } catch (_e) { /* sweep handles it */ } }
+      return ab.response;
     }
-    record.consumedAt = Date.now();
-    // Drop the grant from the cache after consume — single-use by design.
-    await cache.del(_key(record.grantId));
+    var rec = outcome.value;
+    // Single-use by design — drop the (now consumed) grant from the cache.
+    await cache.del(_key(rec.grantId));
     _emit("dual.grant.consumed",
-      { grantId: record.grantId, action: record.action,
-        approvedBy: record.approvedBy.slice(),
-        approvalReasons: record.approvalReasons.slice() },
+      { grantId: rec.grantId, action: rec.action,
+        approvedBy: rec.approvedBy.slice(), approvalReasons: rec.approvalReasons.slice() },
       "success", args.req);
     return {
       ready:      true,
-      grantId:    record.grantId,
-      action:     record.action,
-      resource:   record.resource,
-      approvedBy: record.approvedBy.slice(),
-      requestedBy:record.requestedBy,
+      grantId:    rec.grantId,
+      action:     rec.action,
+      resource:   rec.resource,
+      approvedBy: rec.approvedBy.slice(),
+      requestedBy:rec.requestedBy,
     };
   }