@sidhujag/sysweb3-keyring 1.0.545 → 1.0.547

package/src/ledger/bitcoin_client/index.ts

@@ -0,0 +1,19 @@
+/* eslint-disable import/no-named-as-default */
+import AppClient, { PartialSignature } from './lib/appClient';
+import {
+  DefaultDescriptorTemplate,
+  DefaultWalletPolicy,
+  WalletPolicy,
+} from './lib/policy';
+import { PsbtV2 } from './lib/psbtv2';
+
+export {
+  AppClient,
+  PsbtV2,
+  DefaultDescriptorTemplate,
+  DefaultWalletPolicy,
+  PartialSignature,
+  WalletPolicy,
+};
+
+export default AppClient;

package/src/ledger/bitcoin_client/lib/appClient.ts

@@ -0,0 +1,405 @@
+import Transport from '@ledgerhq/hw-transport';
+
+import { pathElementsToBuffer, pathStringToArray } from './bip32';
+import { ClientCommandInterpreter } from './clientCommands';
+import { MerkelizedPsbt } from './merkelizedPsbt';
+import { hashLeaf, Merkle } from './merkle';
+import { WalletPolicy } from './policy';
+import { PsbtV2 } from './psbtv2';
+import { createVarint, parseVarint } from './varint';
+
+const CLA_BTC = 0xe1;
+const CLA_FRAMEWORK = 0xf8;
+
+const CURRENT_PROTOCOL_VERSION = 1; // supported from version 2.1.0 of the app
+
+enum BitcoinIns {
+  GET_PUBKEY = 0x00,
+  REGISTER_WALLET = 0x02,
+  GET_WALLET_ADDRESS = 0x03,
+  SIGN_PSBT = 0x04,
+  GET_MASTER_FINGERPRINT = 0x05,
+  SIGN_MESSAGE = 0x10,
+}
+
+enum FrameworkIns {
+  CONTINUE_INTERRUPTED = 0x01,
+}
+
+/**
+ * This class represents a partial signature produced by the app during signing.
+ * It always contains the `signature` and the corresponding `pubkey` whose private key
+ * was used for signing; in the case of taproot script paths, it also contains the
+ * tapleaf hash.
+ */
+export class PartialSignature {
+  readonly pubkey: Buffer;
+  readonly signature: Buffer;
+  readonly tapleafHash?: Buffer;
+
+  constructor(pubkey: Buffer, signature: Buffer, tapleafHash?: Buffer) {
+    this.pubkey = pubkey;
+    this.signature = signature;
+    this.tapleafHash = tapleafHash;
+  }
+}
+
+/**
+ * Creates an instance of `PartialSignature` from the returned raw augmented pubkey and signature.
+ * @param pubkeyAugm the public key, concatenated with the tapleaf hash in the case of taproot script path spend.
+ * @param signature the signature
+ * @returns an instance of `PartialSignature`.
+ */
+function makePartialSignature(
+  pubkeyAugm: Buffer,
+  signature: Buffer
+): PartialSignature {
+  if (pubkeyAugm.length == 64) {
+    // tapscript spend: concatenation of 32-bytes x-only pubkey and 32-bytes tapleaf_hash
+    return new PartialSignature(
+      pubkeyAugm.slice(0, 32),
+      signature,
+      pubkeyAugm.slice(32, 64)
+    );
+  } else if (pubkeyAugm.length == 32 || pubkeyAugm.length == 33) {
+    // legacy, segwit or taproot keypath spend: pubkeyAugm is just the pubkey
+    return new PartialSignature(pubkeyAugm, signature);
+  } else {
+    throw new Error(
+      `Invalid length for pubkeyAugm: ${pubkeyAugm.length} bytes.`
+    );
+  }
+}
+
+/**
+ * This class encapsulates the APDU protocol documented at
+ * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/bitcoin.md
+ */
+export class AppClient {
+  readonly transport: Transport;
+
+  constructor(transport: Transport) {
+    this.transport = transport;
+  }
+
+  private async makeRequest(
+    ins: BitcoinIns,
+    data: Buffer,
+    cci?: ClientCommandInterpreter
+  ): Promise<Buffer> {
+    let response: Buffer = await this.transport.send(
+      CLA_BTC,
+      ins,
+      0,
+      CURRENT_PROTOCOL_VERSION,
+      data,
+      [0x9000, 0xe000]
+    );
+    while (response.readUInt16BE(response.length - 2) === 0xe000) {
+      if (!cci) {
+        throw new Error('Unexpected SW_INTERRUPTED_EXECUTION');
+      }
+
+      const hwRequest = response.slice(0, -2);
+      const commandResponse = cci.execute(hwRequest);
+
+      response = await this.transport.send(
+        CLA_FRAMEWORK,
+        FrameworkIns.CONTINUE_INTERRUPTED,
+        0,
+        0,
+        commandResponse,
+        [0x9000, 0xe000]
+      );
+    }
+    return response.slice(0, -2); // drop the status word (can only be 0x9000 at this point)
+  }
+
+  /**
+   * Returns an object containing the currently running app's name, version and the device status flags.
+   *
+   * @returns an object with app name, version and device status flags.
+   */
+  public async getAppAndVersion(): Promise<{
+    flags: number | Buffer;
+    name: string;
+    version: string;
+  }> {
+    const r = await this.transport.send(0xb0, 0x01, 0x00, 0x00);
+    let i = 0;
+    const format = r[i++];
+    if (format !== 1) throw new Error('Unexpected response');
+
+    const nameLength = r[i++];
+    const name = r.slice(i, (i += nameLength)).toString('ascii');
+    const versionLength = r[i++];
+    const version = r.slice(i, (i += versionLength)).toString('ascii');
+    const flagLength = r[i++];
+    const flags = r.slice(i, (i += flagLength));
+    return {
+      name,
+      version,
+      flags,
+    };
+  }
+
+  /**
+   * Requests the BIP-32 extended pubkey to the hardware wallet.
+   * If `display` is `false`, only standard paths will be accepted; an error is returned if an unusual path is
+   * requested.
+   * If `display` is `true`, the requested path is shown on screen for user verification; unusual paths can be
+   * requested, and a warning is shown to the user in that case.
+   *
+   * @param path the requested BIP-32 path as a string
+   * @param display `false` to silently retrieve a pubkey for a standard path, `true` to display the path on screen
+   * @returns the base58-encoded serialized extended pubkey (xpub)
+   */
+  async getExtendedPubkey(path: string, display = false): Promise<string> {
+    const pathElements = pathStringToArray(path);
+    if (pathElements.length > 6) {
+      throw new Error('Path too long. At most 6 levels allowed.');
+    }
+    const response = await this.makeRequest(
+      BitcoinIns.GET_PUBKEY,
+      Buffer.concat([
+        Buffer.from(display ? [1] : [0]),
+        pathElementsToBuffer(pathElements),
+      ])
+    );
+    return response.toString('ascii');
+  }
+
+  /**
+   * Registers a `WalletPolicy`, after interactive verification from the user.
+   * On success, after user's approval, this function returns the id (which is the same that can be computed with
+   * `walletPolicy.getid()`), followed by the 32-byte hmac. The client should store the hmac to use it for future
+   * requests to `getWalletAddress` or `signPsbt` using this `WalletPolicy`.
+   *
+   * @param walletPolicy the `WalletPolicy` to register
+   * @returns a pair of two 32-byte arrays: the id of the Wallet Policy, followed by the policy hmac
+   */
+  async registerWallet(
+    walletPolicy: WalletPolicy
+  ): Promise<readonly [Buffer, Buffer]> {
+    const clientInterpreter = new ClientCommandInterpreter();
+
+    clientInterpreter.addKnownWalletPolicy(walletPolicy);
+
+    const serializedWalletPolicy = walletPolicy.serialize();
+    const response = await this.makeRequest(
+      BitcoinIns.REGISTER_WALLET,
+      Buffer.concat([
+        createVarint(serializedWalletPolicy.length),
+        serializedWalletPolicy,
+      ]),
+      clientInterpreter
+    );
+
+    if (response.length != 64) {
+      throw Error(
+        `Invalid response length. Expected 64 bytes, got ${response.length}`
+      );
+    }
+    const walletId = response.subarray(0, 32);
+    const walletHMAC = response.subarray(32);
+
+    // Note: Address validation removed - trusting Ledger device for address generation
+
+    return [walletId, walletHMAC];
+  }
+
+  /**
+   * Returns the address of `walletPolicy` for the given `change` and `addressIndex`.
+   *
+   * @param walletPolicy the `WalletPolicy` to use
+   * @param walletHMAC the 32-byte hmac returned during wallet registration for a registered policy; otherwise
+   * `null` for a standard policy
+   * @param change `0` for a normal receive address, `1` for a change address
+   * @param addressIndex the address index to retrieve
+   * @param display `True` to show the address on screen, `False` to retrieve it silently
+   * @returns the address, as an ascii string.
+   */
+  async getWalletAddress(
+    walletPolicy: WalletPolicy,
+    walletHMAC: Buffer | null,
+    change: number,
+    addressIndex: number,
+    display: boolean
+  ): Promise<string> {
+    if (change !== 0 && change !== 1)
+      throw new Error('Change can only be 0 or 1');
+    if (addressIndex < 0 || !Number.isInteger(addressIndex))
+      throw new Error('Invalid address index');
+
+    if (walletHMAC != null && walletHMAC.length != 32) {
+      throw new Error('Invalid HMAC length');
+    }
+
+    const clientInterpreter = new ClientCommandInterpreter();
+    // Provide wallet policy artifacts to the interpreter
+    clientInterpreter.addKnownWalletPolicy(walletPolicy);
+
+    const addressIndexBuffer = Buffer.alloc(4);
+    addressIndexBuffer.writeUInt32BE(addressIndex, 0);
+
+    const response = await this.makeRequest(
+      BitcoinIns.GET_WALLET_ADDRESS,
+      Buffer.concat([
+        Buffer.from(display ? [1] : [0]),
+        walletPolicy.getId(),
+        walletHMAC || Buffer.alloc(32, 0),
+        Buffer.from([change]),
+        addressIndexBuffer,
+      ]),
+      clientInterpreter
+    );
+
+    const address = response.toString('ascii');
+    return address;
+  }
+
+  /**
+   * Signs a psbt using a (standard or registered) `WalletPolicy`. This is an interactive command, as user validation
+   * is necessary using the device's secure screen.
+   * On success, a map of input indexes and signatures is returned.
+   * @param psbt a base64-encoded string, or a psbt in a binary Buffer. Using the `PsbtV2` type is deprecated.
+   * @param walletPolicy the `WalletPolicy` to use for signing
+   * @param walletHMAC the 32-byte hmac obtained during wallet policy registration, or `null` for a standard policy
+   * @param progressCallback optionally, a callback that will be called every time a signature is produced during
+   * the signing process. The callback does not receive any argument, but can be used to track progress.
+   * @returns an array of of tuples with 2 elements containing:
+   *    - the index of the input being signed;
+   *    - an instance of PartialSignature
+   */
+  async signPsbt(
+    psbt: PsbtV2 | string | Buffer,
+    walletPolicy: WalletPolicy,
+    walletHMAC: Buffer | null,
+    progressCallback?: () => void
+  ): Promise<[number, PartialSignature][]> {
+    if (typeof psbt === 'string') {
+      psbt = Buffer.from(psbt, 'base64');
+    }
+
+    if (Buffer.isBuffer(psbt)) {
+      const psbtObj = new PsbtV2();
+      psbtObj.deserialize(psbt);
+      psbt = psbtObj;
+    }
+
+    const merkelizedPsbt = new MerkelizedPsbt(psbt);
+
+    if (walletHMAC != null && walletHMAC.length != 32) {
+      throw new Error('Invalid HMAC length');
+    }
+
+    const clientInterpreter = new ClientCommandInterpreter(progressCallback);
+
+    // prepare ClientCommandInterpreter
+    clientInterpreter.addKnownWalletPolicy(walletPolicy);
+
+    clientInterpreter.addKnownMapping(merkelizedPsbt.globalMerkleMap);
+    for (const map of merkelizedPsbt.inputMerkleMaps) {
+      clientInterpreter.addKnownMapping(map);
+    }
+    for (const map of merkelizedPsbt.outputMerkleMaps) {
+      clientInterpreter.addKnownMapping(map);
+    }
+
+    clientInterpreter.addKnownList(merkelizedPsbt.inputMapCommitments);
+    const inputMapsRoot = new Merkle(
+      merkelizedPsbt.inputMapCommitments.map((m) => hashLeaf(m))
+    ).getRoot();
+    clientInterpreter.addKnownList(merkelizedPsbt.outputMapCommitments);
+    const outputMapsRoot = new Merkle(
+      merkelizedPsbt.outputMapCommitments.map((m) => hashLeaf(m))
+    ).getRoot();
+
+    await this.makeRequest(
+      BitcoinIns.SIGN_PSBT,
+      Buffer.concat([
+        merkelizedPsbt.getGlobalKeysValuesRoot(),
+        createVarint(merkelizedPsbt.getGlobalInputCount()),
+        inputMapsRoot,
+        createVarint(merkelizedPsbt.getGlobalOutputCount()),
+        outputMapsRoot,
+        walletPolicy.getId(),
+        walletHMAC || Buffer.alloc(32, 0),
+      ]),
+      clientInterpreter
+    );
+
+    const yielded = clientInterpreter.getYielded();
+
+    const ret: [number, PartialSignature][] = [];
+    for (const inputAndSig of yielded) {
+      // inputAndSig contains:
+      // <inputIndex : varint> <pubkeyLen : 1 byte> <pubkey : pubkeyLen bytes (32 or 33)> <signature : variable length>
+      const [inputIndex, inputIndexLen] = parseVarint(inputAndSig, 0);
+      const pubkeyAugmLen = inputAndSig[inputIndexLen];
+      const pubkeyAugm = inputAndSig.subarray(
+        inputIndexLen + 1,
+        inputIndexLen + 1 + pubkeyAugmLen
+      );
+      const signature = inputAndSig.subarray(inputIndexLen + 1 + pubkeyAugmLen);
+
+      const partialSig = makePartialSignature(pubkeyAugm, signature);
+
+      ret.push([Number(inputIndex), partialSig]);
+    }
+    return ret;
+  }
+
+  /**
+   * Returns the fingerprint of the master public key, as per BIP-32 standard.
+   * @returns the master key fingerprint as a string of 8 hexadecimal digits.
+   */
+  async getMasterFingerprint(): Promise<string> {
+    const fpr = await this.makeRequest(
+      BitcoinIns.GET_MASTER_FINGERPRINT,
+      Buffer.from([])
+    );
+    return fpr.toString('hex');
+  }
+
+  /**
+   * Signs a message using the legacy Bitcoin Message Signing standard. The signed message is
+   * the double-sha256 hash of the concatenation of:
+   * - "\x18Bitcoin Signed Message:\n";
+   * - the length of `message`, encoded as a Bitcoin-style variable length integer;
+   * - `message`.
+   *
+   * @param message the serialized message to sign
+   * @param path the BIP-32 path of the key used to sign the message
+   * @returns base64-encoded signature of the message.
+   */
+  async signMessage(message: Buffer, path: string): Promise<string> {
+    const pathElements = pathStringToArray(path);
+
+    const clientInterpreter = new ClientCommandInterpreter();
+
+    // prepare ClientCommandInterpreter
+    const nChunks = Math.ceil(message.length / 64);
+    const chunks: Buffer[] = [];
+    for (let i = 0; i < nChunks; i++) {
+      chunks.push(message.subarray(64 * i, 64 * i + 64));
+    }
+
+    clientInterpreter.addKnownList(chunks);
+    const chunksRoot = new Merkle(chunks.map((m) => hashLeaf(m))).getRoot();
+
+    const result = await this.makeRequest(
+      BitcoinIns.SIGN_MESSAGE,
+      Buffer.concat([
+        pathElementsToBuffer(pathElements),
+        createVarint(message.length),
+        chunksRoot,
+      ]),
+      clientInterpreter
+    );
+
+    return result.toString('base64');
+  }
+}
+
+export default AppClient;

