chainlesschain 0.161.11 → 0.162.0

package/src/gateways/terminal/terminal-handlers.js

@@ -0,0 +1,121 @@
+/**
+ * terminal-handlers — WS topic handlers for Plan A remote-terminal.
+ *
+ * ESM mirror of `desktop-app-vue/src/main/web-shell/handlers/terminal-handlers.js`.
+ * Keep both copies in sync (see the matching mirror docstring there).
+ */
+
+export const DEFAULT_DANGEROUS_PATTERNS = [
+  /\brm\s+-rf\b/i,
+  /\bformat\s+[a-z]:/i,
+  /\bshutdown\b/i,
+  /\bdel\s+\/[sq]/i,
+  /\bdiskpart\b/i,
+  /:\(\)\s*{\s*:\s*\|\s*:\s*&\s*}\s*;\s*:/,
+];
+
+export function bufferToBase64(buf) {
+  return Buffer.isBuffer(buf)
+    ? buf.toString("base64")
+    : Buffer.from(buf, "utf-8").toString("base64");
+}
+
+export function base64ToBuffer(s) {
+  if (typeof s !== "string") {
+    throw new Error("data_must_be_base64_string");
+  }
+  return Buffer.from(s, "base64");
+}
+
+export function createTerminalHandlers(options) {
+  const { ptyManager, broadcast } = options;
+  if (!ptyManager) throw new TypeError("ptyManager is required");
+  if (typeof broadcast !== "function") {
+    throw new TypeError("broadcast must be a function");
+  }
+  const dangerousPatterns =
+    options.dangerousPatterns || DEFAULT_DANGEROUS_PATTERNS;
+  const requireConfirmation =
+    options.requireConfirmation || (async () => false);
+  const verifyTrustedSource = options.verifyTrustedSource || (() => true);
+
+  function attachServerEvents() {
+    ptyManager.on("stdout", ({ sessionId, data, seq }) => {
+      broadcast({
+        type: "terminal.stdout",
+        payload: { sessionId, data: bufferToBase64(data), seq },
+      });
+    });
+    ptyManager.on("exit", ({ sessionId, exitCode, signal }) => {
+      broadcast({
+        type: "terminal.exit",
+        payload: { sessionId, exitCode, signal },
+      });
+    });
+  }
+
+  const handlers = {
+    "terminal.create": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const payload = frame?.payload || frame || {};
+      return ptyManager.create({
+        shell: payload.shell,
+        cwd: payload.cwd,
+        env: payload.env,
+        cols: payload.cols,
+        rows: payload.rows,
+      });
+    },
+
+    "terminal.list": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      return { sessions: ptyManager.list() };
+    },
+
+    "terminal.stdin": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const { sessionId, data } = frame?.payload || frame || {};
+      if (!sessionId) throw new Error("session_id_required");
+      const buf = base64ToBuffer(data);
+      const text = buf.toString("utf-8");
+      if (dangerousPatterns.some((re) => re.test(text))) {
+        const ok = await requireConfirmation(text, sessionId);
+        if (!ok) throw new Error("dangerous_keyword_blocked");
+      }
+      ptyManager.write(sessionId, buf);
+      return { ok: true };
+    },
+
+    "terminal.resize": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const { sessionId, cols, rows } = frame?.payload || frame || {};
+      if (!sessionId) throw new Error("session_id_required");
+      ptyManager.resize(sessionId, cols, rows);
+      return { ok: true };
+    },
+
+    "terminal.close": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const { sessionId } = frame?.payload || frame || {};
+      if (!sessionId) throw new Error("session_id_required");
+      ptyManager.close(sessionId);
+      return { ok: true };
+    },
+
+    "terminal.history": async (frame) => {
+      if (!verifyTrustedSource(frame)) return null;
+      const { sessionId, fromSeq } = frame?.payload || frame || {};
+      if (!sessionId) throw new Error("session_id_required");
+      const { chunks, truncated } = ptyManager.history(sessionId, fromSeq || 0);
+      return {
+        chunks: chunks.map((c) => ({
+          seq: c.seq,
+          data: bufferToBase64(c.data),
+        })),
+        truncated,
+      };
+    },
+  };
+
+  return { handlers, attachServerEvents };
+}

