Merge pull request #59 from keepkey/feat/clearsign-studio-ironwood

feat: stage complete protocol client integration

Author: BitHighlander

packages/hdwallet-core/src/bitcoin-taproot.test.ts

@@ -0,0 +1,25 @@
+import { BTCInputScriptType, describeUTXOPath, taprootAccount } from "./bitcoin";
+
+describe("Bitcoin Taproot paths", () => {
+  it("describes a BIP-86 account as Taproot", () => {
+    const account = taprootAccount("Bitcoin", 0, 7);
+    expect(account).toEqual({
+      coin: "Bitcoin",
+      scriptType: BTCInputScriptType.SpendTaproot,
+      addressNList: [0x80000000 + 86, 0x80000000, 0x80000000 + 7],
+    });
+    expect(describeUTXOPath(account.addressNList, "Bitcoin", BTCInputScriptType.SpendTaproot)).toMatchObject({
+      coin: "Bitcoin",
+      accountIdx: 7,
+      wholeAccount: true,
+      isKnown: true,
+      scriptType: BTCInputScriptType.SpendTaproot,
+      verbose: "Bitcoin Account #7 (Taproot)",
+    });
+  });
+
+  it("does not describe BIP-86 with another script type", () => {
+    const path = [0x80000000 + 86, 0x80000000, 0x80000000];
+    expect(describeUTXOPath(path, "Bitcoin", BTCInputScriptType.SpendWitness).isKnown).toBe(false);
+  });
+});

packages/hdwallet-core/src/bitcoin.ts

