@blamejs/blamejs-shop 0.4.31 → 0.4.33

package/lib/vendor/blamejs/lib/break-glass.js

@@ -49,6 +49,7 @@ var requestHelpers = require("./request-helpers");
 var safeAsync = require("./safe-async");
 var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var totp = require("./totp");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
@@ -75,6 +76,10 @@ var DEK_BYTES               = C.BYTES.bytes(32);
 var GRANT_ID_BYTES          = C.BYTES.bytes(16);
 
 var DEFAULT_GRANT_TTL_MS    = C.TIME.minutes(15);
+// Replay-step retention. A TOTP code is only valid inside the verifier's
+// drift window (minutes); retaining the highest-accepted step for an hour
+// guarantees any in-window replay attempt arrives after the floor is set.
+var REPLAY_STEP_TTL_MS      = C.TIME.hours(1);
 var DEFAULT_MAX_ROWS        = 1;       // operator-locked: row-by-row auth
 var DEFAULT_REASON_MIN_LEN  = 12;
 var DEFAULT_LOCKED_BEHAVIOR = "throw"; // or "redact"
@@ -82,6 +87,34 @@ var DEFAULT_AUDIT_REASON    = "cleartext";
 var ALLOWED_FACTORS         = ["totp", "passkey"];
 var ALLOWED_REASON_STORAGE  = ["cleartext", "hmac", "both"];
 
+// cryptoField REGISTRY KEYS for the two break-glass framework tables. These
+// are the names db.js's FRAMEWORK_SCHEMA registered the tables under, so
+// seal / unseal / computeDerived must key off the byte-identical literal —
+// resolving them through frameworkSchema.tableName would diverge the seal-side
+// key from the registration under a custom prefix and break decryption. (SQL
+// composed via b.sql passes the SAME bare logical name so clusterStorage can
+// rewrite the table reference; these constants cover only the cryptoField
+// keying.) allow:hand-rolled-sql — cryptoField registry keys, not SQL text.
+var POLICIES_TABLE = "_blamejs_break_glass_policies";   // allow:hand-rolled-sql
+var GRANTS_TABLE   = "_blamejs_break_glass_grants";     // allow:hand-rolled-sql
+
+// b.sql opts for every statement break-glass dispatches through
+// clusterStorage. Thread the ACTIVE backend dialect (clusterStorage.dialect()
+// — "sqlite" single-node, "postgres" | "mysql" in cluster mode) so the
+// emitted identifier quoting + dialect idioms (ON CONFLICT vs ON DUPLICATE
+// KEY) 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. clusterStorage.execute still rewrites framework
+// table names + translates `?` placeholders at dispatch; this controls only
+// the builder-side quoting + idiom selection.
+//   _sqlOpts()    — framework tables (policies / grants); name resolved bare,
+//                   clusterStorage rewrites the prefix.
+//   _appSqlOpts() — the operator's glass-locked app table; quoteName so b.sql
+//                   quotes the (validated) identifier, and it is NOT
+//                   framework-rewritten.
+function _sqlOpts()    { return { dialect: clusterStorage.dialect() }; }
+function _appSqlOpts() { return { dialect: clusterStorage.dialect(), quoteName: true }; }
+
 // In-memory policy cache. Cluster-shared via the policies table; the
 // cache short-circuits the DB roundtrip on the unsealRow hot path.
 // Populated on first access per-table; invalidated on policy.set/delete.
