@blamejs/core 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -6,6 +6,11 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.5.x
+
+- **0.5.1** (2026-04-30) — b.breakGlass: per-cell encryption + context binding + migrate
+- **0.5.0** (2026-04-30) — b.breakGlass: column-policy / row-enforcement step-up auth
+
 ## v0.4.x
 
 - **0.4.29** (2026-04-30) — primitive-drift sweep: second-pass remediation

package/lib/audit.js

@@ -201,7 +201,7 @@ var FRAMEWORK_NAMESPACES = [
   // Per-primitive namespaces — keep alphabetical
   "apikey",     // b.apiKey
   "backup",     // b.backup
-  "breakglass", // b.breakGlass — column-policy / row-enforcement step-up auth
+  "breakglass", // b.breakGlass — column-policy / row-enforcement step-up auth (audit namespace lowercased per the validator's `namespace.verb` rule, same convention as b.apiKey → apikey.*)
   "cache",      // b.cache
   "dkim",       // b.mail.dkim (DKIM-Signature generation events)
   "mail",       // b.mail (b.mail-bounce uses "system.mail.*")

package/lib/break-glass.js

@@ -40,7 +40,7 @@
 var audit = require("./audit");
 var C = require("./constants");
 var clusterStorage = require("./cluster-storage");
-var { generateToken, sha3Hash } = require("./crypto");
+var { generateBytes, generateToken, kdf, sha3Hash, encryptPacked, decryptPacked } = require("./crypto");
 var cryptoField = require("./crypto-field");
 var lazyRequire = require("./lazy-require");
 var observability = require("./observability");
@@ -51,7 +51,10 @@ var totp = require("./totp");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
+var vault = lazyRequire(function () { return require("./vault"); });
+
 var lockout = lazyRequire(function () { return require("./auth/lockout"); });
+var passkey = lazyRequire(function () { return require("./auth/passkey"); });
 
 // Errors — all 14 codes documented in the spec. `permanent: true`
 // means caller's input is bad (Tier-A); `permanent: false` means
@@ -65,7 +68,7 @@ var DEFAULT_MAX_ROWS        = 1;       // operator-locked: row-by-row auth
 var DEFAULT_REASON_MIN_LEN  = 12;
 var DEFAULT_LOCKED_BEHAVIOR = "throw"; // or "redact"
 var DEFAULT_AUDIT_REASON    = "cleartext";
-var ALLOWED_FACTORS         = ["totp"]; // passkey added in v0.5.2
+var ALLOWED_FACTORS         = ["totp", "passkey"];
 var ALLOWED_REASON_STORAGE  = ["cleartext", "hmac", "both"];
 
 // In-memory policy cache. Cluster-shared via the policies table; the
@@ -97,6 +100,207 @@ function _ensureFactorLockout() {
   return _factorLockout;
 }
 
+// ---- Cryptographic mode (Model B) — per-cell encryption with context binding ----
+//
+// Each policy in cryptographic mode has a per-policy DEK (data
+// encryption key) generated at first use. The DEK is vault-sealed so
+// it survives restarts. At cell encrypt time, the framework derives a
+// per-cell key K_cell = SHAKE256(DEK || table || rowId || column) so
+// every (table, rowId, column) triple gets a unique key. Encryption
+// uses XChaCha20-Poly1305 with AAD = SHA3-512(table || rowId || column)
+// — the AEAD tag itself is bound to the encryption context, so a
+// ciphertext from row A literally cannot be decrypted as row B even
+// with the same DEK.
+//
+// THREAT MODEL HONESTY: this provides defense-in-depth via per-cell
+// keys + encryption-context binding (cross-cell tampering / accidental
+// row-swap fails closed). It does NOT defend against vault-key
+// compromise alone — the DEK is still vault-recoverable. True
+// second-factor cryptographic gating ships in v0.5.2 with passkey
+// integration (the passkey private key lives on the YubiKey, not in
+// the framework, so a vault leak alone can't unwrap).
+
+// In-memory DEK cache. Keyed by table name. Cleared on _resetForTest.
+var dekCache = new Map();
+
+function _aadFor(table, rowId, column) {
+  return sha3Hash(table + "|" + String(rowId) + "|" + column);
+}
+
+function _kCell(dek, table, rowId, column) {
+  return kdf(Buffer.concat([
+    Buffer.isBuffer(dek) ? dek : Buffer.from(dek, "base64"),
+    Buffer.from("breakglass.cell|" + table + "|" + String(rowId) + "|" + column, "utf8"),
+  ]), 32);
+}
+
+async function _ensureDek(table) {
+  if (dekCache.has(table)) return dekCache.get(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]
+  );
+  if (!rows || rows.length === 0) {
+    throw new BreakGlassError("breakglass/policy-not-set",
+      "_ensureDek: no policy for table '" + table + "'", true);
+  }
+  var sealed = rows[0].dekSealed;
+  var dek;
+  if (sealed) {
+    dek = Buffer.from(vault().unseal(sealed), "base64");
+  } else {
+    dek = generateBytes(32);
+    var sealedDek = vault().seal(dek.toString("base64"));
+    await clusterStorage.execute(
+      "UPDATE _blamejs_break_glass_policies SET dekSealed = ? WHERE tableName = ?",
+      [sealedDek, table]
+    );
+  }
+  dekCache.set(table, dek);
+  return dek;
+}
+
+// Encrypt a single cell value with encryption context binding. Operators
+// in cryptographic mode use this at write time INSTEAD of letting
+// cryptoField.sealRow seal the column.
+async function encryptCell(plaintext, ctx) {
+  _requireInit();
+  if (!ctx || typeof ctx !== "object" ||
+      typeof ctx.table !== "string" || ctx.table.length === 0 ||
+      ctx.rowId === undefined || ctx.rowId === null ||
+      typeof ctx.column !== "string" || ctx.column.length === 0) {
+    throw new BreakGlassError("breakglass/bad-cell-ctx",
+      "encryptCell: ctx must be { table, rowId, column }");
+  }
+  var policy = await policyGet(ctx.table);
+  if (!policy || !policy.cryptographic) {
+    throw new BreakGlassError("breakglass/policy-not-set",
+      "encryptCell: table '" + ctx.table + "' is not in cryptographic mode " +
+      "(set policy.cryptographic = true to opt in)", true);
+  }
+  if (policy.columns.indexOf(ctx.column) === -1) {
+    throw new BreakGlassError("breakglass/grant-column-mismatch",
+      "encryptCell: column '" + ctx.column + "' is not glass-locked on '" + ctx.table + "'", true);
+  }
+  var dek = await _ensureDek(ctx.table);
+  var kCell = _kCell(dek, ctx.table, ctx.rowId, ctx.column);
+  var aad = _aadFor(ctx.table, ctx.rowId, ctx.column);
+  var pt = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(String(plaintext), "utf8");
+  var packed = encryptPacked(pt, kCell, aad);
+  return "bgcell:1:" + packed.toString("base64");
+}
+
+// Decrypt a cell value. Caller must hold a valid grant covering the
+// (table, column) — caller passes through unsealRow which gates this.
+// The encryption context (table, rowId, column) is passed both to the
+// key derivation AND the AAD; if the caller passes the wrong rowId
+// trying to "swap" ciphertexts between rows, decryption fails closed.
+async function decryptCell(ciphertext, ctx) {
+  _requireInit();
+  if (typeof ciphertext !== "string" || ciphertext.indexOf("bgcell:1:") !== 0) {
+    throw new BreakGlassError("breakglass/bad-ciphertext",
+      "decryptCell: expected 'bgcell:1:<base64>' format");
+  }
+  if (!ctx || typeof ctx !== "object") {
+    throw new BreakGlassError("breakglass/bad-cell-ctx",
+      "decryptCell: ctx must be { table, rowId, column }");
+  }
+  var dek = await _ensureDek(ctx.table);
+  var kCell = _kCell(dek, ctx.table, ctx.rowId, ctx.column);
+  var aad = _aadFor(ctx.table, ctx.rowId, ctx.column);
+  var packed = Buffer.from(ciphertext.slice("bgcell:1:".length), "base64");
+  return decryptPacked(packed, kCell, aad).toString("utf8");
+}
+
+// ---- Migration support ----
+//
+// Operator runs `b.breakGlass.migrate(table, opts)` (or the CLI
+// equivalent) to convert existing Model-A-sealed rows into Model B
+// per-cell-encrypted form. Each row's glass-locked columns are
+// unsealed via cryptoField, re-encrypted via encryptCell, and written
+// back. The migration is idempotent — a row already in Model B form
+// (column starts with "bgcell:") is skipped.
+
+async function migrate(table, opts) {
+  _requireInit();
+  opts = opts || {};
+  validateOpts(opts, ["batchSize", "callerOpts"], "breakGlass.migrate");
+  var policy = await policyGet(table);
+  if (!policy) {
+    throw new BreakGlassError("breakglass/policy-not-set",
+      "migrate: no policy for table '" + table + "'", true);
+  }
+  if (!policy.cryptographic) {
+    throw new BreakGlassError("breakglass/bad-policy",
+      "migrate: policy must be cryptographic: true to migrate to Model B", true);
+  }
+  var batchSize = opts.batchSize || 100;
+  var totalRows = 0;
+  var migratedRows = 0;
+  var skippedRows = 0;
+  var lastId = "";
+  // Iterate via _id-keyset paging so we don't load the whole table into memory.
+  while (true) {
+    var rows = await clusterStorage.executeAll(
+      "SELECT * FROM " + table + " WHERE _id > ? ORDER BY _id ASC LIMIT ?",
+      [lastId, batchSize]
+    );
+    if (!rows || rows.length === 0) break;
+    for (var i = 0; i < rows.length; i++) {
+      totalRows++;
+      var row = rows[i];
+      var unsealed = cryptoField.unsealRow(table, row);
+      var anyChanged = false;
+      var update = { _id: row._id };
+      for (var c = 0; c < policy.columns.length; c++) {
+        var col = policy.columns[c];
+        var current = unsealed[col];
+        if (current == null) continue;
+        if (typeof current === "string" && current.indexOf("bgcell:") === 0) {
+          continue;  // already migrated
+        }
+        var encrypted = await encryptCell(current, { table: table, rowId: row._id, column: col });
+        update[col] = encrypted;
+        anyChanged = true;
+      }
+      if (anyChanged) {
+        // Write Model B ciphertext directly — bypassing cryptoField so
+        // 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) {
+          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 " + table + " SET " + setSql + " WHERE _id = ?",
+            vals
+          );
+          migratedRows++;
+        }
+      } else {
+        skippedRows++;
+      }
+      lastId = row._id;
+    }
+    if (rows.length < batchSize) break;
+  }
+  audit.safeEmit({
+    action:   "breakglass.migrate",
+    outcome:  "success",
+    actor:    requestHelpers.resolveActorWithOverride(opts.callerOpts),
+    metadata: {
+      table:        table,
+      totalRows:    totalRows,
+      migratedRows: migratedRows,
+      skippedRows:  skippedRows,
+    },
+  });
+  return { table: table, totalRows: totalRows, migratedRows: migratedRows, skippedRows: skippedRows };
+}
+
 // ---- init ----
 
 function init(opts) {
@@ -110,6 +314,7 @@ function init(opts) {
 function _resetForTest() {
   initialized = false;
   policyCache.clear();
+  dekCache.clear();
   if (_factorLockoutCache && typeof _factorLockoutCache.close === "function") {
     try { _factorLockoutCache.close(); } catch (_e) { /* best-effort */ }
   }
@@ -163,10 +368,16 @@ function _validatePolicySet(table, opts) {
         " (passkey lands in v0.5.2)");
     }
   }
-  if (opts.cryptographic === true) {
+  // Model B (cryptographic mode) ships in v0.5.1. When enabled,
+  // glass-locked columns must be encrypted with `b.breakGlass.encryptCell`
+  // at write time (the framework can't auto-encrypt at write because
+  // policy-set may post-date existing data; operators run the migration
+  // CLI to convert existing rows). At unseal time, the row's
+  // glass-locked columns are decrypted via decryptCell with encryption
+  // context binding (table, rowId, column).
+  if (opts.cryptographic !== undefined && typeof opts.cryptographic !== "boolean") {
     throw new BreakGlassError("breakglass/bad-policy",
-      "policy.set: cryptographic mode (Model B) ships in v0.5.1 — " +
-      "set cryptographic: false (default) or omit for v0.5.0");
+      "policy.set: cryptographic must be a boolean");
   }
   var grantTtl = opts.grantTtl != null ? opts.grantTtl : DEFAULT_GRANT_TTL_MS;
   if (typeof grantTtl !== "number" || !isFinite(grantTtl) || grantTtl <= 0) {
@@ -188,11 +399,38 @@ function _validatePolicySet(table, opts) {
     throw new BreakGlassError("breakglass/bad-policy",
       "policy.set: auditReasonStorage must be one of " + ALLOWED_REASON_STORAGE.join("/"));
   }
+  // Service-account bypass: explicit opt-in per table. Operators
+  // declare the apiKey ids that may bypass + a required role; the
+  // framework requires BOTH to grant the bypass. Without this opt set,
+  // there is NO bypass path — every read of a glass-locked column
+  // requires a fresh grant.
+  var serviceAccountBypass = null;
   if (opts.serviceAccountBypass != null && opts.serviceAccountBypass !== false) {
-    throw new BreakGlassError("breakglass/bad-policy",
-      "policy.set: serviceAccountBypass ships in v0.5.2 — leave unset for v0.5.0");
+    var sab = opts.serviceAccountBypass;
+    if (!sab || typeof sab !== "object") {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: serviceAccountBypass must be an object { enabled, apiKeyIds, requireRole }");
+    }
+    if (sab.enabled !== true) {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: serviceAccountBypass.enabled must be true (set serviceAccountBypass: false to disable)");
+    }
+    if (!Array.isArray(sab.apiKeyIds) || sab.apiKeyIds.length === 0) {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: serviceAccountBypass.apiKeyIds must be a non-empty array of apiKey ids");
+    }
+    if (typeof sab.requireRole !== "string" || sab.requireRole.length === 0) {
+      throw new BreakGlassError("breakglass/bad-policy",
+        "policy.set: serviceAccountBypass.requireRole must be a non-empty role / scope string");
+    }
+    serviceAccountBypass = {
+      enabled:     true,
+      apiKeyIds:   sab.apiKeyIds.slice(),
+      requireRole: sab.requireRole,
+    };
   }
   return {
+    cryptographic:   opts.cryptographic === true,
     grantTtl:        grantTtl,
     maxRowsPerGrant: maxRows,
     reasonRequired:  opts.reasonRequired !== false,
@@ -202,6 +440,7 @@ function _validatePolicySet(table, opts) {
     onLockedAccess:  opts.onLockedAccess || DEFAULT_LOCKED_BEHAVIOR,
     requireScope:    opts.requireScope != null ? opts.requireScope : null,
     auditReasonStorage: opts.auditReasonStorage || DEFAULT_AUDIT_REASON,
+    serviceAccountBypass: serviceAccountBypass,
   };
 }
 
@@ -212,7 +451,7 @@ async function policySet(table, opts, callerOpts) {
     tableName:                table,
     columnsJson:              JSON.stringify(opts.columns),
     factorsJson:              JSON.stringify(opts.factors),
-    cryptographic:            0,
+    cryptographic:            validated.cryptographic ? 1 : 0,
     grantTtlMs:               validated.grantTtl,
     maxRowsPerGrant:          validated.maxRowsPerGrant,
     reasonRequired:           validated.reasonRequired ? 1 : 0,
@@ -221,7 +460,9 @@ async function policySet(table, opts, callerOpts) {
     sessionPin:               validated.sessionPin ? 1 : 0,
     onLockedAccess:           validated.onLockedAccess,
     requireScope:             validated.requireScope,
-    serviceAccountBypassJson: null,
+    serviceAccountBypassJson: validated.serviceAccountBypass
+      ? JSON.stringify(validated.serviceAccountBypass)
+      : null,
     auditReasonStorage:       validated.auditReasonStorage,
     updatedAt:                Date.now(),
   };
@@ -280,6 +521,9 @@ async function policyGet(table) {
     sessionPin:         unsealed.sessionPin === 1,
     onLockedAccess:     unsealed.onLockedAccess,
     requireScope:       unsealed.requireScope,
+    serviceAccountBypass: unsealed.serviceAccountBypassJson
+      ? safeJson.parse(unsealed.serviceAccountBypassJson, { maxBytes: C.BYTES.kib(8) })
+      : null,
     auditReasonStorage: unsealed.auditReasonStorage,
     updatedAt:          Number(unsealed.updatedAt),
   };
@@ -330,6 +574,34 @@ function _verifyTotpFactor(factor) {
   return { ok: verified !== false, step: verified };
 }
 
+// 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
+// the framework's vault. v0.5.2 uses passkey for identity verification
+// to gate grant issuance; PRF-derived per-policy DEK material (which
+// would give true vault-key-alone-doesn't-decrypt defense) is a
+// follow-up.
+async function _verifyPasskeyFactor(factor) {
+  if (!factor || typeof factor !== "object") return { ok: false };
+  if (!factor.response || !factor.expectedChallenge ||
+      !factor.expectedOrigin || !factor.expectedRPID || !factor.credential) {
+    return { ok: false };
+  }
+  try {
+    var result = await passkey().verifyAuthentication({
+      response:                factor.response,
+      expectedChallenge:       factor.expectedChallenge,
+      expectedOrigin:          factor.expectedOrigin,
+      expectedRPID:            factor.expectedRPID,
+      credential:              factor.credential,
+      requireUserVerification: factor.requireUserVerification !== false,
+    });
+    return { ok: result && result.verified === true };
+  } catch (_e) {
+    return { ok: false };
+  }
+}
+
 async function grant(opts) {
   _requireInit();
   if (!opts || typeof opts !== "object") {
@@ -401,6 +673,8 @@ async function grant(opts) {
   var factorOk = false;
   if (factorType === "totp") {
     factorOk = _verifyTotpFactor(opts.factor).ok;
+  } else if (factorType === "passkey") {
+    factorOk = (await _verifyPasskeyFactor(opts.factor)).ok;
   }
 
   if (!factorOk) {
@@ -592,7 +866,11 @@ async function unsealRow(grantHandle, table, rowId) {
   }
   void updateRes;
 
-  // Fetch + unseal the target row through cryptoField
+  // Fetch + unseal the target row. Model A goes straight through
+  // cryptoField; Model B reads the row, lets cryptoField unseal the
+  // non-glass-locked columns, and then decryptCell handles the
+  // glass-locked columns separately (their ciphertext was written
+  // by encryptCell at app-write time, not by cryptoField.sealRow).
   var rows = await clusterStorage.executeAll(
     "SELECT * FROM " + table + " WHERE _id = ?",
     [String(rowId)]
@@ -601,12 +879,43 @@ async function unsealRow(grantHandle, table, rowId) {
     throw new BreakGlassError("breakglass/row-not-found",
       "unsealRow: " + table + "[" + rowId + "] not found", true);
   }
-  var unsealedRow = cryptoField.unsealRow(table, rows[0]);
+  var policy = await policyGet(table);
+  var unsealedRow;
+  if (policy && policy.cryptographic) {
+    // Snapshot the raw glass-locked column ciphertexts BEFORE
+    // cryptoField.unsealRow runs — cryptoField doesn't know about the
+    // bgcell: format and would no-op (or error) on it. Then unseal the
+    // rest of the row, then decrypt the glass-locked columns via
+    // decryptCell with encryption-context binding.
+    var rawCipher = {};
+    for (var c = 0; c < policy.columns.length; c++) {
+      rawCipher[policy.columns[c]] = rows[0][policy.columns[c]];
+    }
+    var rowMinusLocked = Object.assign({}, rows[0]);
+    for (var c2 = 0; c2 < policy.columns.length; c2++) {
+      delete rowMinusLocked[policy.columns[c2]];
+    }
+    unsealedRow = cryptoField.unsealRow(table, rowMinusLocked);
+    for (var c3 = 0; c3 < policy.columns.length; c3++) {
+      var col = policy.columns[c3];
+      if (rawCipher[col] == null) continue;
+      try {
+        unsealedRow[col] = await decryptCell(rawCipher[col],
+          { table: table, rowId: String(rowId), column: col });
+      } catch (e) {
+        throw new BreakGlassError("breakglass/cell-decrypt-failed",
+          "unsealRow: cell decrypt failed for " + table + "[" + rowId +
+          "]." + col + " (was the row migrated to Model B?): " +
+          ((e && e.message) || String(e)), true);
+      }
+    }
+  } else {
+    unsealedRow = cryptoField.unsealRow(table, rows[0]);
+  }
 
   // Per-row audit. The grant's reasonSealed is already cleartext after
   // unsealRow on the grant; pass it into the audit row honoring the
   // policy's auditReasonStorage mode.
-  var policy = await policyGet(table);
   var reasonForAudit = _reasonForAudit(grantRow.reasonSealed || "",
     policy ? policy.auditReasonStorage : DEFAULT_AUDIT_REASON);
   audit.safeEmit({
@@ -690,6 +999,220 @@ async function listActive(opts) {
   return out;
 }
 
+// ---- Service-account bypass ----
+//
+// Some legitimate workloads (nightly de-identification, scheduled
+// compliance reports) need PHI access without a human at the
+// keyboard. The framework refuses to silently bypass — operators
+// declare explicit service-account bypasses per-table with an apiKey
+// allowlist + required role. Both must match (verified apiKey id is
+// in the allowlist AND the apiKey carries the required role/scope)
+// before the bypass is granted. Each bypass emits its own distinct
+// audit row so post-incident review can distinguish operator-initiated
+// from service-initiated reads.
+
+async function unsealRowAsService(req, table, rowId, opts) {
+  _requireInit();
+  opts = opts || {};
+  if (!req || typeof req !== "object") {
+    throw new BreakGlassError("breakglass/bad-grant-opts",
+      "unsealRowAsService: req is required (with verified req.apiKey)");
+  }
+  if (typeof table !== "string" || table.length === 0) {
+    throw new BreakGlassError("breakglass/bad-grant-opts",
+      "unsealRowAsService: table must be a non-empty string");
+  }
+  var policy = await policyGet(table);
+  if (!policy) {
+    throw new BreakGlassError("breakglass/policy-not-set",
+      "unsealRowAsService: no break-glass policy for table '" + table + "'", true);
+  }
+  if (!policy.serviceAccountBypass) {
+    throw new BreakGlassError("breakglass/bypass-not-configured",
+      "unsealRowAsService: serviceAccountBypass is not configured for '" + table + "'", true);
+  }
+  var apiKeyOnReq = req.apiKey;
+  if (!apiKeyOnReq || typeof apiKeyOnReq.id !== "string") {
+    throw new BreakGlassError("breakglass/bypass-no-apikey",
+      "unsealRowAsService: req.apiKey.id is required (operator must run b.middleware.requireApiKey before this path)", true);
+  }
+  if (policy.serviceAccountBypass.apiKeyIds.indexOf(apiKeyOnReq.id) === -1) {
+    audit.safeEmit({
+      action:   "breakglass.grant.bypass",
+      outcome:  "denied",
+      actor:    requestHelpers.extractActorContext(req),
+      reason:   "apikey-not-in-allowlist",
+      metadata: { table: table, rowId: String(rowId), apiKeyId: apiKeyOnReq.id },
+    });
+    throw new BreakGlassError("breakglass/bypass-unauthorized",
+      "unsealRowAsService: apiKey '" + apiKeyOnReq.id +
+      "' is not in the bypass allowlist for '" + table + "'", true);
+  }
+  // Role check — actor must carry policy.serviceAccountBypass.requireRole
+  // either as a direct scope or via b.permissions.check resolution.
+  var actorScopes = Array.isArray(apiKeyOnReq.scopes) ? apiKeyOnReq.scopes :
+                    Array.isArray(apiKeyOnReq.roles)  ? apiKeyOnReq.roles :
+                    [];
+  var requiredRole = policy.serviceAccountBypass.requireRole;
+  var hasRole = actorScopes.indexOf(requiredRole) !== -1;
+  if (!hasRole) {
+    audit.safeEmit({
+      action:   "breakglass.grant.bypass",
+      outcome:  "denied",
+      actor:    requestHelpers.extractActorContext(req),
+      reason:   "missing-role",
+      metadata: { table: table, rowId: String(rowId), apiKeyId: apiKeyOnReq.id, requiredRole: requiredRole },
+    });
+    throw new BreakGlassError("breakglass/bypass-unauthorized",
+      "unsealRowAsService: apiKey '" + apiKeyOnReq.id +
+      "' lacks required role '" + requiredRole + "'", true);
+  }
+
+  // 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)]
+  );
+  if (!rows || rows.length === 0) {
+    throw new BreakGlassError("breakglass/row-not-found",
+      "unsealRowAsService: " + table + "[" + rowId + "] not found", true);
+  }
+  var unsealedRow;
+  if (policy.cryptographic) {
+    var rawCipher = {};
+    for (var c = 0; c < policy.columns.length; c++) rawCipher[policy.columns[c]] = rows[0][policy.columns[c]];
+    var rowMinusLocked = Object.assign({}, rows[0]);
+    for (var c2 = 0; c2 < policy.columns.length; c2++) delete rowMinusLocked[policy.columns[c2]];
+    unsealedRow = cryptoField.unsealRow(table, rowMinusLocked);
+    for (var c3 = 0; c3 < policy.columns.length; c3++) {
+      var col = policy.columns[c3];
+      if (rawCipher[col] == null) continue;
+      unsealedRow[col] = await decryptCell(rawCipher[col],
+        { table: table, rowId: String(rowId), column: col });
+    }
+  } else {
+    unsealedRow = cryptoField.unsealRow(table, rows[0]);
+  }
+
+  audit.safeEmit({
+    action:   "breakglass.grant.bypass",
+    outcome:  "success",
+    actor:    requestHelpers.extractActorContext(req),
+    reason:   typeof opts.reason === "string" ? opts.reason : null,
+    metadata: {
+      table:        table,
+      rowId:        String(rowId),
+      apiKeyId:     apiKeyOnReq.id,
+      requiredRole: requiredRole,
+      columns:      policy.columns.slice(),
+    },
+  });
+  observability.event("breakglass.grant.bypass", { table: table });
+  return unsealedRow;
+}
+
+// ---- Admin tools ----
+//
+// `listActiveAll` returns every active grant (across all actors) —
+// for security-team dashboards and offboarding workflows.
+// `revokeAll` mass-revokes grants matching criteria — used by IR
+// teams when an account is suspected compromised. Both require
+// admin scope (operator wires via opts.requireScope or their own gate).
+
+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
+  );
+  var out = [];
+  for (var i = 0; i < (rows || []).length; i++) {
+    var u = cryptoField.unsealRow("_blamejs_break_glass_grants", rows[i]);
+    out.push({
+      id:             u._id,
+      issuedToActorId: u.issuedToActorId,
+      scopeTable:     u.scopeTable,
+      scopeColumns:   safeJson.parse(u.scopeColumnsJson || "[]", { maxBytes: C.BYTES.kib(64) }),
+      factorType:     u.factorType,
+      issuedAt:       Number(u.issuedAt),
+      expiresAt:      Number(u.expiresAt),
+      rowsRemaining:  Number(u.maxRowsPerGrant) - Number(u.rowsConsumed),
+    });
+  }
+  audit.safeEmit({
+    action:   "breakglass.admin.listactiveall",
+    outcome:  "success",
+    actor:    requestHelpers.resolveActorWithOverride(opts.callerOpts),
+    metadata: { resultCount: out.length, filterTable: opts.table || null },
+  });
+  return out;
+}
+
+async function revokeAll(criteria, opts) {
+  _requireInit();
+  if (!criteria || typeof criteria !== "object") {
+    throw new BreakGlassError("breakglass/bad-revoke-criteria",
+      "revokeAll: criteria is required ({ actorId?, table? })");
+  }
+  if (!criteria.actorId && !criteria.table) {
+    throw new BreakGlassError("breakglass/bad-revoke-criteria",
+      "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);
+  }
+  // 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 nowMs = Date.now();
+  await clusterStorage.execute(
+    "UPDATE _blamejs_break_glass_grants SET revokedAt = ? WHERE " + clauses.join(" AND "),
+    [nowMs].concat(params)
+  );
+  audit.safeEmit({
+    action:   "breakglass.admin.revokeall",
+    outcome:  "success",
+    actor:    requestHelpers.resolveActorWithOverride(opts.callerOpts),
+    reason:   typeof criteria.reason === "string" ? criteria.reason : null,
+    metadata: {
+      filterActorId: criteria.actorId || null,
+      filterTable:   criteria.table || null,
+      revokedCount:  (ids || []).length,
+      revokedIds:    (ids || []).map(function (r) { return r._id; }),
+    },
+  });
+  return { revokedCount: (ids || []).length };
+}
+
 // ---- Sweep (best-effort cleanup of expired grants) ----
 
 async function _sweepExpired(opts) {
@@ -731,6 +1254,20 @@ module.exports = {
   unsealRow:        unsealRow,
   revoke:           revoke,
   listActive:       listActive,
+  // Cryptographic mode (Model B) — per-cell encryption with context
+  // binding. Operators in cryptographic mode call encryptCell at write
+  // time; unsealRow auto-routes to decryptCell for glass-locked columns.
+  encryptCell:      encryptCell,
+  decryptCell:      decryptCell,
+  migrate:          migrate,
+  // Service-account bypass — operator-declared per-table, gated by
+  // (apiKey id in allowlist) AND (apiKey carries required role).
+  unsealRowAsService: unsealRowAsService,
+  // Admin tools — for security-team dashboards (listActiveAll) and
+  // incident-response offboarding (revokeAll). Operators wire their
+  // own gate (requireScope or middleware) on the calling routes.
+  listActiveAll:    listActiveAll,
+  revokeAll:        revokeAll,
   BreakGlassError:  BreakGlassError,
 
   // Test-only / sweep — operators with active grant volume wire this

package/lib/crypto.js

@@ -206,9 +206,16 @@ function decryptEnvelope(packed, privateKeys) {
 }
 
 // ---- Symmetric buffer encrypt/decrypt (for storage) ----
-function encryptPacked(buffer, key) {
+//
+// Optional `aad` (additional authenticated data) is mixed into the
+// Poly1305 tag — encrypt-time and decrypt-time AAD must match exactly
+// or decrypt fails. Used by primitives that want encryption-context
+// binding (b.breakGlass.encryptCell binds (table, rowId, column) so a
+// ciphertext from row A literally cannot decrypt as row B even with
+// the same key).
+function encryptPacked(buffer, key, aad) {
   var nonce = random(24);
-  var ct = xchacha20poly1305(key, nonce).encrypt(buffer);
+  var ct = xchacha20poly1305(key, nonce, aad ? Buffer.from(aad) : undefined).encrypt(buffer);
   return Buffer.concat([
     Buffer.from([C.FORMAT.XCHACHA20_POLY1305]),
     Buffer.from(nonce),
@@ -216,12 +223,13 @@ function encryptPacked(buffer, key) {
   ]);
 }
 
-function decryptPacked(packed, key) {
+function decryptPacked(packed, key, aad) {
   if (packed[0] !== C.FORMAT.XCHACHA20_POLY1305) {
     throw new Error("Invalid packed format: unsupported version");
   }
   return Buffer.from(
-    xchacha20poly1305(key, packed.subarray(1, 25)).decrypt(packed.subarray(25))
+    xchacha20poly1305(key, packed.subarray(1, 25), aad ? Buffer.from(aad) : undefined)
+      .decrypt(packed.subarray(25))
   );
 }
 

package/lib/db.js

@@ -446,6 +446,7 @@ var FRAMEWORK_SCHEMA = [
       onLockedAccess:             "TEXT NOT NULL DEFAULT 'throw'",
       requireScope:               "TEXT",
       serviceAccountBypassJson:   "TEXT",
+      dekSealed:                  "TEXT",
       auditReasonStorage:         "TEXT NOT NULL DEFAULT 'cleartext'",
       updatedAt:                  "INTEGER NOT NULL",
     },

package/lib/framework-schema.js

@@ -584,6 +584,7 @@ function _breakGlassPoliciesDDL(dialect) {
       "  onLockedAccess             TEXT NOT NULL DEFAULT 'throw'," +
       "  requireScope               TEXT," +
       "  serviceAccountBypassJson   TEXT," +
+      "  dekSealed                  TEXT," +
       "  auditReasonStorage         TEXT NOT NULL DEFAULT 'cleartext'," +
       "  updatedAt                  " + t.INT + " NOT NULL" +
       ")",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",