@blamejs/core 0.8.43 → 0.8.49

package/lib/cluster.js

@@ -1,54 +1,47 @@
 "use strict";
 /**
- * Cluster coordination — leader election + fencing tokens.
+ * @module b.cluster
+ * @featured true
+ * @nav    Production
+ * @title  Cluster
  *
- * Opt-in via `b.cluster.init(...)`. When init is never called, the
- * local process behaves as a permanent single leader: `isLeader()`
- * always returns true, `fencingToken()` returns 0, no heartbeat thread
- * runs, no DB is touched. Single-node deployments pay zero overhead.
+ * @intro
+ *   Opt-in active/active leader election with fencing-tokenized writes.
+ *   An external database is required: the framework's default provider
+ *   stores the leader-election row, the per-chain tip rows, and the
+ *   shared vault-key fingerprint in the same backend so every node sees
+ *   one source of truth. When `b.cluster.init` is never called, the
+ *   local process behaves as a permanent single leader: `isLeader()`
+ *   always returns true, `fencingToken()` returns 0, no heartbeat runs,
+ *   no DB is touched. Single-node deployments pay zero overhead.
  *
- * When init IS called, the framework starts a heartbeat that renews
- * the leader lease via the configured provider. On lease loss (network
- * partition, takeover, lease expiry) the node transitions to follower
- * and write-side framework primitives throw `NotLeaderError`.
+ *   When init IS called, the framework starts a heartbeat that renews
+ *   the leader lease via the configured provider. On lease loss (network
+ *   partition, takeover, lease expiry) the node transitions to follower
+ *   and write-side framework primitives throw `NotLeaderError`. The
+ *   audit + consent chains carry a fencing token alongside every row so
+ *   a stale leader cannot silently extend the chain after losing its
+ *   lease — the audit-tip CHECK constraint refuses the stale token at
+ *   the database layer. The application-level `requireLeader()` gate is
+ *   an early-rejection optimisation; the DB constraint is canonical.
  *
- * Threat model:
- *   - Two leaders writing simultaneously: prevented by fencing tokens.
- *     Every leader-only DB write includes the current token; a
- *     CHECK constraint on the audit-tip row rejects a stale token.
- *     The application-layer `requireLeader()` gate is just an early
- *     rejection optimisation; the DB constraint is the canonical guard.
- *   - Follower receiving a write: rejected at the framework boundary.
- *     Operators front the cluster with a load balancer that routes
- *     write paths to the current leader.
- *   - External-db unreachable: heartbeat fails; after `leaseTtl` no
- *     leader exists and writes fail closed. When the DB recovers,
- *     election resumes.
+ *   Threat model:
+ *     - Two leaders writing simultaneously — prevented by fencing
+ *       tokens carried into the audit-tip row.
+ *     - Follower receiving a write — rejected at the framework boundary
+ *       via NotLeaderError. Operators front the cluster with a load
+ *       balancer that routes write paths to the current leader; the
+ *       discovery handler exposes which node holds the lease.
+ *     - External-db unreachable — heartbeat fails; after `leaseTtl` no
+ *       leader exists and writes fail closed. When the DB recovers,
+ *       election resumes.
+ *     - Vault-key drift — every node fingerprints its vault keys on
+ *       boot and compares against a canonical fingerprint stored in
+ *       the cluster-state row. A node holding a different key refuses
+ *       to participate, preventing silent sealed-column corruption.
  *
- * Public API:
- *   await cluster.init(opts)             one-time bootstrap
- *   cluster.isLeader()                   sync; true on leader (or single-node)
- *   cluster.currentNodeId()              sync; configured nodeId
- *   cluster.endpoint()                   sync; this node's routable URL
- *                                        (operator-supplied at init), or
- *                                        null if unconfigured. Stored in
- *                                        the leader-election row so
- *                                        external observers can resolve
- *                                        "where is the current leader?"
- *   cluster.fencingToken()               sync; current monotonic token
- *   cluster.requireLeader()              sync; throws NotLeaderError
- *   cluster.currentLeader()              async; { nodeId, leaseExpiresAt,
- *                                                 fencingToken,
- *                                                 endpoint } | null
- *   cluster.discoveryHandler()           returns an HTTP request handler
- *                                        (req, res) → JSON. Mount on any
- *                                        route to expose the current
- *                                        leader for service-mesh / LB
- *                                        consumption. 200 with leader,
- *                                        503 with `{ leader: null }`
- *                                        when no leader.
- *   cluster.onTransition(fn)             register transition handler
- *   await cluster.shutdown()             releases lease, stops heartbeat
+ * @card
+ *   Opt-in active/active leader election with fencing-tokenized writes.
  */
 var C = require("./constants");
 var clusterProviderDb = require("./cluster-provider-db");
