@did-btcr2/aggregation 0.1.0

package/src/signer.ts

@@ -0,0 +1,67 @@
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { wipe } from '@did-btcr2/keypair';
+
+/**
+ * A signing capability for MuSig2 aggregation.
+ *
+ * MuSig2 (BIP-327) cannot be driven through a generic `sign(message)` primitive:
+ * both nonce generation and partial signing need the raw 32-byte secret scalar
+ * (see ADR 038). Rather than hand that scalar around as a long-lived field, the
+ * participant holds an `AggregationSigner` and materializes the secret only for
+ * the duration of a single operation via {@link AggregationSigner.withSecret},
+ * which is responsible for wiping its working copy afterward.
+ *
+ * This is the seam a non-extractable / KMS-backed signer (or a session-scoped
+ * signer that destroys its key after the cohort completes) plugs into without
+ * changing the participant state machine.
+ *
+ * @interface AggregationSigner
+ */
+export interface AggregationSigner {
+  /** Compressed 33-byte public key. Not secret; always available. */
+  readonly publicKey: Uint8Array;
+
+  /**
+   * Materialize the raw 32-byte secret key, pass it to `fn`, and zeroize the
+   * working copy before returning - even if `fn` throws. The secret must not
+   * escape the callback.
+   *
+   * @typeParam T The callback's return type (e.g. a nonce contribution or partial signature).
+   * @param {(secretKey: Uint8Array) => T} fn Operation that needs the raw secret for its duration.
+   * @returns {T} Whatever `fn` returns.
+   */
+  withSecret<T>(fn: (secretKey: Uint8Array) => T): T;
+}
+
+/**
+ * {@link AggregationSigner} backed by an in-memory {@link SchnorrKeyPair}.
+ *
+ * The keypair is held privately (never exposed as a public field) and each
+ * `withSecret` call pulls a fresh copy of the secret bytes, hands it to the
+ * callback, and wipes that copy on return. The underlying keypair is the
+ * caller's to own and destroy; this signer never mutates or destroys it.
+ *
+ * @class KeyPairAggregationSigner
+ * @implements {AggregationSigner}
+ */
+export class KeyPairAggregationSigner implements AggregationSigner {
+  readonly publicKey: Uint8Array;
+  readonly #keys: SchnorrKeyPair;
+
+  /** @param {SchnorrKeyPair} keys The keypair whose secret backs this signer. */
+  constructor(keys: SchnorrKeyPair) {
+    this.#keys = keys;
+    this.publicKey = keys.publicKey.compressed;
+  }
+
+  withSecret<T>(fn: (secretKey: Uint8Array) => T): T {
+    // `.bytes` returns a fresh copy; wipe it once the operation completes so the
+    // raw scalar does not linger on the heap beyond a single MuSig2 step.
+    const secretKey = this.#keys.secretKey.bytes;
+    try {
+      return fn(secretKey);
+    } finally {
+      wipe(secretKey);
+    }
+  }
+}

package/src/signing-session.ts

