feat(wasm-utxo): implement MuSig2 nonce generation

- Add FirstRound HashMap storage to WASM BitGoPsbt struct
- Add generate_musig2_nonces WASM method with security checks
- Add generateMusig2Nonces() TypeScript method
- Add to_xpriv() method to WasmBIP32 for internal use
- Create walletKeys.util.ts test helper
- Create musig2Nonces.ts test file with comprehensive test cases
- Security: Custom session IDs only allowed on testnets

Issue: BTC-2786

Author: OttoAllmendinger

packages/wasm-utxo/js/fixedScriptWallet/BitGoPsbt.ts

@@ -179,6 +179,48 @@ export class BitGoPsbt {
     return this.wasm.serialize();
   }
 
+  /**
+   * Generate and store MuSig2 nonces for all MuSig2 inputs
+   *
+   * This method generates nonces using the State-Machine API and stores them in the PSBT.
+   * The nonces are stored as proprietary fields in the PSBT and will be included when serialized.
+   * After ALL participants have generated their nonces, you can sign MuSig2 inputs using
+   * sign().
+   *
+   * @param key - The extended private key (xpriv) for signing. Can be a base58 string, BIP32 instance, or WasmBIP32
+   * @param sessionId - Optional 32-byte session ID for nonce generation. **Only allowed on testnets**.
+   *                    On mainnets, a secure random session ID is always generated automatically.
+   *                    Must be unique per signing session.
+   * @throws Error if nonce generation fails, sessionId length is invalid, or custom sessionId is
+   *         provided on a mainnet (security restriction)
+   *
+   * @security The sessionId MUST be cryptographically random and unique for each signing session.
+   * Never reuse a sessionId with the same key! On mainnets, sessionId is always randomly
+   * generated for security. Custom sessionId is only allowed on testnets for testing purposes.
+   *
+   * @example
+   * ```typescript
+   * // Phase 1: Both parties generate nonces (with auto-generated session ID)
+   * psbt.generateMusig2Nonces(userXpriv);
+   * // Nonces are stored in the PSBT
+   * // Send PSBT to counterparty
+   *
+   * // Phase 2: After receiving counterparty PSBT with their nonces
+   * psbt.combine(counterpartyPsbtBytes);
+   * // Sign MuSig2 key path inputs
+   * const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, replayProtection);
+   * for (let i = 0; i < parsed.inputs.length; i++) {
+   *   if (parsed.inputs[i].scriptType === "p2trMusig2KeyPath") {
+   *     psbt.sign(i, userXpriv);
+   *   }
+   * }
+   * ```
+   */
+  generateMusig2Nonces(key: BIP32Arg, sessionId?: Uint8Array): void {
+    const wasmKey = BIP32.from(key);
+    this.wasm.generate_musig2_nonces(wasmKey.wasm, sessionId);
+  }
+
   /**
    * Finalize all inputs in the PSBT
    *

packages/wasm-utxo/src/wasm/bip32.rs

@@ -334,4 +334,12 @@ impl WasmBIP32 {
     pub(crate) fn to_xpub(&self) -> Result<crate::bitcoin::bip32::Xpub, WasmUtxoError> {
         Ok(self.0.to_xpub())
     }
+
+    /// Convert to Xpriv (for internal Rust use, not exposed to JS)
+    pub(crate) fn to_xpriv(&self) -> Result<crate::bitcoin::bip32::Xpriv, WasmUtxoError> {
+        match &self.0 {
+            BIP32Key::Private(xpriv) => Ok(*xpriv),
+            BIP32Key::Public(_) => Err(WasmUtxoError::new("Cannot get xpriv from public key")),
+        }
+    }
 }

packages/wasm-utxo/src/wasm/fixed_script_wallet.rs

@@ -1,3 +1,4 @@
+use std::collections::HashMap;
 use wasm_bindgen::prelude::*;
 use wasm_bindgen::JsValue;
 
@@ -83,6 +84,9 @@ impl FixedScriptWalletNamespace {
 #[wasm_bindgen]
 pub struct BitGoPsbt {
     psbt: crate::fixed_script_wallet::bitgo_psbt::BitGoPsbt,
+    // Store FirstRound states per (input_index, xpub_string)
+    #[wasm_bindgen(skip)]
+    first_rounds: HashMap<(usize, String), musig2::FirstRound>,
 }
 
 #[wasm_bindgen]
@@ -95,7 +99,10 @@ impl BitGoPsbt {
             crate::fixed_script_wallet::bitgo_psbt::BitGoPsbt::deserialize(bytes, network)
                 .map_err(|e| WasmUtxoError::new(&format!("Failed to deserialize PSBT: {}", e)))?;
 
-        Ok(BitGoPsbt { psbt })
+        Ok(BitGoPsbt {
+            psbt,
+            first_rounds: HashMap::new(),
+        })
     }
 
     /// Get the unsigned transaction ID
@@ -262,6 +269,108 @@ impl BitGoPsbt {
             .map_err(|e| WasmUtxoError::new(&format!("Failed to serialize PSBT: {}", e)))
     }
 
+    /// Generate and store MuSig2 nonces for all MuSig2 inputs
+    ///
+    /// This method generates nonces using the State-Machine API and stores them in the PSBT.
+    /// The nonces are stored as proprietary fields in the PSBT and will be included when serialized.
+    /// After ALL participants have generated their nonces, they can sign MuSig2 inputs using
+    /// sign_with_xpriv().
+    ///
+    /// # Arguments
+    /// * `xpriv` - The extended private key (xpriv) for signing
+    /// * `session_id_bytes` - Optional 32-byte session ID for nonce generation. **Only allowed on testnets**.
+    ///                        On mainnets, a secure random session ID is always generated automatically.
+    ///                        Must be unique per signing session.
+    ///
+    /// # Returns
+    /// Ok(()) if nonces were successfully generated and stored
+    ///
+    /// # Errors
+    /// Returns error if:
+    /// - Nonce generation fails
+    /// - session_id length is invalid
+    /// - Custom session_id is provided on a mainnet (security restriction)
+    ///
+    /// # Security
+    /// The session_id MUST be cryptographically random and unique for each signing session.
+    /// Never reuse a session_id with the same key! On mainnets, session_id is always randomly
+    /// generated for security. Custom session_id is only allowed on testnets for testing purposes.
+    pub fn generate_musig2_nonces(
+        &mut self,
+        xpriv: &WasmBIP32,
+        session_id_bytes: Option<Vec<u8>>,
+    ) -> Result<(), WasmUtxoError> {
+        // Extract Xpriv from WasmBIP32
+        let xpriv = xpriv.to_xpriv()?;
+
+        // Get the network from the PSBT to check if custom session_id is allowed
+        let network = self.psbt.network();
+
+        // Get or generate session ID
+        let session_id = match session_id_bytes {
+            Some(bytes) => {
+                // Only allow custom session_id on testnets for security
+                if !network.is_testnet() {
+                    return Err(WasmUtxoError::new(
+                        "Custom session_id is only allowed on testnets. On mainnets, session_id is always randomly generated for security."
+                    ));
+                }
+                if bytes.len() != 32 {
+                    return Err(WasmUtxoError::new(&format!(
+                        "Session ID must be 32 bytes, got {}",
+                        bytes.len()
+                    )));
+                }
+                let mut session_id = [0u8; 32];
+                session_id.copy_from_slice(&bytes);
+                session_id
+            }
+            None => {
+                // Generate secure random session ID
+                use getrandom::getrandom;
+                let mut session_id = [0u8; 32];
+                getrandom(&mut session_id).map_err(|e| {
+                    WasmUtxoError::new(&format!("Failed to generate random session ID: {}", e))
+                })?;
+                session_id
+            }
+        };
+
+        // Derive xpub from xpriv to use as key
+        let secp = miniscript::bitcoin::secp256k1::Secp256k1::new();
+        let xpub = miniscript::bitcoin::bip32::Xpub::from_priv(&secp, &xpriv);
+        let xpub_str = xpub.to_string();
+
+        // Iterate over all inputs and generate nonces for MuSig2 inputs
+        let input_count = self.psbt.psbt().unsigned_tx.input.len();
+        for input_index in 0..input_count {
+            // Check if this input is a MuSig2 input
+            let psbt = self.psbt.psbt();
+            if !crate::fixed_script_wallet::bitgo_psbt::p2tr_musig2_input::Musig2Input::is_musig2_input(&psbt.inputs[input_index]) {
+                continue;
+            }
+
+            // Generate nonce and get the FirstRound
+            // The nonce is automatically stored in the PSBT
+            let (first_round, _pub_nonce) = self
+                .psbt
+                .generate_nonce_first_round(input_index, &xpriv, session_id)
+                .map_err(|e| {
+                    WasmUtxoError::new(&format!(
+                        "Failed to generate nonce for input {}: {}",
+                        input_index, e
+                    ))
+                })?;
+
+            // Store the FirstRound for later use in signing
+            // Use (input_index, xpub) as key so multiple parties can store their FirstRounds
+            self.first_rounds
+                .insert((input_index, xpub_str.clone()), first_round);
+        }
+
+        Ok(())
+    }
+
     /// Finalize all inputs in the PSBT
     ///
     /// This method attempts to finalize all inputs in the PSBT, computing the final

packages/wasm-utxo/test/fixedScript/musig2Nonces.ts

@@ -0,0 +1,56 @@
+import assert from "assert";
+import { BitGoPsbt } from "../../js/fixedScriptWallet/index.js";
+import { BIP32 } from "../../js/bip32.js";
+import {
+  loadPsbtFixture,
+  getBitGoPsbt,
+  type Fixture,
+} from "./fixtureUtil.js";
+
+describe("MuSig2 nonce management", function () {
+  describe("Bitcoin mainnet", function () {
+    const networkName = "bitcoin";
+    let fixture: Fixture;
+    let unsignedBitgoPsbt: BitGoPsbt;
+    let userKey: BIP32;
+
+    before(function () {
+      fixture = loadPsbtFixture(networkName, "unsigned");
+      unsignedBitgoPsbt = getBitGoPsbt(fixture, networkName);
+      userKey = BIP32.fromBase58(fixture.walletKeys[0]);
+    });
+
+    it("should generate nonces for MuSig2 inputs with auto-generated session ID", function () {
+      // Generate nonces with auto-generated session ID (no second parameter)
+      assert.doesNotThrow(() => {
+        unsignedBitgoPsbt.generateMusig2Nonces(userKey);
+      });
+
+      // Verify nonces were stored by serializing and deserializing
+      const serialized = unsignedBitgoPsbt.serialize();
+      assert.ok(serialized.length > getBitGoPsbt(fixture, networkName).serialize().length);
+    });
+
+    it("should reject invalid session ID length", function () {
+      // Invalid session ID (wrong length)
+      const invalidSessionId = new Uint8Array(16); // Should be 32 bytes
+
+      assert.throws(() => {
+        unsignedBitgoPsbt.generateMusig2Nonces(userKey, invalidSessionId);
+      }, "Should throw error for invalid session ID length");
+    });
+
+    it("should reject custom session ID on mainnet (security)", function () {
+      // Custom session ID should be rejected on mainnet for security
+      const customSessionId = new Uint8Array(32).fill(1);
+
+      assert.throws(
+        () => {
+          unsignedBitgoPsbt.generateMusig2Nonces(userKey, customSessionId);
+        },
+        /Custom session_id is only allowed on testnets/,
+        "Should throw error when providing custom session_id on mainnet",
+      );
+    });
+  });
+});

packages/wasm-utxo/test/fixedScript/walletKeys.util.ts

@@ -0,0 +1,26 @@
+import * as utxolib from "@bitgo/utxo-lib";
+import type { Triple } from "../../js/triple.js";
+
+/**
+ * Convert utxolib BIP32 keys to WASM wallet keys format (Triple<string>)
+ */
+export function toWasmWalletKeys(
+  keys: [utxolib.BIP32Interface, utxolib.BIP32Interface, utxolib.BIP32Interface],
+): Triple<string> {
+  return [
+    keys[0].neutered().toBase58(),
+    keys[1].neutered().toBase58(),
+    keys[2].neutered().toBase58(),
+  ];
+}
+
+/**
+ * Get standard replay protection configuration
+ */
+export function getStandardReplayProtection(): { outputScripts: Uint8Array[] } {
+  const replayProtectionScript = Buffer.from(
+    "a91420b37094d82a513451ff0ccd9db23aba05bc5ef387",
+    "hex",
+  );
+  return { outputScripts: [replayProtectionScript] };
+}