@did-btcr2/aggregation 0.1.0 → 0.3.0

package/dist/cjs/service/index.js

@@ -0,0 +1,3199 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/service/index.ts
+var service_exports = {};
+__export(service_exports, {
+  AggregationService: () => AggregationService,
+  AggregationServiceRunner: () => AggregationServiceRunner,
+  DEFAULT_ADVERT_REPEAT_INTERVAL_MS: () => DEFAULT_ADVERT_REPEAT_INTERVAL_MS,
+  DEFAULT_MAX_UPDATE_SIZE_BYTES: () => DEFAULT_MAX_UPDATE_SIZE_BYTES,
+  HttpServerTransport: () => HttpServerTransport,
+  InMemoryRateLimitStore: () => InMemoryRateLimitStore,
+  InboxBuffer: () => InboxBuffer,
+  NonceCache: () => NonceCache,
+  RateLimiter: () => RateLimiter,
+  formatSseComment: () => formatSseComment,
+  formatSseEvent: () => formatSseEvent
+});
+module.exports = __toCommonJS(service_exports);
+
+// src/service/service.ts
+var import_common4 = require("@did-btcr2/common");
+var import_cryptosuite = require("@did-btcr2/cryptosuite");
+var import_secp256k14 = require("@noble/curves/secp256k1.js");
+var import_utils3 = require("@noble/hashes/utils");
+
+// src/core/beacon-strategy.ts
+var import_common = require("@did-btcr2/common");
+var import_smt = require("@did-btcr2/smt");
+var CAS_STRATEGY = {
+  type: "CASBeacon",
+  buildAggregatedData(cohort) {
+    cohort.buildCASAnnouncement();
+  },
+  getDistributePayload(cohort) {
+    return { casAnnouncement: cohort.casAnnouncement };
+  },
+  validateParticipantView({ participantDid, included, expectedHash, body }) {
+    const casAnnouncement = body.casAnnouncement;
+    if (!casAnnouncement) return { matches: false };
+    if (!included) {
+      return { matches: !(participantDid in casAnnouncement), casAnnouncement };
+    }
+    return {
+      matches: casAnnouncement[participantDid] === expectedHash,
+      casAnnouncement
+    };
+  }
+};
+var SMT_STRATEGY = {
+  type: "SMTBeacon",
+  buildAggregatedData(cohort) {
+    cohort.buildSMTTree();
+  },
+  getDistributePayload(cohort, participantDid) {
+    const proof = cohort.smtProofs?.get(participantDid);
+    return { smtProof: proof };
+  },
+  validateParticipantView({ participantDid, included, submittedUpdate, body }) {
+    const smtProof = body.smtProof;
+    const index = (0, import_smt.didToIndex)(participantDid);
+    if (!included) {
+      if (!smtProof?.nonce || smtProof?.updateId) return { matches: false, smtProof };
+      const candidateHash2 = (0, import_smt.blockHash)((0, import_smt.blockHash)((0, import_smt.base64UrlToHash)(smtProof.nonce)));
+      return { matches: (0, import_smt.verifySerializedProof)(smtProof, index, candidateHash2), smtProof };
+    }
+    if (!smtProof?.updateId || !smtProof?.nonce || !submittedUpdate) return { matches: false, smtProof };
+    const canonicalBytes = new TextEncoder().encode((0, import_common.canonicalize)(submittedUpdate));
+    const expectedUpdateId = (0, import_smt.hashToBase64Url)((0, import_smt.blockHash)(canonicalBytes));
+    if (smtProof.updateId !== expectedUpdateId) {
+      return { matches: false, smtProof };
+    }
+    const candidateHash = (0, import_smt.blockHash)((0, import_smt.blockHash)((0, import_smt.base64UrlToHash)(smtProof.nonce)), (0, import_smt.base64UrlToHash)(smtProof.updateId));
+    return {
+      matches: (0, import_smt.verifySerializedProof)(smtProof, index, candidateHash),
+      smtProof
+    };
+  }
+};
+var STRATEGIES = /* @__PURE__ */ new Map([
+  [CAS_STRATEGY.type, CAS_STRATEGY],
+  [SMT_STRATEGY.type, SMT_STRATEGY]
+]);
+function getBeaconStrategy(type) {
+  return STRATEGIES.get(type);
+}
+
+// src/core/cohort.ts
+var import_bitcoin = require("@did-btcr2/bitcoin");
+var import_common3 = require("@did-btcr2/common");
+var import_smt2 = require("@did-btcr2/smt");
+var import_secp256k12 = require("@noble/curves/secp256k1.js");
+var import_utils2 = require("@noble/hashes/utils");
+var import_btc_signer2 = require("@scure/btc-signer");
+var import_musig22 = require("@scure/btc-signer/musig2");
+
+// src/core/errors.ts
+var import_common2 = require("@did-btcr2/common");
+var AggregationServiceError = class extends import_common2.MethodError {
+  constructor(message, type = "AggregationServiceError", data) {
+    super(message, type, data);
+  }
+};
+var AggregationCohortError = class extends import_common2.MethodError {
+  constructor(message, type = "AggregationCohortError", data) {
+    super(message, type, data);
+  }
+};
+var SigningSessionError = class extends import_common2.MethodError {
+  constructor(message, type = "SigningSessionError", data) {
+    super(message, type, data);
+  }
+};
+
+// src/core/recovery-policy.ts
+var import_secp256k1 = require("@noble/curves/secp256k1.js");
+var import_utils = require("@noble/hashes/utils");
+var import_btc_signer = require("@scure/btc-signer");
+var import_musig2 = require("@scure/btc-signer/musig2");
+var DEFAULT_FUNDING_MODEL = "operator-funded";
+var MAX_RECOVERY_SEQUENCE = 65535;
+var TAPROOT_LEAF_VERSION = 192;
+function compactSize(n) {
+  if (n < 253) return new Uint8Array([n]);
+  if (n <= 65535) return new Uint8Array([253, n & 255, n >> 8 & 255]);
+  return new Uint8Array([254, n & 255, n >> 8 & 255, n >> 16 & 255, n >> 24 & 255]);
+}
+function tapLeafHash(script, leafVersion = TAPROOT_LEAF_VERSION) {
+  return import_secp256k1.schnorr.utils.taggedHash(
+    "TapLeaf",
+    (0, import_utils.concatBytes)(new Uint8Array([leafVersion]), compactSize(script.length), script)
+  );
+}
+function resolveFallbackThreshold(advertised, n) {
+  return advertised ?? Math.max(1, n - 1);
+}
+function assertFallbackParams({ cohortKeys, fallbackThreshold }) {
+  const n = cohortKeys.length;
+  if (n === 0) {
+    throw new AggregationCohortError(
+      "Cannot build fallback leaf: no cohort keys.",
+      "NO_COHORT_KEYS"
+    );
+  }
+  for (const key of cohortKeys) {
+    if (key.length !== 33) {
+      throw new AggregationCohortError(
+        `Cohort key must be a 33-byte compressed public key, got ${key.length} bytes.`,
+        "INVALID_COHORT_KEY",
+        { length: key.length }
+      );
+    }
+  }
+  if (!Number.isInteger(fallbackThreshold) || fallbackThreshold < 1 || fallbackThreshold > n) {
+    throw new AggregationCohortError(
+      `Fallback threshold must be an integer in [1, ${n}] (k-of-n), got ${fallbackThreshold}.`,
+      "INVALID_FALLBACK_THRESHOLD",
+      { fallbackThreshold, n }
+    );
+  }
+}
+function buildFallbackLeaf(params) {
+  assertFallbackParams(params);
+  const xOnlyKeys = (0, import_musig2.sortKeys)(params.cohortKeys).map((k) => k.slice(1));
+  return (0, import_btc_signer.p2tr_ms)(params.fallbackThreshold, xOnlyKeys).script;
+}
+function assertRecoveryParams({ recoveryKey, recoverySequence }) {
+  if (recoveryKey.length !== 32) {
+    throw new AggregationCohortError(
+      `Recovery key must be a 32-byte x-only public key, got ${recoveryKey.length} bytes.`,
+      "INVALID_RECOVERY_KEY"
+    );
+  }
+  if (!Number.isInteger(recoverySequence) || recoverySequence < 1 || recoverySequence > MAX_RECOVERY_SEQUENCE) {
+    throw new AggregationCohortError(
+      `Recovery sequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}], got ${recoverySequence}.`,
+      "INVALID_RECOVERY_SEQUENCE"
+    );
+  }
+}
+function buildRecoveryScript(params) {
+  assertRecoveryParams(params);
+  return import_btc_signer.Script.encode([
+    params.recoverySequence,
+    "CHECKSEQUENCEVERIFY",
+    "DROP",
+    params.recoveryKey,
+    "CHECKSIG"
+  ]);
+}
+function buildRecoveryLeaves(fundingModel, params) {
+  switch (fundingModel) {
+    case "operator-funded":
+      return [
+        { script: buildFallbackLeaf(params) },
+        { script: buildRecoveryScript(params) }
+      ];
+    case "participant-funded":
+      throw new AggregationCohortError(
+        "Funding model 'participant-funded' is reserved and not yet implemented.",
+        "UNSUPPORTED_FUNDING_MODEL",
+        { fundingModel }
+      );
+    default:
+      throw new AggregationCohortError(
+        `Unknown funding model: ${fundingModel}.`,
+        "UNKNOWN_FUNDING_MODEL",
+        { fundingModel }
+      );
+  }
+}
+
+// src/core/cohort.ts
+var AggregationCohort = class {
+  /** Unique identifier for the cohort. */
+  id;
+  /** DID of the Aggregation Service managing this cohort. */
+  serviceDid;
+  /** Minimum number of participants required to finalize the cohort. */
+  minParticipants;
+  /** Network on which the cohort operates (mainnet, mutinynet, etc.). */
+  network;
+  /** Type of beacon used in the cohort: 'CASBeacon' or 'SMTBeacon'. */
+  beaconType;
+  /** List of participant DIDs that have been accepted into the cohort. */
+  participants = [];
+  /**
+   * Mapping from participant DID to their compressed secp256k1 public key.
+   * Distinct from {@link cohortKeys} (which is sorted per BIP-327): this lets
+   * callers look up a participant's key without knowing their position in the
+   * sorted array. Populated by the service at `acceptParticipant` time.
+   */
+  participantKeys = /* @__PURE__ */ new Map();
+  /** Sorted list of cohort participants' compressed public keys. */
+  #cohortKeys = [];
+  /**
+   * BIP-341 TapTweak scalar: `taggedHash("TapTweak", internalPubkey || tapMerkleRoot)`.
+   * The beacon output is an internal key (the MuSig2 aggregate) plus a script
+   * tree (the recovery leaves), so the tweak commits to the tree's Merkle root.
+   * The MuSig2 signing session applies this as an x-only tweak; a value that does
+   * not match the root the funded address was derived from silently yields an
+   * invalid key-path signature.
+   */
+  tapTweak = new Uint8Array();
+  /** The n-of-n MuSig2 aggregate internal key, x-only (32 bytes), set by computeBeaconAddress(). */
+  internalKey = new Uint8Array();
+  /** BIP-341 Taproot Merkle root of the recovery script tree, set by computeBeaconAddress(). */
+  tapMerkleRoot = new Uint8Array();
+  /** Operator recovery key, x-only (32 bytes). Used to build the CSV recovery leaf. */
+  recoveryKey;
+  /** Relative-timelock (BIP-68 nSequence) before the recovery leaf is spendable. */
+  recoverySequence;
+  /** Funding model governing the recovery leaves (default 'operator-funded'). */
+  fundingModel;
+  /**
+   * Advertised k of the k-of-n fallback leaf, or undefined to default to n-1 at
+   * address computation. Read the resolved value via {@link effectiveFallbackThreshold}.
+   */
+  fallbackThreshold;
+  /** The Taproot beacon address: key path is the MuSig2 aggregate, script path is fallback + recovery. */
+  beaconAddress = "";
+  /** Pending DID updates submitted by participants, keyed by DID. */
+  pendingUpdates = /* @__PURE__ */ new Map();
+  /**
+   * Participant DIDs that explicitly declined to submit an update this round
+   * (cooperative non-inclusion). A decliner is absent from the CAS Announcement
+   * Map and carries a non-inclusion leaf in the SMT, yet still signs. Kept
+   * disjoint from {@link pendingUpdates} so CAS correctness holds by construction.
+   */
+  nonIncluded = /* @__PURE__ */ new Set();
+  /** CAS Beacon Announcement Map (DID to updateHash), set by buildCASAnnouncement(). */
+  casAnnouncement;
+  /** Per-participant SMT proofs, set by buildSMTTree(). */
+  smtProofs;
+  /** Signal bytes (32 bytes) for OP_RETURN: SHA-256 of CAS announcement OR SMT root. */
+  signalBytes;
+  /** Set of participant DIDs that have approved the aggregated data. */
+  validationAcks = /* @__PURE__ */ new Set();
+  /** Set of participant DIDs that have rejected the aggregated data. */
+  validationRejections = /* @__PURE__ */ new Set();
+  constructor({ id, minParticipants, serviceDid, network, beaconType, recoveryKey, recoverySequence, fundingModel, fallbackThreshold }) {
+    this.id = id || crypto.randomUUID();
+    this.minParticipants = minParticipants ?? 2;
+    this.serviceDid = serviceDid || "";
+    this.network = network;
+    this.beaconType = beaconType || "CASBeacon";
+    this.recoveryKey = recoveryKey;
+    this.recoverySequence = recoverySequence;
+    this.fundingModel = fundingModel ?? DEFAULT_FUNDING_MODEL;
+    this.fallbackThreshold = fallbackThreshold;
+  }
+  /** Sorted cohort keys (sorted on assignment per BIP-327). */
+  get cohortKeys() {
+    return this.#cohortKeys;
+  }
+  set cohortKeys(keys) {
+    this.#cohortKeys = (0, import_musig22.sortKeys)(keys);
+  }
+  /**
+   * The resolved k of the k-of-n fallback leaf: the advertised
+   * {@link fallbackThreshold}, or n-1 (floored at 1) when unadvertised, where n is
+   * the current cohort size. This is the value the beacon address commits to and
+   * the spend builders must reproduce. Returns 0 before any cohort keys are set.
+   */
+  get effectiveFallbackThreshold() {
+    if (this.#cohortKeys.length === 0) return 0;
+    return resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length);
+  }
+  /**
+   * Computes the Taproot beacon address from the cohort keys and recovery params.
+   *
+   * The output's key path is the n-of-n MuSig2 aggregate of the cohort keys; its
+   * script path is the recovery tree (a CSV recovery leaf so a missing signer
+   * cannot permanently lock the UTXO). Sets `internalKey`, `tapMerkleRoot`, and
+   * the `tapTweak` the MuSig2 session must apply for the key-path spend.
+   *
+   * The tweak is derived from the Merkle root the address was built with (read
+   * back from the payment), never recomputed by hand, so the MuSig2 key-path
+   * signature is guaranteed to validate against the funded address.
+   */
+  computeBeaconAddress() {
+    if (this.#cohortKeys.length === 0) {
+      throw new AggregationCohortError(
+        "Cannot compute beacon address: no cohort keys.",
+        "NO_COHORT_KEYS",
+        { cohortId: this.id }
+      );
+    }
+    if (!this.recoveryKey || this.recoveryKey.length === 0 || this.recoverySequence === void 0) {
+      throw new AggregationCohortError(
+        "Cannot compute beacon address: missing recovery key or sequence.",
+        "NO_RECOVERY_PARAMS",
+        { cohortId: this.id }
+      );
+    }
+    const keyAggContext = (0, import_musig22.keyAggregate)(this.#cohortKeys);
+    const aggPubkey = (0, import_musig22.keyAggExport)(keyAggContext);
+    const leaves = buildRecoveryLeaves(this.fundingModel, {
+      recoveryKey: this.recoveryKey,
+      recoverySequence: this.recoverySequence,
+      cohortKeys: this.#cohortKeys,
+      fallbackThreshold: resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length)
+    });
+    const payment = (0, import_btc_signer2.p2tr)(aggPubkey, leaves, (0, import_bitcoin.getNetwork)(this.network), true);
+    this.internalKey = aggPubkey;
+    this.tapMerkleRoot = payment.tapMerkleRoot;
+    this.tapTweak = import_secp256k12.schnorr.utils.taggedHash("TapTweak", (0, import_utils2.concatBytes)(aggPubkey, payment.tapMerkleRoot));
+    if (!payment.address) {
+      throw new AggregationCohortError(
+        "Failed to compute Taproot address",
+        "BEACON_ADDRESS_ERROR",
+        { cohortId: this.id }
+      );
+    }
+    this.beaconAddress = payment.address;
+    return payment.address;
+  }
+  /**
+   * Validates that the participant's key is in the cohort and the beacon address
+   * matches the locally-computed one. Used by participants to verify cohort ready
+   * messages from the service.
+   */
+  validateMembership(participantPkHex, cohortKeysHex, expectedBeaconAddress) {
+    if (!cohortKeysHex.includes(participantPkHex)) {
+      throw new AggregationCohortError(
+        `Participant key not found in cohort ${this.id}.`,
+        "COHORT_VALIDATION_ERROR",
+        { cohortId: this.id, participantPkHex }
+      );
+    }
+    this.cohortKeys = cohortKeysHex.map((k) => (0, import_utils2.hexToBytes)(k));
+    const computed = this.computeBeaconAddress();
+    if (computed !== expectedBeaconAddress) {
+      throw new AggregationCohortError(
+        `Computed beacon address ${computed} does not match expected ${expectedBeaconAddress}.`,
+        "BEACON_ADDRESS_MISMATCH",
+        { cohortId: this.id, computed, expected: expectedBeaconAddress }
+      );
+    }
+  }
+  /**
+   * Returns the position of a participant's public key in the sorted
+   * {@link cohortKeys} array, or -1 if the participant is not in the cohort.
+   * Required by MuSig2 partial-sig verification which indexes by signer position.
+   */
+  indexOfParticipant(did) {
+    const pk = this.participantKeys.get(did);
+    if (!pk) return -1;
+    return this.#cohortKeys.findIndex(
+      (k) => k.length === pk.length && k.every((b, i) => b === pk[i])
+    );
+  }
+  addUpdate(participantDid, signedUpdate) {
+    if (!this.participants.includes(participantDid)) {
+      throw new AggregationCohortError(
+        `Participant ${participantDid} is not in cohort ${this.id}.`,
+        "UNKNOWN_PARTICIPANT",
+        { cohortId: this.id, participantDid }
+      );
+    }
+    this.pendingUpdates.set(participantDid, signedUpdate);
+  }
+  /**
+   * Record that a participant declined to submit an update this round
+   * (cooperative non-inclusion). The member stays in the cohort and still signs.
+   */
+  addNonInclusion(participantDid) {
+    if (!this.participants.includes(participantDid)) {
+      throw new AggregationCohortError(
+        `Participant ${participantDid} is not in cohort ${this.id}.`,
+        "UNKNOWN_PARTICIPANT",
+        { cohortId: this.id, participantDid }
+      );
+    }
+    if (this.pendingUpdates.has(participantDid)) {
+      throw new AggregationCohortError(
+        `Participant ${participantDid} already submitted an update; cannot also decline.`,
+        "CONFLICTING_RESPONSE",
+        { cohortId: this.id, participantDid }
+      );
+    }
+    this.nonIncluded.add(participantDid);
+  }
+  hasAllUpdates() {
+    return this.pendingUpdates.size === this.participants.length;
+  }
+  /**
+   * True when every participant has responded for this round, either with an
+   * update or with an explicit non-inclusion. This is the aggregation gate when
+   * non-inclusion is in play; it generalizes {@link hasAllUpdates} the same way
+   * {@link hasAllValidationResponses} generalizes a unanimous ack.
+   */
+  hasAllResponses() {
+    return this.pendingUpdates.size + this.nonIncluded.size === this.participants.length;
+  }
+  /**
+   * Builds a CAS Announcement Map from collected updates.
+   * Maps each participant DID to base64url canonical hash of their signed update.
+   * Computes signal bytes as SHA-256 of canonicalized announcement.
+   *
+   * Members who declined (cooperative non-inclusion) are naturally absent from
+   * the map: the body iterates {@link pendingUpdates}, which never holds a
+   * decliner. Absence from the map is exactly the CAS non-inclusion signal.
+   */
+  buildCASAnnouncement() {
+    if (!this.hasAllResponses()) {
+      throw new AggregationCohortError(
+        "Cannot build CAS Announcement: not all participants have responded.",
+        "INCOMPLETE_RESPONSES",
+        { cohortId: this.id, updates: this.pendingUpdates.size, declined: this.nonIncluded.size, total: this.participants.length }
+      );
+    }
+    const announcement = {};
+    for (const [did, signedUpdate] of this.pendingUpdates) {
+      announcement[did] = (0, import_common3.canonicalHash)(signedUpdate);
+    }
+    this.casAnnouncement = announcement;
+    this.signalBytes = (0, import_common3.hash)((0, import_common3.canonicalize)(announcement));
+    return announcement;
+  }
+  /**
+   * Builds an SMT tree with one leaf per participant.
+   *
+   * A member who submitted an update gets an inclusion leaf
+   * (SHA-256(SHA-256(nonce) || SHA-256(update))); a member who declined gets a
+   * non-inclusion leaf (SHA-256(SHA-256(nonce)), the `signedUpdate` entry field
+   * omitted). The cohort mints each member's nonce and returns it inside that
+   * member's serialized proof, so a decliner can self-validate its own
+   * non-inclusion slot and the resolver can recompute the leaf. Stores
+   * per-participant proofs and the SMT root as signalBytes.
+   */
+  buildSMTTree() {
+    if (!this.hasAllResponses()) {
+      throw new AggregationCohortError(
+        "Cannot build SMT tree: not all participants have responded.",
+        "INCOMPLETE_RESPONSES",
+        { cohortId: this.id, updates: this.pendingUpdates.size, declined: this.nonIncluded.size, total: this.participants.length }
+      );
+    }
+    const tree = new import_smt2.BTCR2MerkleTree();
+    const entries = [];
+    const encoder = new TextEncoder();
+    for (const did of this.participants) {
+      const nonce = (0, import_utils2.randomBytes)(32);
+      const signedUpdate = this.pendingUpdates.get(did);
+      if (signedUpdate) {
+        entries.push({ did, nonce, signedUpdate: encoder.encode((0, import_common3.canonicalize)(signedUpdate)) });
+      } else {
+        entries.push({ did, nonce });
+      }
+    }
+    tree.addEntries(entries);
+    tree.finalize();
+    this.signalBytes = tree.rootHash;
+    this.smtProofs = /* @__PURE__ */ new Map();
+    for (const did of this.participants) {
+      this.smtProofs.set(did, tree.proof(did));
+    }
+    return this.smtProofs;
+  }
+  addValidation(participantDid, approved) {
+    if (!this.participants.includes(participantDid)) {
+      throw new AggregationCohortError(
+        `Unknown participant ${participantDid} in cohort ${this.id}.`,
+        "UNKNOWN_PARTICIPANT",
+        { cohortId: this.id, participantDid }
+      );
+    }
+    if (approved) {
+      this.validationAcks.add(participantDid);
+    } else {
+      this.validationRejections.add(participantDid);
+    }
+  }
+  /**
+   * True when every participant has either approved or rejected the aggregated data.
+   */
+  hasAllValidationResponses() {
+    return this.validationAcks.size + this.validationRejections.size === this.participants.length;
+  }
+  /**
+   * True when all participants approved. Note: differs from {@link hasAllValidationResponses},
+   * this returns false if any participant rejected, even if all responses are in.
+   */
+  isFullyValidated() {
+    return this.validationRejections.size === 0 && this.validationAcks.size === this.participants.length;
+  }
+};
+
+// src/core/conditions.ts
+var KNOWN_BEACON_TYPES = ["CASBeacon", "SMTBeacon"];
+var KNOWN_FUNDING_MODELS = ["operator-funded", "participant-funded"];
+function checkPair(problems, label, min, max) {
+  if (min !== void 0 && (!Number.isInteger(min) || min < 0)) {
+    problems.push(`min${label} must be an integer >= 0`);
+  }
+  if (max !== void 0 && (!Number.isInteger(max) || max < 0)) {
+    problems.push(`max${label} must be an integer >= 0`);
+  }
+  if (min !== void 0 && max !== void 0 && Number.isInteger(min) && Number.isInteger(max) && max < min) {
+    problems.push(`max${label} must be >= min${label}`);
+  }
+}
+function checkCost(problems, label, cost) {
+  if (cost === void 0) return;
+  if (typeof cost.amount !== "number" || !Number.isFinite(cost.amount) || cost.amount < 0) {
+    problems.push(`${label}.amount must be a finite number >= 0`);
+  }
+  if (typeof cost.unit !== "string" || cost.unit.length === 0) {
+    problems.push(`${label}.unit must be a non-empty string`);
+  }
+  if (cost.basis !== void 0 && cost.basis !== "per-did" && cost.basis !== "per-participant") {
+    problems.push(`${label}.basis must be 'per-did' or 'per-participant'`);
+  }
+}
+function validateCohortConditions(c) {
+  const problems = [];
+  if (!KNOWN_BEACON_TYPES.includes(c.beaconType)) {
+    problems.push(`beaconType must be one of ${KNOWN_BEACON_TYPES.join(", ")}`);
+  }
+  if (!Number.isInteger(c.minParticipants) || c.minParticipants < 1) {
+    problems.push("minParticipants must be an integer >= 1");
+  }
+  if (c.maxParticipants !== void 0) {
+    if (!Number.isInteger(c.maxParticipants) || c.maxParticipants < 1) {
+      problems.push("maxParticipants must be an integer >= 1");
+    } else if (Number.isInteger(c.minParticipants) && c.maxParticipants < c.minParticipants) {
+      problems.push("maxParticipants must be >= minParticipants");
+    }
+  }
+  checkPair(problems, "DidsPerParticipant", c.minDidsPerParticipant, c.maxDidsPerParticipant);
+  checkPair(problems, "SecondsBetweenAnnouncements", c.minSecondsBetweenAnnouncements, c.maxSecondsBetweenAnnouncements);
+  if (c.pendingUpdateTrigger !== void 0 && (!Number.isInteger(c.pendingUpdateTrigger) || c.pendingUpdateTrigger < 1)) {
+    problems.push("pendingUpdateTrigger must be an integer >= 1");
+  }
+  if (c.fallbackThreshold !== void 0) {
+    if (!Number.isInteger(c.fallbackThreshold) || c.fallbackThreshold < 1) {
+      problems.push("fallbackThreshold must be an integer >= 1");
+    } else if (c.maxParticipants !== void 0 && Number.isInteger(c.maxParticipants) && c.fallbackThreshold > c.maxParticipants) {
+      problems.push("fallbackThreshold must be <= maxParticipants");
+    }
+  }
+  checkCost(problems, "costOfEnrollment", c.costOfEnrollment);
+  checkCost(problems, "costPerAnnouncement", c.costPerAnnouncement);
+  if (typeof c.recoveryKey !== "string" || !/^[0-9a-fA-F]{64}$/.test(c.recoveryKey)) {
+    problems.push("recoveryKey must be a 64-character hex string (x-only public key)");
+  }
+  if (!Number.isInteger(c.recoverySequence) || c.recoverySequence < 1 || c.recoverySequence > MAX_RECOVERY_SEQUENCE) {
+    problems.push(`recoverySequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}]`);
+  }
+  if (c.fundingModel !== void 0 && !KNOWN_FUNDING_MODELS.includes(c.fundingModel)) {
+    problems.push(`fundingModel must be one of ${KNOWN_FUNDING_MODELS.join(", ")}`);
+  }
+  return problems;
+}
+
+// src/core/fallback-spend.ts
+var import_bitcoin2 = require("@did-btcr2/bitcoin");
+var import_secp256k13 = require("@noble/curves/secp256k1.js");
+var import_btc_signer3 = require("@scure/btc-signer");
+var import_musig23 = require("@scure/btc-signer/musig2");
+function bytesEqual(a, b) {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+function fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeafScript) {
+  return tx.preimageWitnessV1(
+    inputIndex,
+    [prevOutScript],
+    import_btc_signer3.SigHash.DEFAULT,
+    [prevOutValue],
+    void 0,
+    fallbackLeafScript,
+    TAPROOT_LEAF_VERSION
+  );
+}
+function buildFallbackSpend(params) {
+  const {
+    pendingTx,
+    cohortKeys,
+    recoveryKey,
+    recoverySequence,
+    fundingModel,
+    network,
+    prevOutScript,
+    prevOutValue,
+    signatures
+  } = params;
+  const inputIndex = params.inputIndex ?? 0;
+  if (cohortKeys.length === 0) {
+    throw new AggregationCohortError(
+      "Cannot build fallback spend: no cohort keys.",
+      "NO_COHORT_KEYS"
+    );
+  }
+  const fallbackThreshold = resolveFallbackThreshold(params.fallbackThreshold, cohortKeys.length);
+  const internalKey = (0, import_musig23.keyAggExport)((0, import_musig23.keyAggregate)((0, import_musig23.sortKeys)(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey,
+    recoverySequence,
+    cohortKeys,
+    fallbackThreshold
+  });
+  const net = (0, import_bitcoin2.getNetwork)(network);
+  const payment = (0, import_btc_signer3.p2tr)(internalKey, leaves, net, true);
+  if (!bytesEqual(payment.script, prevOutScript)) {
+    throw new AggregationCohortError(
+      "Reconstructed beacon output script does not match the spent prevout script.",
+      "PREVOUT_SCRIPT_MISMATCH"
+    );
+  }
+  const fallbackLeaf = buildFallbackLeaf({ cohortKeys, fallbackThreshold });
+  const leafEntry = payment.tapLeafScript?.find(([, scriptVer]) => {
+    const script = scriptVer.slice(0, scriptVer.length - 1);
+    return bytesEqual(script, fallbackLeaf);
+  });
+  if (!leafEntry) {
+    throw new AggregationCohortError(
+      "Could not locate the fallback leaf in the reconstructed beacon output.",
+      "FALLBACK_LEAF_NOT_FOUND"
+    );
+  }
+  const cohortXOnly = (0, import_musig23.sortKeys)(cohortKeys).map((k) => k.slice(1));
+  const tx = pendingTx;
+  const sighash = fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeaf);
+  const leafHash = tapLeafHash(fallbackLeaf);
+  const accepted = /* @__PURE__ */ new Map();
+  for (const { pubKey, signature } of signatures) {
+    if (pubKey.length !== 32 || signature.length !== 64) continue;
+    const isCohortKey = cohortXOnly.some((k) => bytesEqual(k, pubKey));
+    if (!isCohortKey) continue;
+    const hex = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+    if (accepted.has(hex)) continue;
+    let ok = false;
+    try {
+      ok = import_secp256k13.schnorr.verify(signature, sighash, pubKey);
+    } catch {
+      ok = false;
+    }
+    if (ok) accepted.set(hex, signature);
+  }
+  if (accepted.size < fallbackThreshold) {
+    throw new AggregationCohortError(
+      `Not enough valid fallback signatures: have ${accepted.size}, need ${fallbackThreshold}.`,
+      "NOT_ENOUGH_FALLBACK_SIGNATURES",
+      { have: accepted.size, need: fallbackThreshold }
+    );
+  }
+  const chosen = cohortXOnly.filter((k) => accepted.has(Array.from(k, (b) => b.toString(16).padStart(2, "0")).join(""))).slice(0, fallbackThreshold);
+  tx.updateInput(inputIndex, {
+    tapLeafScript: [leafEntry],
+    tapScriptSig: chosen.map((pubKey) => {
+      const hex = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+      return [{ pubKey, leafHash }, accepted.get(hex)];
+    })
+  });
+  tx.finalize();
+  return tx;
+}
+
+// src/core/messages/base.ts
+var AGGREGATION_WIRE_VERSION = 1;
+var BaseMessage = class {
+  type;
+  version;
+  to;
+  from;
+  body;
+  constructor({ type, version, to, from, body }) {
+    this.type = type;
+    this.version = version ?? AGGREGATION_WIRE_VERSION;
+    this.to = to;
+    this.from = from;
+    this.body = body;
+  }
+  /**
+   * Converts a BaseMessage to a JSON object.
+   * @returns {Base} The JSON representation of the BaseMessage.
+   */
+  toJSON() {
+    return {
+      type: this.type,
+      version: this.version,
+      to: this.to,
+      from: this.from,
+      body: this.body
+    };
+  }
+};
+
+// src/core/messages/constants.ts
+var AGGREGATION_MESSAGE_PREFIX = "https://btcr2.dev/aggregation";
+var COHORT_ADVERT = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_advert`;
+var COHORT_OPT_IN = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in`;
+var COHORT_OPT_IN_ACCEPT = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in_accept`;
+var COHORT_READY = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_ready`;
+var SUBMIT_UPDATE = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_update`;
+var SUBMIT_NONINCLUDED = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_nonincluded`;
+var DISTRIBUTE_AGGREGATED_DATA = `${AGGREGATION_MESSAGE_PREFIX}/update/distribute_aggregated_data`;
+var VALIDATION_ACK = `${AGGREGATION_MESSAGE_PREFIX}/update/validation_ack`;
+var AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/authorization_request`;
+var NONCE_CONTRIBUTION = `${AGGREGATION_MESSAGE_PREFIX}/sign/nonce_contribution`;
+var AGGREGATED_NONCE = `${AGGREGATION_MESSAGE_PREFIX}/sign/aggregated_nonce`;
+var SIGNATURE_AUTHORIZATION = `${AGGREGATION_MESSAGE_PREFIX}/sign/signature_authorization`;
+var FALLBACK_AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_authorization_request`;
+var FALLBACK_SIGNATURE = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_signature`;
+
+// src/core/messages/factories.ts
+function createCohortAdvertMessage(fields) {
+  const { from, ...body } = fields;
+  return new BaseMessage({ type: COHORT_ADVERT, from, body });
+}
+function createCohortOptInAcceptMessage(fields) {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: COHORT_OPT_IN_ACCEPT, from, to, body });
+}
+function createCohortReadyMessage(fields) {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: COHORT_READY, from, to, body });
+}
+function createDistributeAggregatedDataMessage(fields) {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: DISTRIBUTE_AGGREGATED_DATA, from, to, body });
+}
+function createAuthorizationRequestMessage(fields) {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: AUTHORIZATION_REQUEST, from, to, body });
+}
+function createAggregatedNonceMessage(fields) {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: AGGREGATED_NONCE, from, to, body });
+}
+function createFallbackAuthorizationRequestMessage(fields) {
+  const { from, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_AUTHORIZATION_REQUEST, from, to, body });
+}
+
+// src/core/signing-session.ts
+var import_keypair = require("@did-btcr2/keypair");
+var import_btc_signer4 = require("@scure/btc-signer");
+var musig2 = __toESM(require("@scure/btc-signer/musig2"), 1);
+var BeaconSigningSession = class {
+  /** Unique identifier for this signing session. */
+  id;
+  /** The cohort this session signs for. */
+  cohort;
+  /** The Bitcoin transaction being signed. */
+  pendingTx;
+  /** Previous output scripts for Taproot sighash computation (BIP-341). */
+  prevOutScripts;
+  /** Previous output values for Taproot sighash computation. */
+  prevOutValues;
+  /** Map of participant publicKey-hex to public nonce contribution. */
+  nonceContributions = /* @__PURE__ */ new Map();
+  /** Aggregated MuSig2 nonce (66 bytes). */
+  aggregatedNonce;
+  /** Map of participant DID to partial signature. */
+  partialSignatures = /* @__PURE__ */ new Map();
+  /** Final 64-byte Schnorr signature. */
+  signature;
+  /** Current signing session phase. */
+  phase;
+  /**
+   * Participant's MuSig2 secret nonce, held only on the participant side
+   * between {@link generateNonceContribution} and {@link generatePartialSignature}.
+   * Private and cleared on every terminal path (success, failure, or teardown
+   * via {@link clearSecrets}) so a spent or abandoned nonce cannot be reused or
+   * serialized.
+   */
+  #secretNonce;
+  constructor({ id, cohort, pendingTx, prevOutScripts, prevOutValues }) {
+    this.id = id || crypto.randomUUID();
+    this.cohort = cohort;
+    this.pendingTx = pendingTx;
+    this.prevOutScripts = prevOutScripts || [];
+    this.prevOutValues = prevOutValues || [];
+    this.phase = "AwaitingNonceContributions" /* AwaitingNonceContributions */;
+  }
+  /**
+   * Computes the Taproot sighash (BIP-341) for the first input.
+   */
+  get sigHash() {
+    if (!this.prevOutScripts.length || !this.prevOutValues.length) {
+      throw new SigningSessionError(
+        "Cannot compute sighash: missing prevOutScripts or prevOutValues.",
+        "SIGHASH_ERROR"
+      );
+    }
+    return this.pendingTx.preimageWitnessV1(
+      0,
+      this.prevOutScripts,
+      import_btc_signer4.SigHash.DEFAULT,
+      this.prevOutValues
+    );
+  }
+  addNonceContribution(participantDid, nonceContribution) {
+    if (this.phase !== "AwaitingNonceContributions" /* AwaitingNonceContributions */) {
+      throw new SigningSessionError(
+        `Nonce contributions not expected. Current phase: ${this.phase}`,
+        "INVALID_PHASE",
+        { phase: this.phase }
+      );
+    }
+    if (!this.cohort.participants.includes(participantDid)) {
+      throw new SigningSessionError(
+        `Participant ${participantDid} is not a member of cohort ${this.cohort.id}.`,
+        "UNKNOWN_PARTICIPANT",
+        { cohortId: this.cohort.id, participantDid }
+      );
+    }
+    if (nonceContribution.length !== 66) {
+      throw new SigningSessionError(
+        `Invalid nonce contribution: expected 66 bytes, got ${nonceContribution.length}.`,
+        "INVALID_NONCE_LENGTH"
+      );
+    }
+    if (this.nonceContributions.has(participantDid)) {
+      throw new SigningSessionError(
+        `Duplicate nonce contribution from ${participantDid}.`,
+        "DUPLICATE_NONCE"
+      );
+    }
+    this.nonceContributions.set(participantDid, nonceContribution);
+    if (this.nonceContributions.size === this.cohort.participants.length) {
+      this.phase = "NonceContributionsReceived" /* NonceContributionsReceived */;
+    }
+  }
+  generateAggregatedNonce() {
+    if (this.phase !== "NonceContributionsReceived" /* NonceContributionsReceived */) {
+      throw new SigningSessionError(
+        `Cannot aggregate nonces: phase is ${this.phase}, expected NonceContributionsReceived.`,
+        "INVALID_PHASE"
+      );
+    }
+    this.aggregatedNonce = musig2.nonceAggregate([...this.nonceContributions.values()]);
+    this.phase = "AwaitingPartialSignatures" /* AwaitingPartialSignatures */;
+    return this.aggregatedNonce;
+  }
+  addPartialSignature(participantDid, partialSig) {
+    if (this.phase !== "AwaitingPartialSignatures" /* AwaitingPartialSignatures */) {
+      throw new SigningSessionError(
+        `Partial signatures not expected. Current phase: ${this.phase}`,
+        "INVALID_PHASE"
+      );
+    }
+    if (!this.cohort.participants.includes(participantDid)) {
+      throw new SigningSessionError(
+        `Participant ${participantDid} is not a member of cohort ${this.cohort.id}.`,
+        "UNKNOWN_PARTICIPANT",
+        { cohortId: this.cohort.id, participantDid }
+      );
+    }
+    if (this.partialSignatures.has(participantDid)) {
+      throw new SigningSessionError(
+        `Duplicate partial signature from ${participantDid}.`,
+        "DUPLICATE_PARTIAL_SIG"
+      );
+    }
+    this.partialSignatures.set(participantDid, partialSig);
+    if (this.partialSignatures.size === this.cohort.participants.length) {
+      this.phase = "PartialSignaturesReceived" /* PartialSignaturesReceived */;
+    }
+  }
+  generateFinalSignature() {
+    if (this.phase !== "PartialSignaturesReceived" /* PartialSignaturesReceived */) {
+      throw new SigningSessionError(
+        `Cannot generate final signature: phase is ${this.phase}.`,
+        "INVALID_PHASE"
+      );
+    }
+    if (!this.aggregatedNonce) {
+      throw new SigningSessionError("Aggregated nonce missing.", "MISSING_AGGREGATED_NONCE");
+    }
+    const session = new musig2.Session(
+      this.aggregatedNonce,
+      this.cohort.cohortKeys,
+      this.sigHash,
+      [this.cohort.tapTweak],
+      [true]
+    );
+    const pubNoncesByIndex = new Array(this.cohort.cohortKeys.length);
+    for (const [did, nonce] of this.nonceContributions) {
+      const idx = this.cohort.indexOfParticipant(did);
+      if (idx < 0) {
+        throw new SigningSessionError(
+          `Cannot verify nonce from ${did}: participant key missing from cohort.`,
+          "UNKNOWN_PARTICIPANT_KEY",
+          { participantDid: did }
+        );
+      }
+      pubNoncesByIndex[idx] = nonce;
+    }
+    for (const [did, partialSig] of this.partialSignatures) {
+      const idx = this.cohort.indexOfParticipant(did);
+      if (idx < 0) {
+        throw new SigningSessionError(
+          `Cannot verify partial signature from ${did}: participant key missing from cohort.`,
+          "UNKNOWN_PARTICIPANT_KEY",
+          { participantDid: did }
+        );
+      }
+      const ok = session.partialSigVerify(partialSig, pubNoncesByIndex, idx);
+      if (!ok) {
+        throw new SigningSessionError(
+          `Bad partial signature from ${did}.`,
+          "BAD_PARTIAL_SIG",
+          { participantDid: did, index: idx }
+        );
+      }
+    }
+    this.signature = session.partialSigAgg([...this.partialSignatures.values()]);
+    this.phase = "Complete" /* Complete */;
+    return this.signature;
+  }
+  /**
+   * Generates a fresh MuSig2 nonce contribution for the participant.
+   * Stores the secret nonce internally for use in `generatePartialSignature()`.
+   */
+  generateNonceContribution(participantPublicKey, participantSecretKey) {
+    const aggPublicKey = musig2.keyAggExport(musig2.keyAggregate(this.cohort.cohortKeys));
+    const nonces = musig2.nonceGen(participantPublicKey, participantSecretKey, aggPublicKey);
+    this.#secretNonce = nonces.secret;
+    return nonces.public;
+  }
+  /**
+   * Generates a partial signature using the participant's secret key + secret nonce.
+   * Requires the aggregated nonce to have been set first (via the service).
+   *
+   * Clears the stored secret nonce after use on every path (success or throw)
+   * via {@link clearSecrets}. JS cannot truly erase memory (GC may relocate
+   * buffers), but overwriting the bytes shortens the exposure window and
+   * prevents accidental reuse or serialization of a spent nonce - reuse of a
+   * MuSig2 nonce leaks the secret key.
+   */
+  generatePartialSignature(participantSecretKey) {
+    if (!this.aggregatedNonce) {
+      throw new SigningSessionError("Aggregated nonce not available.", "MISSING_AGGREGATED_NONCE");
+    }
+    if (!this.#secretNonce) {
+      throw new SigningSessionError("Secret nonce not available - generateNonceContribution() must be called first.", "MISSING_SECRET_NONCE");
+    }
+    const session = new musig2.Session(
+      this.aggregatedNonce,
+      this.cohort.cohortKeys,
+      this.sigHash,
+      [this.cohort.tapTweak],
+      [true]
+    );
+    try {
+      return session.sign(this.#secretNonce, participantSecretKey);
+    } finally {
+      this.clearSecrets();
+    }
+  }
+  /**
+   * Zeroize any retained secret nonce. Safe to call repeatedly and on any path
+   * (completion, failure, or teardown of an abandoned session). Callers that
+   * drop a session before it reaches a partial signature should invoke this so
+   * the secret nonce does not linger on the live object.
+   */
+  clearSecrets() {
+    if (this.#secretNonce) {
+      (0, import_keypair.wipe)(this.#secretNonce);
+      this.#secretNonce = void 0;
+    }
+  }
+  isComplete() {
+    return this.phase === "Complete" /* Complete */;
+  }
+  isFailed() {
+    return this.phase === "Failed" /* Failed */;
+  }
+};
+
+// src/service/service.ts
+var DEFAULT_MAX_UPDATE_SIZE_BYTES = 256 * 1024;
+var AggregationService = class {
+  did;
+  publicKey;
+  maxUpdateSizeBytes;
+  /** Per-cohort state, keyed by cohortId. */
+  #cohortStates = /* @__PURE__ */ new Map();
+  constructor({ did, publicKey, maxUpdateSizeBytes }) {
+    this.did = did;
+    this.publicKey = publicKey;
+    this.maxUpdateSizeBytes = maxUpdateSizeBytes ?? DEFAULT_MAX_UPDATE_SIZE_BYTES;
+  }
+  receive(message) {
+    const version = message.version;
+    if (version === void 0 || version !== AGGREGATION_WIRE_VERSION) {
+      const cohortId = message.body?.cohortId;
+      const state = cohortId ? this.#cohortStates.get(cohortId) : void 0;
+      if (state) {
+        state.rejections.push({
+          from: message.from,
+          code: "WRONG_VERSION",
+          reason: `Expected wire version ${AGGREGATION_WIRE_VERSION}, got ${String(version)}`
+        });
+      }
+      return;
+    }
+    const type = message.type;
+    switch (type) {
+      case COHORT_OPT_IN:
+        this.#handleOptIn(message);
+        break;
+      case SUBMIT_UPDATE:
+        this.#handleSubmitUpdate(message);
+        break;
+      case SUBMIT_NONINCLUDED:
+        this.#handleSubmitNonInclusion(message);
+        break;
+      case VALIDATION_ACK:
+        this.#handleValidationAck(message);
+        break;
+      case NONCE_CONTRIBUTION:
+        this.#handleNonceContribution(message);
+        break;
+      case SIGNATURE_AUTHORIZATION:
+        this.#handleSignatureAuthorization(message);
+        break;
+      case FALLBACK_SIGNATURE:
+        this.#handleFallbackSignature(message);
+        break;
+      default:
+        break;
+    }
+  }
+  /**
+   * Drain the rejection log for a cohort. Used by runners to surface silent
+   * drops (bad proof, oversized update, wrong version, etc.) as structured
+   * events without breaking the sans-I/O state machine contract.
+   */
+  drainRejections(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return [];
+    const out = state.rejections;
+    state.rejections = [];
+    return out;
+  }
+  /**
+   * Create a new cohort with the given config. Returns the cohort ID.
+   * Cohort starts in `Created` phase - call `advertise()` to broadcast.
+   */
+  createCohort(config) {
+    const problems = validateCohortConditions(config);
+    if (problems.length > 0) {
+      throw new AggregationServiceError(
+        `Invalid cohort conditions: ${problems.join("; ")}`,
+        "INVALID_COHORT_CONDITIONS",
+        { problems }
+      );
+    }
+    const cohort = new AggregationCohort({
+      serviceDid: this.did,
+      minParticipants: config.minParticipants,
+      network: config.network,
+      beaconType: config.beaconType,
+      recoveryKey: (0, import_utils3.hexToBytes)(config.recoveryKey),
+      recoverySequence: config.recoverySequence,
+      fundingModel: config.fundingModel,
+      fallbackThreshold: config.fallbackThreshold
+    });
+    this.#cohortStates.set(cohort.id, {
+      phase: "Created" /* Created */,
+      cohort,
+      config,
+      pendingOptIns: /* @__PURE__ */ new Map(),
+      acceptedParticipants: /* @__PURE__ */ new Set(),
+      rejections: []
+    });
+    return cohort.id;
+  }
+  /**
+   * Advertise a cohort to discover participants.
+   * Returns the advert message to broadcast.
+   */
+  advertise(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    if (state.phase !== "Created" /* Created */) {
+      throw new AggregationServiceError(
+        `Cannot advertise cohort ${cohortId}: phase is ${state.phase}.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state.phase }
+      );
+    }
+    const { network, ...conditions } = state.config;
+    const message = createCohortAdvertMessage({
+      from: this.did,
+      cohortId,
+      network,
+      communicationPk: this.publicKey.compressed,
+      ...conditions
+    });
+    state.phase = "Advertised" /* Advertised */;
+    return [message];
+  }
+  /** Pending opt-ins awaiting operator approval. */
+  pendingOptIns(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return /* @__PURE__ */ new Map();
+    const map = /* @__PURE__ */ new Map();
+    for (const [did, optIn] of state.pendingOptIns) {
+      if (!state.acceptedParticipants.has(did)) {
+        map.set(did, optIn);
+      }
+    }
+    return map;
+  }
+  #handleOptIn(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return;
+    if (state.phase !== "Advertised" /* Advertised */) return;
+    const participantDid = message.from;
+    const participantPk = message.body?.participantPk;
+    const communicationPk = message.body?.communicationPk;
+    if (!participantPk || !communicationPk) return;
+    if (state.acceptedParticipants.has(participantDid)) return;
+    state.pendingOptIns.set(participantDid, {
+      cohortId,
+      participantDid,
+      participantPk,
+      communicationPk
+    });
+  }
+  /**
+   * Service operator accepts a participant's opt-in.
+   * Returns the accept message to send.
+   */
+  acceptParticipant(cohortId, participantDid) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    const optIn = state.pendingOptIns.get(participantDid);
+    if (!optIn) {
+      throw new AggregationServiceError(
+        `No pending opt-in from ${participantDid} for cohort ${cohortId}.`,
+        "NO_OPT_IN",
+        { cohortId, participantDid }
+      );
+    }
+    if (state.acceptedParticipants.has(participantDid)) {
+      throw new AggregationServiceError(
+        `Participant ${participantDid} already accepted into cohort ${cohortId}.`,
+        "ALREADY_ACCEPTED",
+        { cohortId, participantDid }
+      );
+    }
+    const maxParticipants = state.config.maxParticipants;
+    if (maxParticipants !== void 0 && state.acceptedParticipants.size >= maxParticipants) {
+      throw new AggregationServiceError(
+        `Cohort ${cohortId} is full: ${maxParticipants} participants already accepted.`,
+        "COHORT_FULL",
+        { cohortId, maxParticipants }
+      );
+    }
+    state.acceptedParticipants.add(participantDid);
+    state.cohort.participants.push(participantDid);
+    state.cohort.participantKeys.set(participantDid, optIn.participantPk);
+    state.cohort.cohortKeys = [...state.cohort.cohortKeys, optIn.participantPk];
+    return [createCohortOptInAcceptMessage({
+      from: this.did,
+      to: participantDid,
+      cohortId
+    })];
+  }
+  /**
+   * Finalize cohort keygen: compute MuSig2 Taproot beacon address and send
+   * COHORT_READY messages to all accepted participants.
+   */
+  finalizeKeygen(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    if (state.phase !== "Advertised" /* Advertised */) {
+      throw new AggregationServiceError(
+        `Cannot finalize keygen for cohort ${cohortId}: phase is ${state.phase}.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state.phase }
+      );
+    }
+    if (state.acceptedParticipants.size < state.config.minParticipants) {
+      throw new AggregationServiceError(
+        `Cohort ${cohortId} has only ${state.acceptedParticipants.size} accepted participants, need ${state.config.minParticipants}.`,
+        "NOT_ENOUGH_PARTICIPANTS",
+        { cohortId }
+      );
+    }
+    const maxParticipants = state.config.maxParticipants;
+    if (maxParticipants !== void 0 && state.acceptedParticipants.size > maxParticipants) {
+      throw new AggregationServiceError(
+        `Cohort ${cohortId} has ${state.acceptedParticipants.size} accepted participants, exceeds max ${maxParticipants}.`,
+        "TOO_MANY_PARTICIPANTS",
+        { cohortId, maxParticipants }
+      );
+    }
+    const beaconAddress = state.cohort.computeBeaconAddress();
+    state.phase = "CohortSet" /* CohortSet */;
+    const messages = [];
+    for (const participantDid of state.cohort.participants) {
+      messages.push(createCohortReadyMessage({
+        from: this.did,
+        to: participantDid,
+        cohortId,
+        beaconAddress,
+        cohortKeys: state.cohort.cohortKeys
+      }));
+    }
+    return messages;
+  }
+  /** Updates collected so far for a cohort. */
+  collectedUpdates(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return /* @__PURE__ */ new Map();
+    return state.cohort.pendingUpdates;
+  }
+  /**
+   * Handle an incoming SUBMIT_UPDATE message from a participant containing their signed update to
+   * submit for aggregation.
+   * @param {BaseMessage} message - incoming SUBMIT_UPDATE message containing a participant's signed
+   * update to submit for aggregation
+   * @returns {void} - no return value; updates the service state with the submitted update if valid
+   */
+  #handleSubmitUpdate(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return;
+    if (state.phase !== "CohortSet" /* CohortSet */ && state.phase !== "CollectingUpdates" /* CollectingUpdates */) return;
+    const signedUpdate = message.body?.signedUpdate;
+    if (!signedUpdate) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "SUBMIT_UPDATE missing signedUpdate body"
+      });
+      return;
+    }
+    const canonicalSize = (0, import_common4.canonicalize)(signedUpdate).length;
+    if (canonicalSize > this.maxUpdateSizeBytes) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_TOO_LARGE",
+        reason: `Canonicalized update is ${canonicalSize} bytes; max allowed is ${this.maxUpdateSizeBytes}`
+      });
+      return;
+    }
+    if (!this.#verifySubmittedUpdate(state, message.from, signedUpdate)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_VERIFICATION_FAILED",
+        reason: "BIP-340 Data Integrity proof verification failed"
+      });
+      return;
+    }
+    if (state.cohort.nonIncluded.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already declined this round; cannot also submit an update"
+      });
+      return;
+    }
+    if (state.cohort.pendingUpdates.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already submitted an update this round; cannot resubmit"
+      });
+      return;
+    }
+    state.cohort.addUpdate(message.from, signedUpdate);
+    if (state.phase === "CohortSet" /* CohortSet */) {
+      state.phase = "CollectingUpdates" /* CollectingUpdates */;
+    }
+    if (state.cohort.hasAllResponses()) {
+      state.phase = "UpdatesCollected" /* UpdatesCollected */;
+    }
+  }
+  /**
+   * Handle an incoming SUBMIT_NONINCLUDED message: a member declares it has no
+   * update this round (cooperative non-inclusion). Membership is proven by the
+   * signed transport envelope, so the body carries only the cohortId. The member
+   * stays in the cohort and still signs; it is absent from the CAS map and
+   * carries a non-inclusion leaf in the SMT.
+   */
+  #handleSubmitNonInclusion(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return;
+    if (state.phase !== "CohortSet" /* CohortSet */ && state.phase !== "CollectingUpdates" /* CollectingUpdates */) return;
+    if (!state.cohort.participants.includes(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Sender is not a member of this cohort"
+      });
+      return;
+    }
+    if (state.cohort.pendingUpdates.has(message.from) || state.cohort.nonIncluded.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already responded this round"
+      });
+      return;
+    }
+    state.cohort.addNonInclusion(message.from);
+    if (state.phase === "CohortSet" /* CohortSet */) {
+      state.phase = "CollectingUpdates" /* CollectingUpdates */;
+    }
+    if (state.cohort.hasAllResponses()) {
+      state.phase = "UpdatesCollected" /* UpdatesCollected */;
+    }
+  }
+  /**
+   * Verify the BIP-340 Schnorr Data Integrity proof on a submitted update using the
+   * participant's public key from their cohort opt-in. Returns `false` (and the
+   * update is silently dropped) if the proof is missing, the verificationMethod does
+   * not name the sender's DID, the participant has no opt-in on record, or the
+   * signature fails verification.
+   * @param {ServiceCohortState} state - the current state of the cohort to which the update was submitted
+   * @param {string} sender - the DID of the participant who submitted the update
+   * @param {SecuredDocument} signedUpdate - the signed update containing the proof to verify
+   * @returns {boolean} - `true` if the proof is valid and the update can be accepted; `false` otherwise
+   */
+  #verifySubmittedUpdate(state, sender, signedUpdate) {
+    const proof = signedUpdate.proof;
+    if (!proof?.verificationMethod || !proof.proofValue) return false;
+    const vmDid = proof.verificationMethod.split("#")[0];
+    if (vmDid !== sender) return false;
+    const optIn = state.pendingOptIns.get(sender);
+    if (!optIn) return false;
+    try {
+      const multikey = import_cryptosuite.SchnorrMultikey.fromPublicKey({
+        id: proof.verificationMethod,
+        controller: sender,
+        publicKeyBytes: optIn.participantPk
+      });
+      const suite = new import_cryptosuite.BIP340Cryptosuite(multikey);
+      return suite.verifyProof(signedUpdate).verified === true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Build the aggregated data structure (CAS Announcement or SMT tree) and
+   * return distribute messages to send to all participants for validation.
+   */
+  buildAndDistribute(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    if (state.phase !== "UpdatesCollected" /* UpdatesCollected */) {
+      throw new AggregationServiceError(
+        `Cannot build aggregated data for cohort ${cohortId}: phase is ${state.phase}.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state.phase }
+      );
+    }
+    const strategy = getBeaconStrategy(state.config.beaconType);
+    if (!strategy) {
+      throw new AggregationServiceError(
+        `Unsupported beacon type: ${state.config.beaconType}`,
+        "UNSUPPORTED_BEACON_TYPE",
+        { cohortId, beaconType: state.config.beaconType }
+      );
+    }
+    strategy.buildAggregatedData(state.cohort);
+    const signalBytesHex = (0, import_utils3.bytesToHex)(state.cohort.signalBytes);
+    state.phase = "DataDistributed" /* DataDistributed */;
+    const messages = [];
+    for (const participantDid of state.cohort.participants) {
+      const payload = strategy.getDistributePayload(state.cohort, participantDid);
+      messages.push(createDistributeAggregatedDataMessage({
+        from: this.did,
+        to: participantDid,
+        cohortId,
+        beaconType: state.config.beaconType,
+        signalBytesHex,
+        casAnnouncement: payload.casAnnouncement,
+        smtProof: payload.smtProof
+      }));
+    }
+    return messages;
+  }
+  validationProgress(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      return { approved: /* @__PURE__ */ new Set(), rejected: /* @__PURE__ */ new Set(), pending: /* @__PURE__ */ new Set(), total: 0 };
+    }
+    const approved = state.cohort.validationAcks;
+    const rejected = state.cohort.validationRejections;
+    const allParticipants = new Set(state.cohort.participants);
+    const responded = /* @__PURE__ */ new Set([...approved, ...rejected]);
+    const pending = new Set([...allParticipants].filter((p) => !responded.has(p)));
+    return {
+      approved,
+      rejected,
+      pending,
+      total: allParticipants.size
+    };
+  }
+  #handleValidationAck(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) return;
+    if (state.phase !== "DataDistributed" /* DataDistributed */) return;
+    const approved = message.body?.approved;
+    if (approved === void 0) return;
+    state.cohort.addValidation(message.from, approved);
+    if (state.cohort.isFullyValidated()) {
+      state.phase = "Validated" /* Validated */;
+    } else if (state.cohort.hasAllValidationResponses()) {
+      state.phase = "Failed" /* Failed */;
+    }
+  }
+  /**
+   * Start a signing session by creating auth requests for all participants.
+   * The caller provides the transaction data - typically built via
+   * `buildBeaconTransaction()` against a Bitcoin connection.
+   */
+  startSigning(cohortId, txData) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    if (state.phase !== "Validated" /* Validated */) {
+      throw new AggregationServiceError(
+        `Cannot start signing for cohort ${cohortId}: phase is ${state.phase}.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state.phase }
+      );
+    }
+    const session = new BeaconSigningSession({
+      cohort: state.cohort,
+      pendingTx: txData.tx,
+      prevOutScripts: txData.prevOutScripts,
+      prevOutValues: txData.prevOutValues
+    });
+    state.signingSession = session;
+    state.phase = "SigningStarted" /* SigningStarted */;
+    const prevOutScript = txData.prevOutScripts[0];
+    if (!prevOutScript) {
+      throw new AggregationServiceError(
+        `Cannot start signing for cohort ${cohortId}: txData.prevOutScripts[0] is missing.`,
+        "MISSING_PREV_OUT_SCRIPT",
+        { cohortId }
+      );
+    }
+    const messages = [];
+    for (const participantDid of state.cohort.participants) {
+      messages.push(createAuthorizationRequestMessage({
+        from: this.did,
+        to: participantDid,
+        cohortId,
+        sessionId: session.id,
+        pendingTx: txData.tx.hex,
+        prevOutScriptHex: (0, import_utils3.bytesToHex)(prevOutScript),
+        prevOutValue: txData.prevOutValues[0]?.toString() ?? "0"
+      }));
+    }
+    return messages;
+  }
+  #handleNonceContribution(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || !state.signingSession) return;
+    if (state.phase !== "SigningStarted" /* SigningStarted */) return;
+    const sessionId = message.body?.sessionId;
+    if (sessionId !== state.signingSession.id) return;
+    const nonceContribution = message.body?.nonceContribution;
+    if (!nonceContribution) return;
+    state.signingSession.addNonceContribution(message.from, nonceContribution);
+    if (state.signingSession.nonceContributions.size === state.cohort.participants.length) {
+      state.phase = "NoncesCollected" /* NoncesCollected */;
+    }
+  }
+  /**
+   * Generate the aggregated nonce and return messages to send to participants.
+   * Call after `validationProgress(cohortId).approved.size === total`.
+   */
+  sendAggregatedNonce(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    if (state.phase !== "NoncesCollected" /* NoncesCollected */ || !state.signingSession) {
+      throw new AggregationServiceError(
+        `Cannot send aggregated nonce for cohort ${cohortId}: phase is ${state.phase}.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state.phase }
+      );
+    }
+    const aggregatedNonce = state.signingSession.generateAggregatedNonce();
+    state.phase = "AwaitingPartialSigs" /* AwaitingPartialSigs */;
+    const messages = [];
+    for (const participantDid of state.cohort.participants) {
+      messages.push(createAggregatedNonceMessage({
+        from: this.did,
+        to: participantDid,
+        cohortId,
+        sessionId: state.signingSession.id,
+        aggregatedNonce
+      }));
+    }
+    return messages;
+  }
+  #handleSignatureAuthorization(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || !state.signingSession) return;
+    if (state.phase !== "AwaitingPartialSigs" /* AwaitingPartialSigs */) return;
+    const sessionId = message.body?.sessionId;
+    if (sessionId !== state.signingSession.id) return;
+    const partialSignature = message.body?.partialSignature;
+    if (!partialSignature) return;
+    state.signingSession.addPartialSignature(message.from, partialSignature);
+    if (state.signingSession.partialSignatures.size === state.cohort.participants.length) {
+      const signature = state.signingSession.generateFinalSignature();
+      state.signingSession.pendingTx.updateInput(0, { finalScriptWitness: [signature] });
+      state.result = {
+        cohortId,
+        signature,
+        signedTx: state.signingSession.pendingTx,
+        path: "key-path"
+      };
+      state.phase = "Complete" /* Complete */;
+    }
+  }
+  /**
+   * Abandon the optimistic n-of-n key path and ask members to authorize the
+   * k-of-n fallback (script-path) spend of the SAME beacon transaction (graceful
+   * liveness, ADR 042). Reuses the in-flight signing session's transaction and
+   * spent output, so the announcement and its outputs are unchanged: only the
+   * witness path differs. Returns one FALLBACK_AUTHORIZATION_REQUEST per
+   * participant.
+   *
+   * Callable once optimistic signing has started (the session and its tx exist)
+   * and before it completes. A cohort can take exactly one of the two paths: the
+   * caller (runner) must commit to fallback and stop driving the optimistic path.
+   */
+  startFallbackSigning(cohortId) {
+    const state = this.#cohortStates.get(cohortId);
+    if (!state) {
+      throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+    }
+    if (!state.signingSession) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: no signing session.`,
+        "NO_SIGNING_SESSION",
+        { cohortId }
+      );
+    }
+    const signingPhases = [
+      "SigningStarted" /* SigningStarted */,
+      "NoncesCollected" /* NoncesCollected */,
+      "AwaitingPartialSigs" /* AwaitingPartialSigs */
+    ];
+    if (!signingPhases.includes(state.phase)) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: phase is ${state.phase}.`,
+        "INVALID_PHASE",
+        { cohortId, phase: state.phase }
+      );
+    }
+    const session = state.signingSession;
+    const prevOutScript = session.prevOutScripts[0];
+    const prevOutValue = session.prevOutValues[0];
+    if (!prevOutScript || prevOutValue === void 0) {
+      throw new AggregationServiceError(
+        `Cannot start fallback for cohort ${cohortId}: signing session missing prevout data.`,
+        "MISSING_PREV_OUT",
+        { cohortId }
+      );
+    }
+    const fallbackLeaf = buildFallbackLeaf({
+      cohortKeys: state.cohort.cohortKeys,
+      fallbackThreshold: state.cohort.effectiveFallbackThreshold
+    });
+    state.fallbackSignatures = /* @__PURE__ */ new Map();
+    state.phase = "FallbackRequested" /* FallbackRequested */;
+    const messages = [];
+    for (const participantDid of state.cohort.participants) {
+      messages.push(createFallbackAuthorizationRequestMessage({
+        from: this.did,
+        to: participantDid,
+        cohortId,
+        sessionId: session.id,
+        pendingTx: session.pendingTx.hex,
+        prevOutScriptHex: (0, import_utils3.bytesToHex)(prevOutScript),
+        prevOutValue: prevOutValue.toString(),
+        fallbackLeafScriptHex: (0, import_utils3.bytesToHex)(fallbackLeaf)
+      }));
+    }
+    return messages;
+  }
+  /**
+   * Handle an incoming FALLBACK_SIGNATURE: a member's standalone BIP-340
+   * signature over the fallback script-path sighash. The signature is
+   * authenticated to the sender (its `signerPk` must be the sender's own cohort
+   * key and the signature must verify against the sighash) and collected. Once k
+   * valid signatures are in, the k-of-n fallback spend is assembled and the
+   * cohort completes via the script path.
+   */
+  #handleFallbackSignature(message) {
+    const cohortId = message.body?.cohortId;
+    if (!cohortId) return;
+    const state = this.#cohortStates.get(cohortId);
+    if (!state || !state.signingSession || !state.fallbackSignatures) return;
+    if (state.phase !== "FallbackRequested" /* FallbackRequested */) return;
+    const sessionId = message.body?.sessionId;
+    if (sessionId !== state.signingSession.id) return;
+    const signerPk = message.body?.signerPk;
+    const fallbackSignature = message.body?.fallbackSignature;
+    if (!signerPk || !fallbackSignature) return;
+    const prevOutScript = state.signingSession.prevOutScripts[0];
+    const prevOutValue = state.signingSession.prevOutValues[0];
+    if (!prevOutScript || prevOutValue === void 0) return;
+    const memberKey = state.cohort.participantKeys.get(message.from);
+    if (!memberKey) {
+      state.rejections.push({ from: message.from, code: "UPDATE_MALFORMED", reason: "Fallback signature from a non-member" });
+      return;
+    }
+    const memberXOnly = memberKey.slice(1);
+    if (signerPk.length !== 32 || !memberXOnly.every((b, i) => b === signerPk[i])) {
+      state.rejections.push({ from: message.from, code: "UPDATE_MALFORMED", reason: "Fallback signerPk does not match the sender cohort key" });
+      return;
+    }
+    const fallbackLeaf = buildFallbackLeaf({
+      cohortKeys: state.cohort.cohortKeys,
+      fallbackThreshold: state.cohort.effectiveFallbackThreshold
+    });
+    const sighash = fallbackSighash(state.signingSession.pendingTx, 0, prevOutScript, prevOutValue, fallbackLeaf);
+    let valid = false;
+    try {
+      valid = fallbackSignature.length === 64 && import_secp256k14.schnorr.verify(fallbackSignature, sighash, signerPk);
+    } catch {
+      valid = false;
+    }
+    if (!valid) {
+      state.rejections.push({ from: message.from, code: "UPDATE_VERIFICATION_FAILED", reason: "Fallback signature failed verification" });
+      return;
+    }
+    state.fallbackSignatures.set(message.from, { pubKey: signerPk, signature: fallbackSignature });
+    if (state.fallbackSignatures.size >= state.cohort.effectiveFallbackThreshold) {
+      const signedTx = buildFallbackSpend({
+        pendingTx: state.signingSession.pendingTx,
+        cohortKeys: state.cohort.cohortKeys,
+        fallbackThreshold: state.cohort.effectiveFallbackThreshold,
+        recoveryKey: state.cohort.recoveryKey,
+        recoverySequence: state.cohort.recoverySequence,
+        fundingModel: state.cohort.fundingModel,
+        network: state.cohort.network,
+        prevOutScript,
+        prevOutValue,
+        signatures: [...state.fallbackSignatures.values()]
+      });
+      state.result = { cohortId, signature: new Uint8Array(), signedTx, path: "script-path" };
+      state.phase = "Complete" /* Complete */;
+    }
+  }
+  getResult(cohortId) {
+    return this.#cohortStates.get(cohortId)?.result;
+  }
+  getCohortPhase(cohortId) {
+    return this.#cohortStates.get(cohortId)?.phase;
+  }
+  getCohort(cohortId) {
+    return this.#cohortStates.get(cohortId)?.cohort;
+  }
+  /**
+   * Get the signing session ID for a cohort, if a signing session has been started.
+   * @param {string} cohortId - The cohort ID.
+   * @returns {string | undefined} The session ID, or undefined if no session is active.
+   */
+  getSigningSessionId(cohortId) {
+    return this.#cohortStates.get(cohortId)?.signingSession?.id;
+  }
+  get cohorts() {
+    return [...this.#cohortStates.values()].map((s) => s.cohort);
+  }
+  /**
+   * Remove a cohort from the state map. Used by runners to GC state on cohort
+   * completion, failure, or expiry. No-op if the cohort doesn't exist.
+   */
+  removeCohort(cohortId) {
+    this.#cohortStates.delete(cohortId);
+  }
+};
+
+// src/service/service-runner.ts
+var import_bitcoin3 = require("@did-btcr2/bitcoin");
+
+// src/core/typed-emitter.ts
+var TypedEventEmitter = class {
+  #listeners = /* @__PURE__ */ new Map();
+  /** Subscribe to an event. */
+  on(event, listener) {
+    let set = this.#listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.#listeners.set(event, set);
+    }
+    set.add(listener);
+    return this;
+  }
+  /** Subscribe to an event, automatically unsubscribing after the first call. */
+  once(event, listener) {
+    const wrapped = ((...args) => {
+      this.off(event, wrapped);
+      listener(...args);
+    });
+    return this.on(event, wrapped);
+  }
+  /** Unsubscribe a specific listener. */
+  off(event, listener) {
+    this.#listeners.get(event)?.delete(listener);
+    return this;
+  }
+  /** Emit an event to all subscribed listeners. */
+  emit(event, ...args) {
+    const set = this.#listeners.get(event);
+    if (!set || set.size === 0) return false;
+    for (const listener of set) {
+      try {
+        listener(...args);
+      } catch (err) {
+        console.error(`Listener for event "${String(event)}" threw:`, err);
+      }
+    }
+    return true;
+  }
+  /** Remove all listeners (optionally for a specific event). */
+  removeAllListeners(event) {
+    if (event === void 0) {
+      this.#listeners.clear();
+    } else {
+      this.#listeners.delete(event);
+    }
+    return this;
+  }
+  /** Number of listeners for an event. */
+  listenerCount(event) {
+    return this.#listeners.get(event)?.size ?? 0;
+  }
+};
+
+// src/service/service-runner.ts
+var DEFAULT_FEE_ESTIMATOR = new import_bitcoin3.StaticFeeEstimator(5);
+var DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 6e4;
+var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEventEmitter {
+  /** Direct access to the underlying state machine for advanced use. */
+  session;
+  #transport;
+  #did;
+  #defaultConfig;
+  #onOptInReceived;
+  #onReadyToFinalize;
+  #onProvideTxData;
+  #feeEstimator;
+  #cohortTtlMs;
+  #phaseTimeoutMs;
+  #advertRepeatIntervalMs;
+  #autoFallbackOnStall;
+  /** Phases during which a stall can be salvaged by the k-of-n fallback (ADR 042). */
+  static #SIGNING_PHASES = [
+    "SigningStarted" /* SigningStarted */,
+    "NoncesCollected" /* NoncesCollected */,
+    "AwaitingPartialSigs" /* AwaitingPartialSigs */
+  ];
+  /** Per-cohort run state, keyed by cohortId. */
+  #contexts = /* @__PURE__ */ new Map();
+  #handlersRegistered = false;
+  #stopped = false;
+  constructor(options) {
+    super();
+    this.#transport = options.transport;
+    this.#did = options.did;
+    this.#defaultConfig = options.config;
+    this.#onOptInReceived = options.onOptInReceived ?? (async () => ({ accepted: true }));
+    this.#onReadyToFinalize = options.onReadyToFinalize ?? (async ({ acceptedCount, minRequired }) => ({
+      finalize: acceptedCount >= minRequired
+    }));
+    this.#onProvideTxData = options.onProvideTxData;
+    this.#feeEstimator = options.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
+    this.#cohortTtlMs = options.cohortTtlMs;
+    this.#phaseTimeoutMs = options.phaseTimeoutMs;
+    this.#advertRepeatIntervalMs = options.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
+    this.#autoFallbackOnStall = options.autoFallbackOnStall ?? false;
+    this.session = new AggregationService({
+      // The coordinator never signs, so the state machine receives only the
+      // public half of the operator's keypair (see ADR 038). The full keypair
+      // remains the operator's transport/communication identity.
+      did: options.did,
+      publicKey: options.keys.publicKey,
+      maxUpdateSizeBytes: options.maxUpdateSizeBytes
+    });
+  }
+  /** Resolve the {@link RunContext} an inbound message belongs to, by cohortId. */
+  #contextFor(msg) {
+    const cohortId = msg.body?.cohortId;
+    if (!cohortId) return void 0;
+    return this.#contexts.get(cohortId);
+  }
+  /**
+   * Drain any silent rejections the state machine recorded for a cohort during
+   * the most recent receive() and surface them as `message-rejected` events.
+   */
+  #drainRejections(ctx) {
+    for (const r of this.session.drainRejections(ctx.cohortId)) {
+      this.emit("message-rejected", { cohortId: ctx.cohortId, ...r });
+    }
+  }
+  /**
+   * Advertise a new cohort and begin driving it to completion. Callable many
+   * times on one runner; each cohort runs concurrently and independently.
+   *
+   * @param config Per-cohort conditions + network (see {@link CohortConfig}).
+   * @returns The new cohort's id and a `completion` promise that resolves with
+   *   that cohort's {@link AggregationResult} (or rejects if it fails/stalls).
+   * @throws If the runner has been stopped, or the config is invalid
+   *   (fail-fast via `createCohort`).
+   */
+  advertiseCohort(config) {
+    if (this.#stopped) {
+      throw new AggregationServiceError("Cannot advertise on a stopped runner.", "RUNNER_STOPPED", {});
+    }
+    this.#registerHandlers();
+    const cohortId = this.session.createCohort(config);
+    let resolve;
+    let reject;
+    const completion = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    const ctx = {
+      cohortId,
+      config,
+      resolve,
+      reject,
+      completion,
+      finalizing: false,
+      settled: false
+    };
+    this.#contexts.set(cohortId, ctx);
+    try {
+      this.#startTimers(ctx);
+      const advertMsgs = this.session.advertise(cohortId);
+      this.#onPhaseMaybeChanged(ctx);
+      this.emit("cohort-advertised", { cohortId });
+      if (this.#advertRepeatIntervalMs > 0) {
+        this.#startAdvertRepeat(ctx, advertMsgs);
+      } else {
+        this.#sendAll(advertMsgs).catch((err) => this.#failCohort(ctx, err));
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+    return { cohortId, completion };
+  }
+  /**
+   * Run a single cohort to completion using the `config` supplied in the
+   * runner options. Thin convenience over {@link advertiseCohort} for the
+   * single-cohort case (and the path {@link AggregationRunner.solo} rides).
+   *
+   * @returns {Promise<AggregationResult>} The final result with signature and signed tx.
+   */
+  run() {
+    if (!this.#defaultConfig) {
+      return Promise.reject(new AggregationServiceError(
+        "run() requires `config` in the runner options; use advertiseCohort(config) to drive cohorts explicitly.",
+        "MISSING_COHORT_CONFIG",
+        {}
+      ));
+    }
+    try {
+      return this.advertiseCohort(this.#defaultConfig).completion;
+    } catch (err) {
+      return Promise.reject(err);
+    }
+  }
+  /**
+   * Wait for every currently-outstanding cohort to settle and return the
+   * successful results. Dynamic drain: cohorts advertised while this is pending
+   * are included, and it resolves only once no cohorts remain. Failed cohorts
+   * are surfaced via `error` / `cohort-failed` events and their rejected
+   * `completion` promises; they are omitted from the returned array (this
+   * method does not throw). Bound long-running cohorts with `cohortTtlMs` /
+   * `phaseTimeoutMs` or this may never resolve.
+   *
+   * @returns {Promise<AggregationResult[]>} Results of the cohorts that completed.
+   */
+  async runAll() {
+    const collected = /* @__PURE__ */ new Map();
+    const onComplete = (result) => {
+      collected.set(result.cohortId, result);
+    };
+    this.on("signing-complete", onComplete);
+    try {
+      while (this.#contexts.size > 0) {
+        await Promise.allSettled([...this.#contexts.values()].map((c) => c.completion));
+      }
+    } finally {
+      this.off("signing-complete", onComplete);
+    }
+    return [...collected.values()];
+  }
+  /**
+   * Begin publishing a cohort's advert immediately and on a repeating interval
+   * until the cohort's advert loop is stopped. Each advert is broadcast (no
+   * recipient) via the transport's `publishRepeating` primitive.
+   */
+  #startAdvertRepeat(ctx, advertMsgs) {
+    const stops = [];
+    for (const msg of advertMsgs) {
+      stops.push(this.#transport.publishRepeating(msg, this.#did, this.#advertRepeatIntervalMs));
+    }
+    ctx.stopAdvertRepeat = () => {
+      for (const stop of stops) {
+        try {
+          stop();
+        } catch {
+        }
+      }
+    };
+  }
+  /** Stop a cohort's advert republish loop. Idempotent. */
+  #stopAdvertRepeating(ctx) {
+    if (!ctx.stopAdvertRepeat) return;
+    const stop = ctx.stopAdvertRepeat;
+    ctx.stopAdvertRepeat = void 0;
+    stop();
+  }
+  /** Schedule a cohort's TTL + phase timeout when it is advertised. */
+  #startTimers(ctx) {
+    if (this.#cohortTtlMs !== void 0) {
+      ctx.cohortTtlTimer = setTimeout(() => {
+        const reason = `Cohort ${ctx.cohortId} exceeded TTL of ${this.#cohortTtlMs}ms`;
+        this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+        this.#failCohort(ctx, new Error(reason));
+      }, this.#cohortTtlMs);
+    }
+    this.#resetPhaseTimer(ctx);
+  }
+  /** Reset a cohort's per-phase stall timer. Called when a phase transition is observed. */
+  #resetPhaseTimer(ctx) {
+    if (ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
+    ctx.phaseTimer = void 0;
+    if (this.#phaseTimeoutMs === void 0) return;
+    ctx.phaseTimer = setTimeout(() => {
+      const phase = this.session.getCohortPhase(ctx.cohortId);
+      const inSigning = phase !== void 0 && _AggregationServiceRunner.#SIGNING_PHASES.includes(phase);
+      if (this.#autoFallbackOnStall && inSigning && !ctx.committedPath && !ctx.settled) {
+        this.triggerFallback(ctx.cohortId).catch((err) => this.#failCohort(ctx, err));
+        return;
+      }
+      const reason = `Cohort ${ctx.cohortId} stalled in phase ${ctx.lastObservedPhase ?? "?"} for ${this.#phaseTimeoutMs}ms`;
+      this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+      this.#failCohort(ctx, new Error(reason));
+    }, this.#phaseTimeoutMs);
+  }
+  /**
+   * Abandon the optimistic n-of-n key path for a cohort and collect k-of-n
+   * fallback (script-path) signatures instead (ADR 042). Idempotent and safe
+   * against the optimistic completion: it commits the cohort to the fallback
+   * path synchronously (the `committedPath` latch) before sending anything, so a
+   * late optimistic signature can no longer complete-and-broadcast a competing
+   * spend of the same UTXO. No-op if the cohort is unknown, already settled, or
+   * already committed to a path.
+   *
+   * Wired automatically to the phase-stall timer when `autoFallbackOnStall` is
+   * set; otherwise call it from an operator decision (a UI "fall back now"
+   * action). Throws only if the underlying state machine rejects the transition
+   * (e.g. signing has not started).
+   */
+  async triggerFallback(cohortId) {
+    const ctx = this.#contexts.get(cohortId);
+    if (!ctx || ctx.settled || ctx.committedPath) return;
+    const messages = this.session.startFallbackSigning(cohortId);
+    ctx.committedPath = "fallback";
+    this.#stopAdvertRepeating(ctx);
+    this.#onPhaseMaybeChanged(ctx);
+    const sessionId = this.session.getSigningSessionId(cohortId) ?? "";
+    this.emit("fallback-started", { cohortId, sessionId });
+    await this.#sendAll(messages);
+  }
+  /** Detect a phase change for a cohort since the last observation and reset its phase timer. */
+  #onPhaseMaybeChanged(ctx) {
+    const phase = this.session.getCohortPhase(ctx.cohortId);
+    if (phase !== ctx.lastObservedPhase) {
+      ctx.lastObservedPhase = phase;
+      this.#resetPhaseTimer(ctx);
+    }
+  }
+  /** Clear a cohort's timers. Called on completion, stop, and failure. */
+  #clearTimers(ctx) {
+    if (ctx.cohortTtlTimer) clearTimeout(ctx.cohortTtlTimer);
+    if (ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
+    ctx.cohortTtlTimer = void 0;
+    ctx.phaseTimer = void 0;
+  }
+  /**
+   * Reclaim one cohort's runner-layer bookkeeping: stop its advert loop, clear
+   * its timers, and drop its {@link RunContext}. Does NOT touch sibling cohorts
+   * and does NOT detach the shared transport handlers. Leaves the cohort in the
+   * state machine; whether that cohort's `session` state is also removed is the
+   * caller's choice (see {@link #completeCohort} vs {@link #failCohort}).
+   */
+  #disposeCohort(ctx) {
+    this.#stopAdvertRepeating(ctx);
+    this.#clearTimers(ctx);
+    this.#contexts.delete(ctx.cohortId);
+  }
+  /**
+   * Settle one cohort successfully. Reclaims the runner context but leaves the
+   * completed cohort in `session` so callers can read its beaconAddress / cohort
+   * via `session.getCohort(result.cohortId)`; reclaim it with
+   * `session.removeCohort(cohortId)` when done. Idempotent via `ctx.settled`.
+   */
+  #completeCohort(ctx, result) {
+    if (ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.emit("signing-complete", result);
+    ctx.resolve(result);
+  }
+  /**
+   * Fail one cohort. Reclaims its runner context, drops its now-dead state from
+   * the state machine, and rejects only its completion; siblings keep running
+   * and the shared transport handlers stay registered. Idempotent via
+   * `ctx.settled`.
+   */
+  #failCohort(ctx, err) {
+    if (ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.session.removeCohort(ctx.cohortId);
+    this.emit("error", err);
+    ctx.reject(err);
+  }
+  /**
+   * Stop a single cohort early without affecting the rest of the runner. Drops
+   * the cohort's state machine state; its `completion` promise rejects with a
+   * stopped error.
+   */
+  stopCohort(cohortId) {
+    const ctx = this.#contexts.get(cohortId);
+    if (!ctx || ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.session.removeCohort(cohortId);
+    ctx.reject(new AggregationServiceError(`Cohort ${cohortId} stopped.`, "COHORT_STOPPED", { cohortId }));
+  }
+  /**
+   * Stop the whole runner. Fails every outstanding cohort, then detaches the
+   * shared transport handlers so a restart or a new runner doesn't inherit
+   * stale dispatch. Safe to call repeatedly.
+   */
+  stop() {
+    this.#stopped = true;
+    for (const ctx of [...this.#contexts.values()]) {
+      if (ctx.settled) continue;
+      ctx.settled = true;
+      this.#disposeCohort(ctx);
+      this.session.removeCohort(ctx.cohortId);
+      ctx.reject(new AggregationServiceError("Service runner stopped.", "RUNNER_STOPPED", { cohortId: ctx.cohortId }));
+    }
+    this.#contexts.clear();
+    this.#unregisterHandlers();
+  }
+  /** Message types this runner listens for on the transport. */
+  static #HANDLED_MESSAGE_TYPES = [
+    COHORT_OPT_IN,
+    SUBMIT_UPDATE,
+    SUBMIT_NONINCLUDED,
+    VALIDATION_ACK,
+    NONCE_CONTRIBUTION,
+    SIGNATURE_AUTHORIZATION,
+    FALLBACK_SIGNATURE
+  ];
+  /**
+   * Internal: handler registration with the transport. Idempotent. Handlers
+   * are DID-scoped and cohort-agnostic - one registration serves every cohort
+   * this runner drives; demux to the right {@link RunContext} happens in each
+   * handler via the inbound message's cohortId.
+   */
+  #registerHandlers() {
+    if (this.#handlersRegistered) return;
+    this.#handlersRegistered = true;
+    this.#transport.registerMessageHandler(this.#did, COHORT_OPT_IN, this.#handleOptIn.bind(this));
+    this.#transport.registerMessageHandler(this.#did, SUBMIT_UPDATE, this.#handleSubmitUpdate.bind(this));
+    this.#transport.registerMessageHandler(this.#did, SUBMIT_NONINCLUDED, this.#handleSubmitUpdate.bind(this));
+    this.#transport.registerMessageHandler(this.#did, VALIDATION_ACK, this.#handleValidationAck.bind(this));
+    this.#transport.registerMessageHandler(this.#did, NONCE_CONTRIBUTION, this.#handleNonceContribution.bind(this));
+    this.#transport.registerMessageHandler(this.#did, SIGNATURE_AUTHORIZATION, this.#handleSignatureAuthorization.bind(this));
+    this.#transport.registerMessageHandler(this.#did, FALLBACK_SIGNATURE, this.#handleFallbackSignature.bind(this));
+  }
+  /** Internal: detach from the transport. Safe to call repeatedly. */
+  #unregisterHandlers() {
+    if (!this.#handlersRegistered) return;
+    this.#handlersRegistered = false;
+    for (const type of _AggregationServiceRunner.#HANDLED_MESSAGE_TYPES) {
+      this.#transport.unregisterMessageHandler(this.#did, type);
+    }
+  }
+  /**
+   * Internal: message handlers for each protocol step. Each handler:
+   * 1) resolves the cohort the message belongs to (by cohortId); ignores it if unknown
+   * 2) feeds the message into the state machine via session.receive()
+   * 3) emits a high-level event (carrying cohortId) for external observers
+   * 4) checks if the new state triggers any automatic next steps, and if so:
+   *    a) calls the appropriate decision callback(s)
+   *    b) sends any resulting messages from the state machine
+   * Errors fail only the owning cohort. A stopped runner ignores messages.
+   * @param {BaseMessage} msg - The incoming message to handle.
+   * @returns {Promise<void>} Resolves when handling is complete.
+   */
+  async #handleOptIn(msg) {
+    if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      const optIn = this.session.pendingOptIns(ctx.cohortId).get(msg.from);
+      if (!optIn) return;
+      this.emit("opt-in-received", optIn);
+      if (optIn.communicationPk) {
+        this.#transport.registerPeer(msg.from, optIn.communicationPk);
+      }
+      const decision = await this.#onOptInReceived(optIn);
+      if (!decision.accepted) return;
+      const maxParticipants = ctx.config.maxParticipants;
+      const cohortNow = this.session.getCohort(ctx.cohortId);
+      if (maxParticipants !== void 0 && cohortNow && cohortNow.participants.length >= maxParticipants) {
+        return;
+      }
+      await this.#sendAll(this.session.acceptParticipant(ctx.cohortId, msg.from));
+      this.emit("participant-accepted", { cohortId: ctx.cohortId, participantDid: msg.from });
+      const cohort = this.session.getCohort(ctx.cohortId);
+      if (cohort.participants.length >= ctx.config.minParticipants && !ctx.finalizing) {
+        ctx.finalizing = true;
+        const finalizeDecision = await this.#onReadyToFinalize({
+          acceptedCount: cohort.participants.length,
+          minRequired: ctx.config.minParticipants
+        });
+        if (!finalizeDecision.finalize) {
+          ctx.finalizing = false;
+          return;
+        }
+        const readyMsgs = this.session.finalizeKeygen(ctx.cohortId);
+        this.#stopAdvertRepeating(ctx);
+        this.emit("keygen-complete", {
+          cohortId: ctx.cohortId,
+          beaconAddress: cohort.beaconAddress
+        });
+        await this.#sendAll(readyMsgs);
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+  }
+  /**
+   * Handler for receiving participant updates. When all updates are received, automatically builds
+   * and distributes the data for validation.
+   * @param {BaseMessage} msg - The incoming message to handle.
+   * @returns {Promise<void>} Resolves when handling is complete.
+   */
+  async #handleSubmitUpdate(msg) {
+    if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      this.emit("update-received", { cohortId: ctx.cohortId, participantDid: msg.from });
+      if (this.session.getCohortPhase(ctx.cohortId) === "UpdatesCollected" /* UpdatesCollected */) {
+        const distributeMsgs = this.session.buildAndDistribute(ctx.cohortId);
+        this.emit("data-distributed", { cohortId: ctx.cohortId });
+        await this.#sendAll(distributeMsgs);
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+  }
+  /**
+   * Handler for receiving validation acknowledgments. When all validations are received,
+   * automatically requests tx data and starts signing.
+   * @param {BaseMessage} msg - The incoming message to handle.
+   * @returns {Promise<void>} Resolves when handling is complete.
+   */
+  async #handleValidationAck(msg) {
+    if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      const approved = !!msg.body?.approved;
+      this.emit("validation-received", { cohortId: ctx.cohortId, participantDid: msg.from, approved });
+      const phase = this.session.getCohortPhase(ctx.cohortId);
+      if (phase === "Failed" /* Failed */) {
+        const reason = `Validation rejected by participant ${msg.from}`;
+        this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+        this.#failCohort(ctx, new Error(reason));
+        return;
+      }
+      if (phase === "Validated" /* Validated */) {
+        const cohort = this.session.getCohort(ctx.cohortId);
+        const txData = await this.#onProvideTxData({
+          cohortId: ctx.cohortId,
+          beaconAddress: cohort.beaconAddress,
+          signalBytes: cohort.signalBytes,
+          feeEstimator: this.#feeEstimator
+        });
+        const authMsgs = this.session.startSigning(ctx.cohortId, txData);
+        const sessionId = this.session.getSigningSessionId(ctx.cohortId) ?? "";
+        this.emit("signing-started", { cohortId: ctx.cohortId, sessionId });
+        await this.#sendAll(authMsgs);
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+  }
+  /**
+   * Handler for receiving nonce contributions. When all nonces are received, sends the aggregated
+   * nonce back to the cohort.
+   * @param {BaseMessage} msg - The incoming message to handle.
+   * @returns {Promise<void>} Resolves when handling is complete.
+   */
+  async #handleNonceContribution(msg) {
+    if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      this.emit("nonce-received", { cohortId: ctx.cohortId, participantDid: msg.from });
+      if (this.session.getCohortPhase(ctx.cohortId) === "NoncesCollected" /* NoncesCollected */) {
+        await this.#sendAll(this.session.sendAggregatedNonce(ctx.cohortId));
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+  }
+  /**
+   * Handler for receiving signature authorizations. When all partial signatures are received, the
+   * session automatically completes; the final result is emitted and the cohort's completion
+   * promise resolves.
+   * @param {BaseMessage} msg - The incoming message to handle.
+   * @returns {Promise<void>} Resolves when handling is complete.
+   */
+  async #handleSignatureAuthorization(msg) {
+    if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      if (ctx.committedPath === "fallback") return;
+      const result = this.session.getResult(ctx.cohortId);
+      if (result) {
+        ctx.committedPath = "optimistic";
+        this.#completeCohort(ctx, result);
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+  }
+  /**
+   * Handler for receiving fallback (k-of-n script-path) signatures. The state
+   * machine assembles and finalizes the fallback spend once k valid signatures
+   * are in; the result is then emitted and the cohort's completion resolves. The
+   * cohort is already committed to the fallback path (via {@link triggerFallback}).
+   * @param {BaseMessage} msg - The incoming FALLBACK_SIGNATURE message.
+   * @returns {Promise<void>} Resolves when handling is complete.
+   */
+  async #handleFallbackSignature(msg) {
+    if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
+    try {
+      this.session.receive(msg);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      const result = this.session.getResult(ctx.cohortId);
+      if (result) {
+        this.#completeCohort(ctx, result);
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
+    }
+  }
+  /**
+   * Internal: helper to send all messages sequentially. Catches and propagates errors.
+   * @param {BaseMessage[]} msgs - The messages to send.
+   * @returns {Promise<void>} Resolves when all messages have been sent.
+   */
+  async #sendAll(msgs) {
+    for (const m of msgs) {
+      await this.#transport.sendMessage(m, this.#did, m.to);
+    }
+  }
+};
+
+// src/service/http-server.ts
+var import_keypair2 = require("@did-btcr2/keypair");
+
+// src/core/logger.ts
+var CONSOLE_LOGGER = {
+  debug: (msg, ...args) => console.debug(msg, ...args),
+  info: (msg, ...args) => console.info(msg, ...args),
+  warn: (msg, ...args) => console.warn(msg, ...args),
+  error: (msg, ...args) => console.error(msg, ...args)
+};
+
+// src/core/transport/http/envelope.ts
+var import_common6 = require("@did-btcr2/common");
+var import_utils4 = require("@noble/hashes/utils");
+
+// src/core/transport/error.ts
+var import_common5 = require("@did-btcr2/common");
+var TransportAdapterError = class extends import_common5.MethodError {
+  constructor(message, type = "TransportAdapterError", data) {
+    super(message, type, data);
+  }
+};
+
+// src/core/transport/http/errors.ts
+var HttpTransportError = class extends TransportAdapterError {
+  constructor(message, type = "HttpTransportError", data) {
+    super(message, type, { adapter: "http", ...data ?? {} });
+  }
+};
+
+// src/core/transport/http/protocol.ts
+var HTTP_ENVELOPE_VERSION = 1;
+var HTTP_ROUTE = {
+  ADVERTS: "/v1/adverts",
+  MESSAGES: "/v1/messages",
+  ACTOR_INBOX: "/v1/actors/{did}/inbox",
+  WELL_KNOWN: "/v1/.well-known/aggregation"
+};
+var SSE_EVENT = {
+  ADVERT: "advert",
+  MESSAGE: "message",
+  HEARTBEAT: "heartbeat"
+};
+var DEFAULT_CLOCK_SKEW_SEC = 60;
+var DEFAULT_NONCE_LEN_BYTES = 16;
+
+// src/core/transport/http/envelope.ts
+function signEnvelope(message, sender, opts = {}) {
+  const timestamp = opts.timestamp ?? Math.floor(Date.now() / 1e3);
+  const nonce = opts.nonce ?? (0, import_utils4.bytesToHex)((0, import_utils4.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
+  const messageJson = normalizeForWire(normalizeMessage(message));
+  const unsigned = {
+    v: HTTP_ENVELOPE_VERSION,
+    from: sender.did,
+    ...opts.to !== void 0 ? { to: opts.to } : {},
+    timestamp,
+    nonce,
+    message: messageJson
+  };
+  const digest = (0, import_common6.canonicalHashBytes)(unsigned);
+  const sig = sender.keys.secretKey.sign(digest, { scheme: "schnorr" });
+  return { ...unsigned, sig: (0, import_utils4.bytesToHex)(sig) };
+}
+function verifyEnvelope(envelope, senderPk, opts = {}) {
+  if (envelope.v !== HTTP_ENVELOPE_VERSION) {
+    throw new HttpTransportError(
+      `Unsupported envelope version: ${envelope.v}`,
+      "ENVELOPE_VERSION_MISMATCH",
+      { version: envelope.v, expected: HTTP_ENVELOPE_VERSION }
+    );
+  }
+  if (opts.expectedFrom !== void 0 && envelope.from !== opts.expectedFrom) {
+    throw new HttpTransportError(
+      `Envelope from mismatch: expected ${opts.expectedFrom}, got ${envelope.from}`,
+      "ENVELOPE_FROM_MISMATCH",
+      { expected: opts.expectedFrom, got: envelope.from }
+    );
+  }
+  if ("expectedTo" in opts && envelope.to !== opts.expectedTo) {
+    throw new HttpTransportError(
+      `Envelope to mismatch: expected ${opts.expectedTo ?? "<broadcast>"}, got ${envelope.to ?? "<broadcast>"}`,
+      "ENVELOPE_TO_MISMATCH",
+      { expected: opts.expectedTo, got: envelope.to }
+    );
+  }
+  const skewSec = opts.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+  const nowMs = opts.now ? opts.now() : Date.now();
+  const nowSec = Math.floor(nowMs / 1e3);
+  const diff = Math.abs(nowSec - envelope.timestamp);
+  if (diff > skewSec) {
+    throw new HttpTransportError(
+      `Envelope timestamp out of skew: ${diff}s > ${skewSec}s`,
+      "ENVELOPE_TIMESTAMP_SKEW",
+      { diff, skewSec, timestamp: envelope.timestamp, now: nowSec }
+    );
+  }
+  let sigBytes;
+  try {
+    sigBytes = (0, import_utils4.hexToBytes)(envelope.sig);
+  } catch {
+    throw new HttpTransportError(
+      "Envelope signature is not valid hex",
+      "ENVELOPE_SIG_HEX"
+    );
+  }
+  if (sigBytes.length !== 64) {
+    throw new HttpTransportError(
+      `Invalid signature length: ${sigBytes.length} (expected 64)`,
+      "ENVELOPE_SIG_LENGTH",
+      { length: sigBytes.length }
+    );
+  }
+  const { sig: _sig, ...unsigned } = envelope;
+  const digest = (0, import_common6.canonicalHashBytes)(unsigned);
+  const ok = senderPk.verify(sigBytes, digest, { scheme: "schnorr" });
+  if (!ok) {
+    throw new HttpTransportError(
+      "Envelope signature verification failed",
+      "ENVELOPE_SIG_INVALID"
+    );
+  }
+}
+function normalizeMessage(message) {
+  const maybeToJSON = message.toJSON;
+  if (typeof maybeToJSON === "function") {
+    return maybeToJSON.call(message);
+  }
+  return message;
+}
+function normalizeForWire(value) {
+  if (value instanceof Uint8Array) {
+    return { __bytes: (0, import_utils4.bytesToHex)(value) };
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => normalizeForWire(v));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = normalizeForWire(v);
+    }
+    return out;
+  }
+  return value;
+}
+function reviveFromWire(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const rec = value;
+    const keys = Object.keys(rec);
+    if (keys.length === 1 && keys[0] === "__bytes" && typeof rec.__bytes === "string") {
+      return (0, import_utils4.hexToBytes)(rec.__bytes);
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(rec)) out[k] = reviveFromWire(v);
+    return out;
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => reviveFromWire(v));
+  }
+  return value;
+}
+
+// src/service/inbox-buffer.ts
+var InboxBuffer = class {
+  #capacity;
+  #entries = [];
+  #nextId = 1;
+  constructor(capacity = 100) {
+    if (capacity < 1) throw new Error(`InboxBuffer capacity must be >= 1; got ${capacity}`);
+    this.#capacity = capacity;
+  }
+  /** Append an event. Returns the stored record (including its assigned id). */
+  append(event, data) {
+    const stored = { id: String(this.#nextId++), event, data };
+    this.#entries.push(stored);
+    if (this.#entries.length > this.#capacity) this.#entries.shift();
+    return stored;
+  }
+  /**
+   * Return stored events with id strictly greater than `lastEventId`. If
+   * `lastEventId` is unset or unparseable, returns everything currently
+   * retained.
+   */
+  since(lastEventId) {
+    if (!lastEventId) return this.#entries.slice();
+    const boundary = Number(lastEventId);
+    if (!Number.isFinite(boundary)) return this.#entries.slice();
+    return this.#entries.filter((e) => Number(e.id) > boundary);
+  }
+  /** Currently retained event count. */
+  size() {
+    return this.#entries.length;
+  }
+};
+
+// src/service/nonce-cache.ts
+var NonceCache = class {
+  #maxEntries;
+  #entries = /* @__PURE__ */ new Map();
+  constructor(config = {}) {
+    this.#maxEntries = config.maxEntries ?? 1e4;
+  }
+  /**
+   * Record a nonce. Returns `true` if it was novel (caller should accept the
+   * request) or `false` if it was a replay (caller should reject).
+   */
+  store(did, nonce, timestampSec) {
+    const key = `${did}:${nonce}`;
+    if (this.#entries.has(key)) return false;
+    this.#entries.set(key, timestampSec);
+    if (this.#entries.size > this.#maxEntries) {
+      const oldest = this.#entries.keys().next();
+      if (!oldest.done) this.#entries.delete(oldest.value);
+    }
+    return true;
+  }
+  /** Current cache size. Exposed for observability and tests. */
+  size() {
+    return this.#entries.size;
+  }
+};
+
+// src/service/rate-limiter.ts
+var InMemoryRateLimitStore = class {
+  #buckets = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.#buckets.get(key);
+  }
+  set(key, state) {
+    this.#buckets.set(key, state);
+  }
+};
+var RateLimiter = class {
+  #rps;
+  #burst;
+  #store;
+  constructor(config = {}) {
+    this.#rps = config.rps ?? 10;
+    this.#burst = config.burst ?? 30;
+    this.#store = config.store ?? new InMemoryRateLimitStore();
+  }
+  /** Consume one token for `key`. Returns `true` if accepted, `false` if throttled. */
+  consume(key, nowMs) {
+    const existing = this.#store.get(key);
+    const state = existing ?? { tokens: this.#burst, lastRefillMs: nowMs };
+    if (existing) {
+      const elapsedSec = Math.max(0, (nowMs - existing.lastRefillMs) / 1e3);
+      state.tokens = Math.min(this.#burst, existing.tokens + elapsedSec * this.#rps);
+      state.lastRefillMs = nowMs;
+    }
+    if (state.tokens < 1) {
+      this.#store.set(key, state);
+      return false;
+    }
+    state.tokens -= 1;
+    this.#store.set(key, state);
+    return true;
+  }
+};
+
+// src/core/transport/http/request-auth.ts
+var import_common7 = require("@did-btcr2/common");
+var import_utils5 = require("@noble/hashes/utils");
+var REQUEST_AUTH_SCHEME = "BTCR2-Sig";
+function parseRequestAuth(headerValue) {
+  const prefix = `${REQUEST_AUTH_SCHEME} `;
+  if (!headerValue.startsWith(prefix)) {
+    throw new HttpTransportError(
+      `Unexpected auth scheme (want ${REQUEST_AUTH_SCHEME})`,
+      "REQUEST_AUTH_SCHEME"
+    );
+  }
+  const params = {};
+  for (const piece of headerValue.slice(prefix.length).split(",")) {
+    const eq = piece.indexOf("=");
+    if (eq === -1) continue;
+    const key = piece.slice(0, eq).trim();
+    const val = piece.slice(eq + 1).trim();
+    if (key.length > 0) params[key] = val;
+  }
+  const v = Number(params.v);
+  const ts = Number(params.ts);
+  if (!Number.isInteger(v) || !Number.isInteger(ts) || !params.did || !params.nonce || !params.sig) {
+    throw new HttpTransportError(
+      "Malformed auth header (missing or invalid field)",
+      "REQUEST_AUTH_MALFORMED",
+      { received: Object.keys(params) }
+    );
+  }
+  return { v, did: params.did, ts, nonce: params.nonce, sig: params.sig };
+}
+function verifyRequestAuth(headerValue, expectedPath, senderPk, opts = {}) {
+  const parsed = parseRequestAuth(headerValue);
+  if (parsed.v !== HTTP_ENVELOPE_VERSION) {
+    throw new HttpTransportError(
+      `Unsupported auth version: ${parsed.v}`,
+      "REQUEST_AUTH_VERSION_MISMATCH",
+      { version: parsed.v, expected: HTTP_ENVELOPE_VERSION }
+    );
+  }
+  const skewSec = opts.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+  const nowMs = opts.now ? opts.now() : Date.now();
+  const nowSec = Math.floor(nowMs / 1e3);
+  const diff = Math.abs(nowSec - parsed.ts);
+  if (diff > skewSec) {
+    throw new HttpTransportError(
+      `Auth timestamp out of skew: ${diff}s > ${skewSec}s`,
+      "REQUEST_AUTH_TIMESTAMP_SKEW",
+      { diff, skewSec }
+    );
+  }
+  let sigBytes;
+  try {
+    sigBytes = (0, import_utils5.hexToBytes)(parsed.sig);
+  } catch {
+    throw new HttpTransportError("Auth signature is not valid hex", "REQUEST_AUTH_SIG_HEX");
+  }
+  if (sigBytes.length !== 64) {
+    throw new HttpTransportError(
+      `Invalid auth signature length: ${sigBytes.length}`,
+      "REQUEST_AUTH_SIG_LENGTH",
+      { length: sigBytes.length }
+    );
+  }
+  const digest = (0, import_common7.canonicalHashBytes)({
+    v: parsed.v,
+    did: parsed.did,
+    ts: parsed.ts,
+    nonce: parsed.nonce,
+    path: expectedPath
+  });
+  const ok = senderPk.verify(sigBytes, digest, { scheme: "schnorr" });
+  if (!ok) {
+    throw new HttpTransportError("Auth signature verification failed", "REQUEST_AUTH_SIG_INVALID");
+  }
+  return parsed;
+}
+
+// src/service/http-server.ts
+var INBOX_PATH_PREFIX = "/v1/actors/";
+var INBOX_PATH_SUFFIX = "/inbox";
+var DEFAULT_ADVERT_TTL_MS = 5 * 60 * 1e3;
+var DEFAULT_HEARTBEAT_MS = 2e4;
+var HttpServerTransport = class {
+  name = "http";
+  #logger;
+  #cors;
+  #clockSkewSec;
+  #inboxBufferSize;
+  #advertTtlMs;
+  #heartbeatMs;
+  #rateLimiter;
+  #nonceCache;
+  #now;
+  #resolveSenderPkFn;
+  #actors = /* @__PURE__ */ new Map();
+  #peers = /* @__PURE__ */ new Map();
+  #inboxes = /* @__PURE__ */ new Map();
+  #broadcastSubscribers = /* @__PURE__ */ new Set();
+  #currentAdvert;
+  #advertSeq = 0;
+  constructor(config = {}) {
+    this.#logger = config.logger ?? CONSOLE_LOGGER;
+    this.#cors = config.cors ?? { mode: "permissive" };
+    this.#clockSkewSec = config.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+    this.#inboxBufferSize = config.inboxBufferSize ?? 100;
+    this.#advertTtlMs = config.advertTtlMs ?? DEFAULT_ADVERT_TTL_MS;
+    this.#heartbeatMs = config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+    this.#rateLimiter = config.rateLimiter ?? new RateLimiter();
+    this.#nonceCache = config.nonceCache ?? new NonceCache();
+    this.#now = config.now ?? (() => Date.now());
+    this.#resolveSenderPkFn = config.resolveSenderPk;
+  }
+  // ----------------------------------------------------------------
+  // Transport interface
+  // ----------------------------------------------------------------
+  start() {
+  }
+  /**
+   * Detach the transport: close every open SSE subscription, clear the advert
+   * cache, and drop all actor / peer / inbox state. Intended for shutdown and
+   * for test teardown.
+   */
+  stop() {
+    for (const sub of this.#broadcastSubscribers) this.#closeBroadcastSubscriber(sub);
+    this.#broadcastSubscribers.clear();
+    for (const inbox of this.#inboxes.values()) {
+      for (const sub of inbox.subscribers) this.#closeInboxSubscriber(sub);
+      inbox.subscribers.clear();
+    }
+    this.#inboxes.clear();
+    this.#currentAdvert = void 0;
+  }
+  registerActor(did, keys) {
+    this.#actors.set(did, { keys, handlers: /* @__PURE__ */ new Map() });
+  }
+  unregisterActor(did) {
+    this.#actors.delete(did);
+    this.#peers.delete(did);
+  }
+  getActorPk(did) {
+    return this.#actors.get(did)?.keys.publicKey.compressed;
+  }
+  registerPeer(did, communicationPk) {
+    try {
+      new import_keypair2.CompressedSecp256k1PublicKey(communicationPk);
+    } catch {
+      throw new HttpTransportError(
+        `Invalid peer public key for ${did}`,
+        "INVALID_PEER_KEY",
+        { did, keyLength: communicationPk.length }
+      );
+    }
+    this.#peers.set(did, communicationPk);
+  }
+  getPeerPk(did) {
+    return this.#peers.get(did);
+  }
+  registerMessageHandler(actorDid, messageType, handler) {
+    const actor = this.#actors.get(actorDid);
+    if (!actor) {
+      throw new HttpTransportError(
+        `Cannot register handler: actor ${actorDid} not registered`,
+        "UNKNOWN_ACTOR",
+        { did: actorDid }
+      );
+    }
+    actor.handlers.set(messageType, handler);
+  }
+  unregisterMessageHandler(actorDid, messageType) {
+    this.#actors.get(actorDid)?.handlers.delete(messageType);
+  }
+  async sendMessage(message, sender, recipient) {
+    if (!recipient) {
+      throw new HttpTransportError(
+        "HttpServerTransport.sendMessage requires a recipient. Use publishRepeating for broadcasts.",
+        "MISSING_RECIPIENT",
+        { messageType: message.type }
+      );
+    }
+    const actor = this.#actors.get(sender);
+    if (!actor) {
+      throw new HttpTransportError(
+        `Unknown sender: ${sender}`,
+        "UNKNOWN_SENDER",
+        { did: sender }
+      );
+    }
+    const envelope = signEnvelope(message, { did: sender, keys: actor.keys }, { to: recipient });
+    const dataJson = JSON.stringify(envelope);
+    const inbox = this.#getOrCreateInbox(recipient);
+    const stored = inbox.buffer.append(SSE_EVENT.MESSAGE, dataJson);
+    for (const sub of inbox.subscribers) {
+      this.#safeWrite(sub.stream, stored.event, stored.data, stored.id);
+    }
+  }
+  publishRepeating(message, sender, _intervalMs, _recipient) {
+    const actor = this.#actors.get(sender);
+    if (!actor) {
+      throw new HttpTransportError(`Unknown sender: ${sender}`, "UNKNOWN_SENDER", { did: sender });
+    }
+    const envelope = signEnvelope(message, { did: sender, keys: actor.keys });
+    const dataJson = JSON.stringify(envelope);
+    const id = String(++this.#advertSeq);
+    const expiresAtMs = this.#now() + this.#advertTtlMs;
+    this.#currentAdvert = { dataJson, id, expiresAtMs };
+    for (const sub of this.#broadcastSubscribers) {
+      this.#safeWrite(sub.stream, SSE_EVENT.ADVERT, dataJson, id);
+    }
+    return () => {
+      if (this.#currentAdvert?.id === id) this.#currentAdvert = void 0;
+    };
+  }
+  // ----------------------------------------------------------------
+  // Sans-I/O HTTP surface
+  // ----------------------------------------------------------------
+  /**
+   * Handle a POST / GET request (non-SSE). The caller dispatches SSE paths to
+   * {@link handleSse} instead. Returns a fully formed response; the caller's
+   * adapter turns it into an HTTP write.
+   */
+  async handleRequest(req) {
+    const method = req.method.toUpperCase();
+    if (method === "OPTIONS") return this.#respond(204, "", req);
+    const path = extractPath(req.url);
+    if (method === "GET" && path === HTTP_ROUTE.WELL_KNOWN) {
+      return this.#respondJson(200, this.#wellKnownMetadata(), req);
+    }
+    if (method === "POST" && path === HTTP_ROUTE.MESSAGES) {
+      return await this.#handleMessagesPost(req);
+    }
+    if (method === "POST" && path === HTTP_ROUTE.ADVERTS) {
+      return await this.#handleAdvertsPost(req);
+    }
+    return this.#respondJson(404, { error: "not_found" }, req);
+  }
+  /**
+   * Open an SSE stream for a GET request. The caller is responsible for
+   * flushing writes and propagating the `onClose` callback when the HTTP
+   * connection ends.
+   */
+  handleSse(req, stream) {
+    if (req.method.toUpperCase() !== "GET") {
+      stream.close();
+      return;
+    }
+    const path = extractPath(req.url);
+    if (path === HTTP_ROUTE.ADVERTS) {
+      this.#openBroadcastSubscription(stream);
+      return;
+    }
+    const inboxMatch = matchInboxPath(path);
+    if (inboxMatch) {
+      this.#openInboxSubscription(req, stream, inboxMatch.did, path);
+      return;
+    }
+    stream.close();
+  }
+  // ----------------------------------------------------------------
+  // Request handlers
+  // ----------------------------------------------------------------
+  async #handleMessagesPost(req) {
+    const envelope = parseJsonBody(req.body);
+    if (!envelope) return this.#respondJson(400, { error: "invalid_json" }, req);
+    const senderPk = this.#resolveSenderPk(envelope.from);
+    if (!senderPk) {
+      return this.#respondJson(401, { error: "unknown_sender" }, req);
+    }
+    try {
+      verifyEnvelope(envelope, senderPk, { clockSkewSec: this.#clockSkewSec });
+    } catch (err) {
+      this.#logger.debug("POST /v1/messages: envelope verification failed:", err);
+      return this.#respondJson(401, { error: "invalid_envelope" }, req);
+    }
+    if (!this.#nonceCache.store(envelope.from, envelope.nonce, envelope.timestamp)) {
+      return this.#respondJson(409, { error: "replay" }, req);
+    }
+    if (!this.#rateLimiter.consume(envelope.from, this.#now())) {
+      return this.#respondJson(429, { error: "rate_limited" }, req);
+    }
+    if (!envelope.to) {
+      return this.#respondJson(400, { error: "missing_recipient" }, req);
+    }
+    const actor = this.#actors.get(envelope.to);
+    if (!actor) {
+      return this.#respondJson(404, { error: "unknown_recipient" }, req);
+    }
+    const revived = reviveFromWire(envelope.message);
+    const flat = flattenMessage(revived);
+    const messageType = typeof flat.type === "string" ? flat.type : void 0;
+    if (!messageType) return this.#respondJson(400, { error: "missing_message_type" }, req);
+    const handler = actor.handlers.get(messageType);
+    if (handler) {
+      try {
+        await handler(flat);
+      } catch (err) {
+        this.#logger.debug(`Handler threw for ${messageType}:`, err);
+      }
+    }
+    return this.#respondJson(202, { ok: true }, req);
+  }
+  async #handleAdvertsPost(req) {
+    const envelope = parseJsonBody(req.body);
+    if (!envelope) return this.#respondJson(400, { error: "invalid_json" }, req);
+    const senderPk = this.#resolveSenderPk(envelope.from);
+    if (!senderPk) return this.#respondJson(401, { error: "unknown_sender" }, req);
+    try {
+      verifyEnvelope(envelope, senderPk, { clockSkewSec: this.#clockSkewSec });
+    } catch {
+      return this.#respondJson(401, { error: "invalid_envelope" }, req);
+    }
+    if (!this.#nonceCache.store(envelope.from, envelope.nonce, envelope.timestamp)) {
+      return this.#respondJson(409, { error: "replay" }, req);
+    }
+    if (!this.#rateLimiter.consume(envelope.from, this.#now())) {
+      return this.#respondJson(429, { error: "rate_limited" }, req);
+    }
+    if (!this.#actors.has(envelope.from)) {
+      return this.#respondJson(403, { error: "not_an_actor" }, req);
+    }
+    const id = String(++this.#advertSeq);
+    this.#currentAdvert = {
+      dataJson: JSON.stringify(envelope),
+      id,
+      expiresAtMs: this.#now() + this.#advertTtlMs
+    };
+    for (const sub of this.#broadcastSubscribers) {
+      this.#safeWrite(sub.stream, SSE_EVENT.ADVERT, this.#currentAdvert.dataJson, id);
+    }
+    return this.#respondJson(202, { ok: true }, req);
+  }
+  #openBroadcastSubscription(stream) {
+    const sub = { stream };
+    this.#broadcastSubscribers.add(sub);
+    stream.onClose(() => {
+      this.#closeBroadcastSubscriber(sub);
+      this.#broadcastSubscribers.delete(sub);
+    });
+    if (this.#currentAdvert && this.#currentAdvert.expiresAtMs > this.#now()) {
+      this.#safeWrite(stream, SSE_EVENT.ADVERT, this.#currentAdvert.dataJson, this.#currentAdvert.id);
+    }
+    if (this.#heartbeatMs > 0) {
+      sub.heartbeatTimer = setInterval(() => {
+        try {
+          stream.writeComment("hb");
+        } catch {
+        }
+      }, this.#heartbeatMs);
+    }
+  }
+  #openInboxSubscription(req, stream, did, path) {
+    const auth = req.headers.authorization;
+    if (!auth) {
+      this.#logger.debug(`Inbox subscribe: missing authorization header for ${did}`);
+      stream.close();
+      return;
+    }
+    const senderPk = this.#resolveSenderPk(did);
+    if (!senderPk) {
+      stream.close();
+      return;
+    }
+    let parsedTs = 0;
+    let parsedNonce = "";
+    try {
+      const parsed = verifyRequestAuth(auth, path, senderPk, {
+        clockSkewSec: this.#clockSkewSec,
+        now: () => this.#now()
+      });
+      if (parsed.did !== did) {
+        stream.close();
+        return;
+      }
+      parsedTs = parsed.ts;
+      parsedNonce = parsed.nonce;
+    } catch (err) {
+      this.#logger.debug(`Inbox subscribe: auth verification failed for ${did}:`, err);
+      stream.close();
+      return;
+    }
+    if (!this.#nonceCache.store(did, parsedNonce, parsedTs)) {
+      stream.close();
+      return;
+    }
+    if (!this.#rateLimiter.consume(did, this.#now())) {
+      stream.close();
+      return;
+    }
+    const inbox = this.#getOrCreateInbox(did);
+    const sub = { stream };
+    inbox.subscribers.add(sub);
+    stream.onClose(() => {
+      this.#closeInboxSubscriber(sub);
+      inbox.subscribers.delete(sub);
+    });
+    const lastEventId = req.headers["last-event-id"];
+    for (const stored of inbox.buffer.since(lastEventId)) {
+      this.#safeWrite(stream, stored.event, stored.data, stored.id);
+    }
+    if (this.#heartbeatMs > 0) {
+      sub.heartbeatTimer = setInterval(() => {
+        try {
+          stream.writeComment("hb");
+        } catch {
+        }
+      }, this.#heartbeatMs);
+    }
+  }
+  // ----------------------------------------------------------------
+  // Internal helpers
+  // ----------------------------------------------------------------
+  #getOrCreateInbox(did) {
+    let inbox = this.#inboxes.get(did);
+    if (!inbox) {
+      inbox = { buffer: new InboxBuffer(this.#inboxBufferSize), subscribers: /* @__PURE__ */ new Set() };
+      this.#inboxes.set(did, inbox);
+    }
+    return inbox;
+  }
+  #resolveSenderPk(did) {
+    const peerBytes = this.#peers.get(did);
+    if (peerBytes) {
+      try {
+        return new import_keypair2.CompressedSecp256k1PublicKey(peerBytes);
+      } catch {
+      }
+    }
+    return this.#resolveSenderPkFn?.(did);
+  }
+  #safeWrite(stream, event, data, id) {
+    try {
+      stream.writeEvent(event, data, id);
+    } catch (err) {
+      this.#logger.debug("SSE writeEvent failed:", err);
+    }
+  }
+  #closeBroadcastSubscriber(sub) {
+    if (sub.heartbeatTimer) clearInterval(sub.heartbeatTimer);
+    try {
+      sub.stream.close();
+    } catch {
+    }
+  }
+  #closeInboxSubscriber(sub) {
+    if (sub.heartbeatTimer) clearInterval(sub.heartbeatTimer);
+    try {
+      sub.stream.close();
+    } catch {
+    }
+  }
+  #respondJson(status, body, req) {
+    return {
+      status,
+      headers: { "content-type": "application/json", ...this.#corsHeaders(req) },
+      body: JSON.stringify(body)
+    };
+  }
+  #respond(status, body, req) {
+    return { status, headers: this.#corsHeaders(req), body };
+  }
+  #corsHeaders(req) {
+    const origin = req.headers.origin;
+    if (!origin) return {};
+    const common = {
+      "access-control-allow-methods": "GET, POST, OPTIONS",
+      "access-control-allow-headers": "authorization, content-type, last-event-id",
+      "access-control-max-age": "86400"
+    };
+    switch (this.#cors.mode) {
+      case "permissive":
+        return { "access-control-allow-origin": "*", ...common };
+      case "allowlist":
+        if (this.#cors.origins.includes(origin)) {
+          return { "access-control-allow-origin": origin, vary: "origin", ...common };
+        }
+        return {};
+      case "same-origin":
+        return {};
+    }
+  }
+  #wellKnownMetadata() {
+    return {
+      envelopeVersion: HTTP_ENVELOPE_VERSION,
+      heartbeatIntervalMs: this.#heartbeatMs,
+      inboxBufferSize: this.#inboxBufferSize,
+      advertTtlMs: this.#advertTtlMs
+    };
+  }
+};
+function extractPath(reqUrl) {
+  if (reqUrl.startsWith("http://") || reqUrl.startsWith("https://")) {
+    return new URL(reqUrl).pathname;
+  }
+  const q = reqUrl.indexOf("?");
+  return q === -1 ? reqUrl : reqUrl.slice(0, q);
+}
+function matchInboxPath(path) {
+  if (!path.startsWith(INBOX_PATH_PREFIX) || !path.endsWith(INBOX_PATH_SUFFIX)) return void 0;
+  const encodedDid = path.slice(INBOX_PATH_PREFIX.length, path.length - INBOX_PATH_SUFFIX.length);
+  if (!encodedDid) return void 0;
+  try {
+    return { did: decodeURIComponent(encodedDid) };
+  } catch {
+    return void 0;
+  }
+}
+function parseJsonBody(body) {
+  if (body === void 0 || body === "") return void 0;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+function flattenMessage(msg) {
+  if (msg.body && typeof msg.body === "object") {
+    return { ...msg, ...msg.body };
+  }
+  return msg;
+}
+
+// src/service/sse-writer.ts
+function formatSseEvent(event, data, id) {
+  const lines = [];
+  if (id !== void 0) lines.push(`id: ${id}`);
+  lines.push(`event: ${event}`);
+  for (const part of data.split("\n")) lines.push(`data: ${part}`);
+  lines.push("");
+  lines.push("");
+  return lines.join("\n");
+}
+function formatSseComment(comment) {
+  const safe = comment.replace(/\n/g, " ");
+  return `: ${safe}
+
+`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AggregationService,
+  AggregationServiceRunner,
+  DEFAULT_ADVERT_REPEAT_INTERVAL_MS,
+  DEFAULT_MAX_UPDATE_SIZE_BYTES,
+  HttpServerTransport,
+  InMemoryRateLimitStore,
+  InboxBuffer,
+  NonceCache,
+  RateLimiter,
+  formatSseComment,
+  formatSseEvent
+});