@@ -0,0 +1,290 @@
+import { wipe } from '@did-btcr2/keypair';
+import type { Transaction } from '@scure/btc-signer';
+import { SigHash } from '@scure/btc-signer';
+import * as musig2 from '@scure/btc-signer/musig2';
+import type { AggregationCohort } from './cohort.js';
+import { SigningSessionError } from './errors.js';
+import type { SigningSessionPhaseType } from './phases.js';
+import { SigningSessionPhase } from './phases.js';
+
+type PublicKeyHex = string;
+type Nonce = Uint8Array;
+
+export interface SigningSessionParams {
+  id?: string;
+  cohort: AggregationCohort;
+  pendingTx: Transaction;
+  prevOutScripts?: Uint8Array[];
+  prevOutValues?: bigint[];
+}
+
+/**
+ * MuSig2 signing session for a beacon transaction.
+ *
+ * Implements the BIP-327 signing protocol over a Taproot key-path-only
+ * transaction. The session is used by both AggregationService (collecting
+ * nonces and partial signatures, computing the final signature) and
+ * AggregationParticipant (generating their nonce and partial signature).
+ *
+ * @class BeaconSigningSession
+ */
+export class BeaconSigningSession {
+  /** Unique identifier for this signing session. */
+  public id: string;
+
+  /** The cohort this session signs for. */
+  public cohort: AggregationCohort;
+
+  /** The Bitcoin transaction being signed. */
+  public pendingTx: Transaction;
+
+  /** Previous output scripts for Taproot sighash computation (BIP-341). */
+  public prevOutScripts: Uint8Array[];
+
+  /** Previous output values for Taproot sighash computation. */
+  public prevOutValues: bigint[];
+
+  /** Map of participant publicKey-hex to public nonce contribution. */
+  public nonceContributions: Map<PublicKeyHex, Nonce> = new Map();
+
+  /** Aggregated MuSig2 nonce (66 bytes). */
+  public aggregatedNonce?: Uint8Array;
+
+  /** Map of participant DID to partial signature. */
+  public partialSignatures: Map<string, Uint8Array> = new Map();
+
+  /** Final 64-byte Schnorr signature. */
+  public signature?: Uint8Array;
+
+  /** Current signing session phase. */
+  public phase: SigningSessionPhaseType;
+
+  /**
+   * 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?: Uint8Array;
+
+  constructor({ id, cohort, pendingTx, prevOutScripts, prevOutValues }: SigningSessionParams) {
+    this.id = id || crypto.randomUUID();
+    this.cohort = cohort;
+    this.pendingTx = pendingTx;
+    this.prevOutScripts = prevOutScripts || [];
+    this.prevOutValues = prevOutValues || [];
+    this.phase = SigningSessionPhase.AwaitingNonceContributions;
+  }
+
+  /**
+   * Computes the Taproot sighash (BIP-341) for the first input.
+   */
+  get sigHash(): Uint8Array {
+    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,
+      SigHash.DEFAULT,
+      this.prevOutValues
+    );
+  }
+
+  public addNonceContribution(participantDid: string, nonceContribution: Uint8Array): void {
+    if(this.phase !== SigningSessionPhase.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 = SigningSessionPhase.NonceContributionsReceived;
+    }
+  }
+
+  public generateAggregatedNonce(): Uint8Array {
+    if(this.phase !== SigningSessionPhase.NonceContributionsReceived) {
+      throw new SigningSessionError(
+        `Cannot aggregate nonces: phase is ${this.phase}, expected NonceContributionsReceived.`,
+        'INVALID_PHASE'
+      );
+    }
+    this.aggregatedNonce = musig2.nonceAggregate([...this.nonceContributions.values()]);
+    this.phase = SigningSessionPhase.AwaitingPartialSignatures;
+    return this.aggregatedNonce;
+  }
+
+  public addPartialSignature(participantDid: string, partialSig: Uint8Array): void {
+    if(this.phase !== SigningSessionPhase.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 = SigningSessionPhase.PartialSignaturesReceived;
+    }
+  }
+
+  public generateFinalSignature(): Uint8Array {
+    if(this.phase !== SigningSessionPhase.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]
+    );
+
+    // 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;
+  }
+
+  /**
+   * Generates a fresh MuSig2 nonce contribution for the participant.
+   * Stores the secret nonce internally for use in `generatePartialSignature()`.
+   */
+  public generateNonceContribution(participantPublicKey: Uint8Array, participantSecretKey: Uint8Array): Uint8Array {
+    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.
+   */
+  public generatePartialSignature(participantSecretKey: Uint8Array): Uint8Array {
+    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.
+   */
+  public clearSecrets(): void {
+    if(this.#secretNonce) {
+      wipe(this.#secretNonce);
+      this.#secretNonce = undefined;
+    }
+  }
+
+  public isComplete(): boolean {
+    return this.phase === SigningSessionPhase.Complete;
+  }
+
+  public isFailed(): boolean {
+    return this.phase === SigningSessionPhase.Failed;
+  }
+}

package/src/transport/didcomm.ts

@@ -0,0 +1,59 @@
+import { NotImplementedError } from '@did-btcr2/common';
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import type { BaseMessage } from '../messages/base.js';
+import type { MessageHandler, Transport } from './transport.js';
+
+/**
+ * DIDComm Transport (stub).
+ *
+ * @class DidCommTransport
+ * @implements {Transport}
+ */
+export class DidCommTransport implements Transport {
+  public name: string = 'didcomm';
+
+  public start(): void {
+    throw new NotImplementedError('DidCommTransport not implemented. Use NostrTransport instead.');
+  }
+
+  public registerActor(_did: string, _keys: SchnorrKeyPair): void {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public getActorPk(_did: string): Uint8Array | undefined {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public registerPeer(_did: string, _communicationPk: Uint8Array): void {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public getPeerPk(_did: string): Uint8Array | undefined {
+    throw new NotImplementedError('DidCommTransport not implemented.');
+  }
+
+  public registerMessageHandler(_actorDid: string, _messageType: string, _handler: MessageHandler): void {
+    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/transport/error.ts

@@ -0,0 +1,13 @@
+import { MethodError } from '@did-btcr2/common';
+
+export class TransportError extends MethodError {
+  constructor(message: string, type: string = 'TransportError', data?: Record<string, any>) {
+    super(message, type, data);
+  }
+}
+
+export class TransportAdapterError extends MethodError {
+  constructor(message: string, type: string = 'TransportAdapterError', data?: Record<string, any>) {
+    super(message, type, data);
+  }
+}

package/src/transport/factory.ts

@@ -0,0 +1,65 @@
+import { NotImplementedError } from '@did-btcr2/common';
+import type { Logger } from '../logger.js';
+import { TransportError } from './error.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 NostrTransportConfigOption {
+  type: 'nostr';
+  relays?: string[];
+  logger?: Logger;
+  broadcastLookbackMs?: number;
+}
+
+export interface DidCommTransportConfigOption {
+  type: 'didcomm';
+}
+
+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) {
+      case 'nostr':
+        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 as { type: string }).type}`,
+          'INVALID_TRANSPORT_TYPE',
+          { config },
+        );
+    }
+  }
+}