@blamejs/core 0.14.21 → 0.14.24

package/lib/crypto-field.js

@@ -132,6 +132,11 @@ var schemas = Object.create(null);
 //
 //   { tableName: { columnName: "eu" | "us" | "global" | <tag> } }
 var columnResidency = Object.create(null);
+// Per-ROW residency registry — table → { residencyColumn, allowedTags }.
+// The row-level sibling of columnResidency: one plaintext column on each
+// row carries that row's residency tag; write gates refuse a tagged row
+// landing on an incompatible backend.
+var perRowResidency = Object.create(null);
 
 // Per-row key declaration registry. For tables that opt
 // into per-row keying, b.subject.eraseHard deletes the wrapped K_row
@@ -1105,7 +1110,7 @@ function getColumnResidency(table) {
  * @signature b.cryptoField.assertColumnResidency(table, row, args)
  * @since     0.7.27
  * @compliance gdpr
- * @related   b.cryptoField.declareColumnResidency
+ * @related   b.cryptoField.declareColumnResidency, b.cryptoField.declarePerRowResidency
  *
  * Storage-write gate. Storage backends call this with the proposed
  * row before the SQL hits the wire; refusal under regulated postures
@@ -1161,6 +1166,104 @@ function assertColumnResidency(table, row, args) {
   return null;
 }
 
+/**
+ * @primitive b.cryptoField.declarePerRowResidency
+ * @signature b.cryptoField.declarePerRowResidency(table, opts)
+ * @since     0.14.24
+ * @compliance gdpr
+ * @related   b.cryptoField.getPerRowResidency, b.cryptoField.declareColumnResidency
+ *
+ * Declares per-ROW data residency for `table`: one plaintext column on
+ * each row carries that row's residency tag, and the write gates
+ * refuse a tagged row landing on an incompatible backend. The sibling
+ * of `declareColumnResidency` — columns answer "which fields are
+ * region-bound", rows answer "which region does THIS record belong
+ * to" (an EU user's row next to a US user's row in the same table).
+ * Local writes (`b.db.from(...).insertOne` / `.update`) enforce the
+ * tag against the deployment's `dataResidency` region set under
+ * cross-border regulated postures; external writes
+ * (`b.externalDb.query`) take the tag per call via
+ * `opts.rowResidencyTag` because raw SQL carries no row object. Rows
+ * tagged "global" or "unrestricted" pass any backend. Throws on bad
+ * input (config-time fail-loud).
+ *
+ * @opts
+ *   residencyColumn: string,    // plaintext column carrying the row's tag
+ *   allowedTags:     string[],  // whitelist of valid tag values ("eu", "us", "global", region names)
+ *
+ * @example
+ *   b.cryptoField.declarePerRowResidency("users", {
+ *     residencyColumn: "dataRegion",
+ *     allowedTags:     ["eu-west-1", "us-east-1", "global"],
+ *   });
+ *   var spec = b.cryptoField.getPerRowResidency("users");
+ *   spec.residencyColumn;   // → "dataRegion"
+ */
+function declarePerRowResidency(table, opts) {
+  validateOpts.requireNonEmptyString(table, "declarePerRowResidency: table",
+    CryptoFieldError, "crypto-field/per-row-residency-table-empty");
+  validateOpts.requireObject(opts, "declarePerRowResidency",
+    CryptoFieldError, "crypto-field/per-row-residency-opts-not-object");
+  validateOpts(opts, ["residencyColumn", "allowedTags"], "cryptoField.declarePerRowResidency");
+  validateOpts.requireNonEmptyString(opts.residencyColumn,
+    "declarePerRowResidency: opts.residencyColumn",
+    CryptoFieldError, "crypto-field/per-row-residency-column-invalid");
+  if (!Array.isArray(opts.allowedTags) || opts.allowedTags.length === 0) {
+    throw new CryptoFieldError("crypto-field/per-row-residency-tags-invalid",
+      "declarePerRowResidency: opts.allowedTags must be a non-empty array of tag strings");
+  }
+  validateOpts.optionalNonEmptyStringArray(opts.allowedTags,
+    "declarePerRowResidency: opts.allowedTags",
+    CryptoFieldError, "crypto-field/per-row-residency-tag-empty");
+  // The residency tag column MUST stay plaintext — the write gate reads
+  // it on every INSERT / UPDATE before sealRow, and reads return it
+  // verbatim. A sealed residency column would be ciphertext the gate
+  // can't compare and reads can't surface. Refuse the misconfiguration
+  // at declaration time when the table's sealed-field set is already
+  // known (registration order permitting).
+  var sealed = getSealedFields(table);
+  if (Array.isArray(sealed) && sealed.indexOf(opts.residencyColumn) !== -1) {
+    throw new CryptoFieldError("crypto-field/per-row-residency-sealed-conflict",
+      "declarePerRowResidency: residencyColumn '" + opts.residencyColumn +
+      "' is a sealed field on table '" + table + "' — the residency tag must " +
+      "stay plaintext so the write gate can read it. Choose a non-sealed column");
+  }
+  perRowResidency[table] = {
+    residencyColumn: opts.residencyColumn,
+    allowedTags:     opts.allowedTags.slice(),
+  };
+  return {
+    table:           table,
+    residencyColumn: opts.residencyColumn,
+    allowedTags:     opts.allowedTags.slice(),
+  };
+}
+
+/**
+ * @primitive b.cryptoField.getPerRowResidency
+ * @signature b.cryptoField.getPerRowResidency(table)
+ * @since     0.14.24
+ * @related   b.cryptoField.declarePerRowResidency
+ *
+ * Returns the per-row residency spec declared for `table`
+ * (`{ residencyColumn, allowedTags }`), or null when the table has no
+ * declaration. Read-only — storage backends call this at the write
+ * boundary to decide whether the row-residency gate applies.
+ *
+ * @example
+ *   b.cryptoField.declarePerRowResidency("users", {
+ *     residencyColumn: "dataRegion",
+ *     allowedTags:     ["eu-west-1", "global"],
+ *   });
+ *   b.cryptoField.getPerRowResidency("users").allowedTags;   // → ["eu-west-1", "global"]
+ *   b.cryptoField.getPerRowResidency("unknown");             // → null
+ */
+function getPerRowResidency(table) {
+  var spec = perRowResidency[table];
+  if (!spec) return null;
+  return { residencyColumn: spec.residencyColumn, allowedTags: spec.allowedTags.slice() };
+}
+
 /**
  * @primitive b.cryptoField.declarePerRowKey
  * @signature b.cryptoField.declarePerRowKey(table, opts)
@@ -1336,10 +1439,10 @@ function destroyPerRowKey(table, rowId, dbHandle) {
  * @related   b.cryptoField.declareColumnResidency, b.cryptoField.declarePerRowKey
  *
  * Test-only helper. Drops every entry from the per-column residency
- * registry AND the per-row-key registry so a test fixture can
- * re-declare both between cases. Operator code never calls this —
- * production declarations come from `b.db.init({ schema })` once at
- * boot.
+ * registry, the per-row residency registry, and the per-row-key
+ * registry so a test fixture can re-declare them between cases.
+ * Operator code never calls this — production declarations come from
+ * `b.db.init({ schema })` once at boot.
  *
  * @example
  *   b.cryptoField.declareColumnResidency("users", {
@@ -1351,6 +1454,7 @@ function destroyPerRowKey(table, rowId, dbHandle) {
 function clearResidencyForTest() {
   for (var t in columnResidency) delete columnResidency[t];
   for (var u in perRowKeyTables) delete perRowKeyTables[u];
+  for (var v in perRowResidency) delete perRowResidency[v];
 }
 
 module.exports = {
@@ -1382,6 +1486,8 @@ module.exports = {
   declareColumnResidency: declareColumnResidency,
   getColumnResidency:     getColumnResidency,
   assertColumnResidency:  assertColumnResidency,
+  declarePerRowResidency: declarePerRowResidency,
+  getPerRowResidency:     getPerRowResidency,
   declarePerRowKey:       declarePerRowKey,
   hasPerRowKey:           hasPerRowKey,
   materializePerRowKey:   materializePerRowKey,

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
@@ -477,6 +593,9 @@ class Query {
     if (withId._id === undefined || withId._id === null) {
       withId._id = generateToken(C.BYTES.bytes(16));
     }
+    // Residency gates read the PLAINTEXT row (the tag column must be
+    // inspectable even when sibling columns seal below).
+    _assertLocalResidency(this._cryptoFieldKey(), withId, "insert");
     var sealed = cryptoField.sealRow(this._cryptoFieldKey(), withId);
     var cols = Object.keys(sealed);
     var placeholders = cols.map(function () { return "?"; }).join(", ");
@@ -514,6 +633,10 @@ class Query {
     if (this._where.length === 0) {
       throw new Error("refusing unconditional update — call where(...) first");
     }
+    // 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 sealed = cryptoField.sealRow(this._cryptoFieldKey(), changes);
     var setKeys = Object.keys(sealed);
     if (setKeys.length === 0) {

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