@@ -153,10 +186,14 @@ async function _ensureDek(table) {
   // DEK is vault-sealed and stored in the policy row's `dekSealed`
   // column. Generated lazily on first use of cryptographic-mode for
   // the table. Cached in-memory after first read.
-  var rows = await clusterStorage.executeAll(
-    "SELECT dekSealed FROM _blamejs_break_glass_policies WHERE tableName = ?",
-    [table]
-  );
+  // The policy table is external-only; its LOGICAL name IS the
+  // `_blamejs_`-prefixed name (self-mapped in LOCAL_TO_EXTERNAL), passed
+  // bare to b.sql so clusterStorage rewrites + placeholderizes.
+  var dekReadBuilt = sql.select("_blamejs_break_glass_policies", _sqlOpts())   // allow:hand-rolled-sql
+    .columns(["dekSealed"])
+    .where("tableName", table)
+    .toSql();
+  var rows = await clusterStorage.executeAll(dekReadBuilt.sql, dekReadBuilt.params);
   if (!rows || rows.length === 0) {
     throw new BreakGlassError("breakglass/policy-not-set",
       "_ensureDek: no policy for table '" + table + "'", true);
@@ -168,10 +205,11 @@ async function _ensureDek(table) {
   } else {
     dek = generateBytes(DEK_BYTES);
     var sealedDek = vault().seal(dek.toString("base64"));
-    await clusterStorage.execute(
-      "UPDATE _blamejs_break_glass_policies SET dekSealed = ? WHERE tableName = ?",
-      [sealedDek, table]
-    );
+    var dekUpdBuilt = sql.update("_blamejs_break_glass_policies", _sqlOpts())   // allow:hand-rolled-sql
+      .set({ dekSealed: sealedDek })
+      .where("tableName", table)
+      .toSql();
+    await clusterStorage.execute(dekUpdBuilt.sql, dekUpdBuilt.params);
   }
   dekCache.set(table, dek);
   return dek;
@@ -343,14 +381,16 @@ async function migrate(table, opts) {
   var lastId = "";
   // Iterate via _id-keyset paging so we don't load the whole table into memory.
   while (true) {
-    // table is already validated as a safe identifier shape via
-    // _validatePolicySet — wrap in "..." per the framework's
-    // identifier-quoting convention.
-    var qTable = '"' + table + '"';
-    var rows = await clusterStorage.executeAll(
-      "SELECT * FROM " + qTable + " WHERE _id > ? ORDER BY _id ASC LIMIT ?",
-      [lastId, batchSize]
-    );
+    // `table` is an operator app table (already validated as a safe
+    // identifier via _validatePolicySet). quoteName:true makes b.sql quote
+    // the name (reserved-word / case-sensitive safe); it is NOT a framework
+    // table, so clusterStorage's resolveTables leaves it untouched.
+    var pageBuilt = sql.select(table, _appSqlOpts())
+      .whereOp("_id", ">", lastId)
+      .orderBy("_id", "asc")
+      .limit(batchSize)
+      .toSql();
+    var rows = await clusterStorage.executeAll(pageBuilt.sql, pageBuilt.params);
     if (!rows || rows.length === 0) break;
     for (var i = 0; i < rows.length; i++) {
       totalRows++;
@@ -374,16 +414,16 @@ async function migrate(table, opts) {
         // the cell ciphertext stays as a literal string, not double-sealed.
         var setCols = Object.keys(update).filter(function (k) { return k !== "_id"; });
         if (setCols.length > 0) {
-          // Column names came from the validated policy.columns —
-          // also wrap each in "..." for the same identifier-quoting
-          // convention.
-          var setSql = setCols.map(function (k) { return '"' + k + '" = ?'; }).join(", ");
-          var vals = setCols.map(function (k) { return update[k]; });
-          vals.push(row._id);
-          await clusterStorage.execute(
-            "UPDATE " + qTable + " SET " + setSql + " WHERE _id = ?",
-            vals
-          );
+          // Column names came from the validated policy.columns. b.sql
+          // quotes every SET target + binds every value; the operator app
+          // table is quoted (quoteName) and not framework-rewritten.
+          var setMap = {};
+          for (var sc = 0; sc < setCols.length; sc++) setMap[setCols[sc]] = update[setCols[sc]];
+          var updBuilt = sql.update(table, _appSqlOpts())
+            .set(setMap)
+            .where("_id", row._id)
+            .toSql();
+          await clusterStorage.execute(updBuilt.sql, updBuilt.params);
           migratedRows++;
         }
       } else {
@@ -658,17 +698,20 @@ async function policySet(table, opts, callerOpts) {
     auditReasonStorage:       validated.auditReasonStorage,
     updatedAt:                Date.now(),
   };
-  var sealed = cryptoField.sealRow("_blamejs_break_glass_policies", policyRow);
-  // UPSERT — both Postgres and SQLite support ON CONFLICT.
+  var sealed = cryptoField.sealRow(POLICIES_TABLE, policyRow);
+  // UPSERT via b.sql ON CONFLICT(tableName) DO UPDATE (Postgres + SQLite).
+  // BARE logical framework table — clusterStorage rewrites + placeholderizes;
+  // b.sql quotes every column + binds every sealed value. The conflict key
+  // (tableName) is excluded from the DO UPDATE set.
   var keys   = Object.keys(sealed);
-  var cols   = keys.join(", ");
-  var qs     = keys.map(function () { return "?"; }).join(", ");
-  var setSql = keys.filter(function (k) { return k !== "tableName"; })
-    .map(function (k) { return k + " = excluded." + k; }).join(", ");
-  var sql = "INSERT INTO _blamejs_break_glass_policies (" + cols + ") " +
-            "VALUES (" + qs + ") " +
-            "ON CONFLICT (tableName) DO UPDATE SET " + setSql;
-  await clusterStorage.execute(sql, keys.map(function (k) { return sealed[k]; }));
+  var setCols = keys.filter(function (k) { return k !== "tableName"; });
+  var policyBuilt = sql.upsert("_blamejs_break_glass_policies", _sqlOpts())   // allow:hand-rolled-sql
+    .columns(keys)
+    .values(sealed)
+    .onConflict(["tableName"])
+    .doUpdateFromExcluded(setCols)
+    .toSql();
+  await clusterStorage.execute(policyBuilt.sql, policyBuilt.params);
   policyCache.delete(table);
 
   audit.safeEmit({
@@ -711,15 +754,15 @@ async function policyGet(table) {
   _requireInit();
   if (typeof table !== "string" || table.length === 0) return null;
   if (policyCache.has(table)) return policyCache.get(table);
-  var rows = await clusterStorage.executeAll(
-    "SELECT * FROM _blamejs_break_glass_policies WHERE tableName = ?",
-    [table]
-  );
+  var getBuilt = sql.select("_blamejs_break_glass_policies", _sqlOpts())   // allow:hand-rolled-sql
+    .where("tableName", table)
+    .toSql();
+  var rows = await clusterStorage.executeAll(getBuilt.sql, getBuilt.params);
   if (!rows || rows.length === 0) {
     policyCache.set(table, null);
     return null;
   }
-  var unsealed = cryptoField.unsealRow("_blamejs_break_glass_policies", rows[0]);
+  var unsealed = cryptoField.unsealRow(POLICIES_TABLE, rows[0]);
   var policy = {
     table:              unsealed.tableName,
     columns:            safeJson.parse(unsealed.columnsJson, { maxBytes: C.BYTES.kib(64) }),
@@ -763,9 +806,11 @@ async function policyGet(table) {
  */
 async function policyList() {
   _requireInit();
-  var rows = await clusterStorage.executeAll(
-    "SELECT tableName FROM _blamejs_break_glass_policies ORDER BY tableName"
-  );
+  var listBuilt = sql.select("_blamejs_break_glass_policies", _sqlOpts())   // allow:hand-rolled-sql
+    .columns(["tableName"])
+    .orderBy("tableName", "asc")
+    .toSql();
+  var rows = await clusterStorage.executeAll(listBuilt.sql, listBuilt.params);
   var out = [];
   for (var i = 0; i < (rows || []).length; i++) {
     var p = await policyGet(rows[i].tableName);
@@ -797,10 +842,10 @@ async function policyDelete(table, callerOpts) {
     throw new BreakGlassError("breakglass/bad-policy",
       "policy.delete: table must be a non-empty string");
   }
-  await clusterStorage.execute(
-    "DELETE FROM _blamejs_break_glass_policies WHERE tableName = ?",
-    [table]
-  );
+  var delBuilt = sql.delete("_blamejs_break_glass_policies", _sqlOpts())   // allow:hand-rolled-sql
+    .where("tableName", table)
+    .toSql();
+  await clusterStorage.execute(delBuilt.sql, delBuilt.params);
   policyCache.delete(table);
   audit.safeEmit({
     action:   "breakglass.policy.delete",
@@ -817,10 +862,58 @@ function _verifyTotpFactor(factor) {
   if (!factor || typeof factor !== "object") return { ok: false };
   if (typeof factor.secret !== "string" || factor.secret.length === 0) return { ok: false };
   if (typeof factor.code !== "string" || factor.code.length === 0)     return { ok: false };
-  var verified = totp.verify(factor.secret, factor.code);
+  // factor.now threads a deterministic test clock into totp.verify. The
+  // replay floor is NOT applied here: acceptance reserves the matched step
+  // atomically in _reserveTotpStep, so two concurrent grants presenting the
+  // same in-window code cannot both pass (a read-then-commit floor races —
+  // both reads observe the old floor before either commits). totp.verify
+  // returns the step the code matches (a fixed value for a given code within
+  // the drift window) or false; the reserve then floors replays of that step.
+  var vopts = {};
+  if (typeof factor.now === "number") vopts.now = factor.now;
+  var verified = totp.verify(factor.secret, factor.code, vopts);
   return { ok: verified !== false, step: verified };
 }
 
+// Replay-step cache key. Keyed by BOTH the actorId AND a non-reversible
+// fingerprint of the TOTP secret. Keying on actorId alone would falsely
+// reject a legitimate second grant when two distinct credentials accept a
+// code at the same TOTP step (the step number is a wall-clock counter, not
+// per-credential) — the secret fingerprint disambiguates them. The secret
+// never reaches the cache in any reversible form.
+function _replayStepKey(actorId, secret) {
+  return "totp-step:" + actorId + ":" + sha3Hash(secret);
+}
+
+// Atomically reserve the accepted TOTP step for (actorId, secret): advance
+// the stored replay floor to `step` only when `step` is strictly above the
+// current floor, and report whether THIS caller won the reservation. The
+// compare-and-advance is one atomic cache update, so two concurrent grant()
+// calls presenting the same in-window code cannot both pass — the first wins
+// and raises the floor to `step`, the second observes step <= floor and is
+// refused. (A separate read-then-commit sequence let both reads see the old
+// floor before either committed, so both verified — the replay this closes.)
+// The TTL outlives the verify drift window many times over so a replayed code
+// stays floored until it expires.
+//
+// Fails CLOSED (returns false) on a cache fault: a grant cannot proceed
+// without a working factor cache regardless — the lockout check at the top of
+// grant() already gates on the same cache — so refusing here can only reject,
+// never loosen replay protection.
+async function _reserveTotpStep(actorId, secret, step) {
+  _ensureFactorLockout();
+  if (typeof step !== "number") return false;
+  var won = false;
+  try {
+    await _factorLockoutCache.update(_replayStepKey(actorId, secret), function (prior) {
+      if (typeof prior === "number" && step <= prior) { won = false; return { value: prior }; }
+      won = true;
+      return { value: step };
+    }, { ttlMs: REPLAY_STEP_TTL_MS });
+  } catch (_e) { return false; }
+  return won;
+}
+
 // Passkey factor — operator presents a WebAuthn assertion plus the
 // challenge/origin/RPID + the previously-enrolled credential record.
 // Phishing-resistant; the private key lives on the YubiKey, not in
@@ -990,8 +1083,20 @@ async function grant(opts) {
   }
 
   var factorOk = false;
+  var totpSecret = null;
   if (factorType === "totp") {
-    factorOk = _verifyTotpFactor(opts.factor).ok;
+    totpSecret = opts.factor && opts.factor.secret;
+    // Verify the code, then atomically reserve the step it matched as the act
+    // of acceptance. The reserve advances the per-(actor,secret) replay floor
+    // in one compare-and-set, so a code already redeemed inside the drift
+    // window — including by a concurrent grant for the same credential — is
+    // refused. (A read-then-commit floor raced: both grants read the old
+    // floor before either committed, so both passed.)
+    var totpResult = _verifyTotpFactor(opts.factor);
+    if (totpResult.ok && typeof totpResult.step === "number" &&
+        typeof totpSecret === "string" && totpSecret.length > 0) {
+      factorOk = await _reserveTotpStep(actorId, totpSecret, totpResult.step);
+    }
   } else if (factorType === "passkey") {
     factorOk = (await _verifyPasskeyFactor(opts.factor)).ok;
   }
@@ -1036,14 +1141,13 @@ async function grant(opts) {
     ip:                 ipFromReq,
     kwGrantHalf:        null,
   };
-  var sealed = cryptoField.sealRow("_blamejs_break_glass_grants", grantRow);
-  var keys = Object.keys(sealed);
-  var cols = keys.join(", ");
-  var qs   = keys.map(function () { return "?"; }).join(", ");
-  await clusterStorage.execute(
-    "INSERT INTO _blamejs_break_glass_grants (" + cols + ") VALUES (" + qs + ")",
-    keys.map(function (k) { return sealed[k]; })
-  );
+  var sealed = cryptoField.sealRow(GRANTS_TABLE, grantRow);
+  // BARE logical framework table — clusterStorage rewrites + placeholderizes;
+  // b.sql quotes every column + binds every sealed value.
+  var grantInsBuilt = sql.insert("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .values(sealed)
+    .toSql();
+  await clusterStorage.execute(grantInsBuilt.sql, grantInsBuilt.params);
 
   // Audit
   var reasonForAudit = _reasonForAudit(reason, policy.auditReasonStorage);
@@ -1086,6 +1190,78 @@ function _reasonForAudit(reason, mode) {
   return out;
 }
 
+// Enforce the grant's IP / session bindings at redemption. policy.set
+// documents pinIp / sessionPin as default-ON, and grant() captures
+// grantRow.ip / grantRow.sessionId at mint time — but without this gate
+// the bindings are stored-and-never-enforced (a grant minted from IP-A
+// would redeem from IP-B). Called BEFORE the SELECT-then-increment so a
+// mismatch does not consume a grant.
+//
+// FAIL-CLOSED: when a pin is requested but the binding was captured null
+// (e.g. an Express-shaped req whose IP requestHelpers.clientIp couldn't
+// read at mint time), the redemption is REFUSED rather than silently
+// skipped — a `grantRow.ip != null` short-circuit would defeat the pin
+// for exactly the requests whose binding capture failed.
+function _enforceGrantPins(policy, grantRow, redeemReq, actorFor) {
+  if (!policy) return;
+  if (policy.pinIp) {
+    if (grantRow.ip == null) {
+      audit.safeEmit({
+        action:   "breakglass.unsealrow",
+        outcome:  "denied",
+        actor:    actorFor(grantRow),
+        reason:   "grant-ip-binding-missing",
+        metadata: { grantId: grantRow._id, table: grantRow.scopeTable },
+      });
+      throw new BreakGlassError("breakglass/grant-ip-mismatch",
+        "unsealRow: grant " + grantRow._id + " has pinIp on but no IP was " +
+        "captured at mint (fail-closed) — re-mint from a request whose client " +
+        "IP the framework can resolve", true);
+    }
+    var redeemIp = requestHelpers.clientIp(redeemReq, { trustProxy: _trustProxy });
+    if (redeemIp !== grantRow.ip) {
+      audit.safeEmit({
+        action:   "breakglass.unsealrow",
+        outcome:  "denied",
+        actor:    actorFor(grantRow),
+        reason:   "grant-ip-mismatch",
+        metadata: { grantId: grantRow._id, table: grantRow.scopeTable },
+      });
+      throw new BreakGlassError("breakglass/grant-ip-mismatch",
+        "unsealRow: grant " + grantRow._id + " is pinned to its issuing IP " +
+        "and this redemption arrived from a different address", true);
+    }
+  }
+  if (policy.sessionPin) {
+    if (grantRow.sessionId == null) {
+      audit.safeEmit({
+        action:   "breakglass.unsealrow",
+        outcome:  "denied",
+        actor:    actorFor(grantRow),
+        reason:   "grant-session-binding-missing",
+        metadata: { grantId: grantRow._id, table: grantRow.scopeTable },
+      });
+      throw new BreakGlassError("breakglass/grant-session-mismatch",
+        "unsealRow: grant " + grantRow._id + " has sessionPin on but no " +
+        "session id was captured at mint (fail-closed) — re-mint from a " +
+        "request carrying req.session.id", true);
+    }
+    var redeemSession = (redeemReq && redeemReq.session && redeemReq.session.id) || null;
+    if (redeemSession !== grantRow.sessionId) {
+      audit.safeEmit({
+        action:   "breakglass.unsealrow",
+        outcome:  "denied",
+        actor:    actorFor(grantRow),
+        reason:   "grant-session-mismatch",
+        metadata: { grantId: grantRow._id, table: grantRow.scopeTable },
+      });
+      throw new BreakGlassError("breakglass/grant-session-mismatch",
+        "unsealRow: grant " + grantRow._id + " is pinned to its issuing " +
+        "session and this redemption arrived from a different session", true);
+    }
+  }
+}
+
 // ---- Use a grant ----
 
 /**
@@ -1137,16 +1313,16 @@ async function unsealRow(grantHandle, table, rowId, opts) {
     throw new BreakGlassError("breakglass/bad-grant-opts",
       "unsealRow: rowId is required");
   }
-  var grantRows = await clusterStorage.executeAll(
-    "SELECT * FROM _blamejs_break_glass_grants WHERE _id = ?",
-    [grantHandle.id]
-  );
+  var grantReadBuilt = sql.select("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .where("_id", grantHandle.id)
+    .toSql();
+  var grantRows = await clusterStorage.executeAll(grantReadBuilt.sql, grantReadBuilt.params);
   if (!grantRows || grantRows.length === 0) {
     throw new BreakGlassError("breakglass/grant-revoked",
       "unsealRow: grant " + grantHandle.id + " not found (deleted or never issued)", true);
   }
   var sealedGrant = grantRows[0];
-  var grantRow = cryptoField.unsealRow("_blamejs_break_glass_grants", sealedGrant);
+  var grantRow = cryptoField.unsealRow(GRANTS_TABLE, sealedGrant);
 
   // Table mismatch
   if (grantRow.scopeTable !== table) {
@@ -1195,35 +1371,53 @@ async function unsealRow(grantHandle, table, rowId, opts) {
       grantRow.maxRowsPerGrant + " allowed rows", true);
   }
 
+  // IP / session pin enforcement — BEFORE the SELECT-then-increment so a
+  // pin mismatch does not consume the grant. Fail-closed when a requested
+  // pin's binding was captured null (see _enforceGrantPins). The policy is
+  // fetched once here and reused for the Model-A/B unseal dispatch below.
+  var policy = await policyGet(table);
+  _enforceGrantPins(policy, grantRow, opts.req, _actorFor);
+
   // SELECT-before-increment — fetch the target row FIRST. If the row
   // doesn't exist (operator typo, race with row-deletion, etc.), the
   // grant should not be consumed. Without this ordering, a single
   // typo against `maxRowsPerGrant: 1` (the default) exhausts the
   // grant and forces the operator to re-do the step-up ceremony.
-  var rows = await clusterStorage.executeAll(
-    "SELECT * FROM " + '"' + table + '"' + " WHERE _id = ?",
-    [String(rowId)]
-  );
+  // Operator app table (validated identifier) — quoteName quotes it; it is
+  // not framework-rewritten.
+  var rowReadBuilt = sql.select(table, _appSqlOpts())
+    .where("_id", String(rowId))
+    .toSql();
+  var rows = await clusterStorage.executeAll(rowReadBuilt.sql, rowReadBuilt.params);
   if (!rows || rows.length === 0) {
     throw new BreakGlassError("breakglass/row-not-found",
       "unsealRow: " + table + "[" + rowId + "] not found", true);
   }
 
-  // Increment rowsConsumed (atomic UPDATE with WHERE rowsConsumed < cap
-  // so concurrent unseals can't both pass the runtime check above).
-  var updateRes = await clusterStorage.execute(
-    "UPDATE _blamejs_break_glass_grants " +
-    "SET rowsConsumed = rowsConsumed + 1 " +
-    "WHERE _id = ? AND rowsConsumed < maxRowsPerGrant AND " +
-    "(revokedAt IS NULL) AND expiresAt > ?",
-    [grantHandle.id, Date.now()]
-  );
+  // Increment rowsConsumed (atomic UPDATE with WHERE rowsConsumed < cap so
+  // concurrent unseals can't both pass the runtime check above). The
+  // rowsConsumed+1 RHS + the rowsConsumed<maxRowsPerGrant column comparison
+  // are guarded raw fragments (b.guardSql + placeholder/literal scan). The
+  // identifier quoting in those raw fragments is dialect-aware (backticks on
+  // MySQL, double-quotes on PG/SQLite) so the column references resolve as
+  // identifiers, not string literals, on the active backend.
+  var incDialect = clusterStorage.dialect();
+  var incBuilt = sql.update("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .setRaw("rowsConsumed", safeSql.quoteIdentifier("rowsConsumed", incDialect) + " + 1", [])
+    .where("_id", grantHandle.id)
+    .whereRaw(safeSql.quoteIdentifier("rowsConsumed", incDialect) + " < " +
+      safeSql.quoteIdentifier("maxRowsPerGrant", incDialect), [])
+    .whereNull("revokedAt")
+    .whereOp("expiresAt", ">", Date.now())
+    .toSql();
+  var updateRes = await clusterStorage.execute(incBuilt.sql, incBuilt.params);
   // executeAll-style result; some backends return rowsAffected, others a count.
   // Re-query to confirm the increment landed and get the post-increment counter.
-  var postRows = await clusterStorage.executeAll(
-    "SELECT rowsConsumed, revokedAt, expiresAt FROM _blamejs_break_glass_grants WHERE _id = ?",
-    [grantHandle.id]
-  );
+  var postReadBuilt = sql.select("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .columns(["rowsConsumed", "revokedAt", "expiresAt"])
+    .where("_id", grantHandle.id)
+    .toSql();
+  var postRows = await clusterStorage.executeAll(postReadBuilt.sql, postReadBuilt.params);
   if (!postRows || postRows.length === 0) {
     throw new BreakGlassError("breakglass/grant-revoked",
       "unsealRow: grant " + grantHandle.id + " disappeared during unseal", true);
@@ -1237,7 +1431,8 @@ async function unsealRow(grantHandle, table, rowId, opts) {
       "unsealRow: grant " + grantHandle.id + " was exhausted by a concurrent read", true);
   }
   void updateRes;
-  var policy = await policyGet(table);
+  // policy was fetched above for the pin enforcement; reuse it for the
+  // Model-A vs Model-B (cryptographic) unseal dispatch.
   var unsealedRow;
   if (policy && policy.cryptographic) {
     // Snapshot the raw glass-locked column ciphertexts BEFORE
@@ -1325,11 +1520,14 @@ async function revoke(grantId, opts) {
   }
   opts = opts || {};
   var nowMs = Date.now();
-  await clusterStorage.execute(
-    "UPDATE _blamejs_break_glass_grants SET revokedAt = ? " +
-    "WHERE _id = ? AND revokedAt IS NULL",
-    [nowMs, grantId]
-  );
+  // revokedAt IS NULL keeps the revoke idempotent (already-revoked grants
+  // keep their original timestamp).
+  var revBuilt = sql.update("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .set({ revokedAt: nowMs })
+    .where("_id", grantId)
+    .whereNull("revokedAt")
+    .toSql();
+  await clusterStorage.execute(revBuilt.sql, revBuilt.params);
   audit.safeEmit({
     action:   "breakglass.grant.revoked",
     outcome:  "success",
@@ -1372,19 +1570,25 @@ async function listActive(opts) {
   // Use cryptoField's computeDerived so the hash matches the table's
   // hashNamespace prefix — raw sha3Hash would produce a different value.
   var derived = cryptoField.computeDerived(
-    "_blamejs_break_glass_grants", "issuedToActorId", actorId
+    GRANTS_TABLE, "issuedToActorId", actorId
   );
   if (!derived) return [];
   var nowMs = Date.now();
-  var rows = await clusterStorage.executeAll(
-    "SELECT * FROM _blamejs_break_glass_grants " +
-    "WHERE issuedToActorHash = ? AND (revokedAt IS NULL) AND expiresAt > ? AND rowsConsumed < maxRowsPerGrant " +
-    "ORDER BY issuedAt DESC",
-    [derived.value, nowMs]
-  );
+  // rowsConsumed < maxRowsPerGrant is a column-to-column comparison (guarded
+  // raw fragment); every other predicate is structured.
+  var laDialect = clusterStorage.dialect();
+  var laBuilt = sql.select("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .where("issuedToActorHash", derived.value)
+    .whereNull("revokedAt")
+    .whereOp("expiresAt", ">", nowMs)
+    .whereRaw(safeSql.quoteIdentifier("rowsConsumed", laDialect) + " < " +
+      safeSql.quoteIdentifier("maxRowsPerGrant", laDialect), [])
+    .orderBy("issuedAt", "desc")
+    .toSql();
+  var rows = await clusterStorage.executeAll(laBuilt.sql, laBuilt.params);
   var out = [];
   for (var i = 0; i < (rows || []).length; i++) {
-    var u = cryptoField.unsealRow("_blamejs_break_glass_grants", rows[i]);
+    var u = cryptoField.unsealRow(GRANTS_TABLE, rows[i]);
     out.push({
       id:             u._id,
       scopeTable:     u.scopeTable,
@@ -1427,6 +1631,12 @@ async function listActive(opts) {
  * distinct `breakglass.grant.bypass` audit row so post-incident review
  * separates operator-initiated reads from scheduled-job reads.
  *
+ * This path is service-to-service: it consumes NO grant row, so the
+ * `pinIp` / `sessionPin` grant bindings enforced by `unsealRow` do not
+ * apply here. A grant that was minted with those pins is not redeemable
+ * through this surface — the bypass is gated solely by the
+ * `serviceAccountBypass` allowlist + required-role check.
+ *
  * @opts
  *   reason: string,   // operator-supplied reason recorded into the audit row
  *
@@ -1494,11 +1704,12 @@ async function unsealRowAsService(req, table, rowId, opts) {
   }
 
   // Fetch + unseal the row (Model A or Model B path, same as
-  // operator-initiated unsealRow).
-  var rows = await clusterStorage.executeAll(
-    "SELECT * FROM " + '"' + table + '"' + " WHERE _id = ?",
-    [String(rowId)]
-  );
+  // operator-initiated unsealRow). Operator app table — quoteName quotes it;
+  // it is not framework-rewritten.
+  var svcRowBuilt = sql.select(table, _appSqlOpts())
+    .where("_id", String(rowId))
+    .toSql();
+  var rows = await clusterStorage.executeAll(svcRowBuilt.sql, svcRowBuilt.params);
   if (!rows || rows.length === 0) {
     throw new BreakGlassError("breakglass/row-not-found",
       "unsealRowAsService: " + table + "[" + rowId + "] not found", true);
@@ -1572,24 +1783,22 @@ async function listActiveAll(opts) {
   _requireInit();
   opts = opts || {};
   var nowMs = Date.now();
-  var clauses = ["(revokedAt IS NULL)", "expiresAt > ?", "rowsConsumed < maxRowsPerGrant"];
-  var params = [nowMs];
-  if (opts.table) {
-    clauses.push("scopeTable = ?");
-    params.push(opts.table);
-  }
-  if (opts.since) {
-    clauses.push("issuedAt >= ?");
-    params.push(opts.since);
-  }
-  var rows = await clusterStorage.executeAll(
-    "SELECT * FROM _blamejs_break_glass_grants WHERE " + clauses.join(" AND ") +
-    " ORDER BY issuedAt DESC",
-    params
-  );
+  // rowsConsumed < maxRowsPerGrant is a column-to-column comparison (guarded
+  // raw fragment); the rest are structured predicates.
+  var laaDialect = clusterStorage.dialect();
+  var laaQb = sql.select("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .whereNull("revokedAt")
+    .whereOp("expiresAt", ">", nowMs)
+    .whereRaw(safeSql.quoteIdentifier("rowsConsumed", laaDialect) + " < " +
+      safeSql.quoteIdentifier("maxRowsPerGrant", laaDialect), []);
+  if (opts.table) laaQb.where("scopeTable", opts.table);
+  if (opts.since) laaQb.whereOp("issuedAt", ">=", opts.since);
+  laaQb.orderBy("issuedAt", "desc");
+  var laaBuilt = laaQb.toSql();
+  var rows = await clusterStorage.executeAll(laaBuilt.sql, laaBuilt.params);
   var out = [];
   for (var i = 0; i < (rows || []).length; i++) {
-    var u = cryptoField.unsealRow("_blamejs_break_glass_grants", rows[i]);
+    var u = cryptoField.unsealRow(GRANTS_TABLE, rows[i]);
     out.push({
       id:             u._id,
       issuedToActorId: u.issuedToActorId,
@@ -1646,31 +1855,28 @@ async function revokeAll(criteria, opts) {
       "revokeAll: at least one of { actorId, table } is required (refusing to mass-revoke without scope)");
   }
   opts = opts || {};
-  var clauses = ["revokedAt IS NULL"];
-  var params = [];
-  if (criteria.actorId) {
-    var derived = cryptoField.computeDerived(
-      "_blamejs_break_glass_grants", "issuedToActorId", criteria.actorId
-    );
-    if (derived) {
-      clauses.push("issuedToActorHash = ?");
-      params.push(derived.value);
-    }
-  }
-  if (criteria.table) {
-    clauses.push("scopeTable = ?");
-    params.push(criteria.table);
+  // The SELECT (snapshot ids) and UPDATE (apply revoke) share one predicate
+  // set; applyRevokeCriteria replays it onto either builder so the WHERE can
+  // never drift between the two.
+  var derived = criteria.actorId
+    ? cryptoField.computeDerived(GRANTS_TABLE, "issuedToActorId", criteria.actorId)
+    : null;
+  function applyRevokeCriteria(qb) {
+    qb.whereNull("revokedAt");
+    if (criteria.actorId && derived) qb.where("issuedToActorHash", derived.value);
+    if (criteria.table) qb.where("scopeTable", criteria.table);
+    return qb;
   }
   // Snapshot the to-be-revoked grant ids first so audit captures specifics.
-  var ids = await clusterStorage.executeAll(
-    "SELECT _id FROM _blamejs_break_glass_grants WHERE " + clauses.join(" AND "),
-    params
-  );
+  var idSelBuilt = applyRevokeCriteria(
+    sql.select("_blamejs_break_glass_grants", _sqlOpts()).columns(["_id"])   // allow:hand-rolled-sql
+  ).toSql();
+  var ids = await clusterStorage.executeAll(idSelBuilt.sql, idSelBuilt.params);
   var nowMs = Date.now();
-  await clusterStorage.execute(
-    "UPDATE _blamejs_break_glass_grants SET revokedAt = ? WHERE " + clauses.join(" AND "),
-    [nowMs].concat(params)
-  );
+  var revAllBuilt = applyRevokeCriteria(
+    sql.update("_blamejs_break_glass_grants", _sqlOpts()).set({ revokedAt: nowMs })   // allow:hand-rolled-sql
+  ).toSql();
+  await clusterStorage.execute(revAllBuilt.sql, revAllBuilt.params);
   audit.safeEmit({
     action:   "breakglass.admin.revokeall",
     outcome:  "success",
@@ -1691,11 +1897,12 @@ async function revokeAll(criteria, opts) {
 async function _sweepExpired(opts) {
   opts = opts || {};
   var nowMs = Date.now();
-  var expired = await clusterStorage.executeAll(
-    "SELECT _id, issuedToActorId, scopeTable, rowsConsumed FROM _blamejs_break_glass_grants " +
-    "WHERE revokedAt IS NULL AND expiresAt <= ?",
-    [nowMs]
-  );
+  var expiredBuilt = sql.select("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .columns(["_id", "issuedToActorId", "scopeTable", "rowsConsumed"])
+    .whereNull("revokedAt")
+    .whereOp("expiresAt", "<=", nowMs)
+    .toSql();
+  var expired = await clusterStorage.executeAll(expiredBuilt.sql, expiredBuilt.params);
   for (var i = 0; i < (expired || []).length; i++) {
     var row = expired[i];
     audit.safeEmit({
@@ -1705,11 +1912,12 @@ async function _sweepExpired(opts) {
       metadata: { grantId: row._id, table: row.scopeTable, rowsConsumed: Number(row.rowsConsumed) },
     });
   }
-  await clusterStorage.execute(
-    "UPDATE _blamejs_break_glass_grants SET revokedAt = ? " +
-    "WHERE revokedAt IS NULL AND expiresAt <= ?",
-    [nowMs, nowMs]
-  );
+  var sweepUpdBuilt = sql.update("_blamejs_break_glass_grants", _sqlOpts())   // allow:hand-rolled-sql
+    .set({ revokedAt: nowMs })
+    .whereNull("revokedAt")
+    .whereOp("expiresAt", "<=", nowMs)
+    .toSql();
+  await clusterStorage.execute(sweepUpdBuilt.sql, sweepUpdBuilt.params);
   return { expired: (expired || []).length };
 }