@blamejs/core 0.14.10 → 0.14.12

package/lib/cluster.js

@@ -52,6 +52,7 @@ 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");
 
 // Lazy: vault → db → cluster forms a load-time chain, and external-db is
@@ -99,6 +100,15 @@ var configuredDialect            = null;
 // (or external observer) can resolve "where is the current leader?"
 // via cluster.currentLeader() / cluster.discoveryHandler().
 var configuredEndpoint          = null;
+// Operator declaration that this node's vault keypair legitimately
+// changed via a key rotation (b.vault.rotate). When set, a fingerprint
+// that differs from the canonical cluster-state row is ADOPTED (the row
+// advances to the new fingerprint + bumps the rotation epoch) instead
+// of FATAL-refusing boot. Unset (the default) keeps the strict
+// drift-refusal posture for the UNexpected mismatch. See
+// _checkVaultKeyConsistency for the consistency model.
+var configuredAcceptRotation     = false;
+var configuredExpectedVaultKeyFp = null;
 
 var log = boot("cluster");
 
@@ -142,6 +152,16 @@ function _emitTransition(kind, detail) {
  * outside `leader` / `follower`, and on a chain or vault-key mismatch
  * that would let this node corrupt cluster state.
  *
+ * After a vault-key rotation (`b.vault.rotate`) the public-key
+ * fingerprint changes, so the canonical cluster-state row no longer
+ * matches and every node would otherwise refuse boot with
+ * `VAULT_KEY_DRIFT`. Pass `acceptVaultKeyRotation: true` to declare the
+ * change legitimate: the node advances the canonical fingerprint and
+ * bumps a rotation epoch instead of refusing. `expectedVaultKeyFp`
+ * narrows the acceptance to a single blessed fingerprint so a typo'd /
+ * stale key file is still caught. The strict cross-node drift refusal
+ * stays in force whenever the rotation is NOT declared.
+ *
  * @opts
  *   nodeId:             string,            // required; stable identity
  *   role:               "leader"|"follower",
@@ -152,6 +172,11 @@ function _emitTransition(kind, detail) {
  *   provider:           object,            // custom election provider
  *   externalDbBackend:  object,            // required when no custom provider
  *   dialect:            "postgres"|"sqlite"|"mysql",
+ *   acceptVaultKeyRotation: boolean,        // adopt a rotated vault-key
+ *                                          // fingerprint instead of
+ *                                          // refusing boot on mismatch
+ *   expectedVaultKeyFp: string,            // optional; bless ONLY this
+ *                                          // post-rotation fingerprint
  *   onTransition:       function (event),
  *
  * @example
@@ -227,6 +252,31 @@ async function init(opts) {
     configuredEndpoint = null;
   }
 
+  // Vault-key rotation acceptance (config-time tier: THROW on bad
+  // input). acceptVaultKeyRotation is a boolean declaration; an
+  // expectedVaultKeyFp without it is a misconfiguration (the operator
+  // blessed a fingerprint but never enabled adoption).
+  validateOpts.optionalBoolean(opts.acceptVaultKeyRotation,
+    "cluster.init({ acceptVaultKeyRotation })", ClusterError, "INVALID_CONFIG");
+  configuredAcceptRotation = opts.acceptVaultKeyRotation === true;
+  if (opts.expectedVaultKeyFp !== undefined) {
+    if (typeof opts.expectedVaultKeyFp !== "string" ||
+        !/^[0-9a-f]{128}$/.test(opts.expectedVaultKeyFp)) {
+      throw _err("INVALID_CONFIG",
+        "cluster.init({ expectedVaultKeyFp }) must be a 128-char " +
+        "lowercase-hex SHA3-512 fingerprint (b.vault rotation output)", true);
+    }
+    if (!configuredAcceptRotation) {
+      throw _err("INVALID_CONFIG",
+        "cluster.init({ expectedVaultKeyFp }) requires " +
+        "acceptVaultKeyRotation: true — blessing a fingerprint without " +
+        "enabling adoption has no effect", true);
+    }
+    configuredExpectedVaultKeyFp = opts.expectedVaultKeyFp;
+  } else {
+    configuredExpectedVaultKeyFp = null;
+  }
+
   if (typeof opts.onTransition === "function") {
     transitionHandlers.push(opts.onTransition);
   }
@@ -433,6 +483,49 @@ function _vaultKeyFingerprint() {
                          keys.ecPublicKey);
 }
 
+// Idempotent migration for the rotationEpoch column. cluster-provider-db
+// ensureSchema creates _blamejs_cluster_state without it (the column was
+// added when rotation-epoch acceptance landed); ADD COLUMN here keeps the
+// path version-agnostic the same way the provider migrates the leader
+// row's `endpoint` column. The only expected failure is "column already
+// exists," which is swallowed. SQLite / MySQL don't take a DEFAULT on a
+// non-constant, so the column is nullable and treated as epoch 0 when
+// absent on legacy rows.
+async function _ensureRotationEpochColumn() {
+  try {
+    await externalDb().query(
+      "ALTER TABLE _blamejs_cluster_state ADD COLUMN rotationEpoch BIGINT",
+      [],
+      { backend: configuredExternalDbBackend }
+    );
+  } catch (_e) { /* column already exists (or table absent — caught upstream) */ }
+}
+
+// Consistency model (CWE-345 binding-integrity for sealed columns):
+//
+//   Every node fingerprints its vault PUBLIC keys (SHA3-512, one-way) and
+//   the cluster agrees on ONE canonical fingerprint stored in
+//   _blamejs_cluster_state. A node holding a different key seals new
+//   writes the rest of the cluster can't unseal — silent corruption — so
+//   an UNDECLARED mismatch fails closed (FATAL: VAULT_KEY_DRIFT).
+//
+//   A vault-key rotation (b.vault.rotate, lib/vault/rotate.js) legitimately
+//   changes the public-key fingerprint on EVERY node. The rotation only
+//   re-seals the local dataDir; it does not touch the external coordination
+//   row, so the canonical fingerprint goes stale and every node would
+//   refuse boot. acceptVaultKeyRotation: true is the operator's signed-off
+//   declaration "this change is a rotation, not drift": the booting node
+//   ADVANCES the canonical row to its own fingerprint and bumps a
+//   monotonic rotationEpoch. expectedVaultKeyFp narrows the adoption to a
+//   single blessed fingerprint so a stale / wrong key file is still
+//   refused. The strict refusal is unchanged when no rotation is declared,
+//   which is exactly the cross-node drift case the check defends.
+//
+//   The epoch is observability + a future-replay guard, not an auth
+//   boundary — the auth boundary is the operator's deliberate opt
+//   (acceptVaultKeyRotation) plus the optional fingerprint allowlist. A
+//   forged row can only ever cost a single declared boot, and a genuinely
+//   different key would still fail every sealed read.
 async function _checkVaultKeyConsistency() {
   var localFp = _vaultKeyFingerprint();
   if (localFp === null) {
@@ -469,10 +562,15 @@ async function _checkVaultKeyConsistency() {
     throw e;
   }
 
+  // Bring the rotationEpoch column into existence (idempotent). The INSERT
+  // above already proved the table is present, so a real ALTER failure
+  // here is "column exists" and is swallowed.
+  await _ensureRotationEpochColumn();
+
   // 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 FROM _blamejs_cluster_state " +
+    "SELECT vaultKeyFp, recordedByNode, recordedAt, rotationEpoch FROM _blamejs_cluster_state " +
     "WHERE scope = 'state'",
     [],
     { backend: configuredExternalDbBackend }
@@ -486,22 +584,92 @@ async function _checkVaultKeyConsistency() {
       true);
   }
   var canonical = rows.rows[0];
+  var fpPrefix = C.BYTES.bytes(16);
   if (canonical.vaultKeyFp !== localFp) {
-    var fpPrefix = C.BYTES.bytes(16);
-    throw _err("VAULT_KEY_DRIFT",
-      "FATAL: vault-key drift detected. " +
-      "local node: " + nodeId +
-      "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
-      "; canonical recorded by: " + canonical.recordedByNode +
-      "; canonical fingerprint: " + canonical.vaultKeyFp.slice(0, fpPrefix) + "…" +
-      ". This node holds a DIFFERENT vault key than the rest of the " +
-      "cluster. Sealed-column writes from this node would be unreadable " +
-      "by the others (and vice versa). Restore the same vault key file " +
-      "before booting this node into the cluster.",
-      true);
+    // Mismatch. Two readings: a legitimate vault-key rotation the
+    // operator has declared, or genuine cross-node drift. Without the
+    // declaration, always fail closed — sealed-column corruption is the
+    // worse outcome.
+    if (!configuredAcceptRotation) {
+      throw _err("VAULT_KEY_DRIFT",
+        "FATAL: vault-key drift detected. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; canonical recorded by: " + canonical.recordedByNode +
+        "; canonical fingerprint: " + canonical.vaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". This node holds a DIFFERENT vault key than the rest of the " +
+        "cluster. Sealed-column writes from this node would be unreadable " +
+        "by the others (and vice versa). If the key changed via " +
+        "b.vault.rotate, re-init with acceptVaultKeyRotation: true to " +
+        "advance the cluster's recorded fingerprint; otherwise restore the " +
+        "same vault key file before booting this node into the cluster.",
+        true);
+    }
+    // Rotation declared. If the operator blessed a specific fingerprint,
+    // the LOCAL key must match it — this rejects a stale / wrong key file
+    // that happens to differ from canonical for the wrong reason.
+    if (configuredExpectedVaultKeyFp && configuredExpectedVaultKeyFp !== localFp) {
+      throw _err("VAULT_KEY_ROTATION_MISMATCH",
+        "FATAL: acceptVaultKeyRotation is set but this node's vault-key " +
+        "fingerprint does not match the blessed expectedVaultKeyFp. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; expected fingerprint: " + configuredExpectedVaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". This node is NOT holding the rotated key the operator approved. " +
+        "Restore the post-rotation vault key file (or correct " +
+        "expectedVaultKeyFp) before booting this node into the cluster.",
+        true);
+    }
+    // Adopt: advance the canonical row to the new fingerprint and bump
+    // the monotonic rotation epoch. The UPDATE is gated on the OLD
+    // fingerprint so two nodes adopting concurrently converge on a single
+    // advance (the loser's WHERE matches nothing and it re-reads the
+    // already-advanced row below).
+    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 }
+    );
+    // 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 post = (after.rows && after.rows[0]) || canonical;
+    if (post.vaultKeyFp !== localFp) {
+      throw _err("VAULT_KEY_DRIFT",
+        "FATAL: vault-key drift detected after rotation-accept. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; canonical fingerprint: " + post.vaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". A concurrent node advanced the cluster to a DIFFERENT key than " +
+        "this node holds — the declared rotation does not cover this " +
+        "fingerprint. Restore the agreed post-rotation vault key file.",
+        true);
+    }
+    log("cluster vault-key rotation accepted (fingerprint " +
+      localFp.slice(0, fpPrefix) + "… epoch " +
+      (post.rotationEpoch != null ? Number(post.rotationEpoch) : nextEpoch) +
+      ", recorded by " + post.recordedByNode + ")");
+    return;
   }
   log("cluster vault-key consistency ok (fingerprint " +
-    localFp.slice(0, C.BYTES.bytes(16)) + "… recorded by " + canonical.recordedByNode + ")");
+    localFp.slice(0, fpPrefix) + "… recorded by " + canonical.recordedByNode +
+    (canonical.rotationEpoch != null ? ", epoch " + Number(canonical.rotationEpoch) : "") + ")");
 }
 
 async function _tryAcquire() {
@@ -967,6 +1135,8 @@ async function shutdown() {
   configuredExternalDbBackend = null;
   configuredDialect = null;
   configuredEndpoint = null;
+  configuredAcceptRotation = false;
+  configuredExpectedVaultKeyFp = null;
   transitionHandlers = [];
   // nodeId is preserved post-shutdown so audit metadata still reflects
   // who this process was; cleared only by _resetForTest.
@@ -988,6 +1158,8 @@ function _resetForTest() {
   configuredExternalDbBackend = null;
   configuredDialect = null;
   configuredEndpoint = null;
+  configuredAcceptRotation = false;
+  configuredExpectedVaultKeyFp = null;
   transitionHandlers = [];
 }
 

package/lib/codepoint-class.js

@@ -67,6 +67,13 @@ function fromCp(cp) { return String.fromCharCode(cp); }
 var BIDI_RANGES       = [0x200E, 0x200F, 0x061C, [0x202A, 0x202E], [0x2066, 0x2069]];
 var C0_CTRL_RANGES    = [[0x0000, 0x0008], 0x000B, 0x000C, [0x000E, 0x001F]];
 var ZERO_WIDTH_RANGES = [0x00AD, [0x200B, 0x200D], 0x2060, 0xFEFF];
+// TAG_RANGES — Unicode Tags block U+E0000..U+E007F. TAG U+E0001 plus
+// the printable-ASCII tag map U+E0020..U+E007E carry an invisible copy
+// of an ASCII instruction that renders as nothing but is read verbatim
+// by an LLM tokenizer — the "ASCII smuggling" / Unicode-Tags prompt-
+// injection class. Stripping the block from untrusted prompt segments
+// removes the hidden instruction channel.
+var TAG_RANGES        = [[0xE0000, 0xE007F]];
 
 // allow:dynamic-regex — codepoints from BIDI_RANGES literal table
 var BIDI_RE       = new RegExp("[" + charClass(BIDI_RANGES) + "]");
@@ -82,6 +89,12 @@ var ZERO_WIDTH_RE = new RegExp("[" + charClass(ZERO_WIDTH_RANGES) + "]");
 var ZW_RE_G       = new RegExp("[" + charClass(ZERO_WIDTH_RANGES) + "]", "g");
 // allow:dynamic-regex — single literal codepoint U+0000
 var NULL_RE_G     = new RegExp(hex4(0x0000), "g");
+// Unicode Tags block (U+E0000..U+E007F). The \u{...} escape keeps this
+// source file pure ASCII (the codepoint-class purity invariant) while
+// matching astral codepoints — hence the `u` flag. Global form for the
+// strip path.
+var TAG_RE        = /[\u{E0000}-\u{E007F}]/u;
+var TAG_RE_G      = /[\u{E0000}-\u{E007F}]/gu;
 
 var NULL_BYTE = fromCp(0x0000);
 var BOM_CHAR  = fromCp(0xFEFF);
@@ -225,6 +238,7 @@ function assertNoCharThreats(text, opts, errorFactory, codePrefix) {
 //   opts.controlPolicy === "strip"   -> strip C0 controls
 //   opts.nullBytePolicy === "strip"  -> strip null bytes
 //   opts.zeroWidthPolicy === "strip" -> strip zero-widths
+//   opts.tagsPolicy === "strip"      -> strip Unicode Tags (U+E0000..)
 // Returns the cleaned string. Used by every guard's sanitize path so
 // each one doesn't reinvent the same sequence of replace() calls.
 function applyCharStripPolicies(text, opts) {
@@ -234,6 +248,7 @@ function applyCharStripPolicies(text, opts) {
   if (opts && opts.controlPolicy === "strip")   out = out.replace(C0_CTRL_RE_G, "");
   if (opts && opts.nullBytePolicy === "strip")  out = out.replace(NULL_RE_G, "");
   if (opts && opts.zeroWidthPolicy === "strip") out = out.replace(ZW_RE_G, "");
+  if (opts && opts.tagsPolicy === "strip")      out = out.replace(TAG_RE_G, "");
   return out;
 }
 
@@ -244,6 +259,7 @@ module.exports = {
   BIDI_RANGES:       BIDI_RANGES,
   C0_CTRL_RANGES:    C0_CTRL_RANGES,
   ZERO_WIDTH_RANGES: ZERO_WIDTH_RANGES,
+  TAG_RANGES:        TAG_RANGES,
   BIDI_RE:           BIDI_RE,
   BIDI_RE_G:         BIDI_RE_G,
   C0_CTRL_RE:        C0_CTRL_RE,
@@ -251,6 +267,8 @@ module.exports = {
   ZERO_WIDTH_RE:     ZERO_WIDTH_RE,
   ZW_RE_G:           ZW_RE_G,
   NULL_RE_G:         NULL_RE_G,
+  TAG_RE:            TAG_RE,
+  TAG_RE_G:          TAG_RE_G,
   NULL_BYTE:         NULL_BYTE,
   BOM_CHAR:          BOM_CHAR,
   applyCharStripPolicies: applyCharStripPolicies,