@blamejs/core 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,10 @@ 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.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,6 +51,8 @@ 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"); });
 
 // Errors — all 14 codes documented in the spec. `permanent: true`
@@ -97,6 +99,208 @@ 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);
+  // 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.
+  var rows = await clusterStorage.executeAll(
+    "SELECT serviceAccountBypassJson 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 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 serviceAccountBypassJson = ? 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) {
@@ -193,6 +404,7 @@ function _validatePolicySet(table, opts) {
       "policy.set: serviceAccountBypass ships in v0.5.2 — leave unset for v0.5.0");
   }
   return {
+    cryptographic:   opts.cryptographic === true,
     grantTtl:        grantTtl,
     maxRowsPerGrant: maxRows,
     reasonRequired:  opts.reasonRequired !== false,
@@ -212,7 +424,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,
@@ -592,7 +804,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 +817,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({
@@ -731,6 +978,12 @@ 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,
   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/package.json

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