@onekeyfe/hd-transport-usb 1.2.0-alpha.19 → 1.2.0-alpha.20

package/__tests__/protocol-v2-link.test.ts

@@ -62,6 +62,7 @@ const createHarness = () => {
   const path = '6136';
   const responseQueue: Buffer[] = [];
   const sentSeqs: number[] = [];
+  let cancelledTransferCount = 0;
   let writeError: Error | undefined;
   let holdNextRead:
     | {
@@ -71,29 +72,84 @@ const createHarness = () => {
       }
     | undefined;
 
+  const performInTransfer = (callback: (error?: Error, data?: Buffer) => void) => {
+    if (epIn.timeout === 50) {
+      callback(new Error('LIBUSB_TRANSFER_TIMED_OUT'));
+      return;
+    }
+    if (holdNextRead) {
+      const pending = holdNextRead;
+      holdNextRead = undefined;
+      pending.callback = callback;
+      pending.markStarted();
+      return;
+    }
+    const response = responseQueue.shift();
+    if (!response) {
+      callback(new Error('LIBUSB_TRANSFER_TIMED_OUT'));
+      return;
+    }
+    callback(undefined, response);
+  };
+
   const epIn = {
     direction: 'in',
     address: 0x81,
     timeout: 30_000,
     transfer: jest.fn((_length: number, callback: (error?: Error, data?: Buffer) => void) => {
-      if (epIn.timeout === 50) {
-        callback(new Error('LIBUSB_TRANSFER_TIMED_OUT'));
-        return;
-      }
-      if (holdNextRead) {
-        const pending = holdNextRead;
-        holdNextRead = undefined;
-        pending.callback = callback;
-        pending.markStarted();
-        return;
-      }
-      const response = responseQueue.shift();
-      if (!response) {
-        callback(new Error('LIBUSB_TRANSFER_TIMED_OUT'));
-        return;
-      }
-      callback(undefined, response);
+      performInTransfer(callback);
     }),
+    makeTransfer: jest.fn(
+      (
+        _timeout: number,
+        callback: (error: Error | undefined, data: Buffer, actualLength: number) => void
+      ) => {
+        let settled = false;
+        const finish = (error?: Error, data = Buffer.alloc(0)) => {
+          if (settled) return;
+          settled = true;
+          callback(error, data, data.length);
+        };
+        return {
+          submit: jest.fn((buffer: Buffer) => {
+            performInTransfer((error, data) => {
+              if (error) {
+                finish(error);
+                return;
+              }
+              data?.copy(buffer);
+              finish(undefined, buffer.subarray(0, data?.length ?? 0));
+            });
+          }),
+          cancel: jest.fn(() => {
+            cancelledTransferCount += 1;
+            finish(new Error('LIBUSB_TRANSFER_CANCELLED'));
+          }),
+        };
+      }
+    ),
+  };
+
+  const performOutTransfer = (data: Buffer, callback: (error?: Error) => void) => {
+    const seq = data[6];
+    sentSeqs.push(seq);
+    if (writeError) {
+      const error = writeError;
+      writeError = undefined;
+      callback(error);
+      return;
+    }
+    responseQueue.push(
+      Buffer.from(
+        ProtocolV2.encodeFrame(
+          schemas,
+          'Success',
+          { message: 'ok' },
+          { router: PROTOCOL_V2_CHANNEL_USB, seq }
+        )
+      )
+    );
+    callback();
   };
 
   const epOut = {
@@ -101,33 +157,40 @@ const createHarness = () => {
     address: 0x01,
     timeout: 30_000,
     transfer: jest.fn((data: Buffer, callback: (error?: Error) => void) => {
-      const seq = data[6];
-      sentSeqs.push(seq);
-      if (writeError) {
-        const error = writeError;
-        writeError = undefined;
-        callback(error);
-        return;
-      }
-      responseQueue.push(
-        Buffer.from(
-          ProtocolV2.encodeFrame(
-            schemas,
-            'Success',
-            { message: 'ok' },
-            { router: PROTOCOL_V2_CHANNEL_USB, seq }
-          )
-        )
-      );
-      callback();
+      performOutTransfer(data, callback);
     }),
+    makeTransfer: jest.fn(
+      (
+        _timeout: number,
+        callback: (error: Error | undefined, data: Buffer, actualLength: number) => void
+      ) => {
+        let settled = false;
+        const finish = (error: Error | undefined, data: Buffer) => {
+          if (settled) return;
+          settled = true;
+          callback(error, data, data.length);
+        };
+        return {
+          submit: jest.fn((data: Buffer) => {
+            performOutTransfer(data, error => finish(error, data));
+          }),
+          cancel: jest.fn(() => {
+            cancelledTransferCount += 1;
+            finish(new Error('LIBUSB_TRANSFER_CANCELLED'), Buffer.alloc(0));
+          }),
+        };
+      }
+    ),
   };
 
   const iface = {
     descriptor: { bInterfaceClass: 0xff, bInterfaceNumber: 0 },
     endpoints: [epIn, epOut],
     claim: jest.fn(),
-    release: jest.fn((callback: () => void) => callback()),
+    release: jest.fn((closeEndpointsOrCallback: boolean | (() => void), callback?: () => void) => {
+      if (typeof closeEndpointsOrCallback === 'function') closeEndpointsOrCallback();
+      else callback?.();
+    }),
     isKernelDriverActive: jest.fn(() => false),
     detachKernelDriver: jest.fn(),
   };
@@ -164,6 +227,7 @@ const createHarness = () => {
     epIn,
     epOut,
     sentSeqs,
+    getCancelledTransferCount: () => cancelledTransferCount,
     async acquire() {
       await transport.enumerate();
       await transport.acquire({ path, expectedProtocol: 'V2' });
@@ -189,6 +253,43 @@ const createHarness = () => {
 };
 
 describe('NodeUsbTransport Protocol V2 link lifecycle', () => {
+  test('does not retry a native transfer cancelled by probe cleanup', () => {
+    const { transport } = createHarness();
+
+    expect((transport as any).isRetryableError(new Error('LIBUSB_TRANSFER_CANCELLED'))).toBe(false);
+  });
+
+  test('cancels pending native transfers before closing a timed-out protocol probe', async () => {
+    const harness = createHarness();
+    const { transport, path } = harness;
+    await harness.acquire();
+    const cancelActiveTransfers = jest.spyOn(transport as any, 'cancelActiveTransfers');
+    const closeOpenDevice = jest.spyOn(transport as any, 'closeOpenDevice');
+
+    await (transport as any).resetConnectionAfterProbe(path);
+
+    expect(cancelActiveTransfers).toHaveBeenCalledWith(path);
+    expect(closeOpenDevice).toHaveBeenCalledWith(path);
+    expect(cancelActiveTransfers.mock.invocationCallOrder[0]).toBeLessThan(
+      closeOpenDevice.mock.invocationCallOrder[0]
+    );
+  });
+
+  test('stop releases an acquired USB interface even before a Protocol V2 call', async () => {
+    const harness = createHarness();
+    const { transport, path, device, iface } = harness;
+    await transport.enumerate();
+    await transport.acquire({ path, expectedProtocol: 'V2' });
+    device.close.mockClear();
+    iface.release.mockClear();
+
+    await transport.stop();
+
+    expect(iface.release).toHaveBeenCalledTimes(1);
+    expect(device.close).toHaveBeenCalledTimes(1);
+    expect(transport.getProtocolType(path)).toBeUndefined();
+  });
+
   test('trusts explicit Protocol V2 during bootloader reconnect without probing Ping', async () => {
     const harness = createHarness();
     const { transport, path, epOut } = harness;
@@ -196,7 +297,7 @@ describe('NodeUsbTransport Protocol V2 link lifecycle', () => {
     await transport.enumerate();
     await transport.acquire({ path, expectedProtocol: 'V2' });
 
-    expect(epOut.transfer).not.toHaveBeenCalled();
+    expect(epOut.makeTransfer).not.toHaveBeenCalled();
     expect(transport.getProtocolType(path)).toBe('V2');
     await transport.release(path);
   });
@@ -219,14 +320,14 @@ describe('NodeUsbTransport Protocol V2 link lifecycle', () => {
     const harness = createHarness();
     const { transport, path, epOut } = harness;
     await harness.acquire();
-    epOut.transfer.mockClear();
+    epOut.makeTransfer.mockClear();
     harness.failNextWrite(new Error('LIBUSB_ERROR_IO'));
 
     await expect(transport.call(path, 'Ping', { message: 'write-failure' })).rejects.toThrow(
       'LIBUSB_ERROR_IO'
     );
 
-    expect(epOut.transfer).toHaveBeenCalledTimes(1);
+    expect(epOut.makeTransfer).toHaveBeenCalledTimes(1);
   });
 
   test('rejects a pending read when release invalidates the link', async () => {
@@ -253,6 +354,20 @@ describe('NodeUsbTransport Protocol V2 link lifecycle', () => {
     expect(settled).not.toBe('still pending');
   });
 
+  test('stop cancels an in-flight native USB transfer before releasing the interface', async () => {
+    const harness = createHarness();
+    const { transport, path } = harness;
+    await harness.acquire();
+    const pendingRead = harness.holdRead();
+
+    const call = transport.call(path, 'Ping', { message: 'pending' }, { timeoutMs: 5000 });
+    await pendingRead.started;
+    await transport.stop();
+
+    await expect(call).rejects.toThrow();
+    expect(harness.getCancelledTransferCount()).toBe(1);
+  });
+
   test('keeps the cursor after a response timeout rebuilds the USB connection', async () => {
     const harness = createHarness();
     const { transport, path, sentSeqs } = harness;

package/dist/index.d.ts

@@ -2,8 +2,18 @@ import * as transport from '@onekeyfe/hd-transport';
 import transport__default, { ProtocolV2UsbTransportBase, OneKeyDeviceInfo, AcquireInput, TransportCallOptions, ProtocolV2Schemas, ProtocolV2CallContext, ProtocolType } from '@onekeyfe/hd-transport';
 import EventEmitter from 'events';
 
+/**
+ * Node.js USB Transport — complete transport implementation using libusb.
+ *
+ * Unlike the old UsbPlugin (which was a LowlevelTransportSharedPlugin piped
+ * through LowlevelTransport), this class is a standalone transport that handles
+ * both protocol encoding/decoding and USB I/O directly.
+ *
+ * Modeled after WebUsbTransport.
+ */
 declare class NodeUsbTransport extends ProtocolV2UsbTransportBase<string> {
     messages: ReturnType<typeof transport__default.parseConfigure> | undefined;
+    /** Protobuf schema for Protocol V2 transports. */
     messagesV2: ReturnType<typeof transport__default.parseConfigure> | undefined;
     name: string;
     version: string;
@@ -11,39 +21,99 @@ declare class NodeUsbTransport extends ProtocolV2UsbTransportBase<string> {
     isOutdated: boolean;
     Log?: any;
     emitter?: EventEmitter;
+    /** serial → bus id, built during enumerate */
     private serialToBusId;
+    /** path → opened device state */
     private openDevices;
+    /** Per-path protocol type detected by active wire-level probe. */
     private deviceProtocol;
+    /** per-path reconnect lock to prevent concurrent reconnects */
     private reconnectLocks;
+    /**
+     * Retain the low-level Transfer so release()/stop() can cancel native pending reads.
+     * Endpoint.transfer() hides it and may keep the CLI alive after output completes.
+     */
+    private activeTransfers;
+    /** set to true when cancel() is called; checked by retry loops */
     private cancelled;
     constructor();
+    /**
+     * Initialize transport.
+     * Signature matches the Transport.init interface (logger, emitter).
+     */
     init(logger: any, emitter?: EventEmitter): Promise<string>;
     configure(signedData: any): Promise<void>;
     configureProtocolV2(signedData: any): void;
     listen(): void;
-    stop(): void;
+    stop(): Promise<void>;
+    /**
+     * Low-level post (send only, no response). Not used by NodeUsbTransport
+     * since call() handles the full send+receive cycle, but required by the Transport interface.
+     */
     post(path: string, name: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Low-level read (receive only). Not used by NodeUsbTransport
+     * since call() handles the full send+receive cycle, but required by the Transport interface.
+     */
     read(path: string): Promise<{
         message: {
             [key: string]: any;
         };
         type: string;
     }>;
+    /**
+     * Enumerate connected OneKey USB devices.
+     * Opens each device briefly to read its serial number (used as `path`),
+     * then closes it. acquire() re-opens from a fresh getDeviceList().
+     */
     enumerate(): Promise<OneKeyDeviceInfo[]>;
+    /**
+     * Acquire device — open USB device, claim interface, return path (string).
+     */
     acquire(input: AcquireInput): Promise<string>;
+    /**
+     * Release device — release interface and close.
+     */
     release(path: string, _onclose?: boolean): Promise<void>;
+    private cancelActiveTransfers;
+    private createTrackedTransfer;
+    private transferInOnce;
+    private transferOutOnce;
     private closeOpenDevice;
+    /**
+     * Call device method — encode protobuf, send packets, receive response.
+     * This is the core method that replaces LowlevelTransport's call + UsbPlugin's send/receive.
+     */
     call(path: string, name: string, data: Record<string, unknown>, options?: TransportCallOptions): Promise<transport.MessageFromOneKey>;
     private callProtocolV1;
     cancel(): void;
+    /**
+     * Get the current open device for a path, re-resolving from the map
+     * so callers always use a fresh reference after reconnect.
+     */
     private getOpenDevice;
     private getErrorMessage;
     private isRetryableError;
     private isUsbTransferTimeout;
     private getDeviceInterface;
+    /**
+     * Reconnect device before retrying a failed transfer (aligned with WebUsbTransport).
+     * Uses per-path lock to prevent concurrent reconnects to the same device.
+     */
     private reconnectForRetry;
+    /**
+     * Send all encoded chunks to the device with retry.
+     * If a chunk fails and triggers reconnect, the entire sequence restarts
+     * from chunk 0 because the device resets protocol state on reconnect.
+     */
     private sendAllChunksWithRetry;
+    /**
+     * USB IN transfer with retry and reconnect (aligned with WebUsbTransport).
+     */
     private transferInWithRetry;
+    /**
+     * Open a USB device by path (serial number), claim interface, cache endpoints.
+     */
     private openDevice;
     private drainStaleInput;
     private createProtocolMismatchError;
@@ -61,6 +131,10 @@ declare class NodeUsbTransport extends ProtocolV2UsbTransportBase<string> {
     protected onProtocolV2UsbLinkInvalidated(path: string, reason: string): void;
     protected createProtocolV2UsbTimeoutError(name: string, timeoutMs: number): Error;
     private callProtocolV2;
+    /**
+     * Receive a complete protobuf response from the device.
+     * Reads 64-byte packets, strips 0x3F marker, reassembles into hex string.
+     */
     private receiveData;
     getProtocolType(path: string): ProtocolType | undefined;
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -140,26 +140,6 @@ function readSerialNumber(dev, openDevices) {
         }
     });
 }
-function transferInOnce(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 transferOutOnce(ep, data) {
-    return new Promise((resolve, reject) => {
-        ep.transfer(data, (err) => {
-            if (err)
-                return reject(err);
-            resolve();
-        });
-    });
-}
 function skipReportByte(packet) {
     if (packet[0] === REPORT_ID) {
         return packet.subarray(1);
@@ -184,6 +164,7 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
         this.openDevices = new Map();
         this.deviceProtocol = new Map();
         this.reconnectLocks = new Map();
+        this.activeTransfers = new Map();
         this.cancelled = false;
     }
     init(logger, emitter) {
@@ -204,7 +185,23 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
     listen() {
     }
     stop() {
-        this.disposeProtocolV2UsbLinks('Node USB transport stopped').catch(error => { var _a; return (_a = this.Log) === null || _a === void 0 ? void 0 : _a.debug('[NodeUsbTransport] stop link cleanup failed:', error); });
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            this.cancelled = true;
+            yield this.cancelActiveTransfers();
+            try {
+                yield this.disposeProtocolV2UsbLinks('Node USB transport stopped');
+            }
+            catch (error) {
+                (_a = this.Log) === null || _a === void 0 ? void 0 : _a.debug('[NodeUsbTransport] stop link cleanup failed:', error);
+            }
+            yield Promise.allSettled(this.reconnectLocks.values());
+            yield this.cancelActiveTransfers();
+            yield Promise.all(Array.from(this.openDevices.keys(), path => this.closeOpenDevice(path)));
+            this.reconnectLocks.clear();
+            this.deviceProtocol.clear();
+            this.serialToBusId.clear();
+        });
     }
     post(path, name, data) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -276,11 +273,83 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
     }
     release(path, _onclose) {
         return __awaiter(this, void 0, void 0, function* () {
+            yield this.cancelActiveTransfers(path);
             yield this.invalidateProtocolV2UsbLink(path, 'Node USB transport released');
             yield this.closeOpenDevice(path);
             this.deviceProtocol.delete(path);
         });
     }
+    cancelActiveTransfers(path) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const transfers = Array.from(this.activeTransfers.entries()).filter(([, active]) => path === undefined || active.path === path);
+            transfers.forEach(([transfer]) => {
+                try {
+                    transfer.cancel();
+                }
+                catch (_a) {
+                }
+            });
+            yield Promise.allSettled(transfers.map(([, active]) => active.settled));
+        });
+    }
+    createTrackedTransfer(path, endpoint, callback) {
+        let resolveSettled = () => undefined;
+        const settled = new Promise(resolve => {
+            resolveSettled = resolve;
+        });
+        const transfer = endpoint.makeTransfer(endpoint.timeout, (error, buffer, actualLength) => {
+            this.activeTransfers.delete(transfer);
+            resolveSettled();
+            callback(error, buffer, actualLength);
+        });
+        this.activeTransfers.set(transfer, { path, settled, resolveSettled });
+        return transfer;
+    }
+    transferInOnce(path, ep, length) {
+        return new Promise((resolve, reject) => {
+            const buffer = Buffer.alloc(length);
+            const transfer = this.createTrackedTransfer(path, ep, (error, _submittedBuffer, actualLength) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                if (actualLength <= 0) {
+                    reject(new Error('Empty USB transfer'));
+                    return;
+                }
+                resolve(buffer.subarray(0, actualLength));
+            });
+            try {
+                transfer.submit(buffer);
+            }
+            catch (error) {
+                const active = this.activeTransfers.get(transfer);
+                this.activeTransfers.delete(transfer);
+                active === null || active === void 0 ? void 0 : active.resolveSettled();
+                reject(error);
+            }
+        });
+    }
+    transferOutOnce(path, ep, data) {
+        return new Promise((resolve, reject) => {
+            const transfer = this.createTrackedTransfer(path, ep, error => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+            try {
+                transfer.submit(data);
+            }
+            catch (error) {
+                const active = this.activeTransfers.get(transfer);
+                this.activeTransfers.delete(transfer);
+                active === null || active === void 0 ? void 0 : active.resolveSettled();
+                reject(error);
+            }
+        });
+    }
     closeOpenDevice(path) {
         return __awaiter(this, void 0, void 0, function* () {
             const openDev = this.openDevices.get(path);
@@ -370,6 +439,9 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
     }
     isRetryableError(error) {
         const message = this.getErrorMessage(error).toLowerCase();
+        if (message.includes('cancelled') || message.includes('canceled')) {
+            return false;
+        }
         return (message.includes('libusb') ||
             message.includes('transfer') ||
             message.includes('disconnected') ||
@@ -438,7 +510,7 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
                         const packet = new Uint8Array(PACKET_SIZE);
                         packet[0] = REPORT_ID;
                         packet.set(new Uint8Array(buffer), 1);
-                        yield transferOutOnce(this.getOpenDevice(path).epOut, Buffer.from(packet));
+                        yield this.transferOutOnce(path, this.getOpenDevice(path).epOut, Buffer.from(packet));
                     }
                     return;
                 }
@@ -471,7 +543,7 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
                     throw hdShared.ERRORS.TypedError(hdShared.HardwareErrorCode.DeviceInterruptedFromOutside, 'Cancelled');
                 }
                 try {
-                    return yield transferInOnce(currentDev.epIn, length);
+                    return yield this.transferInOnce(path, currentDev.epIn, length);
                 }
                 catch (error) {
                     lastError = error;
@@ -530,7 +602,7 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
                 }
                 epIn.timeout = TRANSFER_TIMEOUT_MS;
                 epOut.timeout = TRANSFER_TIMEOUT_MS;
-                yield this.drainStaleInput(epIn);
+                yield this.drainStaleInput(path, epIn);
                 this.openDevices.set(path, { device: dev, iface, epIn, epOut });
             }
             catch (err) {
@@ -543,14 +615,14 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
             }
         });
     }
-    drainStaleInput(epIn) {
+    drainStaleInput(path, epIn) {
         return __awaiter(this, void 0, void 0, function* () {
             const originalTimeout = epIn.timeout;
             epIn.timeout = 50;
             try {
                 for (let index = 0; index < 16; index += 1) {
                     try {
-                        yield transferInOnce(epIn, PACKET_SIZE);
+                        yield this.transferInOnce(path, epIn, PACKET_SIZE);
                     }
                     catch (_a) {
                         break;
@@ -604,6 +676,7 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.rotateProtocolV2UsbGeneration(path, 'Node USB protocol probe reset');
             try {
+                yield this.cancelActiveTransfers(path);
                 yield this.closeOpenDevice(path);
             }
             catch (error) {
@@ -695,7 +768,7 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
             if (this.cancelled) {
                 throw hdShared.ERRORS.TypedError(hdShared.HardwareErrorCode.DeviceInterruptedFromOutside, 'Cancelled');
             }
-            yield transferOutOnce(this.getOpenDevice(path).epOut, Buffer.from(frame));
+            yield this.transferOutOnce(path, this.getOpenDevice(path).epOut, Buffer.from(frame));
         });
     }
     readProtocolV2UsbPacket(path, _context) {
@@ -705,7 +778,7 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
                     throw hdShared.ERRORS.TypedError(hdShared.HardwareErrorCode.DeviceInterruptedFromOutside, 'Cancelled');
                 }
                 try {
-                    const packet = yield transferInOnce(this.getOpenDevice(path).epIn, transport.PROTOCOL_V2_FRAME_MAX_BYTES);
+                    const packet = yield this.transferInOnce(path, this.getOpenDevice(path).epIn, transport.PROTOCOL_V2_FRAME_MAX_BYTES);
                     return new Uint8Array(packet.buffer.slice(packet.byteOffset, packet.byteOffset + packet.byteLength));
                 }
                 catch (error) {
@@ -718,6 +791,7 @@ class NodeUsbTransport extends transport.ProtocolV2UsbTransportBase {
     }
     resetProtocolV2UsbNativeLink(path, _reason) {
         return __awaiter(this, void 0, void 0, function* () {
+            yield this.cancelActiveTransfers(path);
             yield this.closeOpenDevice(path);
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-transport-usb",
-  "version": "1.2.0-alpha.19",
+  "version": "1.2.0-alpha.20",
   "description": "OneKey hardware wallet direct USB transport plugin (libusb)",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
   "license": "MIT",
@@ -20,10 +20,10 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@onekeyfe/hd-shared": "1.2.0-alpha.19",
-    "@onekeyfe/hd-transport": "1.2.0-alpha.19",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.20",
+    "@onekeyfe/hd-transport": "1.2.0-alpha.20",
     "bytebuffer": "^5.0.1",
     "usb": "^2.14.0"
   },
-  "gitHead": "4e79f6a400463f342285b9a761b6b84523f1d6b9"
+  "gitHead": "5fbc1ada90fd3cfda7e5ef08be368cb452018733"
 }

package/src/index.ts

@@ -131,31 +131,6 @@ function readSerialNumber(dev: usb.Device, openDevices?: Map<string, OpenDevice>
   });
 }
 
-/**
- * Promisified USB IN transfer (single attempt).
- */
-function transferInOnce(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 (single attempt).
- */
-function transferOutOnce(ep: usb.OutEndpoint, data: Buffer): Promise<void> {
-  return new Promise((resolve, reject) => {
-    ep.transfer(data, (err: Error | undefined) => {
-      if (err) return reject(err);
-      resolve();
-    });
-  });
-}
-
 /**
  * Skip the 0x3F protocol marker byte from a USB packet.
  */
@@ -212,6 +187,15 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
   /** per-path reconnect lock to prevent concurrent reconnects */
   private reconnectLocks = new Map<string, Promise<OpenDevice>>();
 
+  /**
+   * Retain the low-level Transfer so release()/stop() can cancel native pending reads.
+   * Endpoint.transfer() hides it and may keep the CLI alive after output completes.
+   */
+  private activeTransfers = new Map<
+    usb.Transfer,
+    { path: string; settled: Promise<void>; resolveSettled: () => void }
+  >();
+
   /** set to true when cancel() is called; checked by retry loops */
   private cancelled = false;
 
@@ -251,10 +235,27 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
     // empty — could add hotplug events via usb.on('attach'/'detach')
   }
 
-  stop() {
-    this.disposeProtocolV2UsbLinks('Node USB transport stopped').catch(error =>
-      this.Log?.debug('[NodeUsbTransport] stop link cleanup failed:', error)
-    );
+  async stop(): Promise<void> {
+    this.cancelled = true;
+
+    await this.cancelActiveTransfers();
+
+    try {
+      await this.disposeProtocolV2UsbLinks('Node USB transport stopped');
+    } catch (error) {
+      this.Log?.debug('[NodeUsbTransport] stop link cleanup failed:', error);
+    }
+
+    // Reconnect may already be in flight when dispose starts. Wait for it to
+    // settle, then close every remaining handle so it cannot reopen USB after
+    // the first cleanup pass.
+    await Promise.allSettled(this.reconnectLocks.values());
+    await this.cancelActiveTransfers();
+    await Promise.all(Array.from(this.openDevices.keys(), path => this.closeOpenDevice(path)));
+
+    this.reconnectLocks.clear();
+    this.deviceProtocol.clear();
+    this.serialToBusId.clear();
   }
 
   /**
@@ -344,11 +345,93 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
    * Release device — release interface and close.
    */
   async release(path: string, _onclose?: boolean): Promise<void> {
+    await this.cancelActiveTransfers(path);
     await this.invalidateProtocolV2UsbLink(path, 'Node USB transport released');
     await this.closeOpenDevice(path);
     this.deviceProtocol.delete(path);
   }
 
+  private async cancelActiveTransfers(path?: string): Promise<void> {
+    const transfers = Array.from(this.activeTransfers.entries()).filter(
+      ([, active]) => path === undefined || active.path === path
+    );
+    transfers.forEach(([transfer]) => {
+      try {
+        transfer.cancel();
+      } catch {
+        // A transfer may finish between the snapshot and cancel().
+      }
+    });
+    await Promise.allSettled(transfers.map(([, active]) => active.settled));
+  }
+
+  private createTrackedTransfer(
+    path: string,
+    endpoint: usb.InEndpoint | usb.OutEndpoint,
+    callback: (error: Error | undefined, buffer: Buffer, actualLength: number) => void
+  ): usb.Transfer {
+    let resolveSettled: () => void = () => undefined;
+    const settled = new Promise<void>(resolve => {
+      resolveSettled = resolve;
+    });
+    const transfer = endpoint.makeTransfer(endpoint.timeout, (error, buffer, actualLength) => {
+      this.activeTransfers.delete(transfer);
+      resolveSettled();
+      callback(error, buffer, actualLength);
+    });
+    this.activeTransfers.set(transfer, { path, settled, resolveSettled });
+    return transfer;
+  }
+
+  private transferInOnce(path: string, ep: usb.InEndpoint, length: number): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const buffer = Buffer.alloc(length);
+      const transfer = this.createTrackedTransfer(
+        path,
+        ep,
+        (error, _submittedBuffer, actualLength) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          if (actualLength <= 0) {
+            reject(new Error('Empty USB transfer'));
+            return;
+          }
+          resolve(buffer.subarray(0, actualLength));
+        }
+      );
+      try {
+        transfer.submit(buffer);
+      } catch (error) {
+        const active = this.activeTransfers.get(transfer);
+        this.activeTransfers.delete(transfer);
+        active?.resolveSettled();
+        reject(error);
+      }
+    });
+  }
+
+  private transferOutOnce(path: string, ep: usb.OutEndpoint, data: Buffer): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const transfer = this.createTrackedTransfer(path, ep, error => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+      try {
+        transfer.submit(data);
+      } catch (error) {
+        const active = this.activeTransfers.get(transfer);
+        this.activeTransfers.delete(transfer);
+        active?.resolveSettled();
+        reject(error);
+      }
+    });
+  }
+
   private async closeOpenDevice(path: string): Promise<void> {
     const openDev = this.openDevices.get(path);
     if (!openDev) return;
@@ -468,6 +551,12 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
 
   private isRetryableError(error: unknown): boolean {
     const message = this.getErrorMessage(error).toLowerCase();
+    // cancelActiveTransfers() terminates timed-out or releasing native requests.
+    // LIBUSB_TRANSFER_CANCELLED is not transient. Retrying would start another pending
+    // read on the rebuilt interface and race protocol probing against release.
+    if (message.includes('cancelled') || message.includes('canceled')) {
+      return false;
+    }
     return (
       message.includes('libusb') ||
       message.includes('transfer') ||
@@ -572,7 +661,7 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
           const packet = new Uint8Array(PACKET_SIZE);
           packet[0] = REPORT_ID;
           packet.set(new Uint8Array(buffer), 1);
-          await transferOutOnce(this.getOpenDevice(path).epOut, Buffer.from(packet));
+          await this.transferOutOnce(path, this.getOpenDevice(path).epOut, Buffer.from(packet));
         }
         return; // all chunks sent successfully
       } catch (error) {
@@ -615,7 +704,7 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
         throw ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromOutside, 'Cancelled');
       }
       try {
-        return await transferInOnce(currentDev.epIn, length);
+        return await this.transferInOnce(path, currentDev.epIn, length);
       } catch (error) {
         lastError = error;
         if (options?.waitIndefinitelyOnTimeout && this.isUsbTransferTimeout(error)) {
@@ -695,7 +784,7 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
       epIn.timeout = TRANSFER_TIMEOUT_MS;
       epOut.timeout = TRANSFER_TIMEOUT_MS;
 
-      await this.drainStaleInput(epIn);
+      await this.drainStaleInput(path, epIn);
 
       this.openDevices.set(path, { device: dev, iface, epIn, epOut });
     } catch (err) {
@@ -708,14 +797,14 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
     }
   }
 
-  private async drainStaleInput(epIn: usb.InEndpoint): Promise<void> {
+  private async drainStaleInput(path: string, epIn: usb.InEndpoint): Promise<void> {
     const originalTimeout = epIn.timeout;
     epIn.timeout = 50;
     try {
       // Drain a small bounded number of packets left by the previous USB session.
       for (let index = 0; index < 16; index += 1) {
         try {
-          await transferInOnce(epIn, PACKET_SIZE);
+          await this.transferInOnce(path, epIn, PACKET_SIZE);
         } catch {
           break;
         }
@@ -744,9 +833,9 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
     expectedProtocol?: ProtocolType
   ): Promise<ProtocolType> {
     if (expectedProtocol === 'V2') {
-      // 固件升级重启后的 bootloader 不保证响应 Ping。上层显式传入 V2
-      // 表示协议已在重启前确认；直接建立 V2 链路，由首个业务命令验证
-      // bootloader 是否已经完成 USB 初始化。
+      // Bootloader may not answer Ping after an update reboot. An explicit V2 hint means
+      // the protocol was confirmed earlier; establish the link and let the first command
+      // verify that USB initialization completed.
       this.deviceProtocol.set(path, 'V2');
       this.Log?.debug(`[NodeUsbTransport] detectProtocol: path=${path} -> V2 (expected)`);
       return 'V2';
@@ -783,6 +872,10 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
     await this.rotateProtocolV2UsbGeneration(path, 'Node USB protocol probe reset');
 
     try {
+      // A timed-out probe may leave an IN transfer pending. Cancel and await it before
+      // closing the interface, or libusb may never callback and release()/stop() will
+      // wait forever, surfacing as Polling timeout (809).
+      await this.cancelActiveTransfers(path);
       await this.closeOpenDevice(path);
     } catch (error) {
       this.Log?.debug('[NodeUsbTransport] close after protocol probe error:', error);
@@ -883,7 +976,7 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
     if (this.cancelled) {
       throw ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromOutside, 'Cancelled');
     }
-    await transferOutOnce(this.getOpenDevice(path).epOut, Buffer.from(frame));
+    await this.transferOutOnce(path, this.getOpenDevice(path).epOut, Buffer.from(frame));
   }
 
   protected async readProtocolV2UsbPacket(
@@ -895,7 +988,8 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
         throw ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromOutside, 'Cancelled');
       }
       try {
-        const packet = await transferInOnce(
+        const packet = await this.transferInOnce(
+          path,
           this.getOpenDevice(path).epIn,
           PROTOCOL_V2_FRAME_MAX_BYTES
         );
@@ -911,6 +1005,7 @@ export default class NodeUsbTransport extends ProtocolV2UsbTransportBase<string>
   }
 
   protected async resetProtocolV2UsbNativeLink(path: string, _reason: string): Promise<void> {
+    await this.cancelActiveTransfers(path);
     await this.closeOpenDevice(path);
   }