@blamejs/core 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -8,6 +8,7 @@ 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

package/lib/break-glass.js

@@ -54,6 +54,7 @@ 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
@@ -67,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
@@ -135,19 +136,18 @@ function _kCell(dek, table, rowId, column) {
 
 async function _ensureDek(table) {
   if (dekCache.has(table)) return dekCache.get(table);
-  // The DEK lives in the policy row's serviceAccountBypassJson slot
-  // (repurposed in Model A; v0.5.0 explicitly rejected the slot, so
-  // it's unused in Model A rows). For Model B rows, we vault-seal the
-  // DEK and store it there. Pre-v1 schema: clean and simple.
+  // 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 serviceAccountBypassJson FROM _blamejs_break_glass_policies WHERE tableName = ?",
+    "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].serviceAccountBypassJson;
+  var sealed = rows[0].dekSealed;
   var dek;
   if (sealed) {
     dek = Buffer.from(vault().unseal(sealed), "base64");
@@ -155,7 +155,7 @@ async function _ensureDek(table) {
     dek = generateBytes(32);
     var sealedDek = vault().seal(dek.toString("base64"));
     await clusterStorage.execute(
-      "UPDATE _blamejs_break_glass_policies SET serviceAccountBypassJson = ? WHERE tableName = ?",
+      "UPDATE _blamejs_break_glass_policies SET dekSealed = ? WHERE tableName = ?",
       [sealedDek, table]
     );
   }
@@ -399,9 +399,35 @@ 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,
@@ -414,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,
   };
 }
 
@@ -433,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(),
   };
@@ -492,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),
   };
@@ -542,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") {
@@ -613,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) {
@@ -937,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) {
@@ -984,6 +1260,14 @@ module.exports = {
   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/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.1",
+  "version": "0.5.2",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",