@blamejs/blamejs-shop 0.4.31 → 0.4.33

package/lib/vendor/blamejs/lib/cluster.js

@@ -50,16 +50,88 @@ var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
 var safeAsync = require("./safe-async");
 var safeJson = require("./safe-json");
-var safeSql = require("./safe-sql");
 var safeUrl = require("./safe-url");
 var validateOpts = require("./validate-opts");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
+// The external-DB schema quotes every column identifier, so Postgres
+// stores them case-preserving. The boot-time chain-tip + vault-key-
+// consistency statements compose through b.sql, which quotes every
+// identifier by construction (double-quote on Postgres / SQLite, backtick
+// on MySQL) so an unquoted fold-to-lowercase reference can't miss the
+// column.
+
 // Lazy: vault → db → cluster forms a load-time chain, and external-db is
 // loaded before its init has run; both are safe to call once cluster
 // reaches runtime, but eager require here would deadlock the load order.
 var externalDb = lazyRequire(function () { return require("./external-db"); });
 var vault = lazyRequire(function () { return require("./vault"); });
+// b.sql builder + the `?`->`$N` placeholderizer + the framework-table
+// name resolver. clusterStorage requires cluster, so these are lazy to
+// stay clear of the load cycle; resolved at runtime when the boot-time
+// rollback / vault-key-consistency checks run.
+var sql = lazyRequire(function () { return require("./sql"); });
+var clusterStorage = lazyRequire(function () { return require("./cluster-storage"); });
+var frameworkSchema = lazyRequire(function () { return require("./framework-schema"); });
+
+// b.sql speaks postgres | sqlite | mysql; the cluster's configuredDialect
+// is one of those (validated at init). Used so the boot-time chain-tip /
+// vault-key-consistency statements emit the right identifier quoting.
+function _bDialect() {
+  return configuredDialect === "mysql" ? "mysql"
+       : configuredDialect === "sqlite" ? "sqlite" : "postgres";
+}
+
+// Emit a b.sql builder + run it against the configured external-DB
+// backend. b.sql emits `?` placeholders; the externalDb driver receives
+// the SQL verbatim, so translate to `$N` for Postgres (passthrough for
+// SQLite / MySQL).
+function _runClusterQuery(builder) {
+  var built = builder.toSql();
+  return externalDb().query(
+    clusterStorage().placeholderize(built.sql, configuredDialect),
+    built.params,
+    { backend: configuredExternalDbBackend }
+  );
+}
+
+// "The framework-internal table this check needs does not exist yet" —
+// the signal that a gates-only cluster (leader election wired, but
+// framework state still resident in per-node SQLite without
+// frameworkSchema.ensureSchema) should SKIP the boot-time rollback /
+// vault-key-consistency check instead of FATAL-refusing boot. Each
+// backend phrases the missing-relation fault differently, and not all
+// drivers carry a stable structured code, so this matches BOTH the
+// driver phrasing AND the portable code/SQLSTATE when present:
+//
+//   - SQLite:    "no such table: X"
+//   - Postgres:  "relation "X" does not exist"  (SQLSTATE 42P01)
+//   - MySQL:     "Table 'db.X' doesn't exist"   (errno 1146, SQLSTATE 42S02)
+//
+// The earlier message-only test recognized the SQLite/Postgres phrasing
+// ("no such table" / "does not exist") but NOT MySQL's "doesn't exist"
+// (the apostrophe-contracted form), so a gates-only MySQL cluster boot
+// mis-fired the skip and surfaced ER_NO_SUCH_TABLE instead of completing.
+function _isMissingTableError(e) {
+  if (!e) return false;
+  // Structured code / SQLSTATE first — driver-stable, locale-independent.
+  // mysql2-shape: e.errno === 1146 / e.code === "ER_NO_SUCH_TABLE";
+  // the docker-exec shim + ANSI drivers surface SQLSTATE 42S02 (MySQL) /
+  // 42P01 (Postgres) on e.code / e.sqlState.
+  var code     = (e.code != null) ? String(e.code) : "";
+  var sqlState = (e.sqlState != null) ? String(e.sqlState) : "";
+  if (e.errno === 1146) return true;
+  if (code === "ER_NO_SUCH_TABLE" || code === "42S02" || code === "42P01" ||
+      sqlState === "42S02" || sqlState === "42P01") {
+    return true;
+  }
+  // Driver phrasing fallback. "doesn't exist" (MySQL apostrophe form) is
+  // covered alongside "does not exist" (Postgres) and "no such table"
+  // (SQLite). The MySQL message embeds the table name in quotes, so the
+  // bare "doesn't exist" substring is the portable anchor.
+  var msg = e.message || "";
+  return /no such table|does not exist|doesn't exist|relation .* does not exist/i.test(msg);
+}
 
 var DEFAULT_LEASE_TTL    = C.TIME.seconds(30);
 var DEFAULT_HEARTBEAT    = C.TIME.seconds(10);