package/src/ledger/bitcoin_client/lib/bip32.ts

@@ -0,0 +1,61 @@
+import bippath from 'bip32-path';
+import bs58check from 'bs58check';
+
+export function pathElementsToBuffer(paths: readonly number[]): Buffer {
+  const buffer = Buffer.alloc(1 + paths.length * 4);
+  buffer[0] = paths.length;
+  paths.forEach((element, index) => {
+    buffer.writeUInt32BE(element, 1 + 4 * index);
+  });
+  return buffer;
+}
+
+export function bip32asBuffer(path: string): Buffer {
+  const pathElements = !path ? [] : pathStringToArray(path);
+  return pathElementsToBuffer(pathElements);
+}
+
+export function pathArrayToString(pathElements: readonly number[]): string {
+  // bippath doesn't handle an empty path.
+  if (pathElements.length == 0) {
+    return 'm';
+  }
+  return bippath.fromPathArray(pathElements).toString();
+}
+
+export function pathStringToArray(path: string): readonly number[] {
+  // bippath doesn't handle an empty path.
+  if (path == 'm' || path == '') {
+    return [];
+  }
+  return bippath.fromString(path).toPathArray();
+}
+
+export function pubkeyFromXpub(xpub: string): Buffer {
+  const xpubBuf = Buffer.from(bs58check.decode(xpub));
+  return xpubBuf.slice(xpubBuf.length - 33);
+}
+
+export function getXpubComponents(xpub: string): {
+  readonly chaincode: Buffer;
+  readonly pubkey: Buffer;
+  readonly version: number;
+} {
+  const xpubBuf = Buffer.from(bs58check.decode(xpub));
+  return {
+    chaincode: xpubBuf.slice(13, 13 + 32),
+    pubkey: xpubBuf.slice(xpubBuf.length - 33),
+    version: xpubBuf.readUInt32BE(0),
+  };
+}
+
+export function hardenedPathOf(
+  pathElements: readonly number[]
+): readonly number[] {
+  for (let i = pathElements.length - 1; i >= 0; i--) {
+    if (pathElements[i] >= 0x80000000) {
+      return pathElements.slice(0, i + 1);
+    }
+  }
+  return [];
+}

