@did-btcr2/method 0.28.0 → 0.32.0

package/src/core/aggregation/service.ts

@@ -1,10 +1,14 @@
+import { canonicalize } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
+import { BIP340Cryptosuite, SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import type { SchnorrKeyPair } from '@did-btcr2/keypair';
 import { bytesToHex } from '@noble/hashes/utils';
-import type { Transaction } from 'bitcoinjs-lib';
+import type { Transaction } from '@scure/btc-signer';
+import { getBeaconStrategy } from './beacon-strategy.js';
 import { AggregationCohort } from './cohort.js';
 import { AggregationServiceError } from './errors.js';
 import type { BaseMessage } from './messages/base.js';
+import { AGGREGATION_WIRE_VERSION } from './messages/base.js';
 import {
   COHORT_OPT_IN,
   NONCE_CONTRIBUTION,
@@ -13,12 +17,12 @@ import {
   VALIDATION_ACK,
 } from './messages/constants.js';
 import {
+  createAggregatedNonceMessage,
   createAuthorizationRequestMessage,
   createCohortAdvertMessage,
   createCohortOptInAcceptMessage,
   createCohortReadyMessage,
   createDistributeAggregatedDataMessage,
-  createAggregatedNonceMessage,
 } from './messages/factories.js';
 import type { ServiceCohortPhaseType } from './phases.js';
 import { ServiceCohortPhase } from './phases.js';
@@ -61,6 +65,23 @@ export interface SigningTxData {
   prevOutValues: bigint[];
 }
 
+/** Reason an incoming message was silently dropped by the state machine. */
+export type RejectionReason =
+  | 'WRONG_VERSION'
+  | 'UPDATE_TOO_LARGE'
+  | 'UPDATE_VERIFICATION_FAILED'
+  | 'UPDATE_MALFORMED';
+
+/** Record of a silently-dropped inbound message. Drained by the runner to emit events. */
+export interface Rejection {
+  /** DID of the sender whose message was rejected. */
+  from: string;
+  /** Machine-readable code. */
+  code: RejectionReason;
+  /** Human-readable reason. */
+  reason: string;
+}
+
 /** Per-cohort service state — internal. */
 interface ServiceCohortState {
   phase: ServiceCohortPhaseType;
@@ -70,11 +91,22 @@ interface ServiceCohortState {
   acceptedParticipants: Set<string>;
   signingSession?: BeaconSigningSession;
   result?: AggregationResult;
+  /** Rejections accumulated since last drain. Runner polls via drainRejections(). */
+  rejections: Array<Rejection>;
 }
 
+/** Default maximum canonicalized byte-length of a submitted BTCR2 update. */
+export const DEFAULT_MAX_UPDATE_SIZE_BYTES = 256 * 1024;
+
 export interface AggregationServiceParams {
   did: string;
   keys: SchnorrKeyPair;
+  /**
+   * Maximum canonicalized byte-length of a signed update body accepted by the
+   * service. Submissions above this cap are silently dropped and surfaced as
+   * `UPDATE_TOO_LARGE` rejections. Defaults to {@link DEFAULT_MAX_UPDATE_SIZE_BYTES}.
+   */
+  maxUpdateSizeBytes?: number;
 }
 
 /**
@@ -91,17 +123,36 @@ export interface AggregationServiceParams {
 export class AggregationService {
   readonly did: string;
   readonly keys: SchnorrKeyPair;
+  readonly maxUpdateSizeBytes: number;
 
   /** Per-cohort state, keyed by cohortId. */
   #cohortStates: Map<string, ServiceCohortState> = new Map();
 
-  constructor({ did, keys }: AggregationServiceParams) {
+  constructor({ did, keys, maxUpdateSizeBytes }: AggregationServiceParams) {
     this.did = did;
     this.keys = keys;
+    this.maxUpdateSizeBytes = maxUpdateSizeBytes ?? DEFAULT_MAX_UPDATE_SIZE_BYTES;
   }
 
 
   receive(message: BaseMessage): void {
+    // Reject messages whose wire version doesn't match what this build speaks.
+    // Missing version → treat as legacy and drop: bumping the protocol must be
+    // coordinated across all participants.
+    const version = message.version;
+    if(version === undefined || version !== AGGREGATION_WIRE_VERSION) {
+      const cohortId = message.body?.cohortId;
+      const state = cohortId ? this.#cohortStates.get(cohortId) : undefined;
+      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:
@@ -125,6 +176,19 @@ export class AggregationService {
     }
   }
 
+  /**
+   * 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: string): Array<Rejection> {
+    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.
@@ -143,6 +207,7 @@ export class AggregationService {
       config,
       pendingOptIns        : new Map(),
       acceptedParticipants : new Set(),
+      rejections           : [],
     });
     return cohort.id;
   }
@@ -202,6 +267,13 @@ export class AggregationService {
     const communicationPk = message.body?.communicationPk;
     if(!participantPk || !communicationPk) return;
 
+    // Reject re-opt-in from already-accepted participants. Without this guard a
+    // participant could send a second opt-in with a different key, overwriting
+    // pendingOptIns[did] while cohortKeys still holds the original key — opening
+    // a desync window where #verifySubmittedUpdate accepts updates signed with
+    // a key that is NOT in the MuSig2 cohort.
+    if(state.acceptedParticipants.has(participantDid)) return;
+
     state.pendingOptIns.set(participantDid, {
       cohortId,
       participantDid,
@@ -235,6 +307,7 @@ export class AggregationService {
 
     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({
@@ -290,6 +363,13 @@ export class AggregationService {
     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: BaseMessage): void {
     const cohortId = message.body?.cohortId;
     if(!cohortId) return;
@@ -297,10 +377,43 @@ export class AggregationService {
     if(!state) return;
     if(state.phase !== ServiceCohortPhase.CohortSet && state.phase !== ServiceCohortPhase.CollectingUpdates) return;
 
-    const signedUpdate = message.body?.signedUpdate;
-    if(!signedUpdate) return;
+    const signedUpdate = message.body?.signedUpdate as SignedBTCR2Update | undefined;
+    if(!signedUpdate) {
+      state.rejections.push({
+        from   : message.from,
+        code   : 'UPDATE_MALFORMED',
+        reason : 'SUBMIT_UPDATE missing signedUpdate body',
+      });
+      return;
+    }
+
+    // Cap the canonicalized update size before doing any heavier verification
+    // work. Without this guard, a participant could submit multi-MB payloads
+    // that the service would canonicalize, hash, and aggregate — cheap DoS.
+    const canonicalSize = canonicalize(signedUpdate as unknown as Record<string, unknown>).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;
+    }
+
+    // Verify the BIP-340 Data Integrity proof before aggregating. Without this check,
+    // a malicious cohort member could submit updates with garbage proofs, which the
+    // service would aggregate into the CAS announcement / SMT root and ultimately
+    // anchor on-chain with the cohort's MuSig2 signature.
+    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;
+    }
 
-    state.cohort.addUpdate(message.from, signedUpdate as unknown as SignedBTCR2Update);
+    state.cohort.addUpdate(message.from, signedUpdate);
 
     if(state.phase === ServiceCohortPhase.CohortSet) {
       state.phase = ServiceCohortPhase.CollectingUpdates;
@@ -310,6 +423,46 @@ export class AggregationService {
     }
   }
 
+  /**
+   * 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 {SignedBTCR2Update} 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: ServiceCohortState,
+    sender: string,
+    signedUpdate: SignedBTCR2Update,
+  ): boolean {
+    const proof = signedUpdate.proof;
+    if(!proof?.verificationMethod || !proof.proofValue) return false;
+
+    // The proof must be signed by the sender's own key. Reject if the
+    // verificationMethod references a different DID.
+    const vmDid = proof.verificationMethod.split('#')[0];
+    if(vmDid !== sender) return false;
+
+    const optIn = state.pendingOptIns.get(sender);
+    if(!optIn) return false;
+
+    try {
+      const multikey = SchnorrMultikey.fromPublicKey({
+        id             : proof.verificationMethod,
+        controller     : sender,
+        publicKeyBytes : optIn.participantPk,
+      }) as SchnorrMultikey;
+      const suite = new BIP340Cryptosuite(multikey);
+      return suite.verifyProof(signedUpdate).verified === true;
+    } catch {
+      return false;
+    }
+  }
+
 
   /**
    * Build the aggregated data structure (CAS Announcement or SMT tree) and
@@ -327,30 +480,29 @@ export class AggregationService {
       );
     }
 
-    if(state.config.beaconType === 'CASBeacon') {
-      state.cohort.buildCASAnnouncement();
-    } else if(state.config.beaconType === 'SMTBeacon') {
-      state.cohort.buildSMTTree();
-    } else {
+    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 = bytesToHex(state.cohort.signalBytes!);
     state.phase = ServiceCohortPhase.DataDistributed;
 
     const messages: BaseMessage[] = [];
     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 : state.config.beaconType === 'CASBeacon' ? state.cohort.casAnnouncement : undefined,
-        smtProof        : state.config.beaconType === 'SMTBeacon' ? state.cohort.smtProofs?.get(participantDid) as unknown as Record<string, unknown> : undefined,
+        casAnnouncement : payload.casAnnouncement,
+        smtProof        : payload.smtProof,
       }));
     }
     return messages;
@@ -422,15 +574,24 @@ export class AggregationService {
     state.signingSession = session;
     state.phase = ServiceCohortPhase.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: BaseMessage[] = [];
     for(const participantDid of state.cohort.participants) {
       messages.push(createAuthorizationRequestMessage({
-        from         : this.did,
-        to           : participantDid,
+        from             : this.did,
+        to               : participantDid,
         cohortId,
-        sessionId    : session.id,
-        pendingTx    : txData.tx.toHex(),
-        prevOutValue : txData.prevOutValues[0]?.toString() ?? '0',
+        sessionId        : session.id,
+        pendingTx        : txData.tx.hex,
+        prevOutScriptHex : bytesToHex(prevOutScript),
+        prevOutValue     : txData.prevOutValues[0]?.toString() ?? '0',
       }));
     }
     return messages;
@@ -507,8 +668,8 @@ export class AggregationService {
       // All partial sigs received — generate final signature
       const signature = state.signingSession.generateFinalSignature();
 
-      // Set Taproot key-path witness
-      state.signingSession.pendingTx.setWitness(0, [signature]);
+      // Set Taproot key-path witness (finalScriptWitness injects the aggregated MuSig2 sig)
+      state.signingSession.pendingTx.updateInput(0, { finalScriptWitness: [signature] });
 
       state.result = {
         cohortId,
@@ -544,4 +705,12 @@ export class AggregationService {
   get cohorts(): ReadonlyArray<AggregationCohort> {
     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: string): void {
+    this.#cohortStates.delete(cohortId);
+  }
 }

package/src/core/aggregation/signing-session.ts

@@ -1,5 +1,6 @@
+import type { Transaction } from '@scure/btc-signer';
+import { SigHash } from '@scure/btc-signer';
 import * as musig2 from '@scure/btc-signer/musig2';
-import { Transaction } from 'bitcoinjs-lib';
 import type { AggregationCohort } from './cohort.js';
 import { SigningSessionError } from './errors.js';
 import type { SigningSessionPhaseType } from './phases.js';
@@ -79,11 +80,11 @@ export class BeaconSigningSession {
         'SIGHASH_ERROR'
       );
     }
-    return this.pendingTx.hashForWitnessV1(
+    return this.pendingTx.preimageWitnessV1(
       0,
       this.prevOutScripts,
-      this.prevOutValues,
-      Transaction.SIGHASH_DEFAULT
+      SigHash.DEFAULT,
+      this.prevOutValues
     );
   }
 
@@ -94,6 +95,12 @@ export class BeaconSigningSession {
         '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}.`,
@@ -132,6 +139,12 @@ export class BeaconSigningSession {
         '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}.`,
@@ -159,9 +172,47 @@ export class BeaconSigningSession {
       this.aggregatedNonce,
       this.cohort.cohortKeys,
       this.sigHash,
-      [this.cohort.trMerkleRoot],
+      [this.cohort.tapTweak],
       [true]
     );
+
+    // Pre-verify each partial signature against the signer's public key before
+    // aggregating (BIP-327 §2.3.5). Delegating verification to partialSigAgg
+    // alone makes it impossible to attribute a bad contribution; pinpointing
+    // the offending participant lets the service blame and retry without the
+    // whole cohort.
+    //
+    // partialSigVerify(partialSig, pubNonces, i) needs pubNonces ordered to
+    // match cohort.cohortKeys, and `i` is the signer's position in that array.
+    const pubNoncesByIndex: Uint8Array[] = 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 = SigningSessionPhase.Complete;
     return this.signature;
@@ -181,6 +232,10 @@ export class BeaconSigningSession {
   /**
    * Generates a partial signature using the participant's secret key + secret nonce.
    * Requires the aggregated nonce to have been set first (via the service).
+   *
+   * Zeros the stored `secretNonce` after use. JS cannot truly erase memory (GC
+   * and immutable strings), but overwriting the bytes shortens the exposure
+   * window and prevents accidental reuse or serialization of a spent nonce.
    */
   public generatePartialSignature(participantSecretKey: Uint8Array): Uint8Array {
     if(!this.aggregatedNonce) {
@@ -193,10 +248,13 @@ export class BeaconSigningSession {
       this.aggregatedNonce,
       this.cohort.cohortKeys,
       this.sigHash,
-      [this.cohort.trMerkleRoot],
+      [this.cohort.tapTweak],
       [true]
     );
-    return session.sign(this.secretNonce, participantSecretKey);
+    const partialSig = session.sign(this.secretNonce, participantSecretKey);
+    this.secretNonce.fill(0);
+    this.secretNonce = undefined;
+    return partialSig;
   }
 
   public isComplete(): boolean {

package/src/core/aggregation/transport/didcomm.ts

@@ -36,7 +36,24 @@ export class DidCommTransport implements Transport {
     throw new NotImplementedError('DidCommTransport not implemented.');
   }
 
+  public unregisterMessageHandler(_actorDid: string, _messageType: string): void {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public unregisterActor(_did: string): void {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
   public async sendMessage(_message: BaseMessage, _sender: string, _recipient?: string): Promise<void> {
     throw new NotImplementedError('DidCommTransport not implemented.');
   }
+
+  public publishRepeating(
+    _message: BaseMessage,
+    _sender: string,
+    _intervalMs: number,
+    _recipient?: string,
+  ): () => void {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
 }

package/src/core/aggregation/transport/factory.ts

@@ -1,28 +1,64 @@
 import { NotImplementedError } from '@did-btcr2/common';
-import { NostrTransport } from './nostr.js';
+import type { Logger } from '../logger.js';
 import { TransportError } from './error.js';
-import type { Transport, TransportType } from './transport.js';
+import type { HttpClientTransportConfig } from './http/client.js';
+import { HttpClientTransport } from './http/client.js';
+import type { HttpServerTransportConfig } from './http/server.js';
+import { HttpServerTransport } from './http/server.js';
+import { NostrTransport } from './nostr.js';
+import type { Transport } from './transport.js';
+
+/** Discriminated-union config for {@link TransportFactory.establish}. */
+export type TransportConfig =
+  | NostrTransportConfigOption
+  | DidCommTransportConfigOption
+  | HttpClientTransportConfigOption
+  | HttpServerTransportConfigOption;
 
-export interface TransportConfig {
-  type: TransportType;
+export interface NostrTransportConfigOption {
+  type: 'nostr';
   relays?: string[];
+  logger?: Logger;
+  broadcastLookbackMs?: number;
+}
+
+export interface DidCommTransportConfigOption {
+  type: 'didcomm';
 }
 
-/**
- * Factory for creating Transport instances.
- * @class TransportFactory
- */
+export interface HttpClientTransportConfigOption extends HttpClientTransportConfig {
+  type: 'http';
+  role: 'client';
+}
+
+export interface HttpServerTransportConfigOption extends HttpServerTransportConfig {
+  type: 'http';
+  role: 'server';
+}
+
+/** Factory for creating Transport instances. */
 export class TransportFactory {
   static establish(config: TransportConfig): Transport {
-    switch (config.type) {
+    switch(config.type) {
       case 'nostr':
-        return new NostrTransport({ relays: config.relays });
+        return new NostrTransport({
+          relays              : config.relays,
+          logger              : config.logger,
+          broadcastLookbackMs : config.broadcastLookbackMs,
+        });
       case 'didcomm':
         throw new NotImplementedError('DIDComm transport not implemented yet.');
+      case 'http':
+        if(config.role === 'client') return new HttpClientTransport(config);
+        if(config.role === 'server') return new HttpServerTransport(config);
+        throw new NotImplementedError(
+          `HTTP transport role not implemented: ${(config as { role: string }).role}`,
+        );
       default:
         throw new TransportError(
-          `Invalid transport type: ${config.type}`,
-          'INVALID_TRANSPORT_TYPE', { config }
+          `Invalid transport type: ${(config as { type: string }).type}`,
+          'INVALID_TRANSPORT_TYPE',
+          { config },
         );
     }
   }