@onekeyfe/hd-transport-usb 1.1.25-alpha.0

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const PACKET_SIZE = 64;
+export declare const REPORT_ID = 63;
+export declare const HEADER_LENGTH = 6;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW,KAAK,CAAC;AAG9B,eAAO,MAAM,SAAS,KAAO,CAAC;AAG9B,eAAO,MAAM,aAAa,IAAI,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { LowlevelTransportSharedPlugin } from '@onekeyfe/hd-transport';
+
+declare const PACKET_SIZE = 64;
+
+declare const UsbPlugin: LowlevelTransportSharedPlugin;
+
+export { PACKET_SIZE, UsbPlugin, UsbPlugin as default };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAkB,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAoG5F,eAAO,MAAM,SAAS,EAAE,6BAoLvB,CAAC;AAEF,eAAe,SAAS,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,262 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ByteBuffer = require('bytebuffer');
+var usb = require('usb');
+var transport = require('@onekeyfe/hd-transport');
+var hdShared = require('@onekeyfe/hd-shared');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+function _interopNamespace(e) {
+    if (e && e.__esModule) return e;
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n["default"] = e;
+    return Object.freeze(n);
+}
+
+var ByteBuffer__default = /*#__PURE__*/_interopDefaultLegacy(ByteBuffer);
+var usb__namespace = /*#__PURE__*/_interopNamespace(usb);
+var transport__default = /*#__PURE__*/_interopDefaultLegacy(transport);
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+const PACKET_SIZE = 64;
+const REPORT_ID = 0x3f;
+const HEADER_LENGTH = 6;
+
+const { decodeProtocol } = transport__default["default"];
+const INTERFACE_NUMBER = 0;
+const ENDPOINT_IN = 0x81;
+const ENDPOINT_OUT = 0x01;
+const TRANSFER_TIMEOUT_MS = 30000;
+let activeDevice = null;
+const openDevices = new Map();
+function getDeviceId(dev) {
+    return `usb:${dev.busNumber}:${dev.deviceAddress}`;
+}
+function transferIn(ep, length) {
+    return new Promise((resolve, reject) => {
+        ep.transfer(length, (err, data) => {
+            if (err)
+                return reject(err);
+            if (!data || data.length === 0)
+                return reject(new Error('Empty USB transfer'));
+            resolve(data);
+        });
+    });
+}
+function transferOut(ep, data) {
+    return new Promise((resolve, reject) => {
+        ep.transfer(data, (err) => {
+            if (err)
+                return reject(err);
+            resolve();
+        });
+    });
+}
+function readPacket(dev) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return transferIn(dev.epIn, PACKET_SIZE);
+    });
+}
+function skipReportByte(packet) {
+    if (packet[0] === REPORT_ID) {
+        return packet.subarray(1);
+    }
+    return packet;
+}
+function toArrayBuffer(buf) {
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+}
+const UsbPlugin = {
+    version: '1.0.0',
+    init() {
+        return __awaiter(this, void 0, void 0, function* () {
+        });
+    },
+    enumerate() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const allDevices = usb__namespace.getDeviceList();
+            const onekeyDevices = allDevices.filter(d => {
+                const { idVendor, idProduct } = d.deviceDescriptor;
+                return hdShared.ONEKEY_WEBUSB_FILTER.some(f => idVendor === f.vendorId && idProduct === f.productId);
+            });
+            return onekeyDevices.map(d => {
+                let name = 'OneKey';
+                try {
+                    d.open();
+                    const iface = d.interface(INTERFACE_NUMBER);
+                    if (iface && iface.descriptor.bInterfaceClass === 255) {
+                        name = 'OneKey';
+                    }
+                    d.close();
+                }
+                catch (_a) {
+                    try {
+                        d.close();
+                    }
+                    catch (_b) {
+                    }
+                }
+                return {
+                    id: getDeviceId(d),
+                    name,
+                    commType: 'usb',
+                };
+            });
+        });
+    },
+    connect(uuid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const existing = openDevices.get(uuid);
+            if (existing) {
+                activeDevice = existing;
+                return;
+            }
+            const allDevices = usb__namespace.getDeviceList();
+            const dev = allDevices.find(d => getDeviceId(d) === uuid);
+            if (!dev) {
+                throw new Error(`USB device not found: ${uuid}`);
+            }
+            dev.open();
+            dev.timeout = TRANSFER_TIMEOUT_MS;
+            const iface = dev.interface(INTERFACE_NUMBER);
+            if (process.platform === 'linux') {
+                try {
+                    if (iface.isKernelDriverActive()) {
+                        iface.detachKernelDriver();
+                    }
+                }
+                catch (_a) {
+                }
+            }
+            iface.claim();
+            const epIn = iface.endpoints.find((e) => e.direction === 'in' && e.address === ENDPOINT_IN);
+            const epOut = iface.endpoints.find((e) => e.direction === 'out' && e.address === ENDPOINT_OUT);
+            if (!epIn || !epOut) {
+                dev.close();
+                throw new Error('USB endpoints not found (expected IN 0x81, OUT 0x01)');
+            }
+            epIn.timeout = TRANSFER_TIMEOUT_MS;
+            epOut.timeout = TRANSFER_TIMEOUT_MS;
+            const openDev = { device: dev, iface, epIn, epOut };
+            openDevices.set(uuid, openDev);
+            activeDevice = openDev;
+        });
+    },
+    disconnect(uuid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const openDev = openDevices.get(uuid);
+            if (openDev) {
+                try {
+                    openDev.iface.release(() => {
+                        try {
+                            openDev.device.close();
+                        }
+                        catch (_a) {
+                        }
+                    });
+                }
+                catch (_a) {
+                    try {
+                        openDev.device.close();
+                    }
+                    catch (_b) {
+                    }
+                }
+                openDevices.delete(uuid);
+                if (activeDevice === openDev) {
+                    activeDevice = null;
+                }
+            }
+        });
+    },
+    send(uuid, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const openDev = openDevices.get(uuid);
+            if (!openDev) {
+                throw new Error(`Device not connected: ${uuid}`);
+            }
+            activeDevice = openDev;
+            const dataBuffer = Buffer.from(data, 'hex');
+            yield transferOut(openDev.epOut, dataBuffer);
+        });
+    },
+    receive() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!activeDevice) {
+                throw new Error('No active device for receive');
+            }
+            const dev = activeDevice;
+            const firstPacket = yield readPacket(dev);
+            const firstData = skipReportByte(firstPacket);
+            const { length, typeId, restBuffer } = decodeProtocol.decodeChunked(toArrayBuffer(firstData));
+            const lengthWithHeader = Number(length) + HEADER_LENGTH;
+            const decoded = new ByteBuffer__default["default"](lengthWithHeader);
+            decoded.writeUint16(typeId);
+            decoded.writeUint32(Number(length));
+            if (length) {
+                decoded.append(restBuffer);
+            }
+            while (decoded.offset < lengthWithHeader) {
+                const packet = yield readPacket(dev);
+                const pktData = skipReportByte(packet);
+                const buf = toArrayBuffer(pktData);
+                if (lengthWithHeader - decoded.offset >= PACKET_SIZE) {
+                    decoded.append(buf);
+                }
+                else {
+                    decoded.append(buf.slice(0, lengthWithHeader - decoded.offset));
+                }
+            }
+            decoded.reset();
+            const result = decoded.toBuffer();
+            return Buffer.from(result).toString('hex');
+        });
+    },
+};
+
+exports.PACKET_SIZE = PACKET_SIZE;
+exports.UsbPlugin = UsbPlugin;
+exports["default"] = UsbPlugin;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@onekeyfe/hd-transport-usb",
+  "version": "1.1.25-alpha.0",
+  "description": "OneKey hardware wallet direct USB transport plugin (libusb)",
+  "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneKeyHQ/hardware-js-sdk.git"
+  },
+  "scripts": {
+    "dev": "rimraf dist && rollup -c ../../build/rollup.config.js -w",
+    "build": "rimraf dist && rollup -c ../../build/rollup.config.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "@onekeyfe/hd-shared": "1.1.25-alpha.0",
+    "@onekeyfe/hd-transport": "1.1.25-alpha.0",
+    "bytebuffer": "^5.0.1",
+    "usb": "^2.14.0"
+  },
+  "gitHead": "8cebdb9dea32ab8bfa39c51cd695f5cd9508defa"
+}

