@blamejs/core 0.9.46 → 0.10.1

package/lib/agent-orchestrator.js

@@ -60,11 +60,20 @@ var agentAudit        = require("./agent-audit");
 
 var audit             = lazyRequire(function () { return require("./audit"); });
 var cluster           = lazyRequire(function () { return require("./cluster"); });
+var vault             = lazyRequire(function () { return require("./vault"); });
 
 var AgentOrchestratorError = defineClass("AgentOrchestratorError", { alwaysPermanent: true });
 
 var DEFAULT_DRAIN_TIMEOUT_MS = C.TIME.minutes(2);
 var STREAM_ID_RAND_BYTES     = 8;                                                                     // allow:raw-byte-literal — stream-id random-suffix byte length, not a size cap
+var DEFAULT_PER_CONSUMER_STOP_MS = C.TIME.seconds(5);
+// SUBSTRATE-20 — FNV-1a offset basis salted with the first 32 bits of
+// SHA3-512(vault master). Attackers who don't have read access to the
+// vault keypair can't compute the salt, so they can't engineer
+// tenantIds that all map to one shard. Cached per-process; rotation
+// of vault keys produces a new basis (operator opts to reshard via
+// rebalance — same property as a manual `vault.rotate`).
+var _saltedFnvBasisCache = null;
 
 /**
  * @primitive b.agent.orchestrator.create
@@ -116,6 +125,19 @@ function create(opts) {
     // operator-supplied metadata (kind / tenantId / posture / ...);
     // every consuming process holds its own runtime map of name → agent.
     liveAgents:  new Map(),
+    // SUBSTRATE-8 — drain quiesce wiring. Operator passes
+    // { outbox, sagaInFlightCount, pubsubFlush } via create() so the
+    // drain phase can quiesce real in-flight work, not just stop
+    // consumers. Optional — operators with no outbox / saga / pubsub
+    // pass nothing and drain falls back to the consumer-stop path.
+    outbox:           opts.outbox || null,
+    sagaInFlightCount: typeof opts.sagaInFlightCount === "function" ? opts.sagaInFlightCount : null,
+    pubsubFlush:      typeof opts.pubsubFlush === "function" ? opts.pubsubFlush : null,
+    perConsumerStopMs: typeof opts.perConsumerStopMs === "number" ? opts.perConsumerStopMs : DEFAULT_PER_CONSUMER_STOP_MS,
+    // SUBSTRATE-9 — onTransition handler invalidates election cache
+    // on lease-lost / acquired / released. Operator opts out via
+    // { cacheElections: false } to always re-query b.cluster.
+    cacheElections:   opts.cacheElections !== false,
   };
 
   // Wire the drain phase into b.appShutdown if the operator supplied one.
@@ -125,8 +147,33 @@ function create(opts) {
     });
   }
 
+  // SUBSTRATE-9 — subscribe to cluster lease transitions so cached
+  // election state can't go stale after a partition. b.cluster
+  // .onTransition fires for every lease-acquired / lease-lost / lease-
+  // released event; we invalidate the affected resource's cached
+  // election so the next elect() call re-queries truth. When
+  // b.cluster isn't initialized (single-process deployments)
+  // onTransition still registers a handler — the dispatcher silently
+  // never fires until init completes.
+  if (clusterImpl && typeof clusterImpl.onTransition === "function") {
+    try {
+      clusterImpl.onTransition(function (event) {
+        // event.kind ∈ { "lease-acquired" | "lease-lost" |
+        //                "lease-released" | "lease-renewed" }. Every
+        // kind invalidates because membership / fencing-token may
+        // have changed.
+        ctx.elections.clear();
+        agentAudit.safeAudit(ctx.audit, "agent.orchestrator.election_cache_invalidated", null, {
+          kind: event && event.kind ? event.kind : "unknown",
+          fencingToken: event && event.fencingToken ? event.fencingToken : null,
+        });
+      });
+    } catch (_e) { /* drop-silent — onTransition unavailable in some test stubs */ }
+  }
+
   return {
     register:        function (name, agent, regOpts)         { return _register(ctx, name, agent, regOpts || {}); },
+    hydrate:         function (name, agent)                  { return _hydrate(ctx, name, agent); },
     unregister:      function (name, args)                   { return _unregister(ctx, name, args || {}); },
     lookup:          function (name, args)                   { return _lookup(ctx, name, args || {}); },
     list:            function (args)                         { return _list(ctx, args || {}); },
@@ -142,6 +189,70 @@ function create(opts) {
   };
 }
 
