@blamejs/core 0.14.25 → 0.14.27

package/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
@@ -948,6 +978,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 +1006,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
@@ -1357,10 +1416,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");
@@ -1615,10 +1677,91 @@ function isCrossBorderRegulated(posture) {
   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,

package/lib/crypto-field.js

@@ -155,6 +155,25 @@ var perRowResidency = Object.create(null);
 //   { tableName: { keySize, info } }
 var perRowKeyTables = Object.create(null);
 
+// Seal-envelope strength ranking. A regulated posture can declare a
+// sealEnvelopeFloor in b.compliance POSTURE_DEFAULTS; registerTable
+// refuses a table that seals columns under a weaker envelope than the
+// floor when that posture is the globally-pinned one. Higher rank =
+// stronger binding:
+//   plain       — vault.seal: XChaCha20-Poly1305 under the vault root,
+//                 no AAD; a DB-write attacker can copy a cell to another
+//                 row undetected (CWE-311 / CWE-326).
+//   aad         — vault.aad.seal: AEAD-bound to (table,row,column,
+//                 schemaVersion); a relocated cell fails Poly1305.
+//   per-row-key — K_row crypto-shred: aad binding PLUS a per-row key,
+//                 so destroying the row-secret renders residue
+//                 mathematically undecryptable.
+var SEAL_ENVELOPE_RANK = Object.freeze({
+  "plain":       0,
+  "aad":         1,
+  "per-row-key": 2,
+});
+
 // The framework registry table that holds each row's AAD-sealed
 // row-secret. Named once so the seal-side AAD (materializePerRowKey),
 // the read-side AAD (unsealRow's K_row fetch), and rotate's reseal all
@@ -232,6 +251,14 @@ function isRowSealed(value) {
  * hash namespaces. Subsequent `sealRow` / `unsealRow` / `eraseRow`
  * calls dispatch through this registry.
  *
+ * Seal-envelope floor: when a compliance posture that declares a
+ * `sealEnvelopeFloor` is globally pinned (`b.compliance.set` — today
+ * `hipaa` / `pci-dss` require at least an AAD-bound envelope), a table
+ * that seals columns under a weaker envelope throws
+ * `crypto-field/seal-envelope-below-floor` here at registration so the
+ * operator catches the under-protected schema at boot. Unpinned and
+ * non-regulated deployments register unchanged.
+ *
  * @opts
  *   sealedFields:   string[],              // column names sealed via vault.seal
  *   derivedHashes:  { [hashCol]: { from: string, normalize?: fn } },
@@ -289,8 +316,25 @@ function registerTable(name, opts) {
         "'salted-sha3' or 'hmac-shake256', got " + JSON.stringify(colMode));
     }
   }
+  var sealedFields = Array.isArray(opts.sealedFields) ? opts.sealedFields.slice() : [];
+  // Seal-envelope floor gate. Only fires when ALL hold:
+  //   (1) a posture is globally pinned (b.compliance.set) — read via
+  //       compliance().current(), the same source the residency write
+  //       gates read; an UNPINNED deployment is untouched (back-compat),
+  //   (2) that posture declares a sealEnvelopeFloor in POSTURE_DEFAULTS
+  //       (only regulated regimes do — hipaa / pci-dss), and
+  //   (3) the table actually seals columns under an envelope WEAKER than
+  //       the floor.
+  // A non-sealing table, an unpinned deployment, or a posture without a
+  // floor all pass through exactly as before. Config-time / entry-point
+  // tier: THROW so the operator catches the under-protected schema at
+  // boot rather than shipping PHI/PCI under a relocatable plain seal
+  // (CWE-311 / CWE-326).
+  if (sealedFields.length > 0) {
+    _assertSealEnvelopeFloor(name, aadOn);
+  }
   schemas[name] = {
-    sealedFields:    Array.isArray(opts.sealedFields)   ? opts.sealedFields.slice()   : [],
+    sealedFields:    sealedFields,
     derivedHashes:   derivedHashes,
     hashNamespaces:  Object.assign({}, opts.hashNamespaces || {}),
     aad:             aadOn,
@@ -300,6 +344,48 @@ function registerTable(name, opts) {
   };
 }
 
+// _assertSealEnvelopeFloor — config-time guard for registerTable. Reads
+// the globally-pinned posture (compliance().current()) and its declared
+// sealEnvelopeFloor; throws when `table` seals columns under a weaker
+// envelope. No-op when no posture is pinned, the posture declares no
+// floor, or compliance isn't loaded — so unpinned/non-regulated
+// deployments register exactly as before.
+function _assertSealEnvelopeFloor(table, aadOn) {
+  var posture;
+  var floor;
+  try {
+    var c = compliance();
+    posture = c.current();
+    if (typeof posture !== "string" || posture.length === 0) return;
+    floor = c.postureDefault(posture, "sealEnvelopeFloor");
+  } catch (_e) {
+    // compliance not loaded / unavailable — record nothing, gate nothing.
+    return;
+  }
+  if (typeof floor !== "string" || !Object.prototype.hasOwnProperty.call(SEAL_ENVELOPE_RANK, floor)) {
+    return; // posture pins no recognised floor → back-compat pass-through
+  }
+  // Declared envelope for this table: per-row-key beats aad beats plain.
+  // declarePerRowKey may run before or after registerTable; honour it
+  // when it ran first.
+  var declared = perRowKeyTables[table] ? "per-row-key" : (aadOn ? "aad" : "plain");
+  if (SEAL_ENVELOPE_RANK[declared] < SEAL_ENVELOPE_RANK[floor]) {
+    throw new CryptoFieldError("crypto-field/seal-envelope-below-floor",
+      "registerTable: table '" + table + "' seals columns under the '" +
+      declared + "' envelope, but the pinned compliance posture '" +
+      posture + "' requires at least '" + floor + "'. " +
+      (floor === "aad"
+        ? "Pass registerTable({ aad: true, rowIdField: <pk> }) so each " +
+          "cell is AEAD-bound to (table, row, column) and cannot be " +
+          "relocated between rows"
+        : "Call b.cryptoField.declarePerRowKey('" + table + "', ...) " +
+          "before registerTable so each row gets a crypto-shred K_row") +
+      " (CWE-311 / CWE-326). Unpinned or non-regulated deployments are " +
+      "unaffected; this gate fires only under a posture that declares a " +
+      "sealEnvelopeFloor.");
+  }
+}
+
 // Derived-hash digest width for the keyed (hmac-shake256) mode: 32
 // bytes -> 64 hex chars.
 var DERIVED_HASH_BYTES = 32;