@did-btcr2/method 0.26.0 → 0.28.0

package/src/core/beacon/aggregation/session/index.ts

@@ -1,301 +0,0 @@
-import * as musig2 from '@scure/btc-signer/musig2';
-import { Transaction } from 'bitcoinjs-lib';
-import { AggregateBeaconError } from '../../error.js';
-import type { AggregateBeaconCohort } from '../cohort/index.js';
-import { BeaconCohortAuthorizationRequestMessage } from '../cohort/messages/sign/authorization-request.js';
-import type { SIGNING_SESSION_STATUS_TYPE } from './status.js';
-import { SIGNING_SESSION_STATUS } from './status.js';
-
-/**
- * Convert a big-endian byte array into a bigint.
- * @param bytes - The input Uint8Array representing a big-endian integer.
- * @returns The integer value as a bigint.
- */
-export function bigEndianToInt(bytes: Uint8Array): bigint {
-  return bytes.reduce((num, b) => (num << 8n) + BigInt(b), 0n);
-}
-
-/**
- * Convert a bigint to a big-endian Uint8Array of specified length.
- * @param xInit - The bigint to convert.
- * @param length - The desired length of the output array in bytes.
- * @returns A Uint8Array representing the bigint in big-endian form.
- */
-export function intToBigEndian(xInit: bigint, length: number): Uint8Array {
-  let x = xInit;
-  const result = new Uint8Array(length);
-  for (let i = length - 1; i >= 0; i--) {
-    result[i] = Number(x & 0xffn);
-    x >>= 8n;
-  }
-  return result;
-}
-
-type PublicKeyHex = string;
-type Nonce = Uint8Array;
-type NonceContributions = Map<PublicKeyHex, Nonce>;
-type PartialSignatures = Map<string, Uint8Array>;
-type ProcessedRequests = Record<string, string>;
-
-export interface SigningSession {
-  id?: string;
-  cohort: AggregateBeaconCohort;
-  pendingTx: Transaction;
-  nonceContributions?: NonceContributions;
-  aggregatedNonce?: Uint8Array;
-  partialSignatures?: PartialSignatures;
-  signature?: Uint8Array;
-  status?: SIGNING_SESSION_STATUS_TYPE;
-  processedRequests?: ProcessedRequests;
-  nonceSecrets?: bigint;
-}
-export class BeaconCohortSigningSession implements SigningSession {
-  /**
-   * Unique identifier for the signing session.
-   * @type {string}
-   */
-  public id: string;
-
-  /**
-   * DID of the coordinator.
-   * @type {AggregateBeaconCohort}
-   */
-  public cohort: AggregateBeaconCohort;
-
-  /**
-   * Pending transaction to be signed.
-   * @type {Transaction}
-   */
-  public pendingTx: Transaction;
-
-  /**
-   * Map of nonce contributions from participants.
-   * @type {Map<PublicKeyHex, Nonce>}
-   */
-  public nonceContributions: Map<PublicKeyHex, Nonce> = new Map();
-
-  /**
-   * Aggregated nonce from all participants.
-   * @type {Uint8Array}
-   */
-  public aggregatedNonce?: Uint8Array;
-
-  /**
-   * Map of partial signatures from participants.
-   * @type {Map<string, Uint8Array>}
-   */
-  public partialSignatures: Map<string, Uint8Array> = new Map();
-
-  /**
-   * Final signature for the transaction.
-   * @type {Uint8Array}
-   */
-  public signature?: Uint8Array;
-
-  /**
-   * Current status of the signing session.
-   * @type {SIGNING_SESSION_STATUS_TYPE}
-   */
-  public status: SIGNING_SESSION_STATUS_TYPE;
-
-  /**
-   * Map of processed requests from participants.
-   * @type {Record<string, string>}
-   */
-  public processedRequests: Record<string, string>;
-
-  /**
-   * Secrets for nonces contributed by participants.
-   * @type {Array<bigint>}
-   */
-  public nonceSecrets?: bigint;
-
-  /**
-   * Musig2 session for signing operations.
-   * @type {musig2.Session}
-   */
-  public musig2Session?: musig2.Session;
-
-  /**
-   * Creates a new instance of BeaconCohortSigningSession.
-   * @param {SigningSession} params Parameters to initialize the signing session.
-   * @param {Transaction} params.pendingTx The pending transaction to be signed.
-   * @param {string} [params.id] Optional unique identifier for the signing session. If not provided, a new UUID will be generated.
-   * @param {AggregateBeaconCohort} [params.cohort] The cohort associated with the signing session.
-   * @param {Record<string, string>} [params.processedRequests] Map of processed requests from participants.
-   * @param {SIGNING_SESSION_STATUS_TYPE} [params.status] The current status of the signing session. Defaults to AWAITING_NONCE_CONTRIBUTIONS.
-   */
-  constructor({ id, cohort, pendingTx, processedRequests, status }: SigningSession) {
-    this.id = id || crypto.randomUUID();
-    this.cohort = cohort;
-    this.pendingTx = pendingTx;
-    this.processedRequests = processedRequests || {};
-    this.status = status || SIGNING_SESSION_STATUS.AWAITING_NONCE_CONTRIBUTIONS;
-  }
-
-  /**
-   * Gets the authorization request message for a participant.
-   * @param {string} to The public key of the participant to whom the request is sent.
-   * @param {string} from The public key of the participant sending the request.
-   * @returns {AuthorizationRequest} The authorization request message.
-   */
-  public getAuthorizationRequest(to: string, from: string): BeaconCohortAuthorizationRequestMessage {
-    const txHex = this.pendingTx instanceof Transaction ? this.pendingTx?.toHex() : this.pendingTx;
-    return new BeaconCohortAuthorizationRequestMessage({
-      to,
-      from,
-      sessionId : this.id,
-      cohortId  : this.cohort?.id,
-      pendingTx : txHex,
-    });
-  }
-
-  /**
-   * Adds a nonce contribution from a participant to the session.
-   * @param {string} from The public key of the participant contributing the nonce.
-   * @param {Array<string>} nonceContribution The nonce contribution from the participant.
-   * @throws {Error} If the session is not awaiting nonce contributions or if the contribution is invalid.
-   */
-  public addNonceContribution(from: string, nonceContribution: Uint8Array): void {
-    if(this.status !== SIGNING_SESSION_STATUS.AWAITING_NONCE_CONTRIBUTIONS) {
-      throw new AggregateBeaconError(`Nonce contributions already received. Current status: ${this.status}`);
-    }
-
-    if(nonceContribution.length !== 2) {
-      throw new AggregateBeaconError(`Invalid nonce contribution. Expected 2 points, received ${nonceContribution.length}.`);
-    }
-
-    if (this.nonceContributions.get(from)) {
-      console.warn(`WARNING: Nonce contribution already received from ${from}.`);
-    }
-
-    this.nonceContributions.set(from, nonceContribution);
-
-    if(this.nonceContributions.size === this.cohort?.participants.length) {
-      this.status = SIGNING_SESSION_STATUS.NONCE_CONTRIBUTIONS_RECEIVED;
-    }
-  }
-
-  /**
-   * Generates the aggregated nonce from all nonce contributions for the session.
-   * @returns {Uint8Array} The aggregated nonce.
-   * @throws {AggregateBeaconError} If not all nonce contributions have been received.
-   */
-  public generateAggregatedNonce(): Uint8Array {
-    if(this.status !== SIGNING_SESSION_STATUS.NONCE_CONTRIBUTIONS_RECEIVED) {
-      const missing = this.cohort?.participants.length - this.nonceContributions.size;
-      throw new AggregateBeaconError(
-        `Missing ${missing} nonce contributions. ` +
-        `Received ${this.cohort?.participants.length} of ${this.nonceContributions.size} nonce contributions. ` +
-        `Current status: ${this.status}`,
-        'NONCE_CONTRIBUTION_ERROR', this.toJSON()
-      );
-    }
-    const sortedPubkeys = musig2.sortKeys(this.cohort.cohortKeys);
-    const keyAggContext = musig2.keyAggregate(sortedPubkeys);
-    const aggPubkey = musig2.keyAggExport(keyAggContext);
-    this.aggregatedNonce = musig2.nonceAggregate(this.cohort.cohortKeys.map(key => musig2.nonceGen(key, undefined, aggPubkey, this.cohort.trMerkleRoot).public));
-    this.musig2Session = new musig2.Session(this.aggregatedNonce, this.cohort.cohortKeys, this.cohort.trMerkleRoot);
-    return this.aggregatedNonce;
-  }
-
-  /**
-   * Adds a partial signature from a participant to the session.
-   * @param {string} from The public key of the participant contributing the partial signature.
-   * @param {Uint8Array} partialSignature The partial signature from the participant.
-   */
-  public addPartialSignature(from: string, partialSignature: Uint8Array): void {
-    if(this.status !== SIGNING_SESSION_STATUS.AWAITING_PARTIAL_SIGNATURES) {
-      throw new AggregateBeaconError(`Partial signatures not expected. Current status: ${this.status}`);
-    }
-
-    if(this.partialSignatures.get(from)) {
-      console.warn(`WARNING: Partial signature already received from ${from}.`);
-    }
-
-    this.partialSignatures.set(from, partialSignature);
-  }
-
-  /**
-   * Generates the final signature from all partial signatures.
-   * @returns {Uint8Array} The final aggregated signature.
-   */
-  public async generateFinalSignature(): Promise<Uint8Array> {
-    if(this.status !== SIGNING_SESSION_STATUS.PARTIAL_SIGNATURES_RECEIVED) {
-      throw new AggregateBeaconError(`Partial signatures not received. Current status: ${this.status}`);
-    }
-
-    const inputIdx = (this.pendingTx?.ins?.length || 0) - 1;
-    if (inputIdx < 0) {
-      throw new AggregateBeaconError('No inputs in the pending transaction to sign.');
-    }
-
-    const prevoutScript = this.pendingTx?.ins[inputIdx].script;
-    if (!prevoutScript) {
-      throw new AggregateBeaconError('Previous output script is missing for the input to sign.');
-    }
-
-    const sigSum = [...this.partialSignatures.values()].reduce((sum, sig) => sum + bigEndianToInt(sig), 0n);
-    console.info(`Aggregated Signature computed: ${sigSum}`);
-
-    this.aggregatedNonce ??= this.generateAggregatedNonce();
-
-    const session = new musig2.Session(this.aggregatedNonce!, this.cohort.cohortKeys, this.cohort.trMerkleRoot);
-    this.signature = session.partialSigAgg([...this.partialSignatures.values()]);
-
-    return this.signature;
-  }
-
-  /**
-   * Generates a partial signature for the session using the participant's secret key.
-   * @param {Uint8Array} participantSk The secret key of the participant.
-   * @returns {Uint8Array} The partial signature generated by the participant.
-   */
-  public generatePartialSignature(participantSk: Uint8Array): Uint8Array {
-    if (!this.aggregatedNonce) {
-      throw new AggregateBeaconError('Aggregated nonce is not available. Please generate it first.');
-    }
-    const sigHash = this.pendingTx?.hashForSignature(0, this.pendingTx?.ins[0].script, Transaction.SIGHASH_DEFAULT);
-    if(!sigHash) {
-      throw new AggregateBeaconError('Signature hash is not available. Please ensure the transaction is properly set up.');
-    }
-    const session = new musig2.Session(this.aggregatedNonce!, this.cohort.cohortKeys, this.cohort.trMerkleRoot);
-    return session.sign(this.aggregatedNonce, participantSk);
-  }
-
-  /**
-   * Converts the signing session instance to a JSON object representation.
-   * @returns {BeaconCohortSigningSession} The JSON object representation of the signing session.
-   */
-  public toJSON(): Partial<BeaconCohortSigningSession> {
-    return {
-      id                 : this.id,
-      cohort             : this.cohort,
-      pendingTx          : this.pendingTx,
-      nonceContributions : this.nonceContributions,
-      aggregatedNonce    : this.aggregatedNonce,
-      partialSignatures  : this.partialSignatures,
-      signature          : this.signature,
-      status             : this.status,
-      processedRequests  : this.processedRequests,
-      nonceSecrets       : this.nonceSecrets,
-      musig2Session      : this.musig2Session
-    };
-  }
-
-  /**
-   * Checks if the signing session is a completed state.
-   * @returns {boolean} True if the session is complete, false otherwise.
-   */
-  public isComplete(): boolean {
-    return this.status === SIGNING_SESSION_STATUS.SIGNATURE_COMPLETE;
-  }
-
-  /**
-   * Checks if the signing session is in a failed state.
-   * @returns {boolean} True if the session has failed, false otherwise.
-   */
-  public isFailed(): boolean {
-    return this.status === SIGNING_SESSION_STATUS.FAILED;
-  }
-}