@@ -76,7 +76,7 @@ type BTCSignTxInputNativeBase = BTCSignTxInputBase & {
 };
 
 type BTCSignTxInputNativeSegwitBase = BTCSignTxInputNativeBase & {
-  scriptType: BTCInputScriptType.SpendWitness | BTCInputScriptType.SpendP2SHWitness;
+  scriptType: BTCInputScriptType.SpendWitness | BTCInputScriptType.SpendP2SHWitness | BTCInputScriptType.SpendTaproot;
 };
 
 type BTCSignTxInputNativeSegwitWithHex = BTCSignTxInputNativeSegwitBase & {
@@ -106,7 +106,11 @@ type BTCSignTxInputKKBase = BTCSignTxInputBase & {
 };
 
 type BTCSignTxInputKKSegwit = BTCSignTxInputKKBase & {
-  scriptType: BTCInputScriptType.SpendWitness | BTCInputScriptType.SpendP2SHWitness | BTCInputScriptType.External;
+  scriptType:
+    | BTCInputScriptType.SpendWitness
+    | BTCInputScriptType.SpendP2SHWitness
+    | BTCInputScriptType.SpendTaproot
+    | BTCInputScriptType.External;
   hex?: string;
 };
 
@@ -231,6 +235,7 @@ export enum BTCInputScriptType {
   External = "external",
   SpendWitness = "p2wpkh",
   SpendP2SHWitness = "p2sh-p2wpkh",
+  SpendTaproot = "p2tr",
 }
 
 export enum BTCOutputScriptType {
@@ -239,6 +244,7 @@ export enum BTCOutputScriptType {
   Bech32 = "bech32",
   PayToWitness = "p2wpkh",
   PayToP2SHWitness = "p2sh-p2wpkh",
+  PayToTaproot = "p2tr", // device-derived change only
 }
 
 export enum BTCOutputAddressType {
@@ -362,12 +368,16 @@ export function describeUTXOPath(path: BIP32Path, coin: Coin, scriptType: BTCInp
 
   const purpose = path[0] & 0x7fffffff;
 
-  if (![44, 49, 84].includes(purpose)) return unknown;
+  if (![44, 49, 84, 86].includes(purpose)) return unknown;
 
   if (purpose === 44 && scriptType !== BTCInputScriptType.SpendAddress) return unknown;
 
   if (purpose === 49 && scriptType !== BTCInputScriptType.SpendP2SHWitness) return unknown;
 
+  if (purpose === 84 && scriptType !== BTCInputScriptType.SpendWitness) return unknown;
+
+  if (purpose === 86 && scriptType !== BTCInputScriptType.SpendTaproot) return unknown;
+
   const wholeAccount = path.length === 3;
 
   const script = (
@@ -376,6 +386,7 @@ export function describeUTXOPath(path: BIP32Path, coin: Coin, scriptType: BTCInp
       [BTCInputScriptType.SpendP2SHWitness]: [],
       [BTCInputScriptType.SpendWitness]: ["Segwit"],
       [BTCInputScriptType.Bech32]: ["Segwit Native"],
+      [BTCInputScriptType.SpendTaproot]: ["Taproot"],
     } as Partial<Record<BTCInputScriptType, string[]>>
   )[scriptType];
 
@@ -471,3 +482,11 @@ export function segwitNativeAccount(coin: Coin, slip44: number, accountIdx: numb
     addressNList: [0x80000000 + 84, 0x80000000 + slip44, 0x80000000 + accountIdx],
   };
 }
+
+export function taprootAccount(coin: Coin, slip44: number, accountIdx: number): BTCAccountPath {
+  return {
+    coin,
+    scriptType: BTCInputScriptType.SpendTaproot,
+    addressNList: [0x80000000 + 86, 0x80000000 + slip44, 0x80000000 + accountIdx],
+  };
+}

packages/hdwallet-core/src/ethereum.ts

@@ -103,6 +103,10 @@ export interface ETHSignedTx {
   s: string;
   /** big-endian hex, prefixed with '0x' */
   serialized: string;
+  /** KeepKey-only: keccak256 pre-image the firmware actually signed (32-byte hex).
+   *  Optional — older firmware doesn't populate it. Useful for diagnostics where
+   *  the caller needs to verify which bytes the device hashed. */
+  deviceSignedHash?: string;
 }
 
 export interface ETHSignMessage {

packages/hdwallet-core/src/solana.ts

@@ -9,9 +9,44 @@ export interface SolanaAddress {
   address: string;
 }
 
+export interface SolanaTokenInfo {
+  /** 32-byte SPL mint, encoded as bytes, hex, base64, or base58. */
+  mint: Uint8Array | string;
+  symbol?: string;
+  decimals?: number;
+  signature?: Uint8Array | string;
+  signerKeyId?: number;
+}
+
 export interface SolanaSignTx {
   addressNList: BIP32Path;
   rawTx: Uint8Array | string;
+  /** Optional token definitions used by firmware display policy. */
+  tokenInfo?: SolanaTokenInfo[];
+  /**
+   * Candidate owners for signed SPL token destinations (for example x402
+   * payTo). Firmware displays one only after deriving and matching its ATA.
+   */
+  tokenRecipientOwners?: Array<Uint8Array | string>;
+  /** One-request opaque-signing authorization; does not mutate AdvancedMode. */
+  allowBlindSigning?: boolean;
+  /** Transaction-bound, signer-attested KKSOLSW1 swap descriptor. */
+  swapMetadata?: {
+    payload: Uint8Array | string;
+    signature: Uint8Array | string;
+    signerKeyId: number;
+  };
+  /**
+   * Signer-attested KKSOLSC1 instruction schema. Unlike swapMetadata this is
+   * NOT bound to one transaction: it describes how to read a program's
+   * instruction, so a single signature is reused for every transaction to
+   * that program and the device decodes values from the bytes it signs.
+   */
+  schema?: {
+    payload: Uint8Array | string;
+    signature: Uint8Array | string;
+    signerKeyId: number;
+  };
 }
 
 export interface SolanaSignedTx {

packages/hdwallet-keepkey-nodewebusb/src/adapter.ts

@@ -10,11 +10,13 @@ export const NodeWebUSBAdapterDelegate = {
     return devices.filter((x) => x.vendorId === VENDOR_ID && [WEBUSB_PRODUCT_ID, HID_PRODUCT_ID].includes(x.productId));
   },
   async getDevice(serialNumber?: string): Promise<Device> {
+    // Only match the WebUSB PID (0x0002). The TransportDelegate ctor rejects any
+    // other PID with FirmwareUpdateRequired, so matching legacy 0x0001 here just
+    // produced a doomed pair attempt + a misleading "Firmware 6.1.0 required"
+    // before the caller's HID fallback. Old (PID 0x0001) devices now skip WebUSB
+    // cleanly and pair over HID. (getDevices() still lists 0x0001 for detection.)
     const out = await webusb.requestDevice({
-      filters: [
-        { vendorId: VENDOR_ID, productId: WEBUSB_PRODUCT_ID, serialNumber },
-        { vendorId: VENDOR_ID, productId: HID_PRODUCT_ID, serialNumber },
-      ],
+      filters: [{ vendorId: VENDOR_ID, productId: WEBUSB_PRODUCT_ID, serialNumber }],
     });
     if (out.serialNumber === undefined) throw new Error("expected serial number");
     return out as Device;

packages/hdwallet-keepkey/package.json

@@ -17,7 +17,7 @@
   "dependencies": {
     "@ethereumjs/common": "^2.4.0",
     "@ethereumjs/tx": "^3.3.0",
-    "@keepkey/device-protocol": "npm:@bithighlander/device-protocol@7.16.0",
+    "@keepkey/device-protocol": "https://github.com/keepkey/device-protocol.git#674777f6d4dd16e2b8c4c2df10608976375ee879",
     "@keepkey/hdwallet-core": "1.53.16",
     "@keepkey/proto-tx-builder": "^0.9.1",
     "@shapeshiftoss/bitcoinjs-lib": "5.2.0-shapeshift.2",

packages/hdwallet-keepkey/src/bitcoin.ts

@@ -26,6 +26,7 @@ const supportedCoins = [
 ];
 
 const segwitCoins = ["Bitcoin", "Testnet", "BitcoinGold", "Litecoin"];
+const taprootCoins = ["Bitcoin", "Testnet"];
 
 function legacyAccount(coin: core.Coin, slip44: number, accountIdx: number): core.BTCAccountPath {
   return {
@@ -51,6 +52,14 @@ function segwitNativeAccount(coin: core.Coin, slip44: number, accountIdx: number
   };
 }
 
+function taprootAccount(coin: core.Coin, slip44: number, accountIdx: number): core.BTCAccountPath {
+  return {
+    coin,
+    scriptType: core.BTCInputScriptType.SpendTaproot,
+    addressNList: [0x80000000 + 86, 0x80000000 + slip44, 0x80000000 + accountIdx],
+  };
+}
+
 function packVarint(n: number): string {
   if (n < 253) return n.toString(16).padStart(2, "0");
   else if (n < 0xffff) return "FD" + n.toString(16).padStart(4, "0");
@@ -120,6 +129,7 @@ function prepareSignTx(
     if (
       inputTx.scriptType === core.BTCInputScriptType.SpendP2SHWitness ||
       inputTx.scriptType === core.BTCInputScriptType.SpendWitness ||
+      inputTx.scriptType === core.BTCInputScriptType.SpendTaproot ||
       inputTx.scriptType === core.BTCInputScriptType.External
     )
       return;
@@ -248,6 +258,7 @@ export async function btcSupportsScriptType(coin: core.Coin, scriptType?: core.B
   if (!supportedCoins.includes(coin)) return false;
   if (!segwitCoins.includes(coin) && scriptType === core.BTCInputScriptType.SpendP2SHWitness) return false;
   if (!segwitCoins.includes(coin) && scriptType === core.BTCInputScriptType.SpendWitness) return false;
+  if (!taprootCoins.includes(coin) && scriptType === core.BTCInputScriptType.SpendTaproot) return false;
   return true;
 }
 
@@ -546,6 +557,7 @@ export function btcGetAccountPaths(msg: core.BTCGetAccountPaths): Array<core.BTC
   const bip44 = legacyAccount(msg.coin, slip44, msg.accountIdx);
   const bip49 = segwitAccount(msg.coin, slip44, msg.accountIdx);
   const bip84 = segwitNativeAccount(msg.coin, slip44, msg.accountIdx);
+  const bip86 = taprootAccount(msg.coin, slip44, msg.accountIdx);
 
   // For BTC Forks
   const btcLegacy = legacyAccount(msg.coin, core.slip44ByCoin("Bitcoin"), msg.accountIdx);
@@ -558,12 +570,12 @@ export function btcGetAccountPaths(msg: core.BTCGetAccountPaths): Array<core.BTC
   let paths: Array<core.BTCAccountPath> =
     (
       {
-        Bitcoin: [bip44, bip49, bip84],
+        Bitcoin: [bip44, bip49, bip84, bip86],
         Litecoin: [bip44, bip49, bip84],
         Dash: [bip44],
         DigiByte: [bip44, bip49, bip84],
         Dogecoin: [bip44],
-        Testnet: [bip44, bip49, bip84],
+        Testnet: [bip44, bip49, bip84, bip86],
         BitcoinCash: [bip44, btcLegacy],
         BitcoinSV: [bip44, bchLegacy, btcLegacy],
         BitcoinGold: [bip44, bip49, bip84, btcLegacy, btcSegwit, btcSegwitNative],
@@ -581,7 +593,7 @@ export function btcGetAccountPaths(msg: core.BTCGetAccountPaths): Array<core.BTC
 export function btcIsSameAccount(msg: Array<core.BTCAccountPath>): boolean {
   if (msg.length < 1) return false;
 
-  if (msg.length > 3) return false;
+  if (msg.length > 4) return false;
 
   const account0 = msg[0];
   if (account0.addressNList.length != 3) return false;
@@ -592,6 +604,7 @@ export function btcIsSameAccount(msg: Array<core.BTCAccountPath>): boolean {
     [core.BTCInputScriptType.SpendAddress]: 0x80000000 + 44,
     [core.BTCInputScriptType.SpendP2SHWitness]: 0x80000000 + 49,
     [core.BTCInputScriptType.SpendWitness]: 0x80000000 + 84,
+    [core.BTCInputScriptType.SpendTaproot]: 0x80000000 + 86,
   } as Partial<Record<core.BTCInputScriptType, number>>;
   if (purposeForScriptType[account0.scriptType] !== purpose) return false;
 
@@ -604,12 +617,13 @@ export function btcIsSameAccount(msg: Array<core.BTCAccountPath>): boolean {
   if (idx < 0x80000000) return false;
 
   // Accounts must have the same SLIP44 and Account Idx, but may have differing
-  // purpose fields (so long as they're BIP44/BIP49/BIP84)
+  // purpose fields (so long as they're BIP44/BIP49/BIP84/BIP86)
   if (
     msg.find((path) => {
       if (path.addressNList.length != 3) return true;
 
-      if (![0x80000000 + 44, 0x80000000 + 49, 0x80000000 + 84].includes(path.addressNList[0])) return true;
+      if (![0x80000000 + 44, 0x80000000 + 49, 0x80000000 + 84, 0x80000000 + 86].includes(path.addressNList[0]))
+        return true;
 
       if (purposeForScriptType[path.scriptType] !== path.addressNList[0]) return true;
 

packages/hdwallet-keepkey/src/clearsign.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Regression coverage for ClearSign attestor message decoding.
+ *
+ * Transport.fromMessageBuffer always calls deserializeBinaryFromReader on the
+ * constructor stored in messageTypeRegistry. Keep the attestor entries on the
+ * canonical generated classes so public-key and signature responses cannot be
+ * replaced by incomplete hand-written shims.
+ */
+import "./clearsign";
+
+import * as jspb from "google-protobuf";
+
+import { messageTypeRegistry } from "./typeRegistry";
+
+const ATTESTOR_TYPES = [
+  [1700, "ClearsignAttestorGetPublicKey"],
+  [1701, "ClearsignAttestorPublicKey"],
+  [1702, "ClearsignAttestorSign"],
+  [1703, "ClearsignAttestorSignature"],
+] as const;
+
+describe("ClearSign attestor protobuf transport", () => {
+  it.each(ATTESTOR_TYPES)("registers message type %i (%s) with reader decoding", (typeId) => {
+    const registeredType = messageTypeRegistry[typeId] as any;
+    expect(registeredType).toBeDefined();
+    expect(typeof registeredType.deserializeBinaryFromReader).toBe("function");
+  });
+
+  it("decodes the public-key response through the transport registry path", () => {
+    const publicKey = new Uint8Array(33).fill(0x02);
+    const writer = new jspb.BinaryWriter();
+    writer.writeBytes(1, publicKey);
+    const MType = messageTypeRegistry[1701] as any;
+    const decoded = MType.deserializeBinaryFromReader(new MType(), new jspb.BinaryReader(writer.getResultBuffer()));
+
+    expect(Array.from(decoded.getPublicKey_asU8())).toEqual(Array.from(publicKey));
+  });
+
+  it("decodes the signature response through the transport registry path", () => {
+    const signature = new Uint8Array(64).fill(0x5a);
+    const publicKey = new Uint8Array(33).fill(0x03);
+    const writer = new jspb.BinaryWriter();
+    writer.writeBytes(1, signature);
+    writer.writeBytes(2, publicKey);
+    const MType = messageTypeRegistry[1703] as any;
+    const decoded = MType.deserializeBinaryFromReader(new MType(), new jspb.BinaryReader(writer.getResultBuffer()));
+
+    expect(Array.from(decoded.getSignature_asU8())).toEqual(Array.from(signature));
+    expect(Array.from(decoded.getPublicKey_asU8())).toEqual(Array.from(publicKey));
+  });
+});