@@ -131,6 +124,52 @@ function _emitTransition(kind, detail) {
 
 // ---- init ----
 
+/**
+ * @primitive b.cluster.init
+ * @signature b.cluster.init(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @compliance soc2, dora
+ * @related   b.cluster.shutdown, b.cluster.requireLeader, b.cluster.currentLeader
+ *
+ * One-time cluster bootstrap. Configures the leader-election provider,
+ * validates the operator-supplied endpoint, runs boot-time rollback
+ * detection on the audit + consent chains, fingerprints this node's
+ * vault keys against the canonical cluster-state row, then starts the
+ * heartbeat that acquires and renews the leader lease. Throws on
+ * second invocation, on missing nodeId, on a leaseTtl below 10s, on a
+ * heartbeat that doesn't fit comfortably inside the lease, on a role
+ * outside `leader` / `follower`, and on a chain or vault-key mismatch
+ * that would let this node corrupt cluster state.
+ *
+ * @opts
+ *   nodeId:             string,            // required; stable identity
+ *   role:               "leader"|"follower",
+ *   leaseTtl:           number,            // ms; default 30000, min 10000
+ *   heartbeatInterval:  number,            // ms; default 10000, min 1000
+ *   endpoint:           string,            // routable URL of THIS node
+ *   allowedProtocols:   number,            // safeUrl.ALLOW_HTTP_TLS by default
+ *   provider:           object,            // custom election provider
+ *   externalDbBackend:  object,            // required when no custom provider
+ *   dialect:            "postgres"|"sqlite"|"mysql",
+ *   onTransition:       function (event),
+ *
+ * @example
+ *   await b.cluster.init({
+ *     nodeId:            "api-01",
+ *     role:              "leader",
+ *     leaseTtl:          30000,
+ *     heartbeatInterval: 10000,
+ *     endpoint:          "https://api-01.example.internal:8443",
+ *     externalDbBackend: b.externalDb.backend("primary"),
+ *     dialect:           "postgres",
+ *     onTransition:      function (event) {
+ *       // event.kind ∈ { "lease-acquired", "lease-lost", "lease-released" }
+ *       console.log("cluster transition:", event.kind, event.fencingToken);
+ *     },
+ *   });
+ *   // → undefined (heartbeat now running)
+ */
 async function init(opts) {
   if (initialized) {
     throw _err("ALREADY_INITIALIZED", "cluster.init() called twice", true);
@@ -527,12 +566,54 @@ async function _heartbeat() {
 
 // ---- public sync surface ----
 
+/**
+ * @primitive b.cluster.isLeader
+ * @signature b.cluster.isLeader()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.requireLeader, b.cluster.fencingToken, b.cluster.currentLeader
+ *
+ * Synchronous leader check. Returns `true` when this node currently
+ * holds a non-expired lease, OR when `b.cluster.init` was never called
+ * (single-node permanent-leader fallback). Returns `false` after a
+ * graceful `shutdown()`, after lease loss, or while a follower is
+ * waiting for its first lease. Cheap; safe to call on every request to
+ * branch leader-only work (scheduled jobs, cache warmers, write-side
+ * sweeps).
+ *
+ * @example
+ *   if (b.cluster.isLeader()) {
+ *     // Run scheduled tick on the leader only.
+ *     await runHourlyRollup();
+ *   }
+ *   // → undefined
+ */
 function isLeader() {
   if (terminated) return false;         // post-shutdown: never leader
   if (!initialized) return true;        // never-initialized: permanent leader
   return !!lease && Date.now() < lease.expiresAt;
 }
 
+/**
+ * @primitive b.cluster.isClusterMode
+ * @signature b.cluster.isClusterMode()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.init, b.cluster.externalDbBackend
+ *
+ * Returns `true` when `b.cluster.init` has been called AND an
+ * externalDbBackend is wired — i.e. framework state (audit, consent,
+ * fencing-tokenized writes) should route to the shared external DB.
+ * Returns `false` in single-node fallback or when a custom provider
+ * was supplied without an externalDbBackend; in that case the operator
+ * owns write-dispatch.
+ *
+ * @example
+ *   if (b.cluster.isClusterMode()) {
+ *     console.log("framework state lives on", b.cluster.externalDbBackend());
+ *   }
+ *   // → undefined
+ */
 // Has cluster.init been called with a real configuration? Used by
 // write-dispatch code (audit, consent, …) to decide whether framework
 // state should go to local SQLite or external-db.
@@ -540,31 +621,146 @@ function isClusterMode() {
   return initialized && !!configuredExternalDbBackend;
 }
 
+/**
+ * @primitive b.cluster.externalDbBackend
+ * @signature b.cluster.externalDbBackend()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.init, b.cluster.dialect, b.cluster.isClusterMode
+ *
+ * Returns the externalDb backend handle wired at init, or `null` in
+ * single-node fallback / when a custom provider was supplied without
+ * one. Internal write-dispatch code (audit, consent, fencing-tokenized
+ * primitives) calls this to route framework state to the shared
+ * backend; operator code rarely needs it directly.
+ *
+ * @example
+ *   var backend = b.cluster.externalDbBackend();
+ *   if (backend) {
+ *     // Framework state lands on the shared cluster DB.
+ *   }
+ *   // → undefined
+ */
 function externalDbBackend() {
   return configuredExternalDbBackend;
 }
 
+/**
+ * @primitive b.cluster.dialect
+ * @signature b.cluster.dialect()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.externalDbBackend, b.cluster.init
+ *
+ * Returns the SQL dialect string wired at init — `"postgres"`,
+ * `"sqlite"`, or `"mysql"`. Used by write-dispatch code that emits raw
+ * placeholder syntax (`$1` vs `?`) against the shared backend.
+ *
+ * @example
+ *   var ph = b.cluster.dialect() === "postgres" ? "$1" : "?";
+ *   // → undefined
+ */
 function dialect() {
   return configuredDialect;
 }
 
+/**
+ * @primitive b.cluster.currentNodeId
+ * @signature b.cluster.currentNodeId()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.endpoint, b.cluster.currentLeader
+ *
+ * Returns this node's configured nodeId, or `"single-node-local"` in
+ * the permanent-leader fallback when init was never called. Stable
+ * across the lifetime of the process — operators use it to tag audit
+ * metadata and observability events with the node identity.
+ *
+ * @example
+ *   b.audit.safeEmit({
+ *     action:   "system.bootstrapped",
+ *     actor:    { systemNode: b.cluster.currentNodeId() },
+ *     outcome:  "success",
+ *   });
+ *   // → undefined
+ */
 function currentNodeId() {
   return initialized ? nodeId : "single-node-local";
 }
 
-// This node's routable endpoint (operator-configured at cluster.init).
-// Returns null when not configured or in single-node fallback. External
-// observers should call discoveryHandler() / currentLeader() instead —
-// this getter is for the local node's own self-identity.
+/**
+ * @primitive b.cluster.endpoint
+ * @signature b.cluster.endpoint()
+ * @since     0.7.30
+ * @status    stable
+ * @related   b.cluster.discoveryHandler, b.cluster.currentLeader
+ *
+ * This node's routable endpoint URL — the value supplied as
+ * `opts.endpoint` to `b.cluster.init`. Returns `null` when not
+ * configured or in single-node fallback. External observers wanting
+ * to learn the leader's URL should call `discoveryHandler()` /
+ * `currentLeader()` instead; this getter is for the local node's own
+ * self-identity.
+ *
+ * @example
+ *   var here = b.cluster.endpoint();
+ *   // → "https://api-01.example.internal:8443"
+ */
 function endpoint() {
   return configuredEndpoint;
 }
 
+/**
+ * @primitive b.cluster.fencingToken
+ * @signature b.cluster.fencingToken()
+ * @since     0.4.0
+ * @status    stable
+ * @compliance soc2
+ * @related   b.cluster.isLeader, b.cluster.currentLeader
+ *
+ * Current monotonic fencing token for this node's lease. Increments
+ * with every successful acquisition; a stale leader's token is
+ * strictly less than the new leader's, and the audit-tip CHECK
+ * constraint refuses inserts carrying a stale token. Returns `0` when
+ * no lease is held (follower, between leases, single-node fallback).
+ *
+ * @example
+ *   var token = b.cluster.fencingToken();
+ *   // → 42
+ */
 function fencingToken() {
   if (!initialized) return 0;
   return lease ? lease.fencingToken : 0;
 }
 
+/**
+ * @primitive b.cluster.requireLeader
+ * @signature b.cluster.requireLeader()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.isLeader, b.cluster.currentLeader
+ *
+ * Throws `NotLeaderError` (statusCode 503) when this node is not the
+ * current leader. Use at the top of write-side handlers so a follower
+ * receiving a misrouted request rejects fast instead of producing a
+ * downstream fencing-token rejection. Single-node deployments where
+ * init was never called short-circuit through `isLeader() === true`
+ * and never throw.
+ *
+ * @example
+ *   try {
+ *     b.cluster.requireLeader();
+ *     await runHourlyRollup();
+ *   } catch (e) {
+ *     if (e.isNotLeaderError) {
+ *       // Operator's load balancer should retry on the leader.
+ *       res.writeHead(503).end();
+ *       return;
+ *     }
+ *     throw e;
+ *   }
+ *   // → undefined
+ */
 function requireLeader() {
   if (!isLeader()) {
     throw new NotLeaderError(
@@ -574,6 +770,28 @@ function requireLeader() {
   }
 }
 
+/**
+ * @primitive b.cluster.currentLeader
+ * @signature b.cluster.currentLeader()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.discoveryHandler, b.cluster.endpoint, b.cluster.isLeader
+ *
+ * Async snapshot of the cluster's current leader. Returns
+ * `{ nodeId, leaseExpiresAt, fencingToken, endpoint }` when a leader
+ * holds a non-expired lease, or `null` when no node currently holds
+ * the lease (election in progress, DB unreachable, lease expired).
+ * In single-node fallback, returns the synthetic
+ * `{ nodeId: "single-node-local", leaseExpiresAt: Infinity, ... }`
+ * record so callers don't need a second branch.
+ *
+ * @example
+ *   var leader = await b.cluster.currentLeader();
+ *   if (leader && leader.endpoint) {
+ *     console.log("forward write to", leader.endpoint);
+ *   }
+ *   // → undefined
+ */
 async function currentLeader() {
   if (!initialized) {
     return {
@@ -605,6 +823,31 @@ async function currentLeader() {
 // Handler is method-agnostic so it works behind any HTTP probe shape
 // (GET, HEAD, etc.). Cache-Control: no-store to avoid stale-leader
 // responses pinned by a caching proxy during a takeover.
+/**
+ * @primitive b.cluster.discoveryHandler
+ * @signature b.cluster.discoveryHandler()
+ * @since     0.7.30
+ * @status    stable
+ * @related   b.cluster.currentLeader, b.cluster.endpoint
+ *
+ * Returns an HTTP `(req, res)` handler suitable for mounting on any
+ * route (e.g. `/cluster/leader`). Replies 200 JSON with
+ * `{ leader, self }` when a leader holds the lease, 503 JSON with
+ * `{ leader: null, self }` when no leader exists or the DB is
+ * unreachable. Method-agnostic; emits `Cache-Control: no-store` so
+ * caching proxies don't pin a stale leader during a takeover. No auth
+ * — intended for infrastructure inside the trust boundary (load
+ * balancers, healthchecks, dashboards). Operators exposing the
+ * endpoint externally should layer auth via their own middleware.
+ *
+ * @example
+ *   var leaderProbe = b.cluster.discoveryHandler();
+ *   server.on("request", function (req, res) {
+ *     if (req.url === "/cluster/leader") return leaderProbe(req, res);
+ *     // ... rest of routing
+ *   });
+ *   // → undefined
+ */
 function discoveryHandler() {
   return async function (req, res) {
     var selfInfo = {
@@ -644,6 +887,31 @@ function discoveryHandler() {
   };
 }
 
+/**
+ * @primitive b.cluster.onTransition
+ * @signature b.cluster.onTransition(handler)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.init, b.cluster.shutdown
+ *
+ * Register a callback fired on every cluster role transition. Event
+ * shape: `{ kind, nodeId, at, fencingToken? }` where `kind` is one of
+ * `"lease-acquired"`, `"lease-lost"`, `"lease-released"`. Multiple
+ * handlers can be registered; each runs in registration order and
+ * a throwing handler is logged but doesn't break the chain. Throws
+ * synchronously when `handler` is not a function.
+ *
+ * @example
+ *   b.cluster.onTransition(function (event) {
+ *     b.audit.safeEmit({
+ *       action:   "system.cluster_transition",
+ *       actor:    { systemNode: event.nodeId },
+ *       outcome:  "success",
+ *       metadata: { kind: event.kind, fencingToken: event.fencingToken },
+ *     });
+ *   });
+ *   // → undefined
+ */
 function onTransition(handler) {
   if (typeof handler !== "function") {
     throw _err("INVALID_HANDLER", "onTransition expects a function", true);
@@ -651,6 +919,29 @@ function onTransition(handler) {
   transitionHandlers.push(handler);
 }
 
+/**
+ * @primitive b.cluster.shutdown
+ * @signature b.cluster.shutdown()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.cluster.init, b.cluster.onTransition
+ *
+ * Graceful cluster exit. Stops the heartbeat, releases the lease via
+ * the provider so the next election round can fire immediately
+ * (instead of waiting for `leaseTtl` to expire), emits a
+ * `lease-released` transition, and resets internal state. Idempotent
+ * when init was never called. After shutdown, `isLeader()` returns
+ * `false` permanently for this process; a fresh `init()` is required
+ * to participate again. Wire into the framework's appShutdown hook so
+ * SIGTERM frees the lease before the new replica boots.
+ *
+ * @example
+ *   process.on("SIGTERM", async function () {
+ *     await b.cluster.shutdown();
+ *     process.exit(0);
+ *   });
+ *   // → undefined
+ */
 async function shutdown() {
   if (!initialized) return;
   if (heartbeatTimer) {

package/lib/codepoint-class.js

@@ -86,6 +86,69 @@ var NULL_RE_G     = new RegExp(hex4(0x0000), "g");
 var NULL_BYTE = fromCp(0x0000);
 var BOM_CHAR  = fromCp(0xFEFF);
 
+// Unicode script-range catalog for IDN-homograph / mixed-script
+// confusable detection (UTS #39). Used by guard-domain, guard-email,
+// safe-url IDN host-label classification, and any future caller that
+// needs "is this label entirely one writing system?". Centralizing the
+// table keeps the codepoint definitions in one place — adding a script
+// is a single edit.
+var SCRIPT_RANGES = {
+  latin:    [[0x0041, 0x005A], [0x0061, 0x007A],
+             [0x00C0, 0x024F], [0x1E00, 0x1EFF]],                                 // allow:raw-byte-literal — Unicode script ranges
+  cyrillic: [[0x0400, 0x04FF], [0x0500, 0x052F]],                                 // allow:raw-byte-literal — Unicode Cyrillic + Cyrillic Supplement
+  greek:    [[0x0370, 0x03FF], [0x1F00, 0x1FFF]],                                 // allow:raw-byte-literal — Unicode Greek + Greek Extended
+  armenian: [[0x0530, 0x058F]],                                                   // allow:raw-byte-literal — Unicode Armenian
+  cherokee: [[0x13A0, 0x13FF], [0xAB70, 0xABBF]],                                 // allow:raw-byte-literal — Unicode Cherokee + Cherokee Supplement
+  han:      [[0x4E00, 0x9FFF]],                                                   // allow:raw-byte-literal — CJK Unified Ideographs
+  hiragana: [[0x3040, 0x309F]],                                                   // allow:raw-byte-literal — Hiragana
+  katakana: [[0x30A0, 0x30FF]],                                                   // allow:raw-byte-literal — Katakana
+  hangul:   [[0xAC00, 0xD7AF]],                                                   // allow:raw-byte-literal — Hangul Syllables
+  arabic:   [[0x0600, 0x06FF]],                                                   // allow:raw-byte-literal — Arabic
+  hebrew:   [[0x0590, 0x05FF]],                                                   // allow:raw-byte-literal — Hebrew
+};
+
+// scriptFor(cp) — returns the script-name string for a codepoint, or
+// null when the codepoint is in a script not in the catalog (digits,
+// punctuation, symbols, etc. are not script-classifying).
+function scriptFor(cp) {
+  var keys = Object.keys(SCRIPT_RANGES);
+  for (var i = 0; i < keys.length; i += 1) {
+    var ranges = SCRIPT_RANGES[keys[i]];
+    for (var j = 0; j < ranges.length; j += 1) {
+      if (cp >= ranges[j][0] && cp <= ranges[j][1]) return keys[i];
+    }
+  }
+  return null;
+}
+
+// detectMixedScripts(label, allowedScripts?) — returns null when the
+// label is single-script (or every script appears in the optional
+// allowedScripts allowlist), or an array of the detected script names
+// when the label mixes scripts (homograph attack shape — Cyrillic 'а'
+// inside an otherwise-Latin label, etc.). The result is the FULL set
+// of scripts seen; callers decide refuse / audit / strip.
+//
+// allowedScripts: an array of script names the caller treats as
+// acceptable; when supplied, a label whose every script is on the list
+// returns null even if multiple scripts appear (legitimate mixed-
+// script content like an English word inside a Japanese label).
+function detectMixedScripts(label, allowedScripts) {
+  if (typeof label !== "string" || label.length === 0) return null;
+  var seen = {};
+  for (var i = 0; i < label.length; i += 1) {
+    var script = scriptFor(label.charCodeAt(i));
+    if (script === null) continue;
+    seen[script] = true;
+  }
+  var scripts = Object.keys(seen);
+  if (scripts.length <= 1) return null;
+  if (!allowedScripts) return scripts;
+  for (var k = 0; k < scripts.length; k += 1) {
+    if (allowedScripts.indexOf(scripts[k]) === -1) return scripts;
+  }
+  return null;
+}
+
 // detectCharThreats — returns an array of issue objects for character-
 // class threats (bidi / null / C0-control) per the opts policy. Emits
 // at most one issue per class. Used by guard-* primitives' detection
@@ -193,4 +256,7 @@ module.exports = {
   applyCharStripPolicies: applyCharStripPolicies,
   assertNoCharThreats:    assertNoCharThreats,
   detectCharThreats:      detectCharThreats,
+  SCRIPT_RANGES:          SCRIPT_RANGES,
+  scriptFor:              scriptFor,
+  detectMixedScripts:     detectMixedScripts,
 };