@scure/btc-signer 2.3.0 → 2.4.0

package/src/payment.ts

@@ -228,7 +228,7 @@ const OutTRNS: Coder<OptScript, OutTRNSType | undefined> = {
     // BIP342 "Using a k-of-k script for every combination" documents the shape
     // `<pubkey_1> CHECKSIGVERIFY ... <pubkey_n> CHECKSIG`; this matcher only
     // classifies that embedded-pubkey form, so bare CHECKSIG stays unknown.
-    if (!pubkeys.length) return;
+    if (!pubkeys.length || pubkeys.length > 999) return;
     return { type: 'tr_ns', pubkeys } as TRet<OutTRNSType | undefined>;
   },
   decode: (to: TArg<OutTRNSType>): TRet<OptScript> => {
@@ -393,16 +393,18 @@ export const OutScript: TRet<
         if (i.m <= 0 || n > 16 || i.m > n) throw new Error('OutScript/multisig: invalid params');
       }
       if (i.type === 'tr_ns' || i.type === 'tr_ms') {
+        const n = i.pubkeys.length;
+        // BIP342 keeps the 1,000-element stack limit. Both supported tapscript multisig forms
+        // start with n signatures and then push a pubkey, so n must stay at or below 999.
+        if (n > 999) throw new Error(`OutScript/${i.type}: invalid params`);
         for (const p of i.pubkeys)
           if (!isValidPubkey(p, u.PubT.schnorr))
             throw new Error(`OutScript/${i.type}: wrong pubkey`);
       }
       if (i.type === 'tr_ms') {
         const n = i.pubkeys.length;
-        // BIP 342 keeps the 1000-element stack limit. This CHECKSIG/CHECKSIGADD form
-        // momentarily has n witness items plus one pushed pubkey on the stack, so n must stay <= 999.
         anumber(i.m, 'm');
-        if (i.m <= 0 || n > 999 || i.m > n) throw new Error('OutScript/tr_ms: invalid params');
+        if (i.m <= 0 || i.m > n) throw new Error('OutScript/tr_ms: invalid params');
       }
       return i;
     })
@@ -426,6 +428,28 @@ export const OutScript: TRet<
 >;
 /** Type of the output-script coder. */
 export type OutScriptType = typeof OutScript;
+// Internal raw-aware boundary for actual scriptPubKeys and P2SH-nested witness programs. Generic
+// OutScript remains semantic because witnessScript and tapscript children may use the same opcodes
+// without claiming BIP141 witness-program framing.
+export const _WitnessOutScript: OutScriptType = /* @__PURE__ */ (() =>
+  Object.freeze(
+    P.wrap<P.UnwrapCoder<typeof _OutScript>>({
+      encodeStream: (w, value) => OutScript.encodeStream(w, value),
+      decodeStream: (r) => {
+        const raw = r.bytes(r.leftBytes);
+        const out = OutScript.decode(raw);
+        // Script.decode normalizes push opcodes, but BIP141 recognition requires the exact direct
+        // push. Reject only when this explicit outer-program boundary is selected by the caller.
+        if (
+          out &&
+          (out.type === 'p2a' || out.type === 'wpkh' || out.type === 'wsh' || out.type === 'tr') &&
+          !u.equalBytes(raw, OutScript.encode(out))
+        )
+          throw new Error('OutScript: non-canonical witness program');
+        return out;
+      },
+    })
+  ))() as OutScriptType;
 // TRet-wrapping OutScript changes decode() to the normalized descriptor surface, but the local
 // checkScript/Address caches still need an explicit alias that can carry the decode-side `undefined`.
 type AddressValue = NonNullable<ReturnType<OutScriptType['decode']>>;