package/src/core/beacon/aggregation/session/status.ts

@@ -1,18 +0,0 @@
-export type SIGNING_SESSION_STATUS_TYPE =
-    | 'AWAITING_NONCE_CONTRIBUTIONS'
-    | 'NONCE_CONTRIBUTION_SENT'
-    | 'NONCE_CONTRIBUTIONS_RECEIVED'
-    | 'AWAITING_PARTIAL_SIGNATURES'
-    | 'PARTIAL_SIGNATURES_RECEIVED'
-    | 'SIGNATURE_COMPLETE'
-    | 'FAILED'
-
-export enum SIGNING_SESSION_STATUS {
-    AWAITING_NONCE_CONTRIBUTIONS = 'AWAITING_NONCE_CONTRIBUTIONS',
-    NONCE_CONTRIBUTION_SENT = 'NONCE_CONTRIBUTION_SENT',
-    NONCE_CONTRIBUTIONS_RECEIVED = 'NONCE_CONTRIBUTIONS_RECEIVED',
-    AWAITING_PARTIAL_SIGNATURES = 'AWAITING_PARTIAL_SIGNATURES',
-    PARTIAL_SIGNATURES_RECEIVED = 'PARTIAL_SIGNATURES_RECEIVED',
-    SIGNATURE_COMPLETE = 'SIGNATURE_COMPLETE',
-    FAILED = 'FAILED',
-}

