@did-btcr2/aggregation 0.1.0

package/dist/esm/service.js

@@ -0,0 +1,774 @@
+import { canonicalize } from '@did-btcr2/common';
+import { BIP340Cryptosuite, SchnorrMultikey } from '@did-btcr2/cryptosuite';
+import { schnorr } from '@noble/curves/secp256k1.js';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { getBeaconStrategy } from './beacon-strategy.js';
+import { AggregationCohort } from './cohort.js';
+import { validateCohortConditions } from './conditions.js';
+import { AggregationServiceError } from './errors.js';
+import { buildFallbackSpend, fallbackSighash } from './fallback-spend.js';
+import { buildFallbackLeaf } from './recovery-policy.js';
+import { AGGREGATION_WIRE_VERSION } from './messages/base.js';
+import { COHORT_OPT_IN, FALLBACK_SIGNATURE, NONCE_CONTRIBUTION, SIGNATURE_AUTHORIZATION, SUBMIT_NONINCLUDED, SUBMIT_UPDATE, VALIDATION_ACK, } from './messages/constants.js';
+import { createAggregatedNonceMessage, createAuthorizationRequestMessage, createCohortAdvertMessage, createCohortOptInAcceptMessage, createCohortReadyMessage, createDistributeAggregatedDataMessage, createFallbackAuthorizationRequestMessage, } from './messages/factories.js';
+import { ServiceCohortPhase } from './phases.js';
+import { BeaconSigningSession } from './signing-session.js';
+/** Default maximum canonicalized byte-length of a submitted BTCR2 update. */
+export const DEFAULT_MAX_UPDATE_SIZE_BYTES = 256 * 1024;
+/**
+ * Sans-I/O state machine for an Aggregation Service.
+ *
+ * Manages multiple cohorts simultaneously. The service operator drives the
+ * state machine via `receive()` (for incoming messages) and explicit action
+ * methods (advertising, accepting opt-ins, finalizing keygen, building
+ * aggregated data, starting signing). All outgoing messages are returned for
+ * the caller to send via whatever transport.
+ *
+ * @class AggregationService
+ */
+export class AggregationService {
+    did;
+    publicKey;
+    maxUpdateSizeBytes;
+    /** Per-cohort state, keyed by cohortId. */
+    #cohortStates = new Map();
+    constructor({ did, publicKey, maxUpdateSizeBytes }) {
+        this.did = did;
+        this.publicKey = publicKey;
+        this.maxUpdateSizeBytes = maxUpdateSizeBytes ?? DEFAULT_MAX_UPDATE_SIZE_BYTES;
+    }
+    receive(message) {
+        // 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:
+                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:
+                // Unknown message type - silently ignore
+                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) {
+        // 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,
+            network: config.network,
+            beaconType: config.beaconType,
+            recoveryKey: hexToBytes(config.recoveryKey),
+            recoverySequence: config.recoverySequence,
+            fundingModel: config.fundingModel,
+            fallbackThreshold: config.fallbackThreshold,
+        });
+        this.#cohortStates.set(cohort.id, {
+            phase: ServiceCohortPhase.Created,
+            cohort,
+            config,
+            pendingOptIns: new Map(),
+            acceptedParticipants: 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 !== ServiceCohortPhase.Created) {
+            throw new AggregationServiceError(`Cannot advertise cohort ${cohortId}: phase is ${state.phase}.`, 'INVALID_PHASE', { cohortId, phase: state.phase });
+        }
+        // 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,
+            network,
+            communicationPk: this.publicKey.compressed,
+            ...conditions,
+        });
+        state.phase = ServiceCohortPhase.Advertised;
+        return [message];
+    }
+    /** Pending opt-ins awaiting operator approval. */
+    pendingOptIns(cohortId) {
+        const state = this.#cohortStates.get(cohortId);
+        if (!state)
+            return new Map();
+        // Return only those not yet accepted
+        const map = 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 !== ServiceCohortPhase.Advertised)
+            return;
+        const participantDid = message.from;
+        const participantPk = message.body?.participantPk;
+        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,
+            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 });
+        }
+        // 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);
+        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 !== ServiceCohortPhase.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 });
+        }
+        // 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;
+        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 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 !== ServiceCohortPhase.CohortSet && state.phase !== ServiceCohortPhase.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;
+        }
+        // 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).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;
+        }
+        // One response per round. A member that already declined cannot also submit,
+        // and a member that already submitted cannot resubmit (a silent overwrite
+        // would corrupt the aggregated data the member already validated against).
+        // Both are dropped as rejections, symmetric with #handleSubmitNonInclusion.
+        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 === ServiceCohortPhase.CohortSet) {
+            state.phase = ServiceCohortPhase.CollectingUpdates;
+        }
+        if (state.cohort.hasAllResponses()) {
+            state.phase = ServiceCohortPhase.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 !== ServiceCohortPhase.CohortSet && state.phase !== ServiceCohortPhase.CollectingUpdates)
+            return;
+        // Membership is proven by the signed envelope sender. A non-member decline is
+        // dropped as a rejection, never thrown: addNonInclusion would otherwise throw
+        // UNKNOWN_PARTICIPANT out of receive() and fail the whole cohort, a DoS any
+        // non-member could trigger. Mirrors the SUBMIT_UPDATE verification path.
+        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;
+        }
+        // One response per round: already submitted or already declined. Surface the
+        // conflict as a rejection, symmetric with the double-submit guard above.
+        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 === ServiceCohortPhase.CohortSet) {
+            state.phase = ServiceCohortPhase.CollectingUpdates;
+        }
+        if (state.cohort.hasAllResponses()) {
+            state.phase = ServiceCohortPhase.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 {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, sender, signedUpdate) {
+        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,
+            });
+            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
+     * 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 !== ServiceCohortPhase.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 = bytesToHex(state.cohort.signalBytes);
+        state.phase = ServiceCohortPhase.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: new Set(), rejected: new Set(), pending: new Set(), total: 0 };
+        }
+        const approved = state.cohort.validationAcks;
+        const rejected = state.cohort.validationRejections;
+        const allParticipants = new Set(state.cohort.participants);
+        const responded = 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 !== ServiceCohortPhase.DataDistributed)
+            return;
+        const approved = message.body?.approved;
+        if (approved === undefined)
+            return;
+        state.cohort.addValidation(message.from, approved);
+        // Transition to Validated only when all participants approved.
+        // Transition to Failed when all responses are in but at least one rejected.
+        if (state.cohort.isFullyValidated()) {
+            state.phase = ServiceCohortPhase.Validated;
+        }
+        else if (state.cohort.hasAllValidationResponses()) {
+            state.phase = ServiceCohortPhase.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 !== ServiceCohortPhase.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 = 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 = [];
+        for (const participantDid of state.cohort.participants) {
+            messages.push(createAuthorizationRequestMessage({
+                from: this.did,
+                to: participantDid,
+                cohortId,
+                sessionId: session.id,
+                pendingTx: txData.tx.hex,
+                prevOutScriptHex: 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 !== ServiceCohortPhase.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 = ServiceCohortPhase.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 !== ServiceCohortPhase.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 = ServiceCohortPhase.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 !== ServiceCohortPhase.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) {
+            // All partial sigs received - generate final signature
+            const signature = state.signingSession.generateFinalSignature();
+            // Set Taproot key-path witness (finalScriptWitness injects the aggregated MuSig2 sig)
+            state.signingSession.pendingTx.updateInput(0, { finalScriptWitness: [signature] });
+            state.result = {
+                cohortId,
+                signature,
+                signedTx: state.signingSession.pendingTx,
+                path: 'key-path',
+            };
+            state.phase = ServiceCohortPhase.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 = [
+            ServiceCohortPhase.SigningStarted,
+            ServiceCohortPhase.NoncesCollected,
+            ServiceCohortPhase.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 === undefined) {
+            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 = new Map();
+        state.phase = ServiceCohortPhase.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: bytesToHex(prevOutScript),
+                prevOutValue: prevOutValue.toString(),
+                fallbackLeafScriptHex: 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 !== ServiceCohortPhase.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 === undefined)
+            return;
+        // Authenticate the signature to the sender: signerPk must be the sender's own
+        // cohort key (x-only). A non-member or a mismatched key is dropped as a
+        // rejection, never thrown, so one bad contribution cannot stall the fallback.
+        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 && 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 = ServiceCohortPhase.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);
+    }
+}
+//# sourceMappingURL=service.js.map