+/**
+ * @primitive b.agent.orchestrator.hydrate
+ * @signature b.agent.orchestrator.hydrate(name, agent)
+ * @since     0.9.57
+ * @status    stable
+ * @related   b.agent.orchestrator.create
+ *
+ * SUBSTRATE-3 — attach an in-process live agent reference to a row
+ * that already exists in the persistent registry backend. The
+ * canonical boot-phase contract: the *first* process to start a new
+ * agent calls `register()` (writes the backend row + holds the live
+ * ref); every *subsequent* process that picks up the row from durable
+ * storage (cross-orchestrator-restart, multi-process deploy, k8s pod
+ * recreate) calls `hydrate(name, agent)` to install its local live
+ * ref WITHOUT trying to re-write the backend row (which would refuse
+ * with `agent-orchestrator/duplicate`).
+ *
+ * Throws `agent-orchestrator/not-in-registry` when no backend row
+ * exists for `name`. Throws `agent-orchestrator/already-hydrated` if
+ * the live ref is already installed (operator's boot phase ran
+ * twice).
+ *
+ * Boot-phase contract:
+ *   1. Process A calls `register("tenant-acme.mail", agent, regOpts)`
+ *      → backend row written; A.liveAgents holds the ref.
+ *   2. Process A crashes / redeploys.
+ *   3. Process B starts: backend row already exists.
+ *   4. Process B walks the registry via `list()` → sees rows it
+ *      hasn't hydrated yet.
+ *   5. For each, Process B reconstructs the agent locally (from its
+ *      operator config) and calls `hydrate(name, agent)`.
+ *   6. `lookup("tenant-acme.mail")` from Process B now returns the
+ *      live ref instead of throwing `not-hydrated`.
+ *
+ * @example
+ *   var rows = await orch.list({});
+ *   for (var i = 0; i < rows.length; i += 1) {
+ *     var name = rows[i].name;
+ *     var agent = buildAgent(rows[i]);
+ *     await orch.hydrate(name, agent);
+ *   }
+ */
+async function _hydrate(ctx, name, agent) {
+  guardAgentRegistry.validate({ kind: "register", name: name, agentKind: "hydrate" }, {});
+  if (!agent || typeof agent !== "object") {
+    throw new AgentOrchestratorError("agent-orchestrator/bad-agent",
+      "hydrate: agent object required");
+  }
+  var row = await ctx.backend.get(name);
+  if (!row) {
+    throw new AgentOrchestratorError("agent-orchestrator/not-in-registry",
+      "hydrate: '" + name + "' not in registry backend — call register() first");
+  }
+  if (ctx.liveAgents.has(name)) {
+    throw new AgentOrchestratorError("agent-orchestrator/already-hydrated",
+      "hydrate: '" + name + "' already has a live agent ref in this process");
+  }
+  ctx.liveAgents.set(name, agent);
+  _safeAudit(ctx, "agent.orchestrator.hydrated", null, {
+    name: name, agentKind: row.kind, tenantId: row.tenantId,
+  });
+  return { name: name, agentKind: row.kind };
+}
+
 // ---- Registry -------------------------------------------------------------
 
 async function _register(ctx, name, agent, regOpts) {
@@ -310,11 +421,41 @@ function _spawnSingleConsumer(ctx, agent, queue, topic, maxConcurrency) {
  *   var shard = b.agent.orchestrator.shardFor("tenant-acme", 8);
  *   // → integer in [0, 8)
  */
+function _saltedFnvBasis() {
+  // SUBSTRATE-20 — salt FNV-1a offset basis with the vault master so
+  // an attacker can't engineer tenantIds that all hash to one shard.
+  // Vault-less path (single-process tests / dev) falls back to the
+  // standard FNV offset basis; production deployments with vault
+  // initialized get the salted variant for free.
+  if (_saltedFnvBasisCache !== null) return _saltedFnvBasisCache;
+  var v;
+  try { v = vault(); } catch (_e) { v = null; }
+  if (!v || typeof v.getKeysJson !== "function") {
+    _saltedFnvBasisCache = 2166136261;                                                                  // allow:raw-byte-literal — FNV-1a offset basis (vault-less fallback)
+    return _saltedFnvBasisCache;
+  }
+  var keysJson;
+  try { keysJson = v.getKeysJson(); }
+  catch (_e) {
+    _saltedFnvBasisCache = 2166136261;                                                                  // allow:raw-byte-literal — FNV-1a offset basis (vault-init-pending fallback)
+    return _saltedFnvBasisCache;
+  }
+  var hashHex = bCrypto.sha3Hash(keysJson);
+  // Read the first 32 bits as the salt; mix into the offset basis via
+  // XOR so the distribution properties of FNV are preserved.
+  var saltBuf = Buffer.from(hashHex.slice(0, 8), "hex");                                                // allow:raw-byte-literal — 32-bit prefix of SHA3-512 hex (4 bytes = 8 hex chars)
+  var salt = saltBuf.readUInt32BE(0);
+  _saltedFnvBasisCache = ((2166136261 ^ salt) >>> 0);                                                   // allow:raw-byte-literal — FNV-1a offset basis (vault-salted)
+  return _saltedFnvBasisCache;
+}
+
 function shardFor(shardKey, shards) {
   if (typeof shardKey !== "string" || shardKey.length === 0) return 0;
   if (shards <= 1) return 0;
-  // FNV-1a 32-bit — fast + good distribution for short keys.
-  var h = 2166136261;                                                                                 // allow:raw-byte-literal — FNV-1a offset basis
+  // FNV-1a 32-bit — fast + good distribution for short keys; salted
+  // offset basis defends algorithmic-complexity DoS via attacker-
+  // chosen tenantIds. See _saltedFnvBasis above.
+  var h = _saltedFnvBasis();
   for (var i = 0; i < shardKey.length; i += 1) {
     h ^= shardKey.charCodeAt(i);
     h = (h * 16777619) >>> 0;                                                                         // allow:raw-byte-literal — FNV-1a prime
@@ -337,13 +478,21 @@ async function _elect(ctx, args) {
   if (!isClusterMode) {
     // Single-process trivial leader.
     var elec = { isLeader: true, fencingToken: 1, resource: args.resource };
-    ctx.elections.set(args.resource, elec);
+    if (ctx.cacheElections) ctx.elections.set(args.resource, elec);
     _safeAudit(ctx, "agent.orchestrator.elected", args.actor, {
       resource: args.resource, mode: "single-process",
     });
     return elec;
   }
-  // Cluster mode: query current leader state via b.cluster.
+  // SUBSTRATE-9 — cluster mode: ALWAYS query truth from b.cluster.
+  // The onTransition handler installed in create() invalidates the
+  // cache on every lease event, so a cache hit here is safe (it
+  // means no lease event has fired since the last query). But the
+  // cache hit MUST be invalidated by a transition first; we never
+  // return stale isLeader:true after a lease-lost without re-asking.
+  if (ctx.cacheElections && ctx.elections.has(args.resource)) {
+    return ctx.elections.get(args.resource);
+  }
   var leaderRow = null;
   try { leaderRow = await ctx.cluster.currentLeader(); } catch (_e) { leaderRow = null; }
   var amLeader = false;
@@ -358,7 +507,7 @@ async function _elect(ctx, args) {
     resource:     args.resource,
     leaderId:     leaderRow && leaderRow.nodeId ? leaderRow.nodeId : null,
   };
-  ctx.elections.set(args.resource, elec2);
+  if (ctx.cacheElections) ctx.elections.set(args.resource, elec2);
   _safeAudit(ctx, "agent.orchestrator.elected", args.actor, {
     resource: args.resource, mode: "cluster",
     amLeader: amLeader, leaderId: elec2.leaderId,
@@ -373,20 +522,122 @@ async function _drain(ctx, args) {
   var timeoutMs = typeof args.timeoutMs === "number" ? args.timeoutMs : DEFAULT_DRAIN_TIMEOUT_MS;
   var drained = 0;
   var startedAt = Date.now();
-  // Stop every spawned consumer + collect timing.
+  var perConsumerMs = ctx.perConsumerStopMs;
+  // SUBSTRATE-8 — drain phases:
+  //   1. set ctx.draining so streams emit drain-markers + new task
+  //      dispatches refuse (consumers re-check on every envelope).
+  //   2. stop each consumer with BUG-6 per-consumer timeout race —
+  //      one hung consumer can't block the full drain budget.
+  //   3. quiesce in-flight: poll outbox.pendingCount + sagaInFlightCount
+  //      until 0 OR remaining-budget-ms elapses.
+  //   4. flush pubsub if operator wired it (delivers buffered events).
+  // ---- Phase 2: stop consumers (each capped) ----
   for (var i = 0; i < ctx.spawnedConsumers.length; i += 1) {
+    var remaining = timeoutMs - (Date.now() - startedAt);
+    if (remaining <= 0) break;
     var c = ctx.spawnedConsumers[i];
-    try { await c.stop(); drained += 1; } catch (_e) { /* best-effort */ }
-    if (Date.now() - startedAt > timeoutMs) break;
+    var consumerBudget = Math.min(perConsumerMs, remaining);
+    try {
+      await _raceTimeout(c.stop(), consumerBudget,
+        "consumer '" + c.topic + "' stop");
+      drained += 1;
+    } catch (e) {
+      _safeAudit(ctx, "agent.orchestrator.consumer_stop_timeout", null, {
+        topic: c.topic, budgetMs: consumerBudget,
+        reason: (e && e.message) || String(e),
+      });
+      // Continue with next consumer — one hung shouldn't strand the
+      // rest. The hung work will be reaped at process exit.
+    }
+  }
+
+  // ---- Phase 3: quiesce in-flight work ----
+  var inFlightQuiescent = await _quiesceInFlight(ctx, startedAt, timeoutMs);
+
+  // ---- Phase 4: pubsub flush (optional) ----
+  if (ctx.pubsubFlush) {
+    var flushRemaining = timeoutMs - (Date.now() - startedAt);
+    if (flushRemaining > 0) {
+      try {
+        await _raceTimeout(ctx.pubsubFlush(), flushRemaining, "pubsub flush");
+      } catch (e) {
+        _safeAudit(ctx, "agent.orchestrator.pubsub_flush_timeout", null, {
+          reason: (e && e.message) || String(e),
+        });
+      }
+    }
   }
+
   // Streams: signal each to wrap up (the streams check ctx.draining
   // and emit a drain-marker themselves; orchestrator just sets the flag).
   var streamCount = ctx.streams.size;
   _safeAudit(ctx, "agent.orchestrator.drained", null, {
     drainedConsumers: drained, totalConsumers: ctx.spawnedConsumers.length,
     streamCount: streamCount, elapsedMs: Date.now() - startedAt,
+    inFlightQuiescent: inFlightQuiescent,
+  });
+  return {
+    drained: drained,
+    elapsedMs: Date.now() - startedAt,
+    inFlightQuiescent: inFlightQuiescent,
+  };
+}
+
+function _raceTimeout(p, budgetMs, label) {
+  // Promise.race against a setTimeout. Pure-JS, no `b.safeAsync.withTimeout`
+  // dependency to avoid a load-time circular require. Note: a rejected
+  // race doesn't cancel the original promise (Node has no cancellation
+  // primitive); the consumer's stop() keeps running in the background
+  // and the orchestrator continues. This is the right behavior for
+  // drain — best-effort partial quiesce is better than hanging on one
+  // misbehaving consumer.
+  return new Promise(function (resolve, reject) {
+    var settled = false;
+    var t = setTimeout(function () {
+      if (settled) return;
+      settled = true;
+      reject(new AgentOrchestratorError("agent-orchestrator/drain-timeout",
+        label + " did not finish within " + budgetMs + "ms"));
+    }, budgetMs);
+    // The setTimeout is the timeout signal: when stop() never resolves,
+    // this timer is the ONLY event-loop work tracking drain's progress.
+    // Unref'ing it would let Node exit before the timer fires, leaving
+    // the awaiting drain() promise pending forever (process exits while
+    // the caller's await chain has no driver).
+    Promise.resolve(p).then(
+      function (v) { if (!settled) { settled = true; clearTimeout(t); resolve(v); } },
+      function (e) { if (!settled) { settled = true; clearTimeout(t); reject(e); } }
+    );
   });
-  return { drained: drained, elapsedMs: Date.now() - startedAt };
+}
+
+async function _quiesceInFlight(ctx, startedAt, timeoutMs) {
+  // Outbox + saga in-flight quiesce loop. Polls every 50ms (cheap;
+  // we already paid the consumer-stop budget so this is mostly a
+  // few ticks of waiting for the publisher to mark in-flight rows
+  // 'published'). Returns true if quiescent, false on timeout.
+  if (!ctx.outbox && !ctx.sagaInFlightCount) return true;
+  while (Date.now() - startedAt < timeoutMs) {
+    var anyInFlight = false;
+    if (ctx.outbox && typeof ctx.outbox.pendingCount === "function") {
+      var pending;
+      try { pending = await ctx.outbox.pendingCount(); }
+      catch (_e) { pending = 0; }
+      if (pending > 0) anyInFlight = true;
+    }
+    if (ctx.sagaInFlightCount) {
+      var sagaPending;
+      try { sagaPending = await ctx.sagaInFlightCount(); }
+      catch (_e) { sagaPending = 0; }
+      if (sagaPending > 0) anyInFlight = true;
+    }
+    if (!anyInFlight) return true;
+    await new Promise(function (r) {
+      var t = setTimeout(r, 50);                                                                       // allow:raw-byte-literal — 50ms in-flight poll interval
+      if (t && typeof t.unref === "function") t.unref();
+    });
+  }
+  return false;
 }
 
 // ---- Streams (v0.9.23 substrate hook) -------------------------------------
@@ -460,4 +711,7 @@ module.exports = {
   guards: {
     registry: guardAgentRegistry,
   },
+  // Test-only — flush the salted FNV basis cache so a vault reset
+  // between tests forces re-derivation.
+  _resetForTest: function () { _saltedFnvBasisCache = null; },
 };

package/lib/agent-posture-chain.js

@@ -51,16 +51,90 @@
  */
 
 var lazyRequire             = require("./lazy-require");
+var nodeCrypto              = require("node:crypto");
 var { defineClass }         = require("./framework-error");
 var guardPostureChain       = require("./guard-posture-chain");
 var agentAudit              = require("./agent-audit");
+var safeJson                = require("./safe-json");
+var bCrypto                 = require("./crypto");
 
 var audit                   = lazyRequire(function () { return require("./audit"); });
+var vault                   = lazyRequire(function () { return require("./vault"); });
 
 var AgentPostureChainError = defineClass("AgentPostureChainError", { alwaysPermanent: true });
 
 var BUILTIN_REGIMES = Object.freeze(["hipaa", "pci-dss", "gdpr", "soc2"]);
 
+// SUBSTRATE-10 — envelope MAC vocabulary. Cross-process envelope
+// integrity: an attacker with queue / event-bus write access who
+// strips postureSet to [] and re-sends a saga / sub-agent envelope
+// can bypass the downgrade refusal in _validate (which only checks
+// SHAPE, not authenticity). Defense is a keyed MAC over the canonical
+// envelope bytes, computed at appendHop and verified at validate.
+var ENVELOPE_MAC_LABEL = "blamejs.agent.postureChain/v1";
+var ENVELOPE_MAC_KEY_BYTES = 32;                                                                        // allow:raw-byte-literal — HMAC-SHA3-512 keyed bytes
+// SUBSTRATE-21 — hop count cap defends infinite recursion across
+// agent delegation. 16 is the spec default; operators can lower via
+// opts.maxHopCount but never raise (audit fan-out without a cap is a
+// DoS class).
+var DEFAULT_MAX_HOP_COUNT = 16;                                                                         // allow:raw-byte-literal — hop count cap
+var _macKeyCache = null;                                                                                // memoized per-vault-master key
+
+function _resolveMacKey() {
+  // Lazy derivation keyed off the vault master. Operator rotating
+  // vault keys invalidates every in-flight MAC — desired property.
+  // Memoization is process-local; if vault rotates within the same
+  // process the operator restarts (vault rotation already implies it).
+  if (_macKeyCache) return _macKeyCache;
+  var v;
+  try { v = vault(); } catch (_e) { v = null; }
+  if (!v || typeof v.getKeysJson !== "function") {
+    throw new AgentPostureChainError("agent-posture-chain/vault-not-initialized",
+      "envelope MAC: vault must be initialized before posture-chain envelopes can be authenticated " +
+      "(operator wires b.vault.init() at boot)");
+  }
+  var keysJson;
+  try { keysJson = v.getKeysJson(); }
+  catch (e) {
+    throw new AgentPostureChainError("agent-posture-chain/vault-not-initialized",
+      "envelope MAC: vault.getKeysJson threw — " + (e && e.message ? e.message : String(e)));
+  }
+  var rootBytes = Buffer.from(bCrypto.sha3Hash(keysJson), "hex");
+  var input = Buffer.concat([
+    Buffer.from(ENVELOPE_MAC_LABEL, "utf8"),
+    Buffer.from([0x00]),
+    rootBytes,
+  ]);
+  _macKeyCache = bCrypto.kdf(input, ENVELOPE_MAC_KEY_BYTES);
+  return _macKeyCache;
+}
+
+function _envelopeMacBytes(envelope) {
+  // Sign every field that downstream consumers verify off the wire,
+  // except the `_mac` field itself. SUBSTRATE-21 — also includes
+  // hopCount + chainTrail so a hostile rewriter can't roll back the
+  // trail to evade the cap.
+  var payload = {
+    postureSet: Array.isArray(envelope.postureSet) ? envelope.postureSet.slice().sort() : [],
+    chainTrail: Array.isArray(envelope.chainTrail) ? envelope.chainTrail.slice() : [],
+    enteredAt:  Array.isArray(envelope.enteredAt)  ? envelope.enteredAt.slice()  : [],
+    hopCount:   typeof envelope.hopCount === "number" ? envelope.hopCount : 0,
+  };
+  return Buffer.from(safeJson.canonical(payload), "utf8");
+}
+
+function _signEnvelope(envelope) {
+  var key = _resolveMacKey();
+  var mac = nodeCrypto.createHmac("sha3-512", key).update(_envelopeMacBytes(envelope)).digest();
+  return mac.toString("base64");
+}
+
+function _verifyEnvelopeMac(envelope) {
+  if (typeof envelope._mac !== "string" || envelope._mac.length === 0) return false;
+  var expected = _signEnvelope(envelope);
+  return bCrypto.timingSafeEqual(envelope._mac, expected);
+}
+
 /**
  * @primitive b.agent.postureChain.create
  * @signature b.agent.postureChain.create(opts)
@@ -84,14 +158,32 @@ function create(opts) {
   var auditImpl = opts.audit || audit();
   var declaredRegimes = Object.create(null);
   for (var i = 0; i < BUILTIN_REGIMES.length; i += 1) declaredRegimes[BUILTIN_REGIMES[i]] = true;
+  // allow:numeric-opt-Infinity — operator opt clamped to [1, DEFAULT_MAX_HOP_COUNT]; bad input falls back to default
+  var maxHopCount = typeof opts.maxHopCount === "number" && opts.maxHopCount > 0 &&
+                    opts.maxHopCount <= DEFAULT_MAX_HOP_COUNT
+                      ? Math.floor(opts.maxHopCount)
+                      : DEFAULT_MAX_HOP_COUNT;
+  // SUBSTRATE-10 escape hatch — only operator-confirmed single-process
+  // unit tests should opt out of envelope MAC. Production / multi-
+  // process / queue-spanning deployments leave the default on; the
+  // gate audit-emits when bypassed so the posture is visible.
+  var requireMac = opts.requireMac !== false;
+  var ctx = {
+    audit:        auditImpl,
+    maxHopCount:  maxHopCount,
+    requireMac:   requireMac,
+  };
   return {
     declareRegime: function (name)                          { return _declareRegime(declaredRegimes, name); },
     isSubset:      function (targetSet, sourceSet)          { return _isSubset(targetSet, sourceSet); },
     union:         function ()                              { return _union.apply(null, arguments); },
     canDelegate:   function (sourceSet, targetSet, method)  { return _canDelegate(sourceSet, targetSet, method, auditImpl); },
-    appendHop:     function (envelope, hopName)             { return _appendHop(envelope, hopName); },
-    validate:      function (envelope, agentPostureSet)     { return _validate(envelope, agentPostureSet, auditImpl); },
+    appendHop:     function (envelope, hopName)             { return _appendHop(ctx, envelope, hopName); },
+    validate:      function (envelope, agentPostureSet)     { return _validate(ctx, envelope, agentPostureSet); },
+    sign:          function (envelope)                      { return _signEnvelope(envelope); },
+    verify:        function (envelope)                      { return _verifyEnvelopeMac(envelope); },
     REGIMES:       Object.freeze(Object.keys(declaredRegimes)),
+    MAX_HOP_COUNT: maxHopCount,
     AgentPostureChainError: AgentPostureChainError,
     _declaredRegimes: declaredRegimes,
   };
@@ -155,7 +247,7 @@ function _missing(targetSet, sourceSet) {
   return out;
 }
 
-function _appendHop(envelope, hopName) {
+function _appendHop(ctx, envelope, hopName) {
   if (!envelope || typeof envelope !== "object") {
     throw new AgentPostureChainError("agent-posture-chain/bad-envelope",
       "appendHop: envelope required");
@@ -165,6 +257,19 @@ function _appendHop(envelope, hopName) {
       "appendHop: hopName must be a non-empty string");
   }
   var trail = Array.isArray(envelope.chainTrail) ? envelope.chainTrail.slice() : [];
+  // SUBSTRATE-21 — cap enforced BEFORE the push so the hop-cap throw
+  // fires consistently regardless of whether the operator inspects
+  // trail.length first. Cap is a hard refusal (no truncation) because
+  // a silently-dropped hop loses audit provenance for the call.
+  if (trail.length >= ctx.maxHopCount) {
+    agentAudit.safeAudit(ctx.audit, "agent.posture_chain.hop_cap_refused", null, {
+      hopName: hopName, hopCount: trail.length, maxHopCount: ctx.maxHopCount,
+      chainTrail: trail,
+    });
+    throw new AgentPostureChainError("agent-posture-chain/hop-cap-exceeded",
+      "appendHop: chain trail has " + trail.length + " hops; cap is " + ctx.maxHopCount +
+      " — refusing to extend (operator delegation cycle?)");
+  }
   trail.push(hopName);
   var enteredAt = Array.isArray(envelope.enteredAt) ? envelope.enteredAt.slice() : [];
   enteredAt.push(Date.now());
@@ -174,11 +279,61 @@ function _appendHop(envelope, hopName) {
     hopCount:   trail.length,
   });
   guardPostureChain.validate(newEnvelope);
+  // SUBSTRATE-10 — sign at every hop. Verify-side enforces requireMac.
+  // ctx.requireMac=false (operator-confirmed test escape hatch) skips
+  // the sign so a vault-less test path still works.
+  if (ctx.requireMac) {
+    try {
+      newEnvelope._mac = _signEnvelope(newEnvelope);
+    } catch (e) {
+      // Vault not initialized at boot — surface the error to the
+      // operator. Without the MAC the envelope is unauthenticated and
+      // every downstream _validate would refuse it; better to refuse
+      // here with a clear message.
+      throw new AgentPostureChainError("agent-posture-chain/mac-sign-failed",
+        "appendHop: envelope MAC sign failed — " + (e && e.message ? e.message : String(e)) +
+        " — operator wires b.vault.init() before agent-posture-chain.appendHop OR " +
+        "passes create({ requireMac: false }) for vault-less unit tests");
+    }
+  }
   return newEnvelope;
 }
 
-function _validate(envelope, agentPostureSet, auditImpl) {
+function _validate(ctx, envelope, agentPostureSet) {
   guardPostureChain.validate(envelope);
+  // SUBSTRATE-10 — MAC verification BEFORE any field-based decision so
+  // the wire-rewrite attack (postureSet:[] downgrade with valid SHAPE
+  // but no integrity binding) is refused. ctx.requireMac=false skips
+  // verification and emits an audit so the bypass is visible.
+  if (ctx.requireMac) {
+    if (typeof envelope._mac !== "string" || envelope._mac.length === 0) {
+      agentAudit.safeAudit(ctx.audit, "agent.posture_chain.unauthenticated_envelope", null, {
+        chainTrail: envelope.chainTrail, postureSet: envelope.postureSet,
+      });
+      throw new AgentPostureChainError("agent-posture-chain/missing-mac",
+        "validate: envelope is unauthenticated (no _mac field) — refusing under requireMac=true");
+    }
+    if (!_verifyEnvelopeMac(envelope)) {
+      agentAudit.safeAudit(ctx.audit, "agent.posture_chain.mac_verify_failed", null, {
+        chainTrail: envelope.chainTrail, postureSet: envelope.postureSet,
+      });
+      throw new AgentPostureChainError("agent-posture-chain/mac-verify-failed",
+        "validate: envelope MAC verification failed — bytes tampered, " +
+        "chain trail rewritten, or signed under a different vault keypair");
+    }
+  } else {
+    agentAudit.safeAudit(ctx.audit, "agent.posture_chain.mac_skipped", null, {
+      chainTrail: envelope.chainTrail,
+    });
+  }
+  // SUBSTRATE-21 — hop cap also enforced at validate-time. A hostile
+  // envelope might arrive with hopCount > cap if a prior hop's
+  // requireMac was off; refuse here regardless.
+  if (Array.isArray(envelope.chainTrail) && envelope.chainTrail.length > ctx.maxHopCount) {
+    throw new AgentPostureChainError("agent-posture-chain/hop-cap-exceeded",
+      "validate: chain trail length " + envelope.chainTrail.length +
+      " exceeds cap " + ctx.maxHopCount);
+  }
   // The source (envelope) carries a postureSet; the target (the agent
   // we're entering) declares its own posture set. Target must be a
   // superset of source — i.e., the agent covers every regime the
@@ -186,7 +341,7 @@ function _validate(envelope, agentPostureSet, auditImpl) {
   if (Array.isArray(agentPostureSet)) {
     if (!_isSubset(agentPostureSet, envelope.postureSet)) {
       var missing = _missing(agentPostureSet, envelope.postureSet);
-      agentAudit.safeAudit(auditImpl, "agent.posture_chain.downgrade_refused", null, {
+      agentAudit.safeAudit(ctx.audit, "agent.posture_chain.downgrade_refused", null, {
         sourceSet: envelope.postureSet, targetSet: agentPostureSet, missing: missing,
         chainTrail: envelope.chainTrail,
       });
@@ -201,8 +356,11 @@ function _validate(envelope, agentPostureSet, auditImpl) {
 module.exports = {
   create:                    create,
   BUILTIN_REGIMES:           BUILTIN_REGIMES,
+  MAX_HOP_COUNT:             DEFAULT_MAX_HOP_COUNT,
   AgentPostureChainError:    AgentPostureChainError,
   guards: {
     chain: guardPostureChain,
   },
+  // Test-only — flush the memoized MAC key after a vault reset.
+  _resetForTest: function () { _macKeyCache = null; },
 };