@did-btcr2/method 0.34.0 → 0.36.0

package/src/core/aggregation/participant.ts

@@ -1,13 +1,14 @@
 import { canonicalHash } from '@did-btcr2/common';
 import type { SignedBTCR2Update } from '@did-btcr2/cryptosuite';
-import type { SchnorrKeyPair } from '@did-btcr2/keypair';
 import type { SerializedSMTProof} from '@did-btcr2/smt';
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
 import { Transaction } from '@scure/btc-signer';
 import { getBeaconStrategy } from './beacon-strategy.js';
 import { AggregationCohort } from './cohort.js';
+import type { CohortConditions } from './conditions.js';
 import { AggregationParticipantError } from './errors.js';
 import type { BaseMessage } from './messages/base.js';
+import { isCohortAdvertMessage } from './messages/bodies.js';
 import { AGGREGATION_WIRE_VERSION } from './messages/base.js';
 import {
   AGGREGATED_NONCE,
@@ -26,15 +27,18 @@ import {
 } from './messages/factories.js';
 import type { ParticipantCohortPhaseType } from './phases.js';
 import { ParticipantCohortPhase } from './phases.js';
+import type { AggregationSigner } from './signer.js';
 import { BeaconSigningSession } from './signing-session.js';
 
-/** Cohort advert as discovered by the participant (UI: list of joinable cohorts). */
-export interface CohortAdvert {
+/**
+ * Cohort advert as discovered by the participant (UI: list of joinable cohorts).
+ * Carries the advertised {@link CohortConditions} (beaconType, minParticipants,
+ * maxParticipants, costs, ...) so a `shouldJoin` decision can inspect them.
+ */
+export interface CohortAdvert extends CohortConditions {
   cohortId: string;
   serviceDid: string;
-  cohortSize: number;
   network: string;
-  beaconType: string;
   serviceCommunicationPk: Uint8Array;
 }
 
@@ -82,7 +86,12 @@ interface ParticipantCohortState {
 
 export interface AggregationParticipantParams {
   did: string;
-  keys: SchnorrKeyPair;
+  /**
+   * The participant's MuSig2 signing capability. The raw secret is materialized
+   * only for the duration of a single nonce/partial-sign operation (see ADR 038);
+   * pass a {@link KeyPairAggregationSigner} to back it with an in-memory keypair.
+   */
+  signer: AggregationSigner;
 }
 
 /**
@@ -97,14 +106,21 @@ export interface AggregationParticipantParams {
  */
 export class AggregationParticipant {
   public readonly did: string;
-  public readonly keys: SchnorrKeyPair;
+
+  /** MuSig2 signing capability. The raw secret never lives as a field here. */
+  readonly #signer: AggregationSigner;
 
   /** Per-cohort state, keyed by cohortId. */
   #cohortStates: Map<string, ParticipantCohortState> = new Map();
 
-  constructor({ did, keys }: AggregationParticipantParams) {
+  constructor({ did, signer }: AggregationParticipantParams) {
     this.did = did;
-    this.keys = keys;
+    this.#signer = signer;
+  }
+
+  /** The participant's compressed (33-byte) MuSig2 public key. Not secret. */
+  public get publicKey(): Uint8Array {
+    return this.#signer.publicKey;
   }
 
 
@@ -156,17 +172,18 @@ export class AggregationParticipant {
   }
 
   #handleCohortAdvert(message: BaseMessage): void {
-    const cohortId = message.body?.cohortId;
-    if(!cohortId) return;
+    // Validate the wire shape (incl. minParticipants range) before trusting it,
+    // rather than reading fields with `?? 0` fallbacks (see ADR 039).
+    if(!isCohortAdvertMessage(message)) return;
+    const { cohortId, network, communicationPk, ...conditions } = message.body;
     if(this.#cohortStates.has(cohortId)) return;  // Already known
 
     const advert: CohortAdvert = {
       cohortId,
       serviceDid             : message.from,
-      cohortSize             : message.body?.cohortSize ?? 0,
-      network                : message.body?.network ?? '',
-      beaconType             : message.body?.beaconType ?? 'CASBeacon',
-      serviceCommunicationPk : message.body?.communicationPk ?? new Uint8Array(),
+      network,
+      serviceCommunicationPk : communicationPk,
+      ...conditions,
     };
 
     this.#cohortStates.set(cohortId, {
@@ -194,7 +211,7 @@ export class AggregationParticipant {
     const cohort = new AggregationCohort({
       id              : cohortId,
       serviceDid      : state.serviceDid,
-      minParticipants : state.advert!.cohortSize,
+      minParticipants : state.advert!.minParticipants,
       network         : state.advert!.network,
       beaconType      : state.advert!.beaconType,
     });
@@ -205,8 +222,8 @@ export class AggregationParticipant {
       from            : this.did,
       to              : state.serviceDid,
       cohortId,
-      participantPk   : this.keys.publicKey.compressed,
-      communicationPk : this.keys.publicKey.compressed,
+      participantPk   : this.publicKey,
+      communicationPk : this.publicKey,
     });
 
     return [optInMessage];
@@ -245,7 +262,7 @@ export class AggregationParticipant {
     const cohortKeys = message.body?.cohortKeys;
     if(!beaconAddress || !cohortKeys) return;
 
-    const participantPkHex = bytesToHex(this.keys.publicKey.compressed);
+    const participantPkHex = bytesToHex(this.publicKey);
     const cohortKeysHex = cohortKeys.map(k => bytesToHex(new Uint8Array(k)));
 
     state.cohort.validateMembership(participantPkHex, cohortKeysHex, beaconAddress);
@@ -435,9 +452,8 @@ export class AggregationParticipant {
     });
     state.signingSession = session;
 
-    const nonceContribution = session.generateNonceContribution(
-      this.keys.publicKey.compressed,
-      this.keys.secretKey.bytes
+    const nonceContribution = this.#signer.withSecret(
+      secretKey => session.generateNonceContribution(this.publicKey, secretKey)
     );
 
     state.phase = ParticipantCohortPhase.NonceSent;
@@ -485,7 +501,10 @@ export class AggregationParticipant {
       );
     }
 
-    const partialSig = state.signingSession.generatePartialSignature(this.keys.secretKey.bytes);
+    const signingSession = state.signingSession;
+    const partialSig = this.#signer.withSecret(
+      secretKey => signingSession.generatePartialSignature(secretKey)
+    );
     state.phase = ParticipantCohortPhase.Complete;
 
     return [createSignatureAuthorizationMessage({
@@ -501,4 +520,16 @@ export class AggregationParticipant {
   public getCohortPhase(cohortId: string): ParticipantCohortPhaseType | undefined {
     return this.#cohortStates.get(cohortId)?.phase;
   }
+
+  /**
+   * Zeroize any retained MuSig2 secret nonces across all cohorts. The raw
+   * signing key is never held here (it lives behind the {@link AggregationSigner}
+   * and is wiped per-operation), but an abandoned signing session can still hold
+   * a secret nonce; call this on teardown to clear it deterministically.
+   */
+  public clearSecrets(): void {
+    for(const state of this.#cohortStates.values()) {
+      state.signingSession?.clearSecrets();
+    }
+  }
 }

package/src/core/aggregation/runner/participant-runner.ts

@@ -18,6 +18,7 @@ import {
   AggregationParticipant
 } from '../participant.js';
 import { ParticipantCohortPhase } from '../phases.js';
+import { KeyPairAggregationSigner } from '../signer.js';
 import type { Transport } from '../transport/transport.js';
 import type { AggregationParticipantEvents } from './events.js';
 import { TypedEventEmitter } from './typed-emitter.js';
@@ -129,7 +130,10 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
     this.#onValidateData = options.onValidateData ?? (async (info) => ({ approved: info.matches }));
     this.#onApproveSigning = options.onApproveSigning ?? (async () => ({ approved: true }));
 
-    this.session = new AggregationParticipant({ did: options.did, keys: options.keys });
+    this.session = new AggregationParticipant({
+      did    : options.did,
+      signer : new KeyPairAggregationSigner(options.keys),
+    });
   }
 
   /**
@@ -144,6 +148,10 @@ export class AggregationParticipantRunner extends TypedEventEmitter<AggregationP
   stop(): void {
     this.#stopped = true;
     this.#unregisterHandlers();
+    // Deterministically wipe any secret nonce left on an abandoned signing
+    // session. The signing key itself lives behind the AggregationSigner and is
+    // never retained here.
+    this.session.clearSecrets();
   }
 
   /** Message types this runner listens for on the transport. */

package/src/core/aggregation/runner/service-runner.ts

@@ -184,8 +184,11 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
     this.#advertRepeatIntervalMs = options.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
 
     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,
-      keys               : options.keys,
+      publicKey          : options.keys.publicKey,
       maxUpdateSizeBytes : options.maxUpdateSizeBytes,
     });
   }
@@ -380,6 +383,15 @@ export class AggregationServiceRunner extends TypedEventEmitter<AggregationServi
       const decision = await this.#onOptInReceived(optIn);
       if(!decision.accepted) return;
 
+      // Don't accept past the advertised maxParticipants: acceptParticipant
+      // would throw COHORT_FULL and fail the run. Silently ignore the surplus
+      // opt-in (the cohort is full).
+      const maxParticipants = this.#config.maxParticipants;
+      const cohortNow = this.session.getCohort(this.#cohortId!);
+      if(maxParticipants !== undefined && cohortNow && cohortNow.participants.length >= maxParticipants) {
+        return;
+      }
+
       await this.#sendAll(this.session.acceptParticipant(this.#cohortId!, msg.from));
       this.emit('participant-accepted', { participantDid: msg.from });
 

package/src/core/aggregation/service.ts

@@ -1,11 +1,12 @@
 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 type { CompressedSecp256k1PublicKey } from '@did-btcr2/keypair';
 import { bytesToHex } from '@noble/hashes/utils';
 import type { Transaction } from '@scure/btc-signer';
 import { getBeaconStrategy } from './beacon-strategy.js';
 import { AggregationCohort } from './cohort.js';
+import { validateCohortConditions, type CohortConditions } from './conditions.js';
 import { AggregationServiceError } from './errors.js';
 import type { BaseMessage } from './messages/base.js';
 import { AGGREGATION_WIRE_VERSION } from './messages/base.js';
@@ -28,11 +29,14 @@ import type { ServiceCohortPhaseType } from './phases.js';
 import { ServiceCohortPhase } from './phases.js';
 import { BeaconSigningSession } from './signing-session.js';
 
-/** Cohort configuration set by the service operator. */
-export interface CohortConfig {
-  minParticipants: number;
+/**
+ * Cohort configuration set by the service operator: the advertised cohort
+ * {@link CohortConditions} plus the Bitcoin network. `beaconType` and
+ * `minParticipants` are required; the other conditions are optional (absent =
+ * unconstrained). See ADR 039.
+ */
+export interface CohortConfig extends CohortConditions {
   network: string;
-  beaconType: string;
 }
 
 /** Pending opt-in awaiting service operator approval. */
@@ -100,7 +104,13 @@ export const DEFAULT_MAX_UPDATE_SIZE_BYTES = 256 * 1024;
 
 export interface AggregationServiceParams {
   did: string;
-  keys: SchnorrKeyPair;
+  /**
+   * The service's compressed communication public key (placed in cohort adverts).
+   * The coordinator never signs - it aggregates public nonces and partial
+   * signatures - so it is given a public key only, never a secret-bearing
+   * keypair (see ADR 038).
+   */
+  publicKey: CompressedSecp256k1PublicKey;
   /**
    * Maximum canonicalized byte-length of a signed update body accepted by the
    * service. Submissions above this cap are silently dropped and surfaced as
@@ -122,15 +132,15 @@ export interface AggregationServiceParams {
  */
 export class AggregationService {
   readonly did: string;
-  readonly keys: SchnorrKeyPair;
+  readonly publicKey: CompressedSecp256k1PublicKey;
   readonly maxUpdateSizeBytes: number;
 
   /** Per-cohort state, keyed by cohortId. */
   #cohortStates: Map<string, ServiceCohortState> = new Map();
 
-  constructor({ did, keys, maxUpdateSizeBytes }: AggregationServiceParams) {
+  constructor({ did, publicKey, maxUpdateSizeBytes }: AggregationServiceParams) {
     this.did = did;
-    this.keys = keys;
+    this.publicKey = publicKey;
     this.maxUpdateSizeBytes = maxUpdateSizeBytes ?? DEFAULT_MAX_UPDATE_SIZE_BYTES;
   }
 
@@ -195,6 +205,14 @@ export class AggregationService {
    * Cohort starts in `Created` phase — call `advertise()` to broadcast.
    */
   createCohort(config: CohortConfig): string {
+    // Fail fast on invalid conditions rather than discovering them at finalize.
+    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,
@@ -228,13 +246,15 @@ export class AggregationService {
       );
     }
 
+    // Advertise the full condition set (flat fields, per ADR 039). network is
+    // a separate cohort parameter; everything else in config is a condition.
+    const { network, ...conditions } = state.config;
     const message = createCohortAdvertMessage({
       from            : this.did,
       cohortId,
-      cohortSize      : state.config.minParticipants,
-      beaconType      : state.config.beaconType,
-      network         : state.config.network,
-      communicationPk : this.keys.publicKey.compressed,
+      network,
+      communicationPk : this.publicKey.compressed,
+      ...conditions,
     });
 
     state.phase = ServiceCohortPhase.Advertised;
@@ -304,6 +324,15 @@ export class AggregationService {
         'ALREADY_ACCEPTED', { cohortId, participantDid }
       );
     }
+    // Enforce the maxParticipants condition: a cohort cannot grow past its
+    // advertised ceiling (closes the unbounded-growth path; see ADR 039).
+    const maxParticipants = state.config.maxParticipants;
+    if(maxParticipants !== undefined && 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);
@@ -338,6 +367,15 @@ export class AggregationService {
         'NOT_ENOUGH_PARTICIPANTS', { cohortId }
       );
     }
+    // Ceiling defense: acceptParticipant already rejects past max, so reaching
+    // here over max means state was mutated out-of-band.
+    const maxParticipants = state.config.maxParticipants;
+    if(maxParticipants !== undefined && 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 = ServiceCohortPhase.CohortSet;

package/src/core/aggregation/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/core/aggregation/signing-session.ts

@@ -1,3 +1,4 @@
+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';
@@ -58,8 +59,14 @@ export class BeaconSigningSession {
   /** Current signing session phase. */
   public phase: SigningSessionPhaseType;
 
-  /** Participant's secret nonce (held only by the participant during signing). */
-  public secretNonce?: Uint8Array;
+  /**
+   * 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();
@@ -225,7 +232,7 @@ export class BeaconSigningSession {
   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;
+    this.#secretNonce = nonces.secret;
     return nonces.public;
   }
 
@@ -233,15 +240,17 @@ 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.
+   * 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) {
+    if(!this.#secretNonce) {
       throw new SigningSessionError('Secret nonce not available — generateNonceContribution() must be called first.', 'MISSING_SECRET_NONCE');
     }
     const session = new musig2.Session(
@@ -251,10 +260,24 @@ export class BeaconSigningSession {
       [this.cohort.tapTweak],
       [true]
     );
-    const partialSig = session.sign(this.secretNonce, participantSecretKey);
-    this.secretNonce.fill(0);
-    this.secretNonce = undefined;
-    return partialSig;
+    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 {

package/src/core/aggregation/transport/in-memory.ts

@@ -5,7 +5,8 @@ import type { MessageHandler, Transport } from './transport.js';
 
 /** Internal registration for a single actor sharing an {@link InMemoryTransport}. */
 interface ActorEntry {
-  keys: SchnorrKeyPair;
+  /** Compressed communication public key. The in-process bus does no encryption, so no secret is retained. */
+  publicKey: Uint8Array;
   handlers: Map<string, MessageHandler>;
 }
 
@@ -97,11 +98,14 @@ export class InMemoryTransport implements Transport {
   }
 
   registerActor(did: string, keys: SchnorrKeyPair): void {
-    this.#actors.set(did, { keys, handlers: new Map() });
+    // In-process delivery does no signing or encryption (same trust domain), so
+    // retain only the public key - the secret-bearing keypair is never stored in
+    // the transport registry (see ADR 038).
+    this.#actors.set(did, { publicKey: keys.publicKey.compressed, handlers: new Map() });
   }
 
   getActorPk(did: string): Uint8Array | undefined {
-    return this.#actors.get(did)?.keys.publicKey.compressed;
+    return this.#actors.get(did)?.publicKey;
   }
 
   /** True if `did` is registered on this transport. Used by the bus for routing. */

package/src/index.ts

@@ -1,6 +1,8 @@
 // Aggregation
 export * from './core/aggregation/service.js';
 export * from './core/aggregation/participant.js';
+export * from './core/aggregation/signer.js';
+export * from './core/aggregation/conditions.js';
 export * from './core/aggregation/cohort.js';
 export * from './core/aggregation/signing-session.js';
 export * from './core/aggregation/phases.js';