package/src/gateways/ws/topic-handler-attachment.js

@@ -0,0 +1,211 @@
+/**
+ * topic-handler-attachment — wrap a `ChainlessChainWSServer` instance with
+ * custom topic handlers, mirroring the existing dispatcher.
+ *
+ * Extracted from `desktop-app-vue/src/main/web-shell/ws-cli-loader.js` so
+ * both consumers (desktop web-shell AND `cc ui`) get the same protocol
+ * features:
+ *
+ *   - id + auth gates (token-protected servers reject unauthenticated
+ *     custom-topic calls; native CLI dispatch is untouched)
+ *   - plain async handler → `{type:"<topic>.result", ok, result}`
+ *   - async generator handler → `{type:"<topic>.chunk", ok, chunk}` *N +
+ *     terminal `{type:"<topic>.result", ok, result}`
+ *   - `<topic>.cancel` frame → `gen.return("client_cancel")` for in-flight
+ *     streams (keyed by request id, not topic)
+ *   - `ws.on("close")` → unwind every stream the client owned
+ *
+ * Single call site contract:
+ *
+ *   const handle = attachTopicHandlers(server, {
+ *     handlers: { 'terminal.create': async (frame, ctx) => {...}, ... },
+ *   });
+ *   handle.register('extra.topic', fn);
+ *   handle.broadcast({type:'terminal.stdout', payload:{...}});
+ *
+ * Returns `{ register, broadcast, topicHandlers }`. The server's
+ * `_dispatcher` is mutated in place — calling this twice on the same
+ * server stacks wrappers (each falls through to the previous), which is
+ * fine but usually unnecessary.
+ */
+
+/**
+ * @typedef {(frame: any, ctx: { topic: string, id: string, server: any, ws: any, clientId: string }) => (Promise<any> | any | AsyncIterable<any>)} TopicHandler
+ */
+
+/**
+ * @param {any} server  ChainlessChainWSServer instance (post-start())
+ * @param {object} [opts]
+ * @param {Record<string, TopicHandler>} [opts.handlers]
+ * @returns {{
+ *   register: (topic: string, fn: TopicHandler) => void,
+ *   broadcast: (frame: any) => void,
+ *   topicHandlers: Map<string, TopicHandler>,
+ * }}
+ */
+export function attachTopicHandlers(server, opts = {}) {
+  /** @type {Map<string, TopicHandler>} */
+  const topicHandlers = new Map();
+  if (opts.handlers) {
+    for (const [topic, fn] of Object.entries(opts.handlers)) {
+      if (typeof fn !== "function") {
+        throw new TypeError(
+          `attachTopicHandlers: handler for "${topic}" must be a function`,
+        );
+      }
+      topicHandlers.set(topic, fn);
+    }
+  }
+
+  /** @type {Map<string, { gen: AsyncIterator<any>, clientId: string }>} */
+  const inFlightStreams = new Map();
+
+  async function unwindStream(id, reason) {
+    const entry = inFlightStreams.get(id);
+    if (!entry) return;
+    inFlightStreams.delete(id);
+    try {
+      if (typeof entry.gen.return === "function") {
+        await entry.gen.return(reason);
+      }
+    } catch {
+      // Generator throw on unwind is non-fatal.
+    }
+  }
+
+  const wsCloseHooked = new WeakSet();
+  function ensureWsCloseHook(ws, clientId) {
+    if (!ws || typeof ws.on !== "function") return;
+    if (wsCloseHooked.has(ws)) return;
+    wsCloseHooked.add(ws);
+    ws.on("close", () => {
+      for (const [id, entry] of inFlightStreams) {
+        if (entry.clientId === clientId) {
+          unwindStream(id, "ws_close").catch(() => {});
+        }
+      }
+    });
+  }
+
+  const originalDispatcher = server._dispatcher;
+  server._dispatcher = {
+    async dispatch(clientId, ws, message) {
+      const { id, type } = message || {};
+      ensureWsCloseHook(ws, clientId);
+
+      if (id && typeof type === "string" && type.endsWith(".cancel")) {
+        await unwindStream(id, "client_cancel");
+        return;
+      }
+
+      if (id && type && topicHandlers.has(type)) {
+        const client = server.clients.get(clientId);
+        if (server.token && (!client || !client.authenticated)) {
+          server._send(ws, {
+            id,
+            type: "error",
+            code: "AUTH_REQUIRED",
+            message: "Authentication required. Send an auth message first.",
+          });
+          return;
+        }
+
+        const handler = topicHandlers.get(type);
+        try {
+          const ret = handler(message, {
+            topic: type,
+            id,
+            server,
+            ws,
+            clientId,
+          });
+
+          if (ret && typeof ret[Symbol.asyncIterator] === "function") {
+            inFlightStreams.set(id, { gen: ret, clientId });
+            let finalReturn = null;
+            try {
+              for (;;) {
+                const step = await ret.next();
+                if (step.done) {
+                  finalReturn = step.value ?? null;
+                  break;
+                }
+                if (ws.readyState !== 1) {
+                  await unwindStream(id, "readyState_closed");
+                  return;
+                }
+                server._send(ws, {
+                  id,
+                  type: `${type}.chunk`,
+                  ok: true,
+                  chunk: step.value ?? null,
+                });
+              }
+              server._send(ws, {
+                id,
+                type: `${type}.result`,
+                ok: true,
+                result: finalReturn,
+              });
+            } catch (streamErr) {
+              server._send(ws, {
+                id,
+                type: `${type}.result`,
+                ok: false,
+                error:
+                  streamErr instanceof Error
+                    ? streamErr.message
+                    : String(streamErr),
+              });
+            } finally {
+              inFlightStreams.delete(id);
+            }
+            return;
+          }
+
+          const result = await ret;
+          server._send(ws, {
+            id,
+            type: `${type}.result`,
+            ok: true,
+            result: result ?? null,
+          });
+        } catch (err) {
+          server._send(ws, {
+            id,
+            type: `${type}.result`,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+        return;
+      }
+
+      return originalDispatcher.dispatch(clientId, ws, message);
+    },
+  };
+
+  function register(topic, fn) {
+    if (typeof topic !== "string" || !topic) {
+      throw new TypeError(
+        "attachTopicHandlers: topic must be a non-empty string",
+      );
+    }
+    if (typeof fn !== "function") {
+      throw new TypeError("attachTopicHandlers: handler must be a function");
+    }
+    topicHandlers.set(topic, fn);
+  }
+
+  function broadcast(frame) {
+    if (!frame || typeof frame !== "object") return;
+    try {
+      server._broadcast(frame);
+    } catch {
+      // _send is readyState-guarded inside the server; the only path here
+      // would be an internal CLI ws-server bug. Don't crash the caller.
+    }
+  }
+
+  return { register, broadcast, topicHandlers };
+}

package/src/index.js

@@ -8,6 +8,7 @@ import { registerServicesCommand } from "./commands/services.js";
 import { registerConfigCommand } from "./commands/config.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
+import { registerPairCommand } from "./commands/pair.js";
 import { registerDbCommand } from "./commands/db.js";
 import { registerNoteCommand } from "./commands/note.js";
 import { registerChatCommand } from "./commands/chat.js";
@@ -393,6 +394,7 @@ export function createProgram(opts = {}) {
   registerConfigCommand(program);
   registerUpdateCommand(program);
   registerDoctorCommand(program);
+  registerPairCommand(program);
 
   // Headless commands
   registerDbCommand(program);

package/src/lib/cross-chain-mtc.js

@@ -421,6 +421,12 @@ function stagedFileName(op) {
  * Stage one bridge op for inclusion in the next batch close.
  * Idempotent: same op written twice -> single staging file.
  *
+ * #21 B.5 Layer 2 PR4 — when `op.multisig_provenance` is present, validate
+ * its structure via `verifyMultisigProvenance` before writing. Invalid
+ * provenance is rejected (`INVALID_MULTISIG_PROVENANCE`) instead of being
+ * silently persisted so downstream `closeBatch` / wrapper attachment
+ * cannot pick up malformed data.
+ *
  * @param {string} dir
  * @param {object} op
  * @param {{ requireEnabled?: boolean }} [opts]
@@ -434,6 +440,18 @@ export function stageBridgeOp(dir, op, opts = {}) {
     return { staged: false, path: null, reason: "DISABLED" };
   }
   validateBridgeOp(op);
+  if (op.multisig_provenance) {
+    const pv = verifyMultisigProvenance({
+      multisig_provenance: op.multisig_provenance,
+    });
+    if (!pv.ok) {
+      return {
+        staged: false,
+        path: null,
+        reason: `INVALID_MULTISIG_PROVENANCE:${pv.code}${pv.detail ? `:${pv.detail}` : ""}`,
+      };
+    }
+  }
   const file = path.join(stagingDir(dir), stagedFileName(op));
   if (fs.existsSync(file)) {
     return { staged: false, path: file, reason: "ALREADY_STAGED" };
@@ -564,10 +582,203 @@ export function closeBatch(dir, opts = {}) {
 
 // ─────────────────────────────────────────────────────────────────────
 // v0.2 — Multi-hop envelope (envelope-of-envelope)
+// v0.3 — #21 B.5 Layer 2 PR2: m-of-n multisig provenance on the wrapper
 // ─────────────────────────────────────────────────────────────────────
 
 const SCHEMA_MULTI_HOP_BRIDGE = "mtc-bridge-multihop/v1";
 
+const MULTISIG_PROVENANCE_REQUIRED_FIELDS = Object.freeze([
+  "proposal_id",
+  "threshold_m",
+  "member_count_n",
+  "signers",
+  "partial_sigs",
+]);
+
+const MULTISIG_SUPPORTED_ALGS = Object.freeze(["Ed25519", "SLH-DSA-128F"]);
+
+/**
+ * Attach m-of-n multisig provenance to a bridge envelope (single-hop or
+ * multi-hop wrapper). Returns a new envelope object — does not mutate.
+ *
+ * Provenance carries the proposal id, the m/n policy at consume time, the
+ * sorted-ASC signer DID list, and per-signer {did, alg, sig:hex} entries.
+ * Mirrors the cc_bridges columns introduced in #21 B.5 Layer 2 PR1.
+ *
+ * Layer 3 onchain broadcasters read this field to construct the m-of-n
+ * proof bundle expected by destination-chain verifier contracts.
+ *
+ * @param {object} envelope    - mtc-envelope/v1 or mtc-bridge-multihop/v1
+ * @param {{
+ *   proposalId: string,
+ *   thresholdM: number,
+ *   memberCountN: number,
+ *   signers: string[],
+ *   partialSigs: Array<{did: string, alg: string, sig: string}>,
+ * }} provenance
+ * @returns {object} new envelope with `multisig_provenance` field
+ */
+export function attachMultisigProvenance(envelope, provenance) {
+  if (!envelope || typeof envelope !== "object") {
+    throw new TypeError("attachMultisigProvenance: envelope required");
+  }
+  if (!provenance || typeof provenance !== "object") {
+    throw new TypeError("attachMultisigProvenance: provenance required");
+  }
+  return {
+    ...envelope,
+    multisig_provenance: {
+      proposal_id: provenance.proposalId,
+      threshold_m: provenance.thresholdM,
+      member_count_n: provenance.memberCountN,
+      signers: Array.isArray(provenance.signers) ? [...provenance.signers] : [],
+      partial_sigs: Array.isArray(provenance.partialSigs)
+        ? provenance.partialSigs.map((s) => ({
+            did: s.did,
+            alg: s.alg,
+            sig: s.sig,
+          }))
+        : [],
+    },
+  };
+}
+
+/**
+ * Strip-all-sigs canonical form for a bridge envelope carrying
+ * `multisig_provenance`. Returns a clone with every `partial_sigs[*].sig`
+ * replaced by `""` so producer and verifier can feed an identical byte
+ * sequence into JCS for m-of-n threshold tolerance.
+ *
+ * Mirrors `@chainlesschain/core-mtc/lib/publisher-signing.js
+ * _stripSigsForPublisher` (memory `mtc_publisher_sig_threshold.md`) — both
+ * the publisher_signature on a landmark and a wrapper-level m-of-n proof
+ * need the same canonical-skeleton-without-sigs invariant.
+ *
+ * Reused by PR3 verifier when checking each partial sig against the
+ * canonical wrapper bytes.
+ *
+ * @param {object} envelope - envelope with `multisig_provenance`
+ * @returns {object} clone with sigs zeroed; same envelope returned when no
+ *                   provenance is attached
+ */
+export function stripMultisigSigsForCanonical(envelope) {
+  if (!envelope || !envelope.multisig_provenance) return envelope;
+  return {
+    ...envelope,
+    multisig_provenance: {
+      ...envelope.multisig_provenance,
+      partial_sigs: (envelope.multisig_provenance.partial_sigs || []).map(
+        (s) => ({ ...s, sig: "" }),
+      ),
+    },
+  };
+}
+
+/**
+ * Structural validation of multisig_provenance on a bridge envelope.
+ * Does NOT verify cryptographic signatures (deferred to PR3 — would need
+ * the proposal's payload JCS + member pubkey lookup). Confirms:
+ *   - provenance is present and well-formed
+ *   - partial_sigs.length >= threshold_m
+ *   - every signer DID is in the policy.members allow-list (when supplied)
+ *   - every partial_sig has a supported alg + non-empty hex sig
+ *   - signer list is sorted ASC (canonical form invariant)
+ *
+ * @param {object} envelope - envelope with `multisig_provenance` to check
+ * @param {{ m: number, members?: Array<{did:string}> }} [policy] - optional
+ *   policy spec; when present, signer-membership and threshold are checked
+ *   against it instead of provenance's own `threshold_m` field
+ * @returns {{ ok: boolean, code?: string, detail?: string }}
+ */
+export function verifyMultisigProvenance(envelope, policy) {
+  if (!envelope || typeof envelope !== "object") {
+    return { ok: false, code: "BAD_ENVELOPE" };
+  }
+  const prov = envelope.multisig_provenance;
+  if (!prov || typeof prov !== "object") {
+    return { ok: false, code: "MISSING_PROVENANCE" };
+  }
+  for (const f of MULTISIG_PROVENANCE_REQUIRED_FIELDS) {
+    if (prov[f] === undefined || prov[f] === null) {
+      return { ok: false, code: "INCOMPLETE_PROVENANCE", detail: f };
+    }
+  }
+  if (typeof prov.proposal_id !== "string" || !prov.proposal_id) {
+    return { ok: false, code: "BAD_PROPOSAL_ID" };
+  }
+  if (
+    !Number.isInteger(prov.threshold_m) ||
+    prov.threshold_m < 1 ||
+    !Number.isInteger(prov.member_count_n) ||
+    prov.member_count_n < prov.threshold_m
+  ) {
+    return { ok: false, code: "BAD_THRESHOLD" };
+  }
+  if (!Array.isArray(prov.signers) || !Array.isArray(prov.partial_sigs)) {
+    return { ok: false, code: "BAD_PROVENANCE_SHAPE" };
+  }
+  if (prov.signers.length !== prov.partial_sigs.length) {
+    return { ok: false, code: "SIGNERS_SIGS_LENGTH_MISMATCH" };
+  }
+  const requiredM =
+    policy && Number.isInteger(policy.m) ? policy.m : prov.threshold_m;
+  if (prov.partial_sigs.length < requiredM) {
+    return {
+      ok: false,
+      code: "BELOW_THRESHOLD",
+      detail: `${prov.partial_sigs.length} < ${requiredM}`,
+    };
+  }
+  const sorted = [...prov.signers].sort();
+  for (let i = 0; i < prov.signers.length; i++) {
+    if (prov.signers[i] !== sorted[i]) {
+      return { ok: false, code: "SIGNERS_NOT_SORTED" };
+    }
+  }
+  const allowed =
+    policy && Array.isArray(policy.members)
+      ? new Set(policy.members.map((m) => m.did))
+      : null;
+  for (let i = 0; i < prov.partial_sigs.length; i++) {
+    const s = prov.partial_sigs[i];
+    if (!s || typeof s !== "object") {
+      return { ok: false, code: "BAD_PARTIAL_SIG", detail: `index ${i}` };
+    }
+    if (typeof s.did !== "string" || !s.did) {
+      return { ok: false, code: "BAD_PARTIAL_SIG_DID", detail: `index ${i}` };
+    }
+    if (s.did !== prov.signers[i]) {
+      return {
+        ok: false,
+        code: "SIGNER_DID_MISMATCH",
+        detail: `signers[${i}]=${prov.signers[i]} vs partial_sigs[${i}].did=${s.did}`,
+      };
+    }
+    if (!MULTISIG_SUPPORTED_ALGS.includes(s.alg)) {
+      return {
+        ok: false,
+        code: "UNSUPPORTED_ALG",
+        detail: `index ${i} alg=${s.alg}`,
+      };
+    }
+    if (typeof s.sig !== "string" || !/^[0-9a-fA-F]+$/.test(s.sig) || !s.sig) {
+      return {
+        ok: false,
+        code: "BAD_PARTIAL_SIG_HEX",
+        detail: `index ${i}`,
+      };
+    }
+    if (allowed && !allowed.has(s.did)) {
+      return {
+        ok: false,
+        code: "SIGNER_NOT_IN_POLICY",
+        detail: s.did,
+      };
+    }
+  }
+  return { ok: true };
+}
+
 /**
  * Build a multi-hop bridge envelope by chaining single-hop envelopes.
  * For a route A → B → C, the caller supplies the leg envelopes
@@ -579,9 +790,23 @@ const SCHEMA_MULTI_HOP_BRIDGE = "mtc-bridge-multihop/v1";
  *
  * @param {Array<object>} legEnvelopes - ≥ 2 single-hop bridge envelopes
  * @param {{ route_id?: string, total_amount?: string, asset?: string }} [meta]
+ * @param {{
+ *   proposalId: string,
+ *   thresholdM: number,
+ *   memberCountN: number,
+ *   signers: string[],
+ *   partialSigs: Array<{did:string,alg:string,sig:string}>,
+ * }} [multisigProvenance] - #21 B.5 Layer 2 PR2: optional m-of-n provenance
+ *   carried over from a multisig-gated bridge consume. Attached via
+ *   `attachMultisigProvenance` so canonical form (strip-all-sigs JCS) and
+ *   verifier path (`verifyMultisigProvenance`) work uniformly.
  * @returns {object} multi-hop wrapper envelope
  */
-export function buildMultiHopBridgeEnvelope(legEnvelopes, meta = {}) {
+export function buildMultiHopBridgeEnvelope(
+  legEnvelopes,
+  meta = {},
+  multisigProvenance = null,
+) {
   if (!Array.isArray(legEnvelopes) || legEnvelopes.length < 2) {
     throw new RangeError(
       "buildMultiHopBridgeEnvelope: need at least 2 leg envelopes",
@@ -616,7 +841,7 @@ export function buildMultiHopBridgeEnvelope(legEnvelopes, meta = {}) {
     legEnvelopes[0].leaf.src_chain,
     ...legEnvelopes.map((e) => e.leaf.dst_chain),
   ];
-  return {
+  const wrapper = {
     schema: SCHEMA_MULTI_HOP_BRIDGE,
     route_id:
       meta.route_id ||
@@ -629,6 +854,10 @@ export function buildMultiHopBridgeEnvelope(legEnvelopes, meta = {}) {
     asset: meta.asset || null,
     issued_at: new Date().toISOString(),
   };
+  if (multisigProvenance) {
+    return attachMultisigProvenance(wrapper, multisigProvenance);
+  }
+  return wrapper;
 }
 
 /**
@@ -636,11 +865,30 @@ export function buildMultiHopBridgeEnvelope(legEnvelopes, meta = {}) {
  * own landmark + the chain path must be continuous + at least one leg
  * must be the "lock" op (the trigger).
  *
+ * #21 B.5 Layer 2 PR3 — when `wrapper.multisig_provenance` is present OR
+ * `options.requireMultisig === true`, also runs `verifyMultisigProvenance`
+ * (structural). Result includes nested `multisig_result`. Cryptographic
+ * verification of each partial sig against canonical wrapper bytes is
+ * deferred (would require per-signer pubkey lookup; see Layer 3).
+ *
  * @param {object} wrapper - multi-hop envelope from buildMultiHopBridgeEnvelope
  * @param {Array<{landmark: object}>} legCacheEntries - one per leg, in order
- * @returns {{ ok: boolean, code?: string, leg_results?: Array<{ok, code?}> }}
+ * @param {{
+ *   expectedMultisigPolicy?: { m: number, members?: Array<{did:string}> },
+ *   requireMultisig?: boolean,
+ * }} [options]
+ * @returns {{
+ *   ok: boolean,
+ *   code?: string,
+ *   leg_results?: Array<{ok, code?}>,
+ *   multisig_result?: { ok: boolean, code?: string, detail?: string },
+ * }}
  */
-export function verifyMultiHopBridgeEnvelope(wrapper, legCacheEntries) {
+export function verifyMultiHopBridgeEnvelope(
+  wrapper,
+  legCacheEntries,
+  options = {},
+) {
   if (!wrapper || wrapper.schema !== SCHEMA_MULTI_HOP_BRIDGE) {
     return { ok: false, code: "BAD_MULTIHOP_SCHEMA" };
   }
@@ -679,8 +927,29 @@ export function verifyMultiHopBridgeEnvelope(wrapper, legCacheEntries) {
       }
     }
   }
-  const allOk = results.every((r) => r.ok);
-  return { ok: allOk, leg_results: results };
+  const legsOk = results.every((r) => r.ok);
+  const hasProvenance = !!wrapper.multisig_provenance;
+  const requireMultisig = !!options.requireMultisig;
+  if (hasProvenance || requireMultisig) {
+    const multisigResult = verifyMultisigProvenance(
+      wrapper,
+      options.expectedMultisigPolicy,
+    );
+    if (!multisigResult.ok) {
+      return {
+        ok: false,
+        code: "MULTISIG_PROVENANCE_INVALID",
+        leg_results: results,
+        multisig_result: multisigResult,
+      };
+    }
+    return {
+      ok: legsOk,
+      leg_results: results,
+      multisig_result: multisigResult,
+    };
+  }
+  return { ok: legsOk, leg_results: results };
 }
 
 // ─────────────────────────────────────────────────────────────────────