@@ -470,7 +494,7 @@ export function checkScript(
   let hasWsh = false;
   let r: OutScriptValue = undefined;
   if (script) {
-    const s = OutScript.decode(script);
+    const s = _WitnessOutScript.decode(script);
     // BIP174 Data Signers Check For bullets: provided redeemScript must match
     // the scriptPubKey, and provided witnessScript must match the scriptPubKey
     // or redeemScript instead of being silently ignored as stray metadata.
@@ -481,7 +505,7 @@ export function checkScript(
       if (s.type !== 'sh') throw new Error('checkScript: redeemScript without P2SH');
       if (!u.equalBytes(s.hash, u.hash160(redeemScript)))
         throw new Error('checkScript: sh wrong redeemScript hash');
-      r = OutScript.decode(redeemScript) as OutScriptValue;
+      r = _WitnessOutScript.decode(redeemScript) as OutScriptValue;
       if (r?.type === 'tr' || r?.type === 'tr_ns' || r?.type === 'tr_ms')
         throw new Error(`checkScript: P2${r.type} cannot be wrapped in P2SH`);
       // Not sure if this unspendable, but we cannot represent this via PSBT
@@ -493,7 +517,7 @@ export function checkScript(
     }
   }
   if (redeemScript) {
-    if (r === undefined) r = OutScript.decode(redeemScript) as OutScriptValue;
+    if (r === undefined) r = _WitnessOutScript.decode(redeemScript) as OutScriptValue;
     if (r?.type === 'wsh') {
       hasWsh = true;
       if (witnessScript) checkWSH(r as TArg<OutWSHType>, witnessScript);
@@ -502,12 +526,21 @@ export function checkScript(
   if (witnessScript && !hasWsh) throw new Error('checkScript: witnessScript without P2WSH');
 }
 
-function uniqPubkey(pubkeys: TArg<Bytes[]>) {
+function uniqPubkey(pubkeys: TArg<Bytes[]>, type: u.PubT) {
   const map: Record<string, boolean> = {};
   for (const pub of pubkeys) {
-    // Exact-byte duplicate filter only: BIP383 valid vectors still permit the
-    // same point to appear in compressed and uncompressed SEC1 form in multi().
-    const key = hex.encode(pub);
+    u.validatePubkey(pub, type);
+    let normalized = pub;
+    if (type === u.PubT.ecdsa && pub.length === 65) {
+      // Compressed and uncompressed SEC1 encodings can represent the same curve point. Normalize
+      // valid uncompressed keys before comparing so one signer cannot occupy multiple threshold
+      // slots merely by changing the serialization. `allowSamePubkeys` remains the explicit
+      // compatibility escape hatch for callers that intentionally construct duplicate-key scripts.
+      normalized = new Uint8Array(33);
+      normalized[0] = 2 | (pub[64] & 1);
+      normalized.set(pub.subarray(1, 33), 1);
+    }
+    const key = hex.encode(normalized);
     if (map[key]) throw new Error(`Multisig: non-uniq pubkey: ${pubkeys.map(hex.encode)}`);
     map[key] = true;
   }
@@ -609,10 +642,30 @@ export type P2SHWithoutWitness = Omit<P2SHBase, 'witnessScript'>;
 export type P2SHReturn<T extends P2Ret> = T extends { witnessScript: Bytes }
   ? P2SHWithWitness
   : P2SHWithoutWitness;
+
+const checkCanonicalScript = (
+  script: TArg<Bytes>,
+  name: 'redeemScript' | 'witnessScript',
+  allowNonCanonicalScript: boolean
+): void => {
+  if (allowNonCanonicalScript) return;
+  const decoded = Script.decode(script);
+  const nonMinimalNumber = decoded.some(
+    (op) => u.isBytes(op) && op.length === 1 && ((1 <= op[0] && op[0] <= 16) || op[0] === 0x81)
+  );
+  // Core's default MINIMALDATA policy rejects these spends from its mempool, so address-producing
+  // helpers require an explicit opt-in even though the original bytes remain consensus-valid.
+  if (nonMinimalNumber || !u.equalBytes(script, Script.encode(decoded))) {
+    const wrapper = name === 'redeemScript' ? 'P2SH' : 'P2WSH';
+    throw new Error(`${wrapper}: non-canonical ${name}`);
+  }
+};
+
 /**
  * Wraps a child script inside P2SH.
  * @param child - child payment descriptor to wrap
  * @param network - address network parameters
+ * @param allowNonCanonicalScript - whether to create an address for a non-minimal child script
  * @returns P2SH descriptor preserving witness metadata when present.
  * @throws If the wrapped script combination is invalid or unsupported. {@link Error}
  * @example
@@ -625,7 +678,8 @@ export type P2SHReturn<T extends P2Ret> = T extends { witnessScript: Bytes }
  */
 export const p2sh = <T extends P2Ret>(
   child: TArg<T>,
-  network: BTC_NETWORK = NETWORK
+  network: BTC_NETWORK = NETWORK,
+  allowNonCanonicalScript = false
 ): TRet<Extends<P2SHReturn<T>, P2Ret>> => {
   u.validateObject(child as Record<string, any>, {}, {}, 'child');
   // It is already tested inside noble-hashes and checkScript
@@ -638,6 +692,7 @@ export const p2sh = <T extends P2Ret>(
     throw new Error(
       `P2SH: redeemScript exceeds ${MAX_SCRIPT_BYTE_LENGTH}-byte push limit: len=${cs.length}`
     );
+  checkCanonicalScript(cs, 'redeemScript', allowNonCanonicalScript);
   const hash = u.hash160(cs);
   const out = { type: 'sh', hash } as const;
   const script = OutScript.encode(out);
@@ -680,6 +735,7 @@ export type P2WSH = {
  * Wraps a child script inside native SegWit P2WSH.
  * @param child - child payment descriptor to wrap
  * @param network - address network parameters
+ * @param allowNonCanonicalScript - whether to create an address for a non-minimal child script
  * @returns P2WSH descriptor.
  * @throws If the wrapped script combination is invalid or unsupported. {@link Error}
  * @example
@@ -692,7 +748,8 @@ export type P2WSH = {
  */
 export const p2wsh = (
   child: TArg<P2Ret>,
-  network: BTC_NETWORK = NETWORK
+  network: BTC_NETWORK = NETWORK,
+  allowNonCanonicalScript = false
 ): TRet<Extends<P2WSH, P2Ret>> => {
   u.validateObject(child as Record<string, any>, {}, {}, 'child');
   const cs = child.script;
@@ -700,6 +757,7 @@ export const p2wsh = (
   // BIP141 P2WSH says the witness "must consist of ... a serialized script (witnessScript)"
   // and that witnessScript is limited to 10,000 bytes, so larger wrapped scripts must reject.
   if (cs.length > 10000) throw new Error('P2WSH: witnessScript exceeds 10,000 bytes');
+  checkCanonicalScript(cs, 'witnessScript', allowNonCanonicalScript);
   const hash = u.sha256(cs);
   const script = OutScript.encode({ type: 'wsh', hash });
   checkScript(script, undefined, cs);
@@ -782,7 +840,7 @@ export const p2ms = (
 ): TRet<Extends<P2MS, P2Ret>> => {
   // BIP 11 only standardized bare multisig up to 3 keys; this helper still permits up to 16
   // because the same script shape is commonly wrapped by p2sh()/p2wsh() instead of used bare.
-  if (!allowSamePubkeys) uniqPubkey(pubkeys);
+  if (!allowSamePubkeys) uniqPubkey(pubkeys, u.PubT.ecdsa);
   return {
     type: 'ms',
     script: OutScript.encode({ type: 'ms', pubkeys, m }),
@@ -826,7 +884,7 @@ function checkTaprootScript(
   const outms = out as OutTRNSType | OutTRMSType;
   if (!allowUnknownOutputs && outms.pubkeys) {
     for (const p of outms.pubkeys) {
-      if (u.equalBytes(p, u.TAPROOT_UNSPENDABLE_KEY))
+      if (u.equalBytes(p, u.taprootNumsKey()))
         throw new Error('Unspendable taproot key in leaf script');
       // It's likely a mistake at this point:
       // 1. p2tr(A, p2tr_ns(2, [A, B])) == p2tr(A, p2tr_pk(B)) (A or B key)
@@ -978,12 +1036,19 @@ function taprootWalkTree(tree: TArg<HashedTreeWithPath>): TRet<TaprootLeaf[]> {
   return [...taprootWalkTree(tree.left), ...taprootWalkTree(tree.right)] as TRet<TaprootLeaf[]>;
 }
 
+// BIP 341 control blocks can encode at most 128 sibling hashes.
+const TAPROOT_MAX_DEPTH = 128;
 function taprootHashTree(
   tree: TArg<TaprootScriptTree>,
   internalPubKey: TArg<Bytes>,
   allowUnknownOutputs = false,
-  customScripts?: TArg<CustomScript[]>
+  customScripts?: TArg<CustomScript[]>,
+  depth = 0
 ): TRet<HashedTree> {
+  // Reject before inspecting or descending into the next node, which also bounds the
+  // recursion used by the path annotation and tree-flattening passes below.
+  if (depth > TAPROOT_MAX_DEPTH)
+    throw new RangeError(`P2TR: tree depth exceeds ${TAPROOT_MAX_DEPTH}`);
   if (tree === undefined) throw new Error('taprootHashTree: empty tree');
   if (!Array.isArray(tree) && !P.utils.isPlainObject(tree))
     throw new TypeError('"tree" expected object or array, got type=' + typeof tree);
@@ -1013,8 +1078,20 @@ function taprootHashTree(
   if (tree.length !== 2) throw new Error('hashTree: non binary tree!');
   // branch
   // Both nodes should exist
-  const left = taprootHashTree(tree[0], internalPubKey, allowUnknownOutputs, customScripts);
-  const right = taprootHashTree(tree[1], internalPubKey, allowUnknownOutputs, customScripts);
+  const left = taprootHashTree(
+    tree[0],
+    internalPubKey,
+    allowUnknownOutputs,
+    customScripts,
+    depth + 1
+  );
+  const right = taprootHashTree(
+    tree[1],
+    internalPubKey,
+    allowUnknownOutputs,
+    customScripts,
+    depth + 1
+  );
   // BIP 341 sorts TapBranch child hashes lexicographically for hashing, but the original
   // left/right structure still determines the control-block sibling paths for each leaf.
   let [lH, rH] = [left.hash, right.hash];
@@ -1056,7 +1133,7 @@ export const tapLeafHash = (script: TArg<Bytes>, version: number = TAP_LEAF_VERS
 
 // Works as key OR tree.
 // If we only have tree, need to add unspendable key, otherwise
-// complex multisig wallet can be spent by owner of key only. See TAPROOT_UNSPENDABLE_KEY
+// complex multisig wallet can be spent by owner of key only. See taprootNumsKey
 /** Conditional taproot return type for key-only or tree-backed outputs. */
 export type P2TRRet<T> = T extends TaprootScriptTree ? P2TR_TREE : P2TR;
 /**
@@ -1068,6 +1145,7 @@ export type P2TRRet<T> = T extends TaprootScriptTree ? P2TR_TREE : P2TR;
  * @param customScripts - optional custom script codecs for taproot leaves
  * @returns Taproot descriptor with optional script-path metadata.
  * @throws If the internal key or taproot script tree is invalid. {@link Error}
+ * @throws If a numeric script value is outside its supported range. {@link RangeError}
  * @example
  * Combine script leaves into a final taproot output descriptor and address.
  * ```ts
@@ -1105,7 +1183,7 @@ export function p2tr(
   const pubKey =
     typeof internalPubKey === 'string'
       ? hex.decode(internalPubKey)
-      : internalPubKey || u.TAPROOT_UNSPENDABLE_KEY;
+      : (internalPubKey ?? u.taprootNumsKey());
   if (!isValidPubkey(pubKey, u.PubT.schnorr)) throw new Error('p2tr: non-schnorr pubkey');
   if (tree) {
     let hashedTree = taprootAddPath(
@@ -1156,25 +1234,47 @@ export function p2tr(
   }
 }
 
+/** Maximum number of combinations materialized by one default helper call. */
+export const MAX_COMBINATIONS = 4096;
+
+const combinationCount = (n: number, m: number): number => {
+  const k = Math.min(m, n - m);
+  let count = 1;
+  for (let i = 1; i <= k; i++) {
+    count = (count * (n - k + i)) / i;
+    if (!Number.isSafeInteger(count)) return Number.POSITIVE_INFINITY;
+  }
+  return count;
+};
+
 // Returns all combinations of size M from lst
 /**
  * Returns all size-`m` combinations from a list.
  * @param m - size of each combination
  * @param list - input items to combine
+ * @param maxCombinations - maximum result rows to materialize
  * @returns Array of combinations.
  * @throws If the combination size or input list is invalid. {@link Error}
+ * @throws If the requested result exceeds the materialization limit. {@link RangeError}
  * @example
  * Enumerate all size-two subsets of a short list.
  * ```ts
  * combinations(2, [1, 2, 3]);
  * ```
  */
-export function combinations<T>(m: number, list: T[]): T[][] {
+export function combinations<T>(m: number, list: T[], maxCombinations = MAX_COMBINATIONS): T[][] {
   const res: T[][] = [];
   if (!Array.isArray(list)) throw new Error('combinations: lst arg should be array');
   const n = list.length;
   anumber(m, 'm');
+  anumber(maxCombinations, 'maxCombinations');
   if (m < 1 || m > n) throw new Error('combinations: m must satisfy 1 <= m <= lst.length');
+  if (maxCombinations < 1) throw new Error('combinations: maxCombinations must be >= 1');
+  const count = combinationCount(n, m);
+  if (count > maxCombinations)
+    throw new RangeError(
+      `combinations: C(${n}, ${m}) exceeds materialization limit=${maxCombinations}`
+    );
   /*
   Basically works as M nested loops like:
   for (;idx[0]<lst.length;idx[0]++) for (idx[1]=idx[0]+1;idx[1]<lst.length;idx[1]++)
@@ -1204,8 +1304,8 @@ export function combinations<T>(m: number, list: T[]): T[][] {
 
 /**
  * M-of-N multi-leaf wallet via p2tr_ns. If m == n, single script is emitted.
- * Takes O(n^2) if m != n. 99-of-100 is ok, 5-of-100 is not.
- * It materializes C(n, m) leaves, so middle-of-the-range thresholds blow up combinatorially.
+ * It materializes C(n, m) leaves up to {@link MAX_COMBINATIONS}; middle-of-the-range thresholds
+ * above that bound are rejected before allocation.
  * `2-of-[A,B,C] => [A,B] | [A,C] | [B,C]`
  */
 export type P2TR_NS = {
@@ -1221,6 +1321,7 @@ export type P2TR_NS = {
  * @param allowSamePubkeys - whether duplicate keys are allowed
  * @returns Array of taproot leaf descriptors.
  * @throws If the taproot multisig parameters are invalid. {@link Error}
+ * @throws If the requested leaf set exceeds the materialization limit. {@link RangeError}
  * @example
  * Build the leaf set for an M-of-N taproot `CHECKSIGVERIFY` policy.
  * ```ts
@@ -1234,14 +1335,24 @@ export const p2tr_ns = (
   pubkeys: TArg<Bytes[]>,
   allowSamePubkeys = false
 ): TRet<Extends<P2TR_NS, P2Ret>[]> => {
-  if (!allowSamePubkeys) uniqPubkey(pubkeys);
-  return combinations(m, pubkeys).map(
-    (i) =>
-      ({
-        type: 'tr_ns',
-        script: OutScript.encode({ type: 'tr_ns', pubkeys: i }),
-      }) as const as TRet<Extends<P2TR_NS, P2Ret>>
-  ) as TRet<Extends<P2TR_NS, P2Ret>[]>;
+  anumber(m, 'm');
+  if (m > 999) throw new Error('OutScript/tr_ns: invalid params');
+  // Enforce the allocation bound before doing curve work on an attacker-controlled key list.
+  const keySets = combinations(m, pubkeys);
+  if (allowSamePubkeys) {
+    for (const pubkey of pubkeys) u.validatePubkey(pubkey, u.PubT.schnorr);
+  } else uniqPubkey(pubkeys, u.PubT.schnorr);
+  return keySets.map((keys) => {
+    // Keys were validated once above. Encoding through OutScript here would repeat lift_x for
+    // every key in every combination, turning a bounded leaf set into avoidable curve-level work.
+    const ops: ScriptType = [];
+    for (let i = 0; i < keys.length - 1; i++) ops.push(keys[i], 'CHECKSIGVERIFY');
+    ops.push(keys[keys.length - 1], 'CHECKSIG');
+    return {
+      type: 'tr_ns',
+      script: Script.encode(ops),
+    } as const as TRet<Extends<P2TR_NS, P2Ret>>;
+  }) as TRet<Extends<P2TR_NS, P2Ret>[]>;
 };
 // Taproot public key (case of p2tr_ns)
 /** Single-key taproot leaf descriptor. */
@@ -1253,6 +1364,7 @@ export type P2TR_PK = P2TR_NS;
  * @param pubkey - Schnorr public key
  * @returns Taproot single-key leaf descriptor.
  * @throws If the taproot single-key leaf cannot be encoded. {@link Error}
+ * @throws If the delegated leaf policy exceeds its supported range. {@link RangeError}
  * @example
  * Build a single-key tapscript leaf.
  * ```ts
@@ -1291,7 +1403,7 @@ export function p2tr_ms(
   pubkeys: TArg<Bytes[]>,
   allowSamePubkeys = false
 ): TRet<Extends<P2TR_MS, P2Ret>> {
-  if (!allowSamePubkeys) uniqPubkey(pubkeys);
+  if (!allowSamePubkeys) uniqPubkey(pubkeys, u.PubT.schnorr);
   return {
     type: 'tr_ms',
     script: OutScript.encode({ type: 'tr_ms', pubkeys, m }),
@@ -1306,6 +1418,7 @@ export function p2tr_ms(
  * @param network - address network parameters
  * @returns Encoded Bitcoin address.
  * @throws If the requested address type is unknown. {@link Error}
+ * @throws If a key-derived script value is outside its supported range. {@link RangeError}
  * @example
  * Pick the output type first, then derive the matching address from the private key.
  * ```ts