@@ -324,8 +396,16 @@ async function init(opts) {
   // framework state — the operator owns rollback detection in that
   // case.
   if (configuredExternalDbBackend) {
-    await _checkChainTipRollback("audit",   "_blamejs_audit_log",   "_blamejs_audit_tip");
-    await _checkChainTipRollback("consent", "_blamejs_consent_log", "_blamejs_consent_tip");
+    // Resolve the chain + tip table names through frameworkSchema so the
+    // configurable framework-table prefix is honored (the names are
+    // `_blamejs_`-prefixed and self-mapped, so the resolve is a no-op under
+    // the default prefix).
+    await _checkChainTipRollback("audit",
+      frameworkSchema().tableName("audit_log"),                                   // allow:hand-rolled-sql — logical-name reference
+      frameworkSchema().tableName("_blamejs_audit_tip"));                         // allow:hand-rolled-sql — logical-name reference
+    await _checkChainTipRollback("consent",
+      frameworkSchema().tableName("consent_log"),                                 // allow:hand-rolled-sql — logical-name reference
+      frameworkSchema().tableName("_blamejs_consent_tip"));                       // allow:hand-rolled-sql — logical-name reference
     // Vault-key consistency: every node in a cluster must hold the
     // SAME vault key. A node booting with a different key would seal
     // new writes under a key the rest of the cluster can't unseal,
@@ -373,26 +453,16 @@ async function init(opts) {
 //     hash → FATAL via process.exit(1). Same posture as the
 //     single-node audit.tip sidecar rollback check.
 async function _checkChainTipRollback(chainName, logTable, tipTable) {
-  // Both tables are framework-internal constants from the call sites
-  // (`_blamejs_audit_log`, `_blamejs_consent_log`, etc.). Validate +
-  // quote per the framework's identifier-quoting convention so a
-  // future rename can't silently break the query.
-  safeSql.validateIdentifier(logTable, { allowReserved: true });
-  safeSql.validateIdentifier(tipTable, { allowReserved: true });
-  var qLogTable = safeSql.quoteIdentifier(logTable);
-  var qTipTable = safeSql.quoteIdentifier(tipTable);
-
+  // Both tables are framework-internal constants resolved at the call
+  // sites through frameworkSchema. b.sql quotes every identifier by
+  // construction; the dialect-final SQL is placeholderized to `$N` for
+  // Postgres (passthrough for SQLite).
   var tipRows;
   try {
-    tipRows = await externalDb().query(
-      "SELECT atMonotonicCounter, rowHash FROM " + qTipTable +
-      " WHERE scope = " + (configuredDialect === "postgres" ? "$1" : "?"),
-      [chainName],
-      { backend: configuredExternalDbBackend }
-    );
+    tipRows = await _runClusterQuery(sql().select(tipTable, { dialect: _bDialect() })
+      .columns(["atMonotonicCounter", "rowHash"]).where("scope", chainName));
   } catch (e) {
-    var msg = (e && e.message) || "";
-    if (/no such table|does not exist|relation .* does not exist/i.test(msg)) {
+    if (_isMissingTableError(e)) {
       log(chainName + "-tip table not present — skipping rollback check (cluster gates-only mode)");
       return;
     }
@@ -406,11 +476,8 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   var tipCounter = Number(tip.atMonotonicCounter);
   var tipHash = tip.rowHash;
 
-  var currentRows = await externalDb().query(
-    "SELECT MAX(monotonicCounter) AS m FROM " + qLogTable,
-    [],
-    { backend: configuredExternalDbBackend }
-  );
+  var currentRows = await _runClusterQuery(sql().select(logTable, { dialect: _bDialect() })
+    .max("monotonicCounter", "m"));
   var currentMax = (currentRows.rows && currentRows.rows[0] && currentRows.rows[0].m)
     ? Number(currentRows.rows[0].m)
     : 0;
@@ -426,12 +493,8 @@ async function _checkChainTipRollback(chainName, logTable, tipTable) {
   }
 
   if (tipHash) {
-    var hashRows = await externalDb().query(
-      "SELECT rowHash FROM " + qLogTable + " WHERE monotonicCounter = " +
-      (configuredDialect === "postgres" ? "$1" : "?"),
-      [tipCounter],
-      { backend: configuredExternalDbBackend }
-    );
+    var hashRows = await _runClusterQuery(sql().select(logTable, { dialect: _bDialect() })
+      .columns(["rowHash"]).where("monotonicCounter", tipCounter));
     if (hashRows.rows && hashRows.rows.length > 0) {
       var rowAtTip = hashRows.rows[0].rowHash;
       if (rowAtTip !== tipHash) {
@@ -492,12 +555,13 @@ function _vaultKeyFingerprint() {
 // non-constant, so the column is nullable and treated as epoch 0 when
 // absent on legacy rows.
 async function _ensureRotationEpochColumn() {
+  var stateTable = frameworkSchema().tableName("_blamejs_cluster_state");           // allow:hand-rolled-sql — logical-name reference
   try {
-    await externalDb().query(
-      "ALTER TABLE _blamejs_cluster_state ADD COLUMN rotationEpoch BIGINT",
-      [],
-      { backend: configuredExternalDbBackend }
-    );
+    var alter = sql().alterTable(stateTable,
+      { addColumn: { name: "rotationEpoch", type: "BIGINT" } },
+      { dialect: _bDialect() }).sql;
+    await externalDb().query(clusterStorage().placeholderize(alter, configuredDialect), [],
+      { backend: configuredExternalDbBackend });
   } catch (_e) { /* column already exists (or table absent — caught upstream) */ }
 }
 
@@ -533,29 +597,23 @@ async function _checkVaultKeyConsistency() {
     return;
   }
   var nowMs = Date.now();
-  var ph = configuredDialect === "postgres";
+  var stateTable = frameworkSchema().tableName("_blamejs_cluster_state");           // allow:hand-rolled-sql — logical-name reference
 
   // First boot: try to record THIS node's fingerprint. ON CONFLICT DO
   // NOTHING means the FIRST node to boot wins; subsequent nodes
   // observe whatever's already there. Every node then SELECTs and
   // compares — any mismatch (including ours after a losing race)
-  // surfaces the drift.
+  // surfaces the drift. The scope value binds like any other param; b.sql
+  // folds DO NOTHING to the MySQL `scope = scope` no-op automatically.
   try {
-    await externalDb().query(
-      "INSERT INTO _blamejs_cluster_state " +
-      "  (scope, vaultKeyFp, recordedAt, recordedByNode) " +
-      "VALUES ('state', " +
-      (ph ? "$1, $2, $3" : "?, ?, ?") + ") " +
-      "ON CONFLICT (scope) DO NOTHING",
-      [localFp, nowMs, nodeId],
-      { backend: configuredExternalDbBackend }
-    );
+    await _runClusterQuery(sql().upsert(stateTable, { dialect: _bDialect() })
+      .values({ scope: "state", vaultKeyFp: localFp, recordedAt: nowMs, recordedByNode: nodeId })
+      .onConflict(["scope"]).doNothing());
   } catch (e) {
     // Table missing → the cluster-provider-db ensureSchema didn't run
     // (custom provider that doesn't create _blamejs_cluster_state).
     // Skip silently — same defensive posture as the audit-tip check.
-    var msg = (e && e.message) || "";
-    if (/no such table|does not exist|relation .* does not exist/i.test(msg)) {
+    if (_isMissingTableError(e)) {
       log("cluster-state table not present — skipping vault-key consistency check (custom provider)");
       return;
     }
@@ -569,12 +627,9 @@ async function _checkVaultKeyConsistency() {
 
   // Read whatever fingerprint is canonical (ours if first boot,
   // someone else's if we lost the race or are joining an existing cluster).
-  var rows = await externalDb().query(
-    "SELECT vaultKeyFp, recordedByNode, recordedAt, rotationEpoch FROM _blamejs_cluster_state " +
-    "WHERE scope = 'state'",
-    [],
-    { backend: configuredExternalDbBackend }
-  );
+  var rows = await _runClusterQuery(sql().select(stateTable, { dialect: _bDialect() })
+    .columns(["vaultKeyFp", "recordedByNode", "recordedAt", "rotationEpoch"])
+    .where("scope", "state"));
   if (!rows.rows || rows.rows.length === 0) {
     // Should never happen — we just INSERTed. Surface as fatal so the
     // condition isn't silently ignored.
@@ -628,27 +683,20 @@ async function _checkVaultKeyConsistency() {
     var priorEpoch = (canonical.rotationEpoch != null) ? Number(canonical.rotationEpoch) : 0;
     if (!isFinite(priorEpoch) || priorEpoch < 0) priorEpoch = 0;
     var nextEpoch = priorEpoch + 1;
-    await externalDb().query(
-      "UPDATE _blamejs_cluster_state SET " +
-      "  vaultKeyFp = " + (ph ? "$1" : "?") + ", " +
-      "  recordedAt = " + (ph ? "$2" : "?") + ", " +
-      "  recordedByNode = " + (ph ? "$3" : "?") + ", " +
-      "  rotationEpoch = " + (ph ? "$4" : "?") + " " +
-      "WHERE scope = 'state' AND vaultKeyFp = " + (ph ? "$5" : "?"),
-      [localFp, nowMs, nodeId, nextEpoch, canonical.vaultKeyFp],
-      { backend: configuredExternalDbBackend }
-    );
+    await _runClusterQuery(sql().update(stateTable, { dialect: _bDialect() })
+      .set({
+        vaultKeyFp: localFp, recordedAt: nowMs,
+        recordedByNode: nodeId, rotationEpoch: nextEpoch,
+      })
+      .where("scope", "state").where("vaultKeyFp", canonical.vaultKeyFp));
     // Re-read so the post-adopt state reflects whoever actually won the
     // advance (this node, or a peer that adopted the SAME rotated key a
     // beat earlier). A surviving mismatch here means the row now carries a
     // fingerprint that is neither the old one nor ours — a real drift that
     // the rotation declaration does not cover, so fail closed.
-    var after = await externalDb().query(
-      "SELECT vaultKeyFp, recordedByNode, rotationEpoch FROM _blamejs_cluster_state " +
-      "WHERE scope = 'state'",
-      [],
-      { backend: configuredExternalDbBackend }
-    );
+    var after = await _runClusterQuery(sql().select(stateTable, { dialect: _bDialect() })
+      .columns(["vaultKeyFp", "recordedByNode", "rotationEpoch"])
+      .where("scope", "state"));
     var post = (after.rows && after.rows[0]) || canonical;
     if (post.vaultKeyFp !== localFp) {
       throw _err("VAULT_KEY_DRIFT",

package/lib/vendor/blamejs/lib/codepoint-class.js

@@ -271,7 +271,30 @@ function escapeRegExp(s) {
 // lives once.
 var HEX_PAIR_RE = /^[0-9A-Fa-f]{2}$/;
 
+// isAsciiAlnum — codepoint is an ASCII letter or digit (A-Z / a-z / 0-9).
+// The ASCII-alphanumeric range test recurs across every byte-class parser
+// (URL unreserved, XML name chars, header tokens); centralized so the three
+// range literals live once rather than as a re-rolled `cc>=0x41&&...` chain.
+function isAsciiAlnum(cc) {
+  return (cc >= 0x41 && cc <= 0x5a) ||   // A-Z
+         (cc >= 0x61 && cc <= 0x7a) ||   // a-z
+         (cc >= 0x30 && cc <= 0x39);     // 0-9
+}
+
+// isUnreserved — codepoint is in the RFC 3986 §2.3 unreserved set:
+// ALPHA / DIGIT / "-" / "." / "_" / "~". A percent-escape of an unreserved
+// character is over-encoding the URI spec says SHOULD be decoded (§6.2.2.3).
+function isUnreserved(cc) {
+  return isAsciiAlnum(cc) ||
+         cc === 0x2d ||   // -
+         cc === 0x2e ||   // .
+         cc === 0x5f ||   // _
+         cc === 0x7e;     // ~
+}
+
 module.exports = {
+  isAsciiAlnum:      isAsciiAlnum,
+  isUnreserved:      isUnreserved,
   hex4:              hex4,
   charClass:         charClass,
   fromCp:            fromCp,

package/lib/vendor/blamejs/lib/compliance.js

@@ -50,6 +50,18 @@ var audit         = lazyRequire(function () { return require("./audit"); });
 var retentionMod  = lazyRequire(function () { return require("./retention"); });
 var db            = lazyRequire(function () { return require("./db"); });
 var cryptoField   = lazyRequire(function () { return require("./crypto-field"); });
+var redact        = lazyRequire(function () { return require("./redact"); });
+
+// Postures whose floor implies an outbound-DLP gate (b.redact's
+// classifier presets cover exactly these regimes). Pinning one of these
+// does NOT auto-install outbound DLP — the compliance coordinator holds
+// no httpClient / mail / webhook handles — so set() emits a one-time
+// `compliance.posture.outbound_dlp_unwired` warning when none is wired,
+// so the gap is grep-able in the audit chain instead of a silent paper-
+// compliance hole (CWE-200 / CWE-201 outbound data exposure).
+var OUTBOUND_DLP_FLOOR_POSTURES = Object.freeze([
+  "hipaa", "pci-dss", "gdpr", "soc2", "fapi-2.0", "fapi-2.0-message-signing",
+]);
 
 // Recognised posture names. Aligns with the compliance-posture
 // vocabulary every guard / retention floor / etc. accepts. Operators
@@ -445,6 +457,24 @@ function set(posture) {
         "warning");
     }
   }
+
+  // Outbound-DLP wiring signal. A posture whose floor implies an
+  // outbound-DLP gate is being pinned, but set() cannot install the
+  // interceptors itself (no httpClient / mail / webhook handles). Warn
+  // once when nothing is wired so the gap is visible in the audit chain
+  // rather than a silent paper-compliance hole. Fires at most once per
+  // pin (set() is idempotent for the same posture).
+  if (OUTBOUND_DLP_FLOOR_POSTURES.indexOf(posture) !== -1) {
+    var dlpInstalled = false;
+    try { dlpInstalled = redact().isOutboundDlpInstalled() === true; }
+    catch (_e) { dlpInstalled = false; }
+    if (!dlpInstalled) {
+      _emitAudit("compliance.posture.outbound_dlp_unwired",
+        { posture: posture,
+          recommendation: "compliance.set does not auto-install outbound DLP — it holds no httpClient / mail / webhook handles. Call b.redact.installForPosture('" + posture + "', { httpClient, mail, webhook }) with your primitive instances so outbound payloads are classified (CWE-200 / CWE-201)." },
+        "warning");
+    }
+  }
 }
 
 // _applyPostureCascade — walks every primitive that
@@ -564,6 +594,10 @@ function clear() {
   }
   STATE.posture = null;
   STATE.setAt   = null;
+  // Cascade the reset the same way set() cascades the posture — otherwise a
+  // primitive that inherits the active posture (e.g. retention.complianceFloor)
+  // keeps applying the stale floor after the global posture was cleared.
+  _applyPostureCascade(null);
 }
 
 function _resetForTest() {
@@ -948,6 +982,25 @@ function describe(posture) {
 //                               + DPDP §12 + LGPD-BR Art. 18 + PIPL-CN
 //                               Art. 47 all require effective erasure;
 //                               leftover index residue defeats it.
+//   sealEnvelopeFloor         — minimum field-level seal envelope a
+//                               sealed-column table may declare under
+//                               this posture: "plain" (vault.seal, no
+//                               AAD), "aad" (AEAD-bound to table/row/
+//                               column via b.vault.aad), or "per-row-key"
+//                               (K_row crypto-shred). cryptoField.
+//                               registerTable refuses a table whose
+//                               declared envelope is below the floor when
+//                               this posture is the globally-pinned one.
+//                               PCI-DSS Req. 3.5/3.6 (PAN render
+//                               unreadable, key-management binding) and
+//                               HIPAA 45 CFR 164.312(a)(2)(iv) +
+//                               164.312(e)(2)(ii) (encryption that
+//                               resists ciphertext relocation, CWE-311 /
+//                               CWE-326) need an AAD-bound envelope at
+//                               minimum so a DB-write attacker cannot
+//                               copy a sealed cell between rows. Absent
+//                               on a posture → no floor (back-compat;
+//                               plain envelopes keep registering).
 //
 // This table is the single source-of-truth — duplicating values into
 // per-primitive defaults would drift the moment a regulator updates.
@@ -957,12 +1010,22 @@ var POSTURE_DEFAULTS = Object.freeze({
     auditChainSignedRequired: true,
     tlsMinVersion:            "TLSv1.3",
     requireVacuumAfterErase:  true,
+    // 45 CFR 164.312(a)(2)(iv) + (e)(2)(ii) — ePHI encryption must
+    // resist ciphertext relocation; a plain vault.seal cell can be
+    // copied between rows undetected (CWE-311 / CWE-326). AAD-bound
+    // envelope is the floor.
+    sealEnvelopeFloor:        "aad",
   }),
   "pci-dss": Object.freeze({
     backupEncryptionRequired: true,
     auditChainSignedRequired: true,
     tlsMinVersion:            "TLSv1.3",
     requireVacuumAfterErase:  false,
+    // PCI-DSS v4 Req. 3.5 (PAN unreadable) + Req. 3.6 (key-management
+    // binding) — the seal must bind cardholder data to its storage
+    // location so a relocated ciphertext fails to verify. AAD-bound
+    // envelope is the floor.
+    sealEnvelopeFloor:        "aad",
   }),
   "gdpr": Object.freeze({
     backupEncryptionRequired: false,           // GDPR Art. 32 says "appropriate" — not mandatory floor
@@ -1006,6 +1069,28 @@ var POSTURE_DEFAULTS = Object.freeze({
     tlsMinVersion:            "TLSv1.3",
     requireVacuumAfterErase:  true,
   }),
+  // UK GDPR (DPA 2018 + retained EU GDPR) — Art. 17 right to erasure
+  // applies identically to GDPR, including residual B-tree pages.
+  "uk-gdpr": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
+  // Japan APPI — deletion/cessation right with residue-cleanup floor.
+  "appi-jp": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
+  // Singapore PDPA — right to erasure with effectiveness floor.
+  "pdpa-sg": Object.freeze({
+    backupEncryptionRequired: false,
+    auditChainSignedRequired: true,
+    tlsMinVersion:            "TLSv1.3",
+    requireVacuumAfterErase:  true,
+  }),
   // v0.8.70 — 2026 effective deadlines
   "modpa": Object.freeze({
     // Maryland Online Data Privacy Act (effective 2026-10-01) —
@@ -1357,10 +1442,13 @@ var POSTURE_DEFAULTS = Object.freeze({
  * where `set()` would over-pin the process.
  *
  * Recognised keys per posture include `backupEncryptionRequired`,
- * `auditChainSignedRequired`, `tlsMinVersion`, and
- * `requireVacuumAfterErase` — the floors enforced by `b.backup`,
- * `b.audit`, the TLS minimum-version gate, and `b.cryptoField`'s
- * residual-erasure pass.
+ * `auditChainSignedRequired`, `tlsMinVersion`,
+ * `requireVacuumAfterErase`, and `sealEnvelopeFloor` — the floors
+ * enforced by `b.backup`, `b.audit`, the TLS minimum-version gate,
+ * `b.cryptoField`'s residual-erasure pass, and `b.cryptoField`'s
+ * field-level seal-envelope gate. Keys not declared for a posture
+ * return `null` (no floor), so reading `sealEnvelopeFloor` for a
+ * posture that doesn't pin one is the back-compat no-op signal.
  *
  * @example
  *   b.compliance.postureDefault("hipaa", "tlsMinVersion");
@@ -1580,9 +1668,127 @@ function fipsMode(enable) {
   return STATE.fipsMode;
 }
 
+// Postures whose jurisdictions restrict cross-border data transfer
+// (GDPR Art 44-46 / UK-GDPR / DPDP §16 / PIPL Art 38 / LGPD Art 33 /
+// APPI Art 28 / PDPA §26). The residency write gates (db-query local,
+// external-db backend/replica) refuse mismatched writes under these;
+// other postures observe-and-audit only.
+var CROSS_BORDER_REGULATED_POSTURES = Object.freeze([
+  "gdpr", "uk-gdpr", "dpdp", "pipl-cn", "lgpd-br", "appi-jp", "pdpa-sg",
+]);
+
+/**
+ * @primitive b.compliance.isCrossBorderRegulated
+ * @signature b.compliance.isCrossBorderRegulated(posture)
+ * @since     0.14.24
+ * @compliance gdpr
+ * @related   b.compliance.current, b.cryptoField.declarePerRowResidency
+ *
+ * Returns true when `posture` is one of the cross-border regulated
+ * postures (gdpr / uk-gdpr / dpdp / pipl-cn / lgpd-br / appi-jp /
+ * pdpa-sg) — the jurisdictions whose transfer restrictions flip the
+ * data-residency write gates from advisory to refusing. The set
+ * itself is exported as `CROSS_BORDER_REGULATED_POSTURES`; this
+ * helper is the membership test the local (`b.db.from`) and external
+ * (`b.externalDb.query`) gates share. Non-string and unknown postures
+ * return false.
+ *
+ * @example
+ *   b.compliance.isCrossBorderRegulated("gdpr");      // → true
+ *   b.compliance.isCrossBorderRegulated("soc2");      // → false
+ *   b.compliance.isCrossBorderRegulated(null);        // → false
+ */
+function isCrossBorderRegulated(posture) {
+  if (typeof posture !== "string" || posture.length === 0) return false;
+  return CROSS_BORDER_REGULATED_POSTURES.indexOf(posture) !== -1;
+}
+
+// Region-tag wildcards. Both spellings mean "no residency constraint"
+// across the framework — the external-db gate uses "unrestricted" as
+// its default + wildcard, while the local db-query / external-db row
+// gates also accept "global" as the region-neutral row tag. Normalizing
+// folds both to "unrestricted" so callers reason about one wildcard.
+var _REGION_WILDCARDS = Object.freeze(["global", "unrestricted", "any", "*"]);
+
+/**
+ * @primitive b.compliance.normalizeRegionTag
+ * @signature b.compliance.normalizeRegionTag(tag)
+ * @since     0.14.27
+ * @compliance gdpr
+ * @related   b.compliance.isRegionCompatible, b.compliance.isCrossBorderRegulated
+ *
+ * Canonicalize an operator-supplied residency region tag so the same
+ * region declared as `"EU"`, `"eu"`, or `" Eu "` compares equal. Lower-
+ * cases and trims the tag; folds the no-constraint wildcards
+ * (`"global"` / `"unrestricted"` / `"any"` / `"*"`) to `"unrestricted"`.
+ * Returns `null` for non-string / empty input.
+ *
+ * This is an ADDITIVE helper composed OVER the residency write gates
+ * (`b.db.from` local, `b.externalDb.query` backend/replica) — it does
+ * not change the gate internals. Callers normalize their tags with it
+ * BEFORE handing them to the gate so case / wildcard drift (`"EU"` vs
+ * `"eu"` vs `"global"`) doesn't read as a region mismatch.
+ *
+ * @example
+ *   b.compliance.normalizeRegionTag("EU");           // → "eu"
+ *   b.compliance.normalizeRegionTag(" eu ");         // → "eu"
+ *   b.compliance.normalizeRegionTag("global");       // → "unrestricted"
+ *   b.compliance.normalizeRegionTag("unrestricted"); // → "unrestricted"
+ *   b.compliance.normalizeRegionTag(null);           // → null
+ */
+function normalizeRegionTag(tag) {
+  if (typeof tag !== "string") return null;
+  var t = tag.trim().toLowerCase();
+  if (t.length === 0) return null;
+  if (_REGION_WILDCARDS.indexOf(t) !== -1) return "unrestricted";
+  return t;
+}
+
+/**
+ * @primitive b.compliance.isRegionCompatible
+ * @signature b.compliance.isRegionCompatible(a, b)
+ * @since     0.14.27
+ * @compliance gdpr
+ * @related   b.compliance.normalizeRegionTag, b.compliance.isCrossBorderRegulated
+ *
+ * Returns `true` when two residency region tags are compatible for a
+ * same-region write/replication after normalization: identical
+ * normalized regions are compatible, and a wildcard (`"global"` /
+ * `"unrestricted"`) on EITHER side is compatible. Different concrete
+ * regions (`"eu"` vs `"us"`) are NOT compatible — a cross-border
+ * transfer the operator must opt into explicitly at the gate.
+ *
+ * Mirrors the residency gate's compatibility rule (identical-or-
+ * wildcard) but over NORMALIZED tags, so it is case- and wildcard-drift
+ * insensitive. ADDITIVE helper composed over the gate — it does not
+ * change `_residencyCompatible` in db-query.js / external-db.js.
+ * Missing/non-string tags on either side normalize to `null`, treated
+ * as "no constraint" → compatible (matches the gate's
+ * `!primaryTag || !replicaTag` short-circuit).
+ *
+ * @example
+ *   b.compliance.isRegionCompatible("EU", "eu");            // → true
+ *   b.compliance.isRegionCompatible("eu", "global");        // → true
+ *   b.compliance.isRegionCompatible("unrestricted", "us");  // → true
+ *   b.compliance.isRegionCompatible("eu", "us");            // → false
+ *   b.compliance.isRegionCompatible("EU", null);            // → true
+ */
+function isRegionCompatible(a, b) {
+  var na = normalizeRegionTag(a);
+  var nb = normalizeRegionTag(b);
+  if (na === null || nb === null) return true;            // no constraint either side
+  if (na === nb) return true;                             // identical region (post-normalize)
+  if (na === "unrestricted" || nb === "unrestricted") return true; // wildcard either side
+  return false;
+}
+
 module.exports = {
   set:                    set,
   current:                current,
+  isCrossBorderRegulated: isCrossBorderRegulated,
+  normalizeRegionTag:     normalizeRegionTag,
+  isRegionCompatible:     isRegionCompatible,
+  CROSS_BORDER_REGULATED_POSTURES: CROSS_BORDER_REGULATED_POSTURES,
   assert:                 assert,
   clear:                  clear,
   describe:               describe,