package/src/constants.ts

@@ -0,0 +1,8 @@
+/** USB packet size in bytes */
+export const PACKET_SIZE = 64;
+
+/** Protocol marker byte (0x3F = '?') — first byte of every packet */
+export const REPORT_ID = 0x3f;
+
+/** Protocol header length: typeId (2 bytes) + length (4 bytes) */
+export const HEADER_LENGTH = 6;

package/src/index.ts

@@ -0,0 +1,291 @@
+import ByteBuffer from 'bytebuffer';
+import * as usb from 'usb';
+import transport from '@onekeyfe/hd-transport';
+import { ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared';
+
+import { HEADER_LENGTH, PACKET_SIZE, REPORT_ID } from './constants';
+
+import type { LowLevelDevice, LowlevelTransportSharedPlugin } from '@onekeyfe/hd-transport';
+
+const { decodeProtocol } = transport;
+
+/** USB interface number for vendor-specific communication */
+const INTERFACE_NUMBER = 0;
+/** USB endpoint addresses */
+const ENDPOINT_IN = 0x81;
+const ENDPOINT_OUT = 0x01;
+
+/** Transfer timeout in milliseconds */
+const TRANSFER_TIMEOUT_MS = 30000;
+
+/**
+ * Opened device state — holds the USB device, claimed interface, and endpoints.
+ */
+interface OpenDevice {
+  device: usb.Device;
+  iface: usb.Interface;
+  epIn: usb.InEndpoint;
+  epOut: usb.OutEndpoint;
+}
+
+/**
+ * The currently active device — used by receive() since
+ * LowlevelTransportSharedPlugin.receive() takes no uuid parameter.
+ */
+let activeDevice: OpenDevice | null = null;
+
+/** Map of uuid → open device state */
+const openDevices = new Map<string, OpenDevice>();
+
+/**
+ * Build a unique identifier for a USB device.
+ * Uses bus number + device address which is stable within a session.
+ */
+function getDeviceId(dev: usb.Device): string {
+  return `usb:${dev.busNumber}:${dev.deviceAddress}`;
+}
+
+/**
+ * Promisified USB IN transfer.
+ */
+function transferIn(ep: usb.InEndpoint, length: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    ep.transfer(length, (err: Error | undefined, data: Buffer | undefined) => {
+      if (err) return reject(err);
+      if (!data || data.length === 0) return reject(new Error('Empty USB transfer'));
+      resolve(data);
+    });
+  });
+}
+
+/**
+ * Promisified USB OUT transfer.
+ */
+function transferOut(ep: usb.OutEndpoint, data: Buffer): Promise<void> {
+  return new Promise((resolve, reject) => {
+    ep.transfer(data, (err: Error | undefined) => {
+      if (err) return reject(err);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Read a single 64-byte packet from the device via libusb bulk/interrupt transfer.
+ */
+async function readPacket(dev: OpenDevice): Promise<Buffer> {
+  return transferIn(dev.epIn, PACKET_SIZE);
+}
+
+/**
+ * Skip the 0x3F protocol marker byte from a USB packet.
+ * The device sends 0x3F as the first byte of every response packet.
+ */
+function skipReportByte(packet: Buffer): Buffer {
+  if (packet[0] === REPORT_ID) {
+    return packet.subarray(1);
+  }
+  return packet;
+}
+
+/**
+ * Convert a Buffer to ArrayBuffer (required by decodeChunked).
+ */
+function toArrayBuffer(buf: Buffer): ArrayBuffer {
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+}
+
+/**
+ * Node.js USB plugin for LowlevelTransport.
+ *
+ * Implements the 6-method LowlevelTransportSharedPlugin interface
+ * using the `usb` (libusb) library for direct USB communication
+ * with OneKey hardware wallets.
+ *
+ * Uses libusb to access the vendor-specific interface (class 255)
+ * which is NOT visible to the HID framework on macOS.
+ */
+export const UsbPlugin: LowlevelTransportSharedPlugin = {
+  version: '1.0.0',
+
+  async init(): Promise<void> {
+    // libusb requires no global initialization
+  },
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async enumerate(): Promise<LowLevelDevice[]> {
+    const allDevices = usb.getDeviceList();
+
+    const onekeyDevices = allDevices.filter(d => {
+      const { idVendor, idProduct } = d.deviceDescriptor;
+      return ONEKEY_WEBUSB_FILTER.some(f => idVendor === f.vendorId && idProduct === f.productId);
+    });
+
+    return onekeyDevices.map(d => {
+      // Try to get product name
+      let name = 'OneKey';
+      try {
+        d.open();
+        const iface = d.interface(INTERFACE_NUMBER);
+        // Check interface class is 255 (vendor-specific) — the communication interface
+        if (iface && iface.descriptor.bInterfaceClass === 255) {
+          name = 'OneKey';
+        }
+        d.close();
+      } catch {
+        // Can't open — might be in use, just return basic info
+        try {
+          d.close();
+        } catch {
+          /* ignore */
+        }
+      }
+
+      return {
+        id: getDeviceId(d),
+        name,
+        commType: 'usb' as const,
+      };
+    });
+  },
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async connect(uuid: string): Promise<void> {
+    const existing = openDevices.get(uuid);
+    if (existing) {
+      activeDevice = existing;
+      return;
+    }
+
+    // Find the device by our uuid (bus:address)
+    const allDevices = usb.getDeviceList();
+    const dev = allDevices.find(d => getDeviceId(d) === uuid);
+    if (!dev) {
+      throw new Error(`USB device not found: ${uuid}`);
+    }
+
+    dev.open();
+    dev.timeout = TRANSFER_TIMEOUT_MS;
+
+    const iface = dev.interface(INTERFACE_NUMBER);
+
+    // On Linux, detach kernel driver if active
+    if (process.platform === 'linux') {
+      try {
+        if (iface.isKernelDriverActive()) {
+          iface.detachKernelDriver();
+        }
+      } catch {
+        // May not be supported — continue
+      }
+    }
+
+    iface.claim();
+
+    // Find IN and OUT endpoints
+    const epIn = iface.endpoints.find(
+      (e): e is usb.InEndpoint => e.direction === 'in' && e.address === ENDPOINT_IN
+    );
+    const epOut = iface.endpoints.find(
+      (e): e is usb.OutEndpoint => e.direction === 'out' && e.address === ENDPOINT_OUT
+    );
+
+    if (!epIn || !epOut) {
+      dev.close();
+      throw new Error('USB endpoints not found (expected IN 0x81, OUT 0x01)');
+    }
+
+    epIn.timeout = TRANSFER_TIMEOUT_MS;
+    epOut.timeout = TRANSFER_TIMEOUT_MS;
+
+    const openDev: OpenDevice = { device: dev, iface, epIn, epOut };
+    openDevices.set(uuid, openDev);
+    activeDevice = openDev;
+  },
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async disconnect(uuid: string): Promise<void> {
+    const openDev = openDevices.get(uuid);
+    if (openDev) {
+      try {
+        openDev.iface.release(() => {
+          try {
+            openDev.device.close();
+          } catch {
+            /* ignore */
+          }
+        });
+      } catch {
+        try {
+          openDev.device.close();
+        } catch {
+          /* ignore */
+        }
+      }
+      openDevices.delete(uuid);
+      if (activeDevice === openDev) {
+        activeDevice = null;
+      }
+    }
+  },
+
+  async send(uuid: string, data: string): Promise<void> {
+    const openDev = openDevices.get(uuid);
+    if (!openDev) {
+      throw new Error(`Device not connected: ${uuid}`);
+    }
+    activeDevice = openDev;
+
+    // data is a hex string of a 64-byte packet (0x3F + 63 bytes payload),
+    // already framed by LowlevelTransport's buildBuffers().
+    const dataBuffer = Buffer.from(data, 'hex');
+
+    // libusb transfers the raw packet directly — no Report ID prepend needed
+    // (Report ID is a HID concept; libusb operates at USB level)
+    await transferOut(openDev.epOut, dataBuffer);
+  },
+
+  async receive(): Promise<string> {
+    if (!activeDevice) {
+      throw new Error('No active device for receive');
+    }
+    const dev = activeDevice;
+
+    // Mirrors WebUsbTransport.receiveData() exactly:
+    // 1. Read first 64-byte packet, skip byte[0] (0x3F marker)
+    const firstPacket = await readPacket(dev);
+    const firstData = skipReportByte(firstPacket);
+
+    // 2. Use SDK's decodeChunked to parse ## header → { typeId, length, restBuffer }
+    const { length, typeId, restBuffer } = decodeProtocol.decodeChunked(toArrayBuffer(firstData));
+
+    // 3. Allocate result buffer: typeId(2) + length(4) + payload(length)
+    const lengthWithHeader = Number(length) + HEADER_LENGTH;
+    const decoded = new ByteBuffer(lengthWithHeader);
+    decoded.writeUint16(typeId);
+    decoded.writeUint32(Number(length));
+    if (length) {
+      decoded.append(restBuffer);
+    }
+
+    // 4. Read subsequent packets until complete
+    while (decoded.offset < lengthWithHeader) {
+      const packet = await readPacket(dev);
+      const pktData = skipReportByte(packet);
+      const buf = toArrayBuffer(pktData);
+      if (lengthWithHeader - decoded.offset >= PACKET_SIZE) {
+        decoded.append(buf);
+      } else {
+        decoded.append(buf.slice(0, lengthWithHeader - decoded.offset));
+      }
+    }
+
+    // 5. Return as hex string
+    decoded.reset();
+    const result = decoded.toBuffer();
+    return Buffer.from(result as unknown as ArrayBuffer).toString('hex');
+  },
+};
+
+export default UsbPlugin;
+export { PACKET_SIZE } from './constants';

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.lib.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["./src"]
+}