package/src/core/update.ts

@@ -1,158 +0,0 @@
-import type {
-  KeyBytes,
-  PatchOperation} from '@did-btcr2/common';
-import {
-  canonicalHash,
-  INVALID_DID_UPDATE,
-  JSONPatch,
-  UpdateError
-} from '@did-btcr2/common';
-import type {
-  DataIntegrityConfig,
-  SignedBTCR2Update,
-  UnsignedBTCR2Update
-} from '@did-btcr2/cryptosuite';
-import {
-  SchnorrMultikey
-} from '@did-btcr2/cryptosuite';
-import type { Btcr2DidDocument, DidVerificationMethod } from '../utils/did-document.js';
-import { DidDocument } from '../utils/did-document.js';
-import { BeaconFactory } from './beacon/factory.js';
-import type { BeaconService } from './beacon/interfaces.js';
-import type { BitcoinConnection } from '@did-btcr2/bitcoin';
-
-/**
- * Implements {@link https://dcdpr.github.io/did-btcr2/operations/update.html | 7.3 Update}.
- *
- * An update to a did:btcr2 document is an invoked capability using the ZCAP-LD
- * data format, signed by a verificationMethod that has the authority to make
- * the update as specified in the previous DID document. Capability invocations
- * for updates MUST be authorized using Data Integrity following the
- * bip340-jcs-2025 cryptosuite with a proofPurpose of capabilityInvocation.
- *
- * @class Update
- * @type {Update}
- */
-export class Update {
-  /**
-   * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-unsigned-update | 7.3.b Construct BTCR2 Unsigned Update}.
-   * This process constructs a BTCR2 Unsigned Update conformant to the spec template.
-   *
-   * @param {Btcr2DidDocument} sourceDocument The source DID document to be updated.
-   * @param {PatchOperation[]} patches The array of JSON Patch operations to apply to the sourceDocument.
-   * @param {number} sourceVersionId The version ID of the source document.
-   * @returns {UnsignedBTCR2Update} The constructed UnsignedBTCR2Update object.
-   * @throws {UpdateError} InvalidDid if sourceDocument.id does not match identifier.
-   */
-  static construct(
-    sourceDocument: Btcr2DidDocument,
-    patches: PatchOperation[],
-    sourceVersionId: number,
-  ): UnsignedBTCR2Update {
-    // Initialize an unsigned update conformant to btcr2 spec.
-    const unsignedUpdate: UnsignedBTCR2Update = {
-      '@context'      : [
-        'https://w3id.org/security/v2',
-        'https://w3id.org/zcap/v1',
-        'https://w3id.org/json-ld-patch/v1',
-        'https://btcr2.dev/context/v1'
-      ],
-      patch           : patches,
-      targetHash      : '',
-      targetVersionId : sourceVersionId + 1,
-      sourceHash      : canonicalHash(sourceDocument),
-    };
-
-    // Apply all JSON patches to sourceDocument.
-    const targetDocument = JSONPatch.apply(sourceDocument, patches);
-
-    try {
-      // Ensure the targetDocument is conformant to DID Core v1.1.
-      DidDocument.isValid(targetDocument);
-    } catch (error) {
-      // If validation fails, throw an UpdateError with INVALID_DID_UPDATE.
-      throw new UpdateError(
-        'Error validating targetDocument: ' + (error instanceof Error ? error.message : String(error)),
-        INVALID_DID_UPDATE, targetDocument
-      );
-    }
-
-    // Set the targetHash by canonicalizing the targetDocument and encoding it in base64url.
-    unsignedUpdate.targetHash = canonicalHash(targetDocument);
-
-    // Return unsignedUpdate.
-    return unsignedUpdate;
-  }
-
-  /**
-   * Implements subsection {@link http://dcdpr.github.io/did-btcr2/operations/update.html#construct-btcr2-signed-update | 7.3.c Construct BTCR2 Signed Update }.
-   * This process constructs a BTCR2 Signed Update from a BTCR2 Unsigned Update.
-   *
-   * @param {string} did The did-btcr2 identifier to derive the root capability from
-   * @param {UnsignedBTCR2Update} unsignedUpdate The updatePayload object to be signed
-   * @param {DidVerificationMethod} verificationMethod The verificationMethod object to be used for signing
-   * @returns {SignedBTCR2Update} Did update payload secured with a proof => SignedBTCR2Update
-   * @throws {UpdateError} if the privateKeyBytes are invalid
-   */
-  static sign(
-    did: string,
-    unsignedUpdate: UnsignedBTCR2Update,
-    verificationMethod: DidVerificationMethod,
-    secretKey: KeyBytes,
-  ): SignedBTCR2Update {
-    // Parse the controller from the verificationMethod
-    const controller = verificationMethod.controller;
-    // Parse the fragment from the vmId
-    const id = verificationMethod.id.slice(verificationMethod.id.indexOf('#'));
-
-    // Construct a Schnorr Multikey
-    const multikey = SchnorrMultikey.fromSecretKey(id, controller, secretKey);
-
-    // Define the Data Integrity proof config
-    const config: DataIntegrityConfig = {
-      '@context' : [
-        'https://w3id.org/security/v2',
-        'https://w3id.org/zcap/v1',
-        'https://w3id.org/json-ld-patch/v1',
-        'https://btcr2.dev/context/v1'
-      ],
-      cryptosuite        : 'bip340-jcs-2025',
-      type               : 'DataIntegrityProof',
-      verificationMethod : verificationMethod.id,
-      proofPurpose       : 'capabilityInvocation',
-      capability         : `urn:zcap:root:${encodeURIComponent(did)}`,
-      capabilityAction   : 'Write',
-    };
-
-    // Go from multikey => cryptosuite => diproof
-    const diproof = multikey.toCryptosuite().toDataIntegrityProof();
-
-    // Use the config to add a proof to the unsigned update
-    return diproof.addProof(unsignedUpdate, config);
-  }
-
-  /**
-   * Implements subsection {@link https://dcdpr.github.io/did-btcr2/operations/update.html#announce-did-update | 7.3.d Announce DID Update}.
-   * BTCR2 Signed Updates are announced to the Bitcoin blockchain depending on the Beacon Type.
-   * @param {BeaconService} beaconService The BeaconService object representing the funded beacon to announce the update to.
-   * @param {SignedBTCR2Update} update The signed update object to be announced.
-   * @param {KeyBytes} secretKey The private key used to sign the update for announcement.
-   * @returns {SignedBTCR2Update} The SignedBTCR2Update object containing data to validate the Beacon Signal
-   * @throws {UpdateError} if the beaconService type is invalid
-   */
-  static async announce(
-    beaconService: BeaconService,
-    update: SignedBTCR2Update,
-    secretKey: KeyBytes,
-    bitcoin: BitcoinConnection
-  ): Promise<SignedBTCR2Update> {
-    // Establish a beacon object
-    const beacon = BeaconFactory.establish(beaconService);
-
-    // Broadcast the update
-    const result = await beacon.broadcastSignal(update, secretKey, bitcoin);
-
-    // Return the sidecarData
-    return result;
-  }
-}