@onekeyfe/hd-transport-web-device 1.2.8-alpha.16 → 1.2.8-alpha.18

package/__tests__/webusb-identity-probe.test.ts

@@ -2,8 +2,11 @@ import { ERRORS, HardwareErrorCode, createDeferred } from '@onekeyfe/hd-shared';
 
 import WebUsbTransport from '../src/webusb';
 import { probeUsbDeviceIdentities } from '@onekeyfe/hd-common-connect-sdk/src';
+import Core from '@onekeyfe/hd-core/src/core';
+import TransportManager from '@onekeyfe/hd-core/src/data-manager/TransportManager';
+import { Device } from '@onekeyfe/hd-core/src/device/Device';
 
-import type { MessageFromOneKey, TransportCallOptions } from '@onekeyfe/hd-transport';
+import type { MessageFromOneKey, Transport, TransportCallOptions } from '@onekeyfe/hd-transport';
 
 jest.mock('@onekeyfe/hd-core', () => jest.requireActual('../../core/src'));
 jest.mock('../../core/src/data/config', () => ({
@@ -19,7 +22,7 @@ jest.mock('@onekeyfe/hd-transport-emulator', () => ({}));
 
 type PacketIoTransport = {
   rotateProtocolV2UsbGeneration: () => Promise<void>;
-  detectProtocol: () => Promise<'V1'>;
+  detectProtocol: () => Promise<'V1' | 'V2'>;
   transferInWithRetry: (path: string, length: number) => Promise<DataView>;
   transferInOnce: (path: string, length: number) => Promise<DataView>;
   transferOutWithRetry: (path: string, packet: Uint8Array) => Promise<void>;
@@ -64,6 +67,251 @@ describe('WebUSB identity probe ownership', () => {
     else delete (globalThis as { navigator?: Navigator }).navigator;
   });
 
+  function createAcquiredTransport(protocol: 'V1' | 'V2' = 'V1') {
+    const active = new WebUsbTransport();
+    active.init({ debug: jest.fn() });
+    jest
+      .spyOn(active as unknown as PacketIoTransport, 'detectProtocol')
+      .mockResolvedValue(protocol);
+    jest.spyOn(active, 'connect').mockImplementation(() => {
+      device.opened = true;
+      return Promise.resolve();
+    });
+    return active;
+  }
+
+  test.each(['V1', 'V2'] as const)(
+    'Core disposal releases a retained %s USB session for a new transport',
+    async protocol => {
+      const active = createAcquiredTransport(protocol);
+      const next = createAcquiredTransport(protocol);
+      const selected = new Device({
+        path: 'USB_PATH',
+        id: 'USB_PATH',
+        name: 'Mock device',
+        commType: 'webusb',
+        debug: false,
+      });
+      selected.keepSession = true;
+      selected.mainId = 'USB_PATH';
+      jest.spyOn(selected, 'isUsedHere').mockReturnValue(true);
+      const release = jest.spyOn(active, 'release');
+      jest.spyOn(TransportManager, 'getTransport').mockReturnValue(active as unknown as Transport);
+      const core = new Core();
+      try {
+        await active.acquire({ path: 'USB_PATH' });
+        await selected.release();
+        expect(release).not.toHaveBeenCalled();
+        expect(device.opened).toBe(true);
+        await core.dispose();
+        await core.dispose();
+        expect(device.opened).toBe(false);
+        expect(device.close).toHaveBeenCalledTimes(1);
+        await expect(next.acquire({ path: 'USB_PATH' })).resolves.toBe('USB_PATH');
+      } finally {
+        await active.release('USB_PATH');
+        await next.release('USB_PATH');
+        jest.restoreAllMocks();
+      }
+    }
+  );
+
+  test('stop waits for a pending native open and closes its captured handle', async () => {
+    const entered = createDeferred<void>();
+    const opening = createDeferred<void>();
+    const native = Object.assign(device, {
+      open: jest.fn(async () => {
+        entered.resolve();
+        await opening.promise;
+        device.opened = true;
+      }),
+      reset: jest.fn(),
+      configurations: [],
+      configuration: { configurationValue: 1 },
+      selectConfiguration: jest.fn(),
+      claimInterface: jest.fn(),
+      clearHalt: jest.fn(),
+    });
+    const active = new WebUsbTransport();
+    active.init({ debug: jest.fn() });
+    const connecting = active.connectToDevice('USB_PATH', true);
+    const result = expect(connecting).rejects.toThrow('WebUSB transport is stopped');
+    try {
+      await entered.promise;
+      let stopped = false;
+      const stopping = active.stop().then(() => {
+        stopped = true;
+      });
+      await Promise.resolve();
+      expect(stopped).toBe(false);
+      opening.resolve();
+      await result;
+      await stopping;
+      expect(native.reset).not.toHaveBeenCalled();
+      expect(native.claimInterface).not.toHaveBeenCalled();
+      expect(device.opened).toBe(false);
+      const next = createAcquiredTransport();
+      await expect(next.acquire({ path: 'USB_PATH' })).resolves.toBe('USB_PATH');
+      await next.release('USB_PATH');
+    } finally {
+      opening.resolve();
+      await connecting.catch(() => undefined);
+      await active.release('USB_PATH');
+      jest.restoreAllMocks();
+    }
+  });
+
+  test.each(['read', 'read retry', 'write', 'write retry'])(
+    'stop rejects a late native %s result without touching the new owner',
+    async operation => {
+      const entered = createDeferred<void>();
+      const packet = createDeferred<{ status: 'ok'; data: DataView; bytesWritten: number }>();
+      Object.assign(device, {
+        transferIn: jest.fn(() => {
+          entered.resolve();
+          return packet.promise;
+        }),
+        transferOut: jest.fn(() => {
+          entered.resolve();
+          return packet.promise;
+        }),
+      });
+      const active = createAcquiredTransport();
+      const next = createAcquiredTransport();
+      await active.acquire({ path: 'USB_PATH' });
+      const state = active as unknown as PacketIoTransport;
+      let call: Promise<unknown>;
+      if (operation === 'read') call = state.transferInOnce('USB_PATH', 64);
+      else if (operation === 'read retry') call = state.transferInWithRetry('USB_PATH', 64);
+      else if (operation === 'write') call = state.transferOutOnce('USB_PATH', new Uint8Array([1]));
+      else call = state.transferOutWithRetry('USB_PATH', new Uint8Array([1]));
+      const result = expect(call).rejects.toThrow('WebUSB transport is stopped');
+      try {
+        await entered.promise;
+        await active.stop();
+        await next.acquire({ path: 'USB_PATH' });
+        packet.resolve({ status: 'ok', data: new DataView(new ArrayBuffer(64)), bytesWritten: 1 });
+        await result;
+        expect(device.close).toHaveBeenCalledTimes(1);
+        expect(device.opened).toBe(true);
+      } finally {
+        packet.resolve({ status: 'ok', data: new DataView(new ArrayBuffer(64)), bytesWritten: 1 });
+        await call.catch(() => undefined);
+        await active.release('USB_PATH');
+        await next.release('USB_PATH');
+        jest.restoreAllMocks();
+      }
+    }
+  );
+
+  test.each(['in', 'out'] as const)(
+    'stop prevents a delayed transfer%s retry from closing or reopening the new owner',
+    async direction => {
+      const entered = createDeferred<void>();
+      const native = Object.assign(device, {
+        transferIn: jest.fn().mockRejectedValue(new Error('transferIn NetworkError')),
+        transferOut: jest.fn().mockRejectedValue(new Error('transferOut NetworkError')),
+      });
+      const active = createAcquiredTransport();
+      const next = createAcquiredTransport();
+      await active.acquire({ path: 'USB_PATH' });
+      const state = active as unknown as PacketIoTransport;
+      const retry = state.reconnectForPacketIoRetry.bind(active);
+      jest.spyOn(state, 'reconnectForPacketIoRetry').mockImplementation((...args) => {
+        entered.resolve();
+        return retry(...args);
+      });
+      const call =
+        direction === 'in'
+          ? state.transferInWithRetry('USB_PATH', 64)
+          : state.transferOutWithRetry('USB_PATH', new Uint8Array([1]));
+      const result = expect(call).rejects.toThrow('WebUSB transport is stopped');
+      try {
+        await entered.promise;
+        await active.stop();
+        await next.acquire({ path: 'USB_PATH' });
+        await result;
+        expect(native[direction === 'in' ? 'transferIn' : 'transferOut']).toHaveBeenCalledTimes(1);
+        expect(device.close).toHaveBeenCalledTimes(1);
+        expect(device.opened).toBe(true);
+      } finally {
+        await call.catch(() => undefined);
+        await active.release('USB_PATH');
+        await next.release('USB_PATH');
+        jest.restoreAllMocks();
+      }
+    }
+  );
+
+  test('failed stop keeps ownership until a later discovery confirms native closure', async () => {
+    const active = createAcquiredTransport();
+    const next = createAcquiredTransport();
+    const failure = new Error('native close failed');
+    await active.acquire({ path: 'USB_PATH' });
+    device.close.mockRejectedValueOnce(failure).mockRejectedValueOnce(failure);
+    try {
+      await expect(active.stop()).rejects.toBe(failure);
+      await next.getConnectedDevices();
+      await expect(next.acquire({ path: 'USB_PATH' })).rejects.toThrow(
+        'USB device is already in use'
+      );
+      expect(device.opened).toBe(true);
+      await next.getConnectedDevices();
+      expect(device.opened).toBe(false);
+      await expect(next.acquire({ path: 'USB_PATH' })).resolves.toBe('USB_PATH');
+      expect(device.close).toHaveBeenCalledTimes(3);
+    } finally {
+      await active.release('USB_PATH');
+      await next.release('USB_PATH');
+      jest.restoreAllMocks();
+    }
+  });
+
+  test('stop closes captured handles across paths without closing re-enumerated or foreign handles', async () => {
+    const other = {
+      ...device,
+      serialNumber: 'OTHER_PATH',
+      close: jest.fn(() => {
+        other.opened = false;
+        return Promise.resolve();
+      }),
+    };
+    const foreign = { ...device, serialNumber: 'FOREIGN_PATH', close: jest.fn() };
+    usb.getDevices.mockResolvedValue([device, other, foreign]);
+    const active = createAcquiredTransport();
+    jest.spyOn(active, 'connect').mockImplementation(path => {
+      (path === 'USB_PATH' ? device : other).opened = true;
+      return Promise.resolve();
+    });
+    const current = createAcquiredTransport();
+    jest.spyOn(current, 'connect').mockImplementation(() => {
+      foreign.opened = true;
+      return Promise.resolve();
+    });
+    const currentDisconnect = jest.spyOn(current, 'markProtocolStale');
+    try {
+      await active.acquire({ path: 'USB_PATH' });
+      await active.acquire({ path: 'OTHER_PATH' });
+      await current.acquire({ path: 'FOREIGN_PATH' });
+      const replacement = { ...device, opened: false, close: jest.fn() };
+      usb.getDevices.mockResolvedValue([replacement, foreign]);
+      await active.getConnectedDevices();
+      await active.stop();
+      expect(device.opened).toBe(false);
+      expect(other.opened).toBe(false);
+      expect(replacement.close).not.toHaveBeenCalled();
+      expect(foreign.close).not.toHaveBeenCalled();
+      expect(foreign.opened).toBe(true);
+      disconnectListener({ device: replacement });
+      expect(currentDisconnect).toHaveBeenCalledWith('USB_PATH');
+    } finally {
+      await active.release('USB_PATH');
+      await active.release('OTHER_PATH');
+      await current.release('FOREIGN_PATH');
+      jest.restoreAllMocks();
+    }
+  });
+
   test('does not close a handle already opened by another operation', async () => {
     const probe = new WebUsbTransport(true);
     probe.init({ debug: jest.fn() });

package/dist/index.d.ts

@@ -32,6 +32,8 @@ declare class WebUsbTransport extends ProtocolV2UsbTransportBase<string> {
     private acquiredPaths;
     private identityProbeDevices;
     private normalDevices;
+    private pendingHandleOperations;
+    private stopPromise?;
     private identityProbeCleanupPaths;
     /**
      * The exact USBDevice object each cached protocol was probed against. The
@@ -62,6 +64,10 @@ declare class WebUsbTransport extends ProtocolV2UsbTransportBase<string> {
      * Initialize WebUSB transport
      */
     init(logger: any, emitter?: EventEmitter): void;
+    stop(): Promise<void>;
+    private stopResources;
+    private assertRunning;
+    private runHandleOperation;
     /**
      * Announce that a USB device left. Called from the module-scoped disconnect
      * listener, which is why it is public rather than inlined.

package/dist/index.js

@@ -90,6 +90,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         this.acquiredPaths = new Set();
         this.identityProbeDevices = new Map();
         this.normalDevices = new Map();
+        this.pendingHandleOperations = new Set();
         this.identityProbeCleanupPaths = new Set();
         this.probedDeviceObjects = new Map();
         this.deviceEndpoints = new Map();
@@ -112,6 +113,102 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         if (!this.identityProbe)
             registerActiveWebUsbTransport(this, usb);
     }
+    stop() {
+        this.stopped = true;
+        this.acquiredPaths.clear();
+        if (activeWebUsbTransport === this)
+            activeWebUsbTransport = undefined;
+        if (!this.stopPromise) {
+            this.stopPromise = this.stopResources().catch(error => {
+                this.stopPromise = undefined;
+                throw error;
+            });
+        }
+        return this.stopPromise;
+    }
+    stopResources() {
+        var _a, _b, _c;
+        return __awaiter(this, void 0, void 0, function* () {
+            let cleanupError;
+            try {
+                yield this.disposeProtocolV2UsbLinks('WebUSB transport stopped');
+            }
+            catch (error) {
+                cleanupError = error;
+            }
+            yield Promise.allSettled([...this.pendingHandleOperations]);
+            const handles = this.identityProbe
+                ? [...this.identityProbeDevices].map(([path, device]) => [device, path])
+                : [...this.normalDevices];
+            for (const [device, path] of handles) {
+                if (!this.identityProbe && normalHandleOwners.get(device) !== this) {
+                    this.normalDevices.delete(device);
+                }
+                else {
+                    try {
+                        if (device.opened) {
+                            const iface = (_b = (_a = this.deviceEndpoints.get(path)) === null || _a === void 0 ? void 0 : _a.interfaceNumber) !== null && _b !== void 0 ? _b : this.interfaceId;
+                            try {
+                                yield device.releaseInterface(iface);
+                            }
+                            catch (error) {
+                                (_c = this.Log) === null || _c === void 0 ? void 0 : _c.debug('[WebUsbTransport] stop releaseInterface failed:', error);
+                            }
+                            yield device.close();
+                            if (device.opened)
+                                throw new Error('WebUSB handle remains open after stop');
+                        }
+                        if (this.identityProbe) {
+                            identityProbeHandles.delete(device);
+                            this.identityProbeDevices.delete(path);
+                            this.identityProbeCleanupPaths.delete(path);
+                        }
+                        else {
+                            normalHandleOwners.delete(device);
+                            this.normalDevices.delete(device);
+                        }
+                    }
+                    catch (error) {
+                        cleanupError !== null && cleanupError !== void 0 ? cleanupError : (cleanupError = error);
+                    }
+                }
+            }
+            this.deviceList = [];
+            this.deviceProtocol.clear();
+            this.confirmedDeviceProtocols.clear();
+            this.deviceProtocolHints.clear();
+            this.staleProtocolPaths.clear();
+            this.probedDeviceObjects.clear();
+            if (!this.normalDevices.size && !this.identityProbeDevices.size) {
+                this.deviceEndpoints.clear();
+            }
+            if (cleanupError) {
+                throw cleanupError instanceof Error
+                    ? cleanupError
+                    : new Error(this.getErrorMessage(cleanupError));
+            }
+        });
+    }
+    assertRunning() {
+        if (this.stopped) {
+            throw hdShared.ERRORS.TypedError(hdShared.HardwareErrorCode.RuntimeError, 'WebUSB transport is stopped');
+        }
+    }
+    runHandleOperation(operation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.assertRunning();
+            const pending = Promise.resolve(operation());
+            this.pendingHandleOperations.add(pending);
+            try {
+                const result = yield pending;
+                this.assertRunning();
+                return result;
+            }
+            finally {
+                this.pendingHandleOperations.delete(pending);
+            }
+        });
+    }
     emitDeviceDisconnect(path, device) {
         var _a, _b;
         (_a = this.emitter) === null || _a === void 0 ? void 0 : _a.emit(transport.TRANSPORT_EVENT.DEVICE_DISCONNECT, {
@@ -171,10 +268,24 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         });
     }
     getConnectedDevices() {
+        var _a;
         return __awaiter(this, void 0, void 0, function* () {
+            this.assertRunning();
             if (!this.usb)
                 return [];
             const devices = yield this.usb.getDevices();
+            this.assertRunning();
+            for (const owner of new Set(devices.map(device => normalHandleOwners.get(device)))) {
+                if (owner === null || owner === void 0 ? void 0 : owner.stopped) {
+                    try {
+                        yield owner.stop();
+                    }
+                    catch (error) {
+                        (_a = this.Log) === null || _a === void 0 ? void 0 : _a.debug('[WebUsbTransport] stopped owner cleanup failed:', error);
+                    }
+                }
+            }
+            this.assertRunning();
             const onekeyDevices = devices.filter(dev => {
                 const isOneKey = hdShared.ONEKEY_WEBUSB_FILTER.some((desc) => dev.vendorId === desc.vendorId && dev.productId === desc.productId);
                 return isOneKey && !hdShared.isKnownTrezorWebUsbDevice(dev);
@@ -201,6 +312,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
     acquire(input) {
         var _a, _b, _c, _d, _e, _f, _g;
         return __awaiter(this, void 0, void 0, function* () {
+            this.assertRunning();
             if (!input.path)
                 return;
             if (this.identityProbe) {
@@ -259,12 +371,14 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
                         this.deviceProtocolHints.set(input.path, protocolHint);
                     }
                     const detectedProtocol = yield this.detectProtocol(input.path, input.expectedProtocol, protocolHint);
+                    this.assertRunning();
                     this.confirmedDeviceProtocols.set(input.path, detectedProtocol);
                     const probedDevice = (_g = this.deviceList.find(d => d.path === input.path)) === null || _g === void 0 ? void 0 : _g.device;
                     if (probedDevice) {
                         this.probedDeviceObjects.set(input.path, probedDevice);
                     }
                 }
+                this.assertRunning();
                 this.acquiredPaths.add(input.path);
                 return yield Promise.resolve(input.path);
             }
@@ -357,10 +471,12 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         return __awaiter(this, void 0, void 0, function* () {
             const maxRetries = 5;
             for (let i = 0; i < maxRetries; i++) {
+                this.assertRunning();
                 try {
                     return yield this.connectToDevice(path, first);
                 }
                 catch (e) {
+                    this.assertRunning();
                     if (e instanceof hdShared.HardwareError && e.errorCode === hdShared.HardwareErrorCode.BridgeNeedsPermission) {
                         throw e;
                     }
@@ -403,6 +519,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
     connectToDevice(path, first) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
+            this.assertRunning();
             let device = yield this.findDevice(path);
             if (this.identityProbe && this.identityProbeDevices.get(path) !== device) {
                 yield this.closeOpenDevice(path);
@@ -415,7 +532,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             if (!device.opened) {
                 openingHandles.add(device);
                 try {
-                    yield device.open();
+                    yield this.runHandleOperation(() => device.open());
                 }
                 catch (error) {
                     return yield this.throwWebUsbIoError(path, 'open', error);
@@ -426,9 +543,10 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             }
             if (first || this.deviceProtocol.get(path) !== 'V1') {
                 try {
-                    yield device.reset();
+                    yield this.runHandleOperation(() => device.reset());
                 }
                 catch (error) {
+                    this.assertRunning();
                     (_a = this.Log) === null || _a === void 0 ? void 0 : _a.debug('[WebUsbTransport] reset before claim failed, continuing:', error);
                 }
             }
@@ -445,7 +563,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             if (!device.opened) {
                 openingHandles.add(device);
                 try {
-                    yield device.open();
+                    yield this.runHandleOperation(() => device.open());
                 }
                 catch (error) {
                     return yield this.throwWebUsbIoError(path, 'open', error);
@@ -457,12 +575,12 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             if (first ||
                 !device.configuration ||
                 device.configuration.configurationValue !== this.configurationId) {
-                yield device.selectConfiguration(this.configurationId);
+                yield this.runHandleOperation(() => device.selectConfiguration(this.configurationId));
             }
             const endpoints = this.discoverEndpoints(device);
             this.deviceEndpoints.set(path, endpoints);
             try {
-                yield device.claimInterface(endpoints.interfaceNumber);
+                yield this.runHandleOperation(() => device.claimInterface(endpoints.interfaceNumber));
             }
             catch (error) {
                 return this.throwWebUsbIoError(path, 'claimInterface', error);
@@ -472,6 +590,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         });
     }
     assertHandleAvailable(device) {
+        this.assertRunning();
         const normalOwner = normalHandleOwners.get(device);
         if ((normalOwner && normalOwner !== this) ||
             (identityProbeHandles.has(device) &&
@@ -485,6 +604,8 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         this.normalDevices.set(device, path);
     }
     releaseNormalHandles(path) {
+        if (this.stopped)
+            return;
         for (const [device, ownedPath] of this.normalDevices) {
             if (ownedPath === path) {
                 normalHandleOwners.delete(device);
@@ -498,6 +619,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             this.getErrorMessage(error).includes(USB_DEVICE_IN_USE));
     }
     claimIdentityProbeHandle(path, device) {
+        this.assertRunning();
         if (device.opened ||
             openingHandles.has(device) ||
             identityProbeHandles.has(device) ||
@@ -508,6 +630,8 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         this.identityProbeDevices.set(path, device);
     }
     releaseIdentityProbeHandle(path) {
+        if (this.stopped)
+            return;
         const device = this.identityProbeDevices.get(path);
         if (device === null || device === void 0 ? void 0 : device.opened) {
             this.identityProbeCleanupPaths.add(path);
@@ -521,6 +645,8 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
     closeOpenDevice(path) {
         var _a, _b, _c, _d;
         return __awaiter(this, void 0, void 0, function* () {
+            if (this.stopped)
+                return;
             const current = this.identityProbe
                 ? this.identityProbeDevices.get(path)
                 : (_a = this.deviceList.find(device => device.path === path)) === null || _a === void 0 ? void 0 : _a.device;
@@ -530,14 +656,14 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             const endpoints = this.deviceEndpoints.get(path);
             const ifaceNum = (_b = endpoints === null || endpoints === void 0 ? void 0 : endpoints.interfaceNumber) !== null && _b !== void 0 ? _b : this.interfaceId;
             try {
-                yield current.releaseInterface(ifaceNum);
+                yield this.runHandleOperation(() => current.releaseInterface(ifaceNum));
             }
             catch (error) {
                 (_c = this.Log) === null || _c === void 0 ? void 0 : _c.debug('[WebUsbTransport] releaseInterface before reconnect failed:', error);
             }
             this.assertHandleAvailable(current);
             try {
-                yield current.close();
+                yield this.runHandleOperation(() => current.close());
             }
             catch (error) {
                 (_d = this.Log) === null || _d === void 0 ? void 0 : _d.debug('[WebUsbTransport] close before reconnect failed:', error);
@@ -551,14 +677,16 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         return __awaiter(this, void 0, void 0, function* () {
             this.assertHandleAvailable(device);
             try {
-                yield device.clearHalt(direction, endpointNumber);
+                yield this.runHandleOperation(() => device.clearHalt(direction, endpointNumber));
             }
             catch (error) {
+                this.assertRunning();
                 (_a = this.Log) === null || _a === void 0 ? void 0 : _a.debug(`[WebUsbTransport] clearHalt ${direction} endpoint ${endpointNumber} failed, continuing:`, error);
             }
         });
     }
     assertAcquired(path) {
+        this.assertRunning();
         if (!this.acquiredPaths.has(path)) {
             throw hdShared.ERRORS.TypedError(hdShared.HardwareErrorCode.RuntimeError, `Device is not acquired for ${path}`);
         }
@@ -615,6 +743,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
     throwWebUsbIoError(path, operation, error) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
+            this.assertRunning();
             if (this.isHandleOwnershipError(error) || this.isWebUsbIoHardwareError(error))
                 throw error;
             if (error instanceof transport.ProtocolV2LinkError && error.code !== 'io')
@@ -649,6 +778,8 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
         return /LIBUSB_ERROR_ACCESS|\b(?:access|permission) denied\b/i.test(message);
     }
     isRetryablePacketIoError(error) {
+        if (this.stopped)
+            return false;
         if (this.isHandleOwnershipError(error) || this.isWebUsbIoHardwareError(error))
             return false;
         const message = this.getErrorMessage(error).toLowerCase();
@@ -668,6 +799,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             this.Log.debug(`[WebUsbTransport] transfer${direction} failed, retry ${attempt}/${PACKET_IO_MAX_RETRIES}: ${this.getErrorMessage(error)}`);
             this.staleProtocolPaths.add(path);
             yield hdShared.wait(attempt * PACKET_IO_RETRY_DELAY);
+            this.assertRunning();
             try {
                 const currentDevice = yield this.findDevice(path);
                 this.assertHandleAvailable(currentDevice);
@@ -675,16 +807,17 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
                     const endpoints = this.deviceEndpoints.get(path);
                     const ifaceNum = (_a = endpoints === null || endpoints === void 0 ? void 0 : endpoints.interfaceNumber) !== null && _a !== void 0 ? _a : this.interfaceId;
                     try {
-                        yield currentDevice.releaseInterface(ifaceNum);
+                        yield this.runHandleOperation(() => currentDevice.releaseInterface(ifaceNum));
                     }
                     catch (releaseError) {
                         this.Log.debug('[WebUsbTransport] releaseInterface before retry error:', releaseError);
                     }
                     this.assertHandleAvailable(currentDevice);
-                    yield currentDevice.close();
+                    yield this.runHandleOperation(() => currentDevice.close());
                 }
             }
             catch (closeError) {
+                this.assertRunning();
                 if (this.isHandleOwnershipError(closeError))
                     throw closeError;
                 this.Log.debug('[WebUsbTransport] close device before retry error:', closeError);
@@ -728,6 +861,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
                         yield this.reconnectForPacketIoRetry(path, 'out', attempt, error);
                     }
                     catch (reconnectError) {
+                        this.assertRunning();
                         if (this.isHandleOwnershipError(reconnectError))
                             throw reconnectError;
                         lastError = reconnectError;
@@ -750,6 +884,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             const transferBuffer = this.toArrayBuffer(packet.buffer.slice(packet.byteOffset, packet.byteOffset + packet.byteLength));
             this.assertHandleAvailable(device);
             const result = yield device.transferOut(endpointOut, transferBuffer);
+            this.assertHandleAvailable(device);
             if (result.status !== 'ok') {
                 return this.throwWebUsbIoError(path, 'transferOut', new Error(`transferOut status: ${String(result.status)}`));
             }
@@ -772,6 +907,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
                     const endpointIn = (_a = endpoints === null || endpoints === void 0 ? void 0 : endpoints.endpointIn) !== null && _a !== void 0 ? _a : this.endpointId;
                     this.assertHandleAvailable(device);
                     const result = yield device.transferIn(endpointIn, length);
+                    this.assertHandleAvailable(device);
                     return this.getTransferInData(result);
                 }
                 catch (error) {
@@ -787,6 +923,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
                         yield this.reconnectForPacketIoRetry(path, 'in', attempt, error);
                     }
                     catch (reconnectError) {
+                        this.assertRunning();
                         if (this.isHandleOwnershipError(reconnectError))
                             throw reconnectError;
                         lastError = reconnectError;
@@ -808,6 +945,7 @@ class WebUsbTransport extends transport.ProtocolV2UsbTransportBase {
             const endpointIn = (_a = endpoints === null || endpoints === void 0 ? void 0 : endpoints.endpointIn) !== null && _a !== void 0 ? _a : this.endpointId;
             this.assertHandleAvailable(device);
             const result = yield device.transferIn(endpointIn, length);
+            this.assertHandleAvailable(device);
             return this.getTransferInData(result);
         });
     }

package/dist/webusb.d.ts

@@ -20,6 +20,8 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     private acquiredPaths;
     private identityProbeDevices;
     private normalDevices;
+    private pendingHandleOperations;
+    private stopPromise?;
     private identityProbeCleanupPaths;
     private probedDeviceObjects;
     private deviceEndpoints;
@@ -35,6 +37,10 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     interfaceId: number;
     constructor(identityProbe?: boolean);
     init(logger: any, emitter?: EventEmitter): void;
+    stop(): Promise<void>;
+    private stopResources;
+    private assertRunning;
+    private runHandleOperation;
     emitDeviceDisconnect(path: string, device?: USBDevice): void;
     markProtocolStale(path: string): void;
     configure(signedData: any): void;

package/dist/webusb.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-transport-web-device",
-  "version": "1.2.8-alpha.16",
+  "version": "1.2.8-alpha.18",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
   "license": "MIT",
@@ -21,13 +21,13 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@onekeyfe/hd-shared": "1.2.8-alpha.16",
-    "@onekeyfe/hd-transport": "1.2.8-alpha.16"
+    "@onekeyfe/hd-shared": "1.2.8-alpha.18",
+    "@onekeyfe/hd-transport": "1.2.8-alpha.18"
   },
   "devDependencies": {
-    "@onekeyfe/hd-transport-electron": "1.2.8-alpha.16",
+    "@onekeyfe/hd-transport-electron": "1.2.8-alpha.18",
     "@types/w3c-web-usb": "^1.0.6",
     "@types/web-bluetooth": "^0.0.17"
   },
-  "gitHead": "7ccc3f507e2b536e6b5832e1cbb24a5fc1970ebe"
+  "gitHead": "1f66fc960c9d775272f989aa673d8efe2174729b"
 }

package/src/webusb.ts

@@ -135,6 +135,10 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
 
   private normalDevices = new Map<USBDevice, string>();
 
+  private pendingHandleOperations = new Set<Promise<unknown>>();
+
+  private stopPromise?: Promise<void>;
+
   private identityProbeCleanupPaths = new Set<string>();
 
   /**
@@ -199,6 +203,96 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     if (!this.identityProbe) registerActiveWebUsbTransport(this, usb);
   }
 
+  stop(): Promise<void> {
+    this.stopped = true;
+    this.acquiredPaths.clear();
+    if (activeWebUsbTransport === this) activeWebUsbTransport = undefined;
+    if (!this.stopPromise) {
+      this.stopPromise = this.stopResources().catch(error => {
+        // A later discovery can retry closure without dropping the handle guard.
+        this.stopPromise = undefined;
+        throw error;
+      });
+    }
+    return this.stopPromise;
+  }
+
+  private async stopResources() {
+    let cleanupError: unknown;
+    try {
+      await this.disposeProtocolV2UsbLinks('WebUSB transport stopped');
+    } catch (error) {
+      cleanupError = error;
+    }
+    // Wait for late open/reset/claim/close completions before releasing ownership.
+    // Reads are aborted by closing their handle and reject late results below.
+    await Promise.allSettled([...this.pendingHandleOperations]);
+    const handles = this.identityProbe
+      ? [...this.identityProbeDevices].map(([path, device]) => [device, path] as const)
+      : [...this.normalDevices];
+    for (const [device, path] of handles) {
+      if (!this.identityProbe && normalHandleOwners.get(device) !== this) {
+        this.normalDevices.delete(device);
+      } else {
+        try {
+          if (device.opened) {
+            const iface = this.deviceEndpoints.get(path)?.interfaceNumber ?? this.interfaceId;
+            try {
+              await device.releaseInterface(iface);
+            } catch (error) {
+              this.Log?.debug('[WebUsbTransport] stop releaseInterface failed:', error);
+            }
+            await device.close();
+            if (device.opened) throw new Error('WebUSB handle remains open after stop');
+          }
+          if (this.identityProbe) {
+            identityProbeHandles.delete(device);
+            this.identityProbeDevices.delete(path);
+            this.identityProbeCleanupPaths.delete(path);
+          } else {
+            normalHandleOwners.delete(device);
+            this.normalDevices.delete(device);
+          }
+        } catch (error) {
+          cleanupError ??= error;
+        }
+      }
+    }
+    this.deviceList = [];
+    this.deviceProtocol.clear();
+    this.confirmedDeviceProtocols.clear();
+    this.deviceProtocolHints.clear();
+    this.staleProtocolPaths.clear();
+    this.probedDeviceObjects.clear();
+    if (!this.normalDevices.size && !this.identityProbeDevices.size) {
+      this.deviceEndpoints.clear();
+    }
+    if (cleanupError) {
+      throw cleanupError instanceof Error
+        ? cleanupError
+        : new Error(this.getErrorMessage(cleanupError));
+    }
+  }
+
+  private assertRunning() {
+    if (this.stopped) {
+      throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'WebUSB transport is stopped');
+    }
+  }
+
+  private async runHandleOperation<T>(operation: () => Promise<T>): Promise<T> {
+    this.assertRunning();
+    const pending = Promise.resolve(operation());
+    this.pendingHandleOperations.add(pending);
+    try {
+      const result = await pending;
+      this.assertRunning();
+      return result;
+    } finally {
+      this.pendingHandleOperations.delete(pending);
+    }
+  }
+
   /**
    * Announce that a USB device left. Called from the module-scoped disconnect
    * listener, which is why it is public rather than inlined.
@@ -296,9 +390,21 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
    * Get list of connected devices
    */
   async getConnectedDevices() {
+    this.assertRunning();
     if (!this.usb) return [];
 
     const devices = await this.usb.getDevices();
+    this.assertRunning();
+    for (const owner of new Set(devices.map(device => normalHandleOwners.get(device)))) {
+      if (owner?.stopped) {
+        try {
+          await owner.stop();
+        } catch (error) {
+          this.Log?.debug('[WebUsbTransport] stopped owner cleanup failed:', error);
+        }
+      }
+    }
+    this.assertRunning();
     const onekeyDevices = devices.filter(dev => {
       const isOneKey = ONEKEY_WEBUSB_FILTER.some(
         (desc: { vendorId: number; productId: number }) =>
@@ -331,6 +437,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
    * Acquire device control
    */
   async acquire(input: AcquireInput) {
+    this.assertRunning();
     if (!input.path) return;
     if (this.identityProbe) {
       await this.getConnectedDevices();
@@ -410,12 +517,14 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
           input.expectedProtocol,
           protocolHint
         );
+        this.assertRunning();
         this.confirmedDeviceProtocols.set(input.path, detectedProtocol);
         const probedDevice = this.deviceList.find(d => d.path === input.path)?.device;
         if (probedDevice) {
           this.probedDeviceObjects.set(input.path, probedDevice);
         }
       }
+      this.assertRunning();
       this.acquiredPaths.add(input.path);
       return await Promise.resolve(input.path);
     } catch (e) {
@@ -548,9 +657,11 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
   async connect(path: string, first: boolean) {
     const maxRetries = 5;
     for (let i = 0; i < maxRetries; i++) {
+      this.assertRunning();
       try {
         return await this.connectToDevice(path, first);
       } catch (e) {
+        this.assertRunning();
         if (e instanceof HardwareError && e.errorCode === HardwareErrorCode.BridgeNeedsPermission) {
           throw e;
         }
@@ -600,6 +711,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
    * Discovers interface/endpoint numbers from USB descriptors on first connection.
    */
   async connectToDevice(path: string, first: boolean) {
+    this.assertRunning();
     let device: USBDevice = await this.findDevice(path);
     if (this.identityProbe && this.identityProbeDevices.get(path) !== device) {
       await this.closeOpenDevice(path);
@@ -611,7 +723,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     if (!device.opened) {
       openingHandles.add(device);
       try {
-        await device.open();
+        await this.runHandleOperation(() => device.open());
       } catch (error) {
         return await this.throwWebUsbIoError(path, 'open', error);
       } finally {
@@ -622,8 +734,9 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     // state as in the legacy transport; probing and V2 recovery still reset.
     if (first || this.deviceProtocol.get(path) !== 'V1') {
       try {
-        await device.reset();
+        await this.runHandleOperation(() => device.reset());
       } catch (error) {
+        this.assertRunning();
         this.Log?.debug('[WebUsbTransport] reset before claim failed, continuing:', error);
       }
     }
@@ -639,7 +752,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     if (!device.opened) {
       openingHandles.add(device);
       try {
-        await device.open();
+        await this.runHandleOperation(() => device.open());
       } catch (error) {
         return await this.throwWebUsbIoError(path, 'open', error);
       } finally {
@@ -652,14 +765,14 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
       !device.configuration ||
       device.configuration.configurationValue !== this.configurationId
     ) {
-      await device.selectConfiguration(this.configurationId);
+      await this.runHandleOperation(() => device.selectConfiguration(this.configurationId));
     }
 
     // Discover endpoints from USB descriptors; descriptors are not used for protocol selection.
     const endpoints = this.discoverEndpoints(device);
     this.deviceEndpoints.set(path, endpoints);
     try {
-      await device.claimInterface(endpoints.interfaceNumber);
+      await this.runHandleOperation(() => device.claimInterface(endpoints.interfaceNumber));
     } catch (error) {
       return this.throwWebUsbIoError(path, 'claimInterface', error);
     }
@@ -668,6 +781,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
   }
 
   private assertHandleAvailable(device: USBDevice) {
+    this.assertRunning();
     const normalOwner = normalHandleOwners.get(device);
     if (
       (normalOwner && normalOwner !== this) ||
@@ -685,6 +799,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
   }
 
   private releaseNormalHandles(path: string) {
+    if (this.stopped) return;
     for (const [device, ownedPath] of this.normalDevices) {
       if (ownedPath === path) {
         normalHandleOwners.delete(device);
@@ -702,6 +817,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
   }
 
   private claimIdentityProbeHandle(path: string, device: USBDevice) {
+    this.assertRunning();
     if (
       device.opened ||
       openingHandles.has(device) ||
@@ -715,6 +831,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
   }
 
   private releaseIdentityProbeHandle(path: string) {
+    if (this.stopped) return;
     const device = this.identityProbeDevices.get(path);
     // A failed native close must not make an open probe handle available to other callers.
     if (device?.opened) {
@@ -727,6 +844,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
   }
 
   private async closeOpenDevice(path: string) {
+    if (this.stopped) return;
     const current = this.identityProbe
       ? this.identityProbeDevices.get(path)
       : this.deviceList.find(device => device.path === path)?.device;
@@ -736,13 +854,13 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     const endpoints = this.deviceEndpoints.get(path);
     const ifaceNum = endpoints?.interfaceNumber ?? this.interfaceId;
     try {
-      await current.releaseInterface(ifaceNum);
+      await this.runHandleOperation(() => current.releaseInterface(ifaceNum));
     } catch (error) {
       this.Log?.debug('[WebUsbTransport] releaseInterface before reconnect failed:', error);
     }
     this.assertHandleAvailable(current);
     try {
-      await current.close();
+      await this.runHandleOperation(() => current.close());
     } catch (error) {
       this.Log?.debug('[WebUsbTransport] close before reconnect failed:', error);
       if (this.identityProbe) throw error;
@@ -756,8 +874,9 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
   ) {
     this.assertHandleAvailable(device);
     try {
-      await device.clearHalt(direction, endpointNumber);
+      await this.runHandleOperation(() => device.clearHalt(direction, endpointNumber));
     } catch (error) {
+      this.assertRunning();
       this.Log?.debug(
         `[WebUsbTransport] clearHalt ${direction} endpoint ${endpointNumber} failed, continuing:`,
         error
@@ -773,6 +892,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
    * protocol entry produced the same fail-fast).
    */
   private assertAcquired(path: string) {
+    this.assertRunning();
     if (!this.acquiredPaths.has(path)) {
       throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, `Device is not acquired for ${path}`);
     }
@@ -830,6 +950,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     operation: WebUsbOperation,
     error: unknown
   ): Promise<never> {
+    this.assertRunning();
     if (this.isHandleOwnershipError(error) || this.isWebUsbIoHardwareError(error)) throw error;
     if (error instanceof ProtocolV2LinkError && error.code !== 'io') throw error;
 
@@ -870,6 +991,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
   }
 
   private isRetryablePacketIoError(error: unknown) {
+    if (this.stopped) return false;
     if (this.isHandleOwnershipError(error) || this.isWebUsbIoHardwareError(error)) return false;
     const message = this.getErrorMessage(error).toLowerCase();
     if (this.isWebUsbPermissionDeniedMessage(message)) return false;
@@ -901,6 +1023,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     // USB disconnect event itself was missed.
     this.staleProtocolPaths.add(path);
     await wait(attempt * PACKET_IO_RETRY_DELAY);
+    this.assertRunning();
 
     try {
       const currentDevice = await this.findDevice(path);
@@ -909,14 +1032,15 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
         const endpoints = this.deviceEndpoints.get(path);
         const ifaceNum = endpoints?.interfaceNumber ?? this.interfaceId;
         try {
-          await currentDevice.releaseInterface(ifaceNum);
+          await this.runHandleOperation(() => currentDevice.releaseInterface(ifaceNum));
         } catch (releaseError) {
           this.Log.debug('[WebUsbTransport] releaseInterface before retry error:', releaseError);
         }
         this.assertHandleAvailable(currentDevice);
-        await currentDevice.close();
+        await this.runHandleOperation(() => currentDevice.close());
       }
     } catch (closeError) {
+      this.assertRunning();
       if (this.isHandleOwnershipError(closeError)) throw closeError;
       this.Log.debug('[WebUsbTransport] close device before retry error:', closeError);
     }
@@ -959,6 +1083,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
         try {
           await this.reconnectForPacketIoRetry(path, 'out', attempt, error);
         } catch (reconnectError) {
+          this.assertRunning();
           if (this.isHandleOwnershipError(reconnectError)) throw reconnectError;
           lastError = reconnectError;
           this.Log.debug(
@@ -984,6 +1109,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     );
     this.assertHandleAvailable(device);
     const result = await device.transferOut(endpointOut, transferBuffer);
+    this.assertHandleAvailable(device);
     if (result.status !== 'ok') {
       return this.throwWebUsbIoError(
         path,
@@ -1012,6 +1138,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
         const endpointIn = endpoints?.endpointIn ?? this.endpointId;
         this.assertHandleAvailable(device);
         const result = await device.transferIn(endpointIn, length);
+        this.assertHandleAvailable(device);
         return this.getTransferInData(result);
       } catch (error) {
         lastError = error;
@@ -1025,6 +1152,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
         try {
           await this.reconnectForPacketIoRetry(path, 'in', attempt, error);
         } catch (reconnectError) {
+          this.assertRunning();
           if (this.isHandleOwnershipError(reconnectError)) throw reconnectError;
           lastError = reconnectError;
           this.Log.debug(
@@ -1047,6 +1175,7 @@ export default class WebUsbTransport extends ProtocolV2UsbTransportBase<string>
     const endpointIn = endpoints?.endpointIn ?? this.endpointId;
     this.assertHandleAvailable(device);
     const result = await device.transferIn(endpointIn, length);
+    this.assertHandleAvailable(device);
     return this.getTransferInData(result);
   }