package/src/ledger/bitcoin_client/lib/buffertools.ts

@@ -0,0 +1,134 @@
+import { createVarint, parseVarint, sanitizeBigintToNumber } from './varint';
+
+export function unsafeTo64bitLE(n: number): Buffer {
+  // we want to represent the input as a 8-bytes array
+  if (n > Number.MAX_SAFE_INTEGER) {
+    throw new Error("Can't convert numbers > MAX_SAFE_INT");
+  }
+  const byteArray = Buffer.alloc(8, 0);
+  for (let index = 0; index < byteArray.length; index++) {
+    const byte = n & 0xff;
+    byteArray[index] = byte;
+    n = (n - byte) / 256;
+  }
+  return byteArray;
+}
+
+export function unsafeFrom64bitLE(byteArray: Buffer): number {
+  let value = 0;
+  if (byteArray.length != 8) {
+    throw new Error('Expected Bufffer of lenght 8');
+  }
+  if (byteArray[7] != 0) {
+    throw new Error("Can't encode numbers > MAX_SAFE_INT");
+  }
+  if (byteArray[6] > 0x1f) {
+    throw new Error("Can't encode numbers > MAX_SAFE_INT");
+  }
+  for (let i = byteArray.length - 1; i >= 0; i--) {
+    value = value * 256 + byteArray[i];
+  }
+  return value;
+}
+
+export class BufferWriter {
+  private bufs: Buffer[] = [];
+
+  write(alloc: number, fn: (b: Buffer) => void): void {
+    const b = Buffer.alloc(alloc);
+    fn(b);
+    this.bufs.push(b);
+  }
+
+  writeUInt8(i: number): void {
+    this.write(1, (b) => b.writeUInt8(i, 0));
+  }
+
+  writeInt32(i: number): void {
+    this.write(4, (b) => b.writeInt32LE(i, 0));
+  }
+
+  writeUInt32(i: number): void {
+    this.write(4, (b) => b.writeUInt32LE(i, 0));
+  }
+
+  writeUInt64(i: number): void {
+    const bytes = unsafeTo64bitLE(i);
+    this.writeSlice(bytes);
+  }
+
+  writeVarInt(i: number): void {
+    this.bufs.push(createVarint(i));
+  }
+
+  writeSlice(slice: Buffer): void {
+    this.bufs.push(Buffer.from(slice));
+  }
+
+  writeVarSlice(slice: Buffer): void {
+    this.writeVarInt(slice.length);
+    this.writeSlice(slice);
+  }
+
+  buffer(): Buffer {
+    return Buffer.concat(this.bufs);
+  }
+}
+
+export class BufferReader {
+  constructor(public readonly buffer: Buffer, public offset: number = 0) {}
+
+  available(): number {
+    return this.buffer.length - this.offset;
+  }
+
+  readUInt8(): number {
+    const result = this.buffer.readUInt8(this.offset);
+    this.offset++;
+    return result;
+  }
+
+  readInt32(): number {
+    const result = this.buffer.readInt32LE(this.offset);
+    this.offset += 4;
+    return result;
+  }
+
+  readUInt32(): number {
+    const result = this.buffer.readUInt32LE(this.offset);
+    this.offset += 4;
+    return result;
+  }
+
+  readUInt64(): number {
+    const buf = this.readSlice(8);
+    return unsafeFrom64bitLE(buf);
+  }
+
+  readVarInt(): bigint {
+    const [vi, viSize] = parseVarint(this.buffer, this.offset);
+    this.offset += viSize;
+    return vi;
+  }
+
+  readSlice(n: number): Buffer {
+    if (this.buffer.length < this.offset + n) {
+      throw new Error('Cannot read slice out of bounds');
+    }
+    const result = this.buffer.slice(this.offset, this.offset + n);
+    this.offset += n;
+    return result;
+  }
+
+  readVarSlice(): Buffer {
+    const n = sanitizeBigintToNumber(this.readVarInt());
+    return this.readSlice(n);
+  }
+
+  readVector(): readonly Buffer[] {
+    const count = this.readVarInt();
+    const vector: Buffer[] = [];
+    for (let i = 0; i < count; i++) vector.push(this.readVarSlice());
+    return vector;
+  }
+}