@scure/btc-signer 2.2.0 → 2.4.0

package/src/_type_test.ts

@@ -0,0 +1,83 @@
+import { secp256k1 as secp } from '@noble/curves/secp256k1.js';
+import { hex } from '@scure/base';
+import * as btc from './index.ts';
+import type { TxOpts, Unknowns } from './index.ts';
+import type { TArg } from './utils.ts';
+
+const unknownPolicy: Unknowns = 'strip';
+const extensionOpts: TxOpts = { unknown: unknownPolicy, proprietary: 'strict' };
+new btc.Transaction(extensionOpts);
+
+declare const combineOpts: TArg<TxOpts>;
+btc.PSBTCombine([], combineOpts);
+declare const first: btc.Transaction;
+declare const second: btc.Transaction;
+// Direct combination retains main's receiver-options API; byte-only PSBTCombine owns policy opts.
+// @ts-expect-error Transaction.combine does not accept operation-specific options.
+first.combine(second, combineOpts);
+
+const privKey1 = hex.decode('0101010101010101010101010101010101010101010101010101010101010101');
+const P1 = secp.getPublicKey(privKey1, true);
+
+const wpkh = btc.p2wpkh(P1);
+
+const tx = new btc.Transaction();
+
+// Basic input test
+tx.addInput({
+  txid: hex.decode('0af50a00a22f74ece24c12cd667c290d3a35d48124a69f4082700589172a3aa2'),
+  index: 0,
+  ...wpkh,
+  finalScriptSig: Uint8Array.of(),
+  sequence: 1,
+});
+
+// Doesn't force any fields on input addition (only on sign)
+tx.addInput({
+  sequence: 1,
+});
+
+tx.updateInput(0, {
+  sequence: 1,
+});
+
+const nonWitnessUtxo =
+  '0200000001aad73931018bd25f84ae400b68848be09db706eac2ac18298babee71ab656f8b0000000048473044022058f6fc7c6a33e1b31548d481c826c015bd30135aad42cd67790dab66d2ad243b02204a1ced2604c6735b6393e5b41691dd78b00f0c5942fb9f751856faa938157dba01feffffff0280f0fa020000000017a9140fb9463421696b82c833af241c78c17ddbde493487d0f20a270100000017a91429ca74f8a08f81999428185c97b5d852e4063f618765000000';
+const nonWitnessUtxoB = hex.decode(nonWitnessUtxo);
+
+tx.updateInput(0, { nonWitnessUtxo: nonWitnessUtxo });
+tx.updateInput(0, { nonWitnessUtxo: nonWitnessUtxoB });
+tx.addInput({
+  txid: hex.decode('0af50a00a22f74ece24c12cd667c290d3a35d48124a69f4082700589172a3aa2'),
+  index: 0,
+  nonWitnessUtxo: nonWitnessUtxo,
+});
+
+tx.addInput({
+  txid: hex.decode('0af50a00a22f74ece24c12cd667c290d3a35d48124a69f4082700589172a3aa2'),
+  index: 0,
+  nonWitnessUtxo: nonWitnessUtxoB,
+});
+
+// Should fail!
+// tx.updateInput(0, {
+//   nonWitnessUtxo: 1,
+// });
+// Outputs
+tx.addOutput({ amount: BigInt(123) });
+// should fail
+// tx.updateOutput(0, { amount: '1' });
+// tx.updateOutput(0, { amount: 1 });
+// should fail
+// tx.addOutput({ amount: '123' });
+// tx.addOutput({ amount: 123 });
+
+for (let i = 0; i < tx.inputsLength; i++) {
+  // @ts-ignore
+  console.log('I', tx.getInput(i));
+}
+
+for (let i = 0; i < tx.outputsLength; i++) {
+  // @ts-ignore
+  console.log('O', tx.getOutput(i));
+}

package/src/index.ts

@@ -25,9 +25,10 @@ export {
 } from './script.ts';
 export type { ScriptType } from './script.ts';
 export { getInputType, Transaction } from './transaction.ts';
-export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK } from './utils.ts';
+export type { TxOpts, Unknowns } from './transaction.ts';
+export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK, taprootNumsKey } from './utils.ts';
 export type { TArg, TRet } from './utils.ts';
-export { selectUTXO } from './utxo.ts';
+export { filterTaproot, selectUTXO } from './utxo.ts';
 
 /**
  * Small collection of commonly used utility exports.
@@ -62,6 +63,7 @@ export {
   Address,
   combinations,
   getAddress,
+  MAX_COMBINATIONS,
   OutScript,
   sortedMultisig,
   taprootListToTree,

package/src/musig2.ts

@@ -1,8 +1,9 @@
 import { schnorr, secp256k1 } from '@noble/curves/secp256k1.js';
+import type { WeierstrassPoint } from '@noble/curves/abstract/weierstrass.js';
 import { aInRange, concatBytes, equalBytes, numberToBytesBE } from '@noble/curves/utils.js';
 import { abytes, anumber, randomBytes } from '@noble/hashes/utils.js';
 import * as P from 'micro-packed';
-import { compareBytes, hasEven, type TArg, type TRet } from './utils.ts';
+import { compareBytes, hasEven, type TArg, type TRet, validateObject } from './utils.ts';
 
 /*
 MuSig2. This is not the full protocol: only an implementation of primitives from BIP-327.
@@ -10,9 +11,16 @@ The implementation can be used to create own protocol,
 but you need to implement nonce/partial signatures exchange yourself.
 Someday BIP-373 will be more "implementable" and we can use this from PSBT.
 
+SECURITY: A secret nonce MUST be used for exactly one partial signature. Session.sign() zeroes
+only the Uint8Array instance passed to it; copies, serialized values, database records, and process
+snapshots are not erased. Reusing the same nonce scalars in distinct sessions can reveal the
+signer's secret key. Stateful integrations must keep one authoritative nonce record and atomically
+consume it before releasing a partial signature.
+
 Links:
 - https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki#user-content-Test_Vectors_and_Reference_Code
-- https://github.com/bitcoin/bips/blob/master/bip-0373.mediawiki (PSBT MUSIG2): very raw, no vectors, not implemented for now.
+- https://github.com/bitcoin/bips/blob/master/bip-0373.mediawiki (PSBT MuSig2): psbt.ts supports
+  its transport fields and vectors, but this module does not orchestrate the signing protocol.
 - https://github.com/bitcoin/bips/blob/master/bip-0327/reference.py
 */
 // Types
@@ -20,7 +28,10 @@ Links:
 export type Nonces = {
   /** Public nonce that gets shared with the other participants. */
   public: Uint8Array;
-  /** Secret nonce that stays local until partial signing finishes. */
+  /**
+   * Secret nonce that stays local until partial signing finishes. It MUST be consumed exactly once;
+   * never retain a copy that could be loaded for another signing session.
+   */
   secret: Uint8Array;
 };
 /**
@@ -33,6 +44,15 @@ export type DetNonce = {
   /** Partial signature produced after combining all participant data. */
   partialSig: Uint8Array;
 };
+/** MuSig2 key aggregation context used by signing sessions. */
+export type KeyAggregate = {
+  /** Aggregate public key before x-only export. */
+  aggPublicKey: WeierstrassPoint<bigint>;
+  /** Accumulated sign from x-only tweaks. */
+  gAcc: bigint;
+  /** Accumulated tweak scalar. */
+  tweakAcc: bigint;
+};
 /**
  * Represents an error indicating an invalid contribution from a signer.
  * This allows pointing out which participant is malicious and what specifically is wrong.
@@ -75,6 +95,9 @@ const PUBKEY_LEN = /* @__PURE__ */ (() => secp256k1.lengths.publicKey!)();
 // BIP327 uses bytes(33, 0) both as cbytes_ext(Point.ZERO) for infinity and as GetSecondKey's
 // "no second distinct key" sentinel, so this all-zero compressed slot is intentionally out-of-band.
 const ZERO = /* @__PURE__ */ new Uint8Array(PUBKEY_LEN); // Compressed zero point
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0), _1n = /* @__PURE__ */ BigInt(1);
 
 // Encoding
 // TODO: re-use in PSBT?
@@ -89,7 +112,7 @@ const compressed = /* @__PURE__ */ (() =>
 // nonzero scalars in [1, n); tweak scalars use different validation because 0 is allowed there.
 const scalar = /* @__PURE__ */ (() =>
   P.validate(P.U256BE, (n) => {
-    aInRange('n', n, 1n, Fn.ORDER);
+    aInRange('n', n, _1n, Fn.ORDER);
     return n;
   }))();
 // Shared for both per-signer pubnonce bytes and aggregate aggnonce bytes. Because it accepts
@@ -216,7 +239,7 @@ function keyAggCoeffInternal(
   // pk2 is the all-zero sentinel from GetSecondKey, so every real signer key still hashes.
   abytes(publicKey1, PUBKEY_LEN);
   abytes(publicKey2, PUBKEY_LEN);
-  if (equalBytes(publicKey1, publicKey2)) return 1n;
+  if (equalBytes(publicKey1, publicKey2)) return _1n;
   return taggedInt('KeyAgg coefficient', L, publicKey1);
 }
 
@@ -248,7 +271,7 @@ export function keyAggregate(
   publicKeys: TArg<Uint8Array[]>,
   tweaks: TArg<Uint8Array[]> = [],
   isXonly: boolean[] = []
-) {
+): KeyAggregate {
   // BIP327 KeyAgg inputs require `0 < u < 2^32`, and ApplyTweak consumes a one-for-one
   // list of boolean tweak modes; callers should enforce that public contract here.
   abytesArray(publicKeys, PUBKEY_LEN);
@@ -270,6 +293,10 @@ export function keyAggregate(
     }
     aggPublicKey = aggPublicKey.add(Pi.multiply(keyAggCoeffInternal(publicKeys[i], pk2, L)));
   }
+  // BIP327 KeyAggInternal: "Fail if is_infinite(Q)". Computationally unreachable for
+  // hash-derived coefficients, but the spec mandates the explicit check before tweaking.
+  if (isZero(aggPublicKey))
+    throw new Error('keyAggregate: aggregate public key cannot be infinity');
   let gAcc = Fn.ONE;
   let tweakAcc = Fn.ZERO;
   // Apply tweaks
@@ -302,6 +329,9 @@ export function keyAggregate(
  * ```
  */
 export function keyAggExport(ctx: ReturnType<typeof keyAggregate>): TRet<Uint8Array> {
+  validateObject(ctx as Record<string, any>, {}, {}, 'ctx');
+  if (!(ctx.aggPublicKey instanceof Point))
+    throw new TypeError('"ctx.aggPublicKey" expected point, got type=' + typeof ctx.aggPublicKey);
   // BIP327 GetXonlyPubkey returns xbytes(Q), so this is the 32-byte x-only aggregate key
   // instead of the 33-byte compressed SEC1 form.
   return pointToBytes(ctx.aggPublicKey) as TRet<Uint8Array>;
@@ -342,6 +372,12 @@ const nonceHash = (
 
 /**
  * Generates a nonce pair (public and secret) for MuSig2 signing.
+ *
+ * SECURITY: The returned secret nonce MUST be used for exactly one partial signature. Keep one
+ * authoritative copy and atomically consume it when calling {@link Session.sign}. That method
+ * zeroes only the exact `Uint8Array` passed to it; clones, serialized values, database records, and
+ * snapshots remain live. Reusing a secret nonce in distinct sessions can reveal the secret key.
+ *
  * @param publicKey - individual public key of the signer
  * @param secretKey - optional secret key, mixed in to blind the randomness source
  * @param aggPublicKey - aggregate public key of all signers
@@ -502,6 +538,7 @@ export class Session {
     tweaks: Uint8Array[] = [],
     isXonly: boolean[] = []
   ) {
+    abytes(aggNonce, 66);
     abytesArray(publicKeys, 33);
     abytesArray(tweaks, 32);
     aXonly(isXonly);
@@ -520,7 +557,10 @@ export class Session {
     this.gAcc = gAcc;
     this.tweakAcc = tweakAcc;
     this.b = taggedInt('MuSig/noncecoef', aggNonce, pointToBytes(aggPublicKey), msg);
-    const R = R1.add(R2.multiply(this.b));
+    // b and the nonce points are public session values, so the faster variable-time
+    // multiplication is safe here; it also matches the reference point_mul, which
+    // maps a (negligible-probability) zero coefficient to infinity instead of failing.
+    const R = R1.add(R2.multiplyUnsafe(this.b));
     this.R = isZero(R) ? Point.BASE : R;
     this.e = taggedInt('BIP0340/challenge', pointToBytes(this.R), pointToBytes(aggPublicKey), msg);
     this.tweaks = tweaks.map((t) => Uint8Array.from(t));
@@ -555,20 +595,28 @@ export class Session {
     // BIP327 PartialSigVerifyInternal: `Let s = int(psig); fail if s >= n`, so s=0 must stay
     // in the public verification equation and return false on mismatch instead of throwing.
     const { R1, R2 } = PubNonce.decode(publicNonce);
-    const Re_s_ = R1.add(R2.multiply(b));
+    // Verification only handles public data (nonces, pubkeys, hash-derived scalars),
+    // so the faster variable-time multiplications are safe here; they also match the
+    // reference point_mul, which maps zero scalars to infinity instead of failing.
+    const Re_s_ = R1.add(R2.multiplyUnsafe(b));
     const Re_s = hasEven(R.y) ? Re_s_ : Re_s_.negate();
     const P = Point.fromBytes(publicKey);
     const a = this.getSessionKeyAggCoeff(P);
-    const g = Fn.mul(evenScalar(Q, 1n), gAcc);
+    const g = Fn.mul(evenScalar(Q, _1n), gAcc);
     const left = Point.BASE.multiplyUnsafe(s);
-    const right = Re_s.add(P.multiply(Fn.mul(e, Fn.mul(a, g))));
+    const right = Re_s.add(P.multiplyUnsafe(Fn.mul(e, Fn.mul(a, g))));
     return left.equals(right);
   }
 
   /**
    * Generates a partial signature for a given message, secret nonce,
    * secret key, and session context.
-   * @param secretNonce - secret nonce for this signing session; it is zeroed after use
+   *
+   * SECURITY: `secretNonce` MUST be used exactly once. This method zeroes the first 64 bytes of the
+   * supplied array, including when later validation fails, but cannot erase copies or persisted
+   * representations. Reusing those nonce scalars in a distinct session can reveal the secret key.
+   *
+   * @param secretNonce - sole authoritative secret-nonce buffer for this signing session
    * @param secret - secret key of the signer
    * @param fastSign - if `true`, skip the self-verification pass
    * @returns The partial signature (Uint8Array).
@@ -587,7 +635,7 @@ export class Session {
     // Modifying input arguments is pretty bad.
     secretNonce.fill(0, 0, 64);
     if (!Fn.isValid(k1_)) throw new Error('wrong k1');
-    if (!Fn.isValid(k2_)) throw new Error('wrong k1');
+    if (!Fn.isValid(k2_)) throw new Error('wrong k2');
     const k1 = evenScalar(R, k1_);
     const k2 = evenScalar(R, k2_);
     const d_ = Fn.fromBytes(secret);
@@ -596,7 +644,7 @@ export class Session {
     const pk = P.toBytes(true);
     if (!equalBytes(pk, originalPk)) throw new Error('Public key does not match nonceGen argument');
     const a = this.getSessionKeyAggCoeff(P);
-    const g = evenScalar(Q, 1n);
+    const g = evenScalar(Q, _1n);
     const d = Fn.mul(g, Fn.mul(gAcc, d_));
     /// k1 + (b*k2) + (e*a*d)
     const s = Fn.add(k1, Fn.add(Fn.mul(b, k2), Fn.mul(e, Fn.mul(a, d))));
@@ -643,24 +691,28 @@ export class Session {
   }
   /**
    * Aggregates partial signatures from multiple signers into a single final signature.
-   * @param partialSigs - partial signatures from each signer
+   * @param partialSigs - exactly one positional partial signature per session participant
    * @returns The final aggregate signature (Uint8Array).
    * @throws If the input is invalid, such as wrong array sizes or malformed
    * signatures. {@link Error}
    */
   partialSigAgg(partialSigs: TArg<Uint8Array[]>): TRet<Uint8Array> {
     abytesArray(partialSigs, 32);
-    // BIP327 PartialSigAgg is defined for a non-empty psig_1..u list tied to this session_ctx;
-    // [] is not a valid aggregate-signature input even though the sum starts from zero.
-    if (partialSigs.length < 1) throw new RangeError('partialSigs.length must be >= 1');
+    // BIP327 PartialSigAgg consumes psig_1..u for the same u signers in session_ctx. Accepting
+    // fewer or more scalars would return a signature-shaped value for a different equation.
+    if (partialSigs.length !== this.publicKeys.length)
+      throw new RangeError(
+        `partialSigs.length=${partialSigs.length} must equal ` +
+          `participant count=${this.publicKeys.length}`
+      );
     const { Q, tweakAcc, R, e } = this;
-    let s = 0n;
+    let s = _0n;
     for (let i = 0; i < partialSigs.length; i++) {
       const si = Fn.fromBytes(partialSigs[i], true);
       if (!Fn.isValid(si)) throw new InvalidContributionErr(i, 'psig');
       s = Fn.add(s, si);
     }
-    const g = evenScalar(Q, 1n);
+    const g = evenScalar(Q, _1n);
     s = Fn.add(s, Fn.mul(e, Fn.mul(g, tweakAcc))); // s + e * g * tweakAcc
     return concatBytes(pointToBytes(R), Fn.toBytes(s)) as TRet<Uint8Array>;
   }