@blamejs/core 0.14.22 → 0.14.25

package/lib/db-query.js

@@ -34,6 +34,122 @@ var safeJson = require("./safe-json");
 var safeJsonPath = require("./safe-jsonpath");
 var safeSql = require("./safe-sql");
 var audit = require("./audit");
+var lazyRequire = require("./lazy-require");
+var { DbQueryError } = require("./framework-error");
+
+// Circular load — db.js requires db-query at module scope, so the
+// residency gate reaches back for getDataResidency() lazily.
+var db = lazyRequire(function () { return require("./db"); });
+
+// Cross-border regulated postures live on b.compliance
+// (CROSS_BORDER_REGULATED_POSTURES — one vocabulary shared with
+// external-db's gate): under these, a residency mismatch REFUSES the
+// write; under anything else the gates emit an advisory audit and
+// pass (backward-compatible).
+function _postureState() {
+  try {
+    var compliance = require("./compliance");                                     // allow:inline-require — defensive against optional load
+    var posture = compliance.current();
+    return { posture: posture, regulated: compliance.isCrossBorderRegulated(posture) };
+  } catch (_e) { return { posture: null, regulated: false }; }
+}
+
+// Local-SQLite write-residency gate (GDPR Art 44-46 / PIPL Art 38 /
+// DPDP §16 cross-border transfer restrictions). Runs on the PLAINTEXT
+// row before sealRow so the tag column is readable even when other
+// columns seal. Two layers:
+//
+//   1. Per-ROW tag (declarePerRowResidency): on INSERT the declared
+//      column must be present and within allowedTags; under a
+//      regulated posture a tag outside the deployment's region set
+//      ({ region } + allowedStorageRegions from db.init's
+//      dataResidency) refuses the write. UPDATEs gate only when the
+//      change set touches the residency column (an update that does
+//      not move residency is not a transfer).
+//   2. Per-COLUMN tags (declareColumnResidency): the long-advertised
+//      assertColumnResidency gate, enforced here against the
+//      deployment region. Operators tag columns with the region
+//      value their dataResidency declares.
+//
+// Unregulated postures audit (drop-silent) and pass; tables with no
+// declaration are untouched.
+function _assertLocalResidency(table, plaintextRow, op) {
+  var spec = cryptoField.getPerRowResidency(table);
+  var colMap = cryptoField.getColumnResidency(table);
+  if (!spec && !colMap) return;
+
+  var residency = null;
+  try { residency = db().getDataResidency(); } catch (_e) { residency = null; }
+  var region = residency && residency.region ? residency.region : null;
+  var allowedRegions = region
+    ? [region].concat(Array.isArray(residency.allowedStorageRegions)
+        ? residency.allowedStorageRegions : [])
+    : null;
+  var state = _postureState();
+  var posture = state.posture;
+  var regulated = state.regulated;
+
+  if (spec) {
+    var tag = plaintextRow[spec.residencyColumn];
+    var tagPresent = tag !== undefined && tag !== null;
+    var colInChangeSet = Object.prototype.hasOwnProperty.call(plaintextRow, spec.residencyColumn);
+    if (op === "insert" && !tagPresent) {
+      throw new DbQueryError("db-query/row-residency-tag-missing",
+        op + ": table '" + table + "' declares per-row residency on column '" +
+        spec.residencyColumn + "' — every inserted row must carry a tag from [" +
+        spec.allowedTags.join(", ") + "]", true);
+    }
+    // An UPDATE that explicitly sets the residency column to null /
+    // undefined would clear the row's region binding (INSERT refuses a
+    // missing tag; the same row must not be nullable into an untagged
+    // state on update). UPDATEs that don't touch the column pass.
+    if (op === "update" && colInChangeSet && !tagPresent) {
+      throw new DbQueryError("db-query/row-residency-tag-missing",
+        op + ": table '" + table + "' residency column '" + spec.residencyColumn +
+        "' cannot be cleared — set a tag from [" + spec.allowedTags.join(", ") + "]", true);
+    }
+    if (tagPresent) {
+      if (typeof tag !== "string" || spec.allowedTags.indexOf(tag) === -1) {
+        throw new DbQueryError("db-query/row-residency-tag-invalid",
+          op + ": table '" + table + "' residency tag '" + tag +
+          "' is not in allowedTags [" + spec.allowedTags.join(", ") + "]", true);
+      }
+      if (tag !== "global" && tag !== "unrestricted" && allowedRegions &&
+          allowedRegions.indexOf(tag) === -1) {
+        if (regulated) {
+          audit.safeEmit({ action: "db.residency.gate.rejected", outcome: "denied",
+            metadata: { table: table, rowTag: tag, region: region, posture: posture,
+                        operation: op, scope: "local" } });
+          throw new DbQueryError("db-query/row-residency-local-mismatch",
+            op + ": row residency tag '" + tag + "' is outside this deployment's " +
+            "region set [" + allowedRegions.join(", ") + "] under '" + posture +
+            "' posture (cross-border transfer refused)", true);
+        }
+        audit.safeEmit({ action: "db.residency.gate.advisory", outcome: "info",
+          metadata: { table: table, rowTag: tag, region: region, posture: posture || null,
+                      operation: op, scope: "local" } });
+      }
+    }
+  }
+
+  if (colMap && region) {
+    var refusal = cryptoField.assertColumnResidency(table, plaintextRow, { backendTag: region });
+    if (refusal) {
+      if (regulated) {
+        audit.safeEmit({ action: "db.column_residency.gate.rejected", outcome: "denied",
+          metadata: { table: refusal.table, column: refusal.column, want: refusal.want,
+                      got: refusal.got, posture: posture, operation: op, scope: "local" } });
+        throw new DbQueryError("db-query/column-residency-mismatch",
+          op + ": column '" + refusal.column + "' on table '" + refusal.table +
+          "' is bound to residency '" + refusal.want + "' but this deployment's " +
+          "region is '" + refusal.got + "' under '" + posture + "' posture", true);
+      }
+      audit.safeEmit({ action: "db.residency.gate.advisory", outcome: "info",
+        metadata: { table: refusal.table, column: refusal.column, want: refusal.want,
+                    got: refusal.got, posture: posture || null, operation: op, scope: "local" } });
+    }
+  }
+}
 
 // "@>" / "?" / "?|" / "?&" are JSONB containment + key-existence
 // operators. Routed through safeJsonPath validation before binding so
@@ -393,7 +509,9 @@ class Query {
               this._whereClause() + this._orderLimitOffset() + " LIMIT 1";
     var stmt = this._db.prepare(sql);
     var row = stmt.get.apply(stmt, this._whereParams);
-    return row ? cryptoField.unsealRow(this._cryptoFieldKey(), row) : null;
+    // 4th arg (dbHandle) lets unsealRow fetch + unwrap the row-scoped
+    // K_row for vault.row: cells (declarePerRowKey tables).
+    return row ? cryptoField.unsealRow(this._cryptoFieldKey(), row, undefined, this._db) : null;
   }
 
   all() {
@@ -403,8 +521,9 @@ class Query {
     var rows = stmt.all.apply(stmt, this._whereParams);
     var out = new Array(rows.length);
     var key = this._cryptoFieldKey();
+    var dbHandle = this._db;
     for (var i = 0; i < rows.length; i++) {
-      out[i] = cryptoField.unsealRow(key, rows[i]);
+      out[i] = cryptoField.unsealRow(key, rows[i], undefined, dbHandle);
     }
     return out;
   }
@@ -433,6 +552,7 @@ class Query {
     }
     var stmt = this._db.prepare(sql);
     var key = this._cryptoFieldKey();
+    var dbHandle = this._db;
     var iter;
     try { iter = stmt.iterate.apply(stmt, this._whereParams); }
     catch (e) {
@@ -454,7 +574,7 @@ class Query {
           var step = iter.next();
           if (step.done) { this.push(null); return; }
           emitted += 1;
-          this.push(cryptoField.unsealRow(key, step.value));
+          this.push(cryptoField.unsealRow(key, step.value, undefined, dbHandle));
         } catch (e) {
           this.destroy(e);
         }
@@ -477,7 +597,22 @@ class Query {
     if (withId._id === undefined || withId._id === null) {
       withId._id = generateToken(C.BYTES.bytes(16));
     }
-    var sealed = cryptoField.sealRow(this._cryptoFieldKey(), withId);
+    // Residency gates read the PLAINTEXT row (the tag column must be
+    // inspectable even when sibling columns seal below).
+    _assertLocalResidency(this._cryptoFieldKey(), withId, "insert");
+    // Per-row-key tables (declarePerRowKey): materialize a fresh K_row
+    // BEFORE sealRow so sealed columns encrypt under the row-scoped key
+    // (vault.row: cells). rowId MUST be withId._id — the same value
+    // b.subject.eraseHard / b.retention destroy on, so a later shred
+    // makes these cells undecryptable. Materialize stores the random
+    // row-secret AAD-sealed in _blamejs_per_row_keys.
+    var sealOpts;
+    var cfKey = this._cryptoFieldKey();
+    if (cryptoField.hasPerRowKey(cfKey)) {
+      var kRow = cryptoField.materializePerRowKey(cfKey, withId._id, this._db);
+      sealOpts = { kRow: kRow, rowId: withId._id };
+    }
+    var sealed = cryptoField.sealRow(cfKey, withId, sealOpts);
     var cols = Object.keys(sealed);
     var placeholders = cols.map(function () { return "?"; }).join(", ");
     var quotedCols = cols.map(function (c) { return '"' + c + '"'; }).join(", ");
@@ -514,7 +649,20 @@ class Query {
     if (this._where.length === 0) {
       throw new Error("refusing unconditional update — call where(...) first");
     }
-    var sealed = cryptoField.sealRow(this._cryptoFieldKey(), changes);
+    // Residency gates on the plaintext change set — an UPDATE that
+    // touches the residency tag (or a region-bound column) is a
+    // transfer and goes through the same refusal matrix as INSERT.
+    _assertLocalResidency(this._cryptoFieldKey(), changes, "update");
+    var cfKey = this._cryptoFieldKey();
+    // Per-row-key tables: sealed columns must re-encrypt under EACH
+    // affected row's own K_row, so a single set-based UPDATE can't seal
+    // one value across rows. Resolve the affected _id set, then seal +
+    // write each row under its row-scoped key. Idempotent materialize
+    // re-derives the existing K_row (created on INSERT).
+    if (cryptoField.hasPerRowKey(cfKey)) {
+      return this._updatePerRowKey(cfKey, changes, single);
+    }
+    var sealed = cryptoField.sealRow(cfKey, changes);
     var setKeys = Object.keys(sealed);
     if (setKeys.length === 0) {
       throw new Error("update changes object is empty");
@@ -543,6 +691,41 @@ class Query {
     return info.changes;
   }
 
+  // Per-row-key UPDATE. Sealed columns on a declarePerRowKey table are
+  // K_row cells (vault.row:), so each affected row must be re-sealed
+  // under its OWN K_row — a single set-based UPDATE can't carry per-row
+  // ciphertext. Resolve the affected _id set via the WHERE, then for
+  // each row: materialize (idempotent) its K_row, seal the change set
+  // under it (derived hashes computed from plaintext as usual), and
+  // UPDATE that single row by _id. `single` stops after the first row.
+  _updatePerRowKey(cfKey, changes, single) {
+    var whereSql = this._where.join(" AND ");
+    var qt = this._quotedTable();
+    var idStmt = this._db.prepare(
+      "SELECT _id FROM " + qt + " WHERE " + whereSql + (single ? " LIMIT 1" : ""));
+    var idRows = idStmt.all.apply(idStmt, this._whereParams);
+    var changed = 0;
+    for (var r = 0; r < idRows.length; r++) {
+      var rowId = idRows[r]._id;
+      if (rowId === undefined || rowId === null) continue;
+      var kRow = cryptoField.materializePerRowKey(cfKey, rowId, this._db);
+      var sealed = cryptoField.sealRow(cfKey, changes, { kRow: kRow, rowId: rowId });
+      var setKeys = Object.keys(sealed);
+      if (setKeys.length === 0) {
+        throw new Error("update changes object is empty");
+      }
+      setKeys.forEach(_validateField);
+      var selfUpd = this;
+      setKeys.forEach(function (k) { selfUpd._assertColumnMember(k, "update"); });
+      var setClause = setKeys.map(function (k) { return '"' + k + '" = ?'; }).join(", ");
+      var setValues = setKeys.map(function (k) { return sealed[k]; });
+      var updStmt = this._db.prepare("UPDATE " + qt + " SET " + setClause + " WHERE _id = ?");
+      var info = updStmt.run.apply(updStmt, setValues.concat([rowId]));
+      changed += (info && info.changes) || 0;
+    }
+    return changed;
+  }
+
   deleteOne() {
     return this._delete(true) > 0;
   }

package/lib/db.js

@@ -295,11 +295,21 @@ var FRAMEWORK_SCHEMA = [
   },
   {
     // Per-row crypto-erasure key registry — per-row keys.
-    // Each entry holds a sealed wrapped K_row keyed by (table,
-    // rowId). b.subject.eraseHard deletes the entry, leaving WAL /
-    // replica residuals undecryptable.
+    // Each entry holds the AAD-sealed random row-secret keyed by
+    // (tableName, rowId); the row-scoped K_row is derived from it.
+    // b.subject.eraseHard / b.retention destroy the entry, leaving WAL /
+    // replica residuals undecryptable. wrappedKey is registered as an
+    // AAD-bound sealed field (aad:true, rowIdField:"rowId") so a vault
+    // keypair rotation auto-reseals it old-root -> new-root via
+    // rotate._rotateColumn — without this a rotation would orphan every
+    // wrapped secret and brick every keyed row.
     name: "_blamejs_per_row_keys",
     columns: {
+      // _id is the rotation pipeline's keyset-pagination + UPDATE key
+      // (rotate._rotateColumn SELECTs _id and orders by it); the natural
+      // identity stays the composite (tableName, rowId). materialize
+      // populates _id with a fresh token.
+      _id:        "TEXT",
       tableName:  "TEXT NOT NULL",
       rowId:      "TEXT NOT NULL",
       wrappedKey: "BLOB NOT NULL",
@@ -307,6 +317,10 @@ var FRAMEWORK_SCHEMA = [
     },
     primaryKey: ["tableName", "rowId"],
     indexes: [],
+    sealedFields:  ["wrappedKey"],
+    aad:           true,
+    rowIdField:    "rowId",
+    schemaVersion: "1",
   },
   {
     // Operator-declared WORM (write-once-read-many) registry. Each

package/lib/external-db-migrate.js

@@ -75,6 +75,16 @@ var Q_TRACKING = '"' + TRACKING_TABLE + '"';
 var Q_LOCK     = '"' + LOCK_TABLE + '"';
 var Q_HISTORY  = '"' + HISTORY_TABLE + '"';
 
+// The migration tracking / history / lock tables hold framework
+// bookkeeping ("migration X ran at time T"), not region-bound personal
+// data, so their writes carry the residency-neutral "unrestricted" tag
+// — the per-row residency write gate (b.externalDb.query) refuses DML
+// to a residency-tagged backend under a cross-border regulated posture
+// unless a compatible rowResidencyTag is supplied. Operator migration
+// DML (mod.up) stays subject to the gate; only these internal writes
+// are exempt. Passed as the per-statement opts override on the txClient.
+var FRAMEWORK_METADATA_OPTS = Object.freeze({ rowResidencyTag: "unrestricted" });
+
 // Bytes that get signed for one history row. Stable forever — changing
 // it invalidates every prior signature.
 var HISTORY_SIGNATURE_FORMAT = "blamejs-schema-history-v1";
@@ -187,7 +197,8 @@ async function _writeHistoryRow(xdb, row) {
       row.schemaIntrospectionHash,
       row.signature,
       row.publicKeyFingerprint,
-    ]
+    ],
+    FRAMEWORK_METADATA_OPTS
   );
 }
 
@@ -221,7 +232,7 @@ async function _acquireLock(xdb, opts) {
   try {
     await xdb.query(
       "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
-      [nowMs, holder]
+      [nowMs, holder], FRAMEWORK_METADATA_OPTS
     );
     return { holder: holder, takeoverFrom: null, takeoverAgeMs: 0 };
   } catch (_e) {
@@ -235,7 +246,7 @@ async function _acquireLock(xdb, opts) {
       try {
         await xdb.query(
           "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
-          [nowMs, holder]
+          [nowMs, holder], FRAMEWORK_METADATA_OPTS
         );
         return { holder: holder, takeoverFrom: null, takeoverAgeMs: 0 };
       } catch (e2) {
@@ -250,11 +261,11 @@ async function _acquireLock(xdb, opts) {
       var prevHolder = existing.lockedby || existing.lockedBy;
       await xdb.query(
         "DELETE FROM " + Q_LOCK + " WHERE scope = 'lock' AND lockedAt = $1",
-        [Number(existing.lockedat || existing.lockedAt)]
+        [Number(existing.lockedat || existing.lockedAt)], FRAMEWORK_METADATA_OPTS
       );
       await xdb.query(
         "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
-        [nowMs, holder]
+        [nowMs, holder], FRAMEWORK_METADATA_OPTS
       );
       return { holder: holder, takeoverFrom: prevHolder, takeoverAgeMs: ageMs };
     }
@@ -269,7 +280,7 @@ async function _releaseLock(xdb, holder) {
   try {
     await xdb.query(
       "DELETE FROM " + Q_LOCK + " WHERE scope = 'lock' AND lockedBy = $1",
-      [holder]
+      [holder], FRAMEWORK_METADATA_OPTS
     );
   } catch (_e) {
     // best-effort release; operator can DELETE manually.
@@ -441,7 +452,8 @@ function create(opts) {
               await xdb.query(
                 "INSERT INTO " + Q_TRACKING +
                 " (name, description, appliedAt) VALUES ($1, $2, $3)",
-                [file, mod.description || "", ranAt]
+                [file, mod.description || "", ranAt],
+                FRAMEWORK_METADATA_OPTS
               );
               // Schema-version history with signature. Sign post-INSERT
               // so the introspection hash reflects the row that just