@onekeyfe/hd-core 1.2.8-alpha.9 → 1.2.9

package/README.md

@@ -29,4 +29,31 @@ import Core from '@onekeyfe/hd-core';
 Documentation is available [Hardware SDK Getting Started](https://developer.onekey.so/en/hardware-sdk/getting-started)
 
 ## Examples
+
+### Babylon context hash
+
+`btcDeriveContextHash(connectId, deviceId, params)` requires Classic 1s firmware
+3.21.0 or later and Protocol V1. It uses the existing wallet session and device
+confirmation flow. Other device families and Protocol V2 are not supported.
+
+```typescript
+const result = await HardwareSDK.btcDeriveContextHash(connectId, deviceId, {
+  path: "m/84'/0'/0'/0/0", // The currently selected Bitcoin key, not the IKM path.
+  appName: 'babylon-btc-vault',
+  context: 'deadbeef',
+  network: 'bitcoin-mainnet',
+});
+// result.payload.secret is a 32-byte value encoded as 64 lowercase hex characters.
+```
+
+`appName` must contain 1–64 ASCII lowercase letters, digits or hyphens. `context`
+must be lowercase hex without `0x`, containing 1–1024 decoded bytes. `network` is
+required: `bitcoin-mainnet`, `bitcoin-testnet` (testnet3/testnet4), `bitcoin-signet`,
+or `bitcoin-regtest`. The SDK infers the Bitcoin input script type from `path` and
+encodes `appName` as ASCII bytes; the device performs the derivation internally.
+Device rejection and unsupported firmware errors propagate through the normal
+SDK response. Treat the returned secret as sensitive and do not log or persist it.
+
+See the [Babylon specification](https://github.com/babylonlabs-io/babylon-toolkit/blob/main/docs/specs/derive-context-hash.md).
+
 // TODO: add example url

package/__tests__/AllNetworkGetAddressBase.tracing.test.ts

@@ -1,4 +1,9 @@
-import { EDeviceType, HardwareErrorCode, HardwareErrorCodeMessage } from '@onekeyfe/hd-shared';
+import {
+  EDeviceType,
+  ERRORS,
+  HardwareErrorCode,
+  HardwareErrorCodeMessage,
+} from '@onekeyfe/hd-shared';
 
 import AllNetworkGetAddressBase from '../src/api/allnetwork/AllNetworkGetAddressBase';
 import AllNetworkGetAddress from '../src/api/allnetwork/AllNetworkGetAddress';
@@ -17,6 +22,10 @@ jest.mock('../src/api/utils', () => ({
   findMethod: jest.fn(),
 }));
 
+// What DeviceCommands raises when the firmware refuses a path under strict safety checks.
+const forbiddenKeyPathError = () =>
+  ERRORS.TypedError(HardwareErrorCode.ForbiddenKeyPath, 'Forbidden key path');
+
 class TestAllNetworkMethod extends AllNetworkGetAddressBase {
   async getAllNetworkAddress() {
     return Promise.resolve([]);
@@ -515,7 +524,7 @@ describe('AllNetworkGetAddressBase tracing', () => {
       .fn()
       .mockImplementation((_type: string, _response: string, params: { address_n: number[] }) => {
         const index = params.address_n[2] - 0x80000000;
-        if (index === 1) return Promise.reject(new Error('Forbidden key path'));
+        if (index === 1) return Promise.reject(forbiddenKeyPathError());
         return Promise.resolve({ message: { address: `address-${index}` } });
       });
     method.device.commands.typedCall = typedCall;
@@ -536,7 +545,7 @@ describe('AllNetworkGetAddressBase tracing', () => {
       expect(result.map(item => item.path)).toEqual(bundle.map(item => item.path));
       expect(result[0].payload).toMatchObject({ address: 'address-0', rootFingerprint: 7 });
       expect(result[1].payload).toMatchObject({
-        code: HardwareErrorCode.CallMethodInvalidParameter,
+        code: HardwareErrorCode.ForbiddenKeyPath,
       });
       expect(result[2].payload).toMatchObject({ address: 'address-2', rootFingerprint: 7 });
       expect(typedCall.mock.calls.map(([, , params]) => params.address_n[2] - 0x80000000)).toEqual(
@@ -624,7 +633,7 @@ describe('AllNetworkGetAddressBase tracing', () => {
     const { method, typedCall } = createGroupedAddressHarness(false);
     typedCall.mockImplementationOnce(() => {
       method.abortController?.abort();
-      return Promise.reject(new Error('Forbidden key path'));
+      return Promise.reject(forbiddenKeyPathError());
     });
 
     await expect(method.getAllNetworkAddress(7)).rejects.toThrow(

package/__tests__/DeviceCommands.test.ts

@@ -39,6 +39,31 @@ describe('DeviceCommands failure mapping', () => {
     }
   );
 
+  it.each([
+    // Touch and Pro under strict safety checks; Classic 1S adds a trailing period.
+    ['Forbidden key path', HardwareErrorCode.ForbiddenKeyPath],
+    ['Forbidden key path.', HardwareErrorCode.ForbiddenKeyPath],
+    // Touch and Pro on Monero's Cake path.
+    ['Non-hardened paths unsupported on Ed25519', HardwareErrorCode.DeviceNotSupportPath],
+    // Classic 1S on a path off the chain's pattern.
+    ['Invalid path', HardwareErrorCode.DeviceNotSupportPath],
+    // Wording varies in case across firmware.
+    ['forbidden key path', HardwareErrorCode.ForbiddenKeyPath],
+    ['Invalid Path', HardwareErrorCode.DeviceNotSupportPath],
+    ['invalid path', HardwareErrorCode.DeviceNotSupportPath],
+  ])('maps path refusal "%s" to its own code', async (message, errorCode) => {
+    const commands = createCommands();
+    await expect(
+      commands._filterCommonTypes(
+        {
+          type: 'Failure',
+          message: { code: 'Failure_DataError', message },
+        } as any,
+        'MoneroGetAddress'
+      )
+    ).rejects.toMatchObject({ errorCode, message });
+  });
+
   it('logs passphrase request and canonical response without exposing the passphrase', async () => {
     const commands = createCommands();
     const log = getLogger(LoggerNames.DeviceCommands);

package/__tests__/allNetworkGetAddress-privacy-networks.test.ts

@@ -0,0 +1,77 @@
+import AllNetworkGetAddress from '../src/api/allnetwork/AllNetworkGetAddress';
+
+import type { AllNetworkAddressParams } from '../src/types/api/allNetworkGetAddress';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+// Breaks the api index import cycle, as the all-network tests do.
+jest.mock('../src/api/utils', () => ({
+  findMethod: jest.fn(),
+}));
+
+function mapItem(payload: AllNetworkAddressParams) {
+  const method = new AllNetworkGetAddress({
+    id: 1,
+    payload: { method: 'allNetworkGetAddress', bundle: [payload] },
+  });
+  return method.generateMethodName({ network: payload.network, payload, originalIndex: 0 });
+}
+
+describe('allNetworkGetAddress privacy networks', () => {
+  test.each([
+    [undefined, 0],
+    ['mainnet', 0],
+    ['testnet', 1],
+    ['stagenet', 2],
+  ])('asks moneroGetAddress on the %s network type', (chainName, networkType) => {
+    const payload = {
+      network: 'xmr' as const,
+      path: "m/44'/128'/0'",
+      chainName,
+      showOnOneKey: false,
+    };
+
+    expect(mapItem(payload)).toEqual(
+      expect.objectContaining({
+        methodName: 'moneroGetAddress',
+        params: {
+          path: "m/44'/128'/0'",
+          networkType,
+          showOnOneKey: false,
+          originPayload: payload,
+        },
+      })
+    );
+  });
+
+  test.each(['fakechain', 'constructor'])(
+    'rejects the unknown Monero chainName %s instead of using mainnet',
+    chainName => {
+      expect(() =>
+        mapItem({ network: 'xmr', path: "m/44'/128'/0'", chainName, showOnOneKey: false })
+      ).toThrow(`Unsupported Monero chainName: ${chainName}`);
+    }
+  );
+
+  test('asks zcashGetAddress for the Orchard address and seed fingerprint only', () => {
+    const payload = { network: 'zcash' as const, path: "m/32'/133'/0'", showOnOneKey: false };
+
+    expect(mapItem(payload)).toEqual(
+      expect.objectContaining({
+        methodName: 'zcashGetAddress',
+        params: {
+          path: "m/32'/133'/0'",
+          showOnOneKey: false,
+          addressType: 2,
+          scope: 0,
+          diversifierIndex: 0,
+          includeSeedFingerprint: true,
+          originPayload: payload,
+        },
+      })
+    );
+  });
+});

package/__tests__/allNetworkGetAddress-skippable.test.ts

@@ -0,0 +1,49 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import { handleSkippableHardwareError } from '../src/api/allnetwork/AllNetworkGetAddressBase';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+// Breaks the api/index -> AllNetworkGetAddress import cycle, as the tracing test does.
+jest.mock('../src/api/utils', () => ({
+  findMethod: jest.fn(),
+}));
+
+const device = {
+  getCurrentMethodVersionRange: jest.fn(() => undefined),
+  getCurrentFirmwareVersionString: jest.fn(() => '1.0.0'),
+  getCurrentFirmwareType: jest.fn(() => 'universal'),
+} as any;
+const method = { name: 'zcashGetAddress', getVersionRange: () => ({}) } as any;
+
+describe('all-network chains the firmware lacks', () => {
+  test.each([
+    'Failure_UnexpectedMessage,Unknown message',
+    'Failure_UnknownMessage,Unknown message',
+    // Pro 2's wording for a message type it has no handler for.
+    'Failure_ProcessError,Handler not found: No handler for type: 12400',
+  ])('skips the chain on %s', message => {
+    const error = handleSkippableHardwareError(new Error(message), device, method);
+    expect(error?.errorCode).toBe(HardwareErrorCode.DeviceNotSupportMethod);
+  });
+
+  test.each([HardwareErrorCode.ForbiddenKeyPath, HardwareErrorCode.DeviceNotSupportPath])(
+    'skips the chain when the device refuses its path (%s)',
+    errorCode => {
+      const error = handleSkippableHardwareError(ERRORS.TypedError(errorCode), device, method);
+      expect(error?.errorCode).toBe(errorCode);
+    }
+  );
+
+  test('still fails the request on any other device error', () => {
+    const error = handleSkippableHardwareError(
+      new Error('Failure_ProcessError,Cancelled'),
+      device,
+      method
+    );
+    expect(error).toBeUndefined();
+  });
+});

package/__tests__/btc-derive-context-hash.test.ts

@@ -0,0 +1,200 @@
+import { EDeviceType, EFirmwareType, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import BTCDeriveContextHash from '../src/api/btc/BTCDeriveContextHash';
+import { findMethod } from '../src/api/utils';
+import { getLogBlockLabel, getSafeLogPayload } from '../src/events/logBlockEvent';
+import { createCoreApi } from '../src/inject';
+import { Device } from '../src/device/Device';
+
+import type { DeviceFirmwareRange } from '../src/types';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+const createMethod = (overrides: Record<string, unknown> = {}) =>
+  new BTCDeriveContextHash({
+    id: 1,
+    payload: {
+      method: 'btcDeriveContextHash',
+      path: "m/84'/0'/0'/0/0",
+      appName: 'test-app',
+      context: 'deadbeef',
+      network: 'bitcoin-mainnet',
+      ...overrides,
+    },
+  });
+
+describe('btcDeriveContextHash', () => {
+  test('forwards the public API call through the existing dispatcher', async () => {
+    const call = jest
+      .fn()
+      .mockResolvedValue({ success: true, payload: { secret: '00'.repeat(32) } });
+    const api = createCoreApi(call);
+    const params = {
+      path: "m/84'/0'/0'/0/0",
+      appName: 'test-app',
+      context: 'deadbeef',
+      network: 'bitcoin-mainnet' as const,
+    };
+    await api.btcDeriveContextHash('connect-id', 'device-id', params);
+    expect(call).toHaveBeenCalledWith({
+      ...params,
+      connectId: 'connect-id',
+      deviceId: 'device-id',
+      method: 'btcDeriveContextHash',
+    });
+  });
+
+  test.each([
+    ['bitcoin-mainnet', 'BITCOIN_MAINNET'],
+    ['bitcoin-testnet', 'BITCOIN_TESTNET'],
+    ['bitcoin-signet', 'BITCOIN_SIGNET'],
+    ['bitcoin-regtest', 'BITCOIN_REGTEST'],
+  ])('maps %s and returns the device result', async (network, wireNetwork) => {
+    const method = createMethod({ network });
+    method.init();
+    const response = { secret: '00'.repeat(32) };
+    const typedCall = jest.fn().mockResolvedValue({ message: response });
+    method.device = { commands: { typedCall } } as unknown as Device;
+
+    await expect(method.run()).resolves.toBe(response);
+    expect(typedCall).toHaveBeenCalledWith(
+      'BabylonDeriveContextHash',
+      'BabylonDerivedContextHash',
+      {
+        address_n: [2147483732, 2147483648, 2147483648, 0, 0],
+        script_type: 'SPENDWITNESS',
+        app_name: '746573742d617070',
+        context: 'deadbeef',
+        network: wireNetwork,
+      }
+    );
+  });
+
+  test.each([
+    ["m/44'/0'/0'/0/0", 'SPENDADDRESS'],
+    ["m/49'/0'/0'/0/0", 'SPENDP2SHWITNESS'],
+    [[2147483734, 2147483648, 2147483648, 0, 0], 'SPENDTAPROOT'],
+  ])('uses the selected path script type for %s', (path, scriptType) => {
+    const method = createMethod({ path });
+    method.init();
+    expect(method.params.script_type).toBe(scriptType);
+  });
+
+  test('accepts the maximum app name and context sizes', () => {
+    const method = createMethod({ appName: 'a'.repeat(64), context: 'ab'.repeat(1024) });
+    expect(() => method.init()).not.toThrow();
+    expect(method.params.context).toHaveLength(2048);
+  });
+
+  test.each([
+    { appName: '' },
+    { appName: 'a'.repeat(65) },
+    { appName: 'Test-App' },
+    { appName: 'test_app' },
+    { appName: '你好' },
+    { appName: null },
+    { context: '' },
+    { context: 'abc' },
+    { context: 'DEADBEEF' },
+    { context: '0xdeadbeef' },
+    { context: 'gg' },
+    { context: 'ab'.repeat(1025) },
+    { context: null },
+    { network: '' },
+    { network: 'litecoin' },
+    { network: 'toString' },
+    { network: 1 },
+    { path: 'm' },
+    { path: "m/84x'/0'/0'/0/0" },
+    { path: "m/2147483648'/0'/0'/0/0" },
+    { path: [2147483732, 2147483648, 2147483648, 0, 0.5] },
+    { path: [2147483732, 2147483648, 2147483648, 0, 4294967296] },
+  ])('rejects invalid inputs before a device call: %j', overrides => {
+    expect(() => createMethod(overrides).init()).toThrow(
+      expect.objectContaining({ errorCode: HardwareErrorCode.CallMethodInvalidParameter })
+    );
+  });
+
+  test('rejects sparse numeric paths before a device call', () => {
+    const sparsePath = [2147483732, 2147483648, 2147483648, 0, 5];
+    delete sparsePath[3];
+
+    [Array<number>(3), sparsePath].forEach(path => {
+      expect(() => createMethod({ path }).init()).toThrow(
+        expect.objectContaining({ errorCode: HardwareErrorCode.CallMethodInvalidParameter })
+      );
+    });
+  });
+
+  test('registers the public method and restricts it to supported firmware and protocol', () => {
+    const method = findMethod({ id: 1, payload: { ...createMethod().payload } });
+    method.init();
+    expect(method).toBeInstanceOf(BTCDeriveContextHash);
+    expect(method.strictCheckDeviceSupport).toBe(true);
+    expect(() => method.assertProtocolSupported('V2', EFirmwareType.Universal)).toThrow(
+      expect.objectContaining({ errorCode: HardwareErrorCode.DeviceNotSupportMethod })
+    );
+  });
+
+  test.each([EDeviceType.Classic1s, EDeviceType.ClassicPure])(
+    'resolves the firmware requirement for %s through the device support check',
+    deviceType => {
+      const method = createMethod();
+      const device = Object.create(Device.prototype) as Device;
+      device.getCurrentDeviceType = jest.fn(() => deviceType);
+      const range: DeviceFirmwareRange = method.getVersionRange();
+
+      expect(device.getCurrentMethodVersionRange(type => range[type])).toEqual({ min: '3.21.0' });
+      expect(() => method.assertProtocolSupported('V1', EFirmwareType.Universal)).not.toThrow();
+    }
+  );
+
+  test.each([EDeviceType.Classic, EDeviceType.Mini, EDeviceType.Touch, EDeviceType.Pro])(
+    'keeps %s outside the supported firmware range',
+    deviceType => {
+      const method = createMethod();
+      const device = Object.create(Device.prototype) as Device;
+      device.getCurrentDeviceType = jest.fn(() => deviceType);
+      const range: DeviceFirmwareRange = method.getVersionRange();
+
+      expect(device.getCurrentMethodVersionRange(type => range[type])).toBeUndefined();
+    }
+  );
+
+  test('propagates device rejection without returning a secret', async () => {
+    const method = createMethod();
+    method.init();
+    const error = new Error('User rejected');
+    method.device = {
+      commands: { typedCall: jest.fn().mockRejectedValue(error) },
+    } as unknown as Device;
+    await expect(method.run()).rejects.toBe(error);
+  });
+
+  test.each([undefined, '00', '00'.repeat(33)])(
+    'rejects malformed device responses',
+    async secret => {
+      const method = createMethod();
+      method.init();
+      method.device = {
+        commands: { typedCall: jest.fn().mockResolvedValue({ message: { secret } }) },
+      } as unknown as Device;
+      await expect(method.run()).rejects.toMatchObject({
+        errorCode: HardwareErrorCode.CallMethodError,
+      });
+    }
+  );
+
+  test('blocks API request and response payloads in logs', () => {
+    const request = { payload: { method: 'btcDeriveContextHash' } };
+    const label = getLogBlockLabel(request);
+    expect(label).toBe('btcDeriveContextHash');
+    expect(getSafeLogPayload({ payload: { secret: '00'.repeat(32) } }, label)).toEqual({
+      method: 'btcDeriveContextHash',
+      payload: '[REDACTED]',
+    });
+  });
+});

package/__tests__/core-dispose.test.ts

@@ -1,4 +1,7 @@
-import Core, { initConnector } from '../src/core';
+import { HardwareErrorCode, createDeferred } from '@onekeyfe/hd-shared';
+
+import Core, { init, initConnector, initCore, switchTransport } from '../src/core';
+import DataManager from '../src/data-manager/DataManager';
 import TransportManager from '../src/data-manager/TransportManager';
 import { DevicePool } from '../src/device/DevicePool';
 
@@ -31,4 +34,114 @@ describe('Core.dispose', () => {
     expect(transportStop).toHaveBeenCalledTimes(1);
     expect(disposeDevicePool).toHaveBeenCalledTimes(1);
   });
+
+  test('disposal rejects a queued switch without recreating a transport or connector', async () => {
+    const previous = TransportManager.transport;
+    const { settings } = DataManager;
+    const active = { stop: jest.fn().mockResolvedValue(undefined) };
+    const replacement = jest.fn(() => ({ stop: jest.fn().mockResolvedValue(undefined) }));
+    TransportManager.transport = active as never;
+    const core = initCore();
+    initConnector();
+    const switching = switchTransport({ env: 'emulator', Transport: replacement });
+    const rejected = expect(switching).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.NotInitialized,
+    });
+    try {
+      await core.dispose();
+      await rejected;
+      expect(replacement).not.toHaveBeenCalled();
+      expect(TransportManager.transport).toBe(active);
+      expect(DataManager.settings).toBe(settings);
+      expect(DevicePool.emitter.eventNames()).toHaveLength(0);
+    } finally {
+      await Promise.allSettled([switching]);
+      await core.dispose();
+      TransportManager.transport = previous;
+      DataManager.settings = settings;
+    }
+  });
+
+  test.each(['dispose/reinit', 'init', 'initCore'] as const)(
+    '%s invalidates running and queued switches without blocking a new lifecycle',
+    async lifecycle => {
+      const previous = TransportManager.transport;
+      const { settings } = DataManager;
+      const entered = createDeferred<void>();
+      const closing = createDeferred<void>();
+      const loading = createDeferred<void>();
+      const active = {
+        stop: jest.fn(() => {
+          entered.resolve();
+          return closing.promise;
+        }),
+      };
+      const intermediate = jest.fn(() => ({ stop: jest.fn().mockResolvedValue(undefined) }));
+      const stale = jest.fn(() => ({ stop: jest.fn().mockResolvedValue(undefined) }));
+      const fresh = { stop: jest.fn().mockResolvedValue(undefined) };
+      const current = { stop: jest.fn().mockResolvedValue(undefined) };
+      const Fresh = jest.fn(() => fresh);
+      jest.spyOn(DataManager, 'load').mockImplementation(async next => {
+        await loading.promise;
+        DataManager.settings = next;
+      });
+      TransportManager.transport = active as never;
+      let core = initCore();
+      initConnector();
+      const first = switchTransport({ env: 'emulator', Transport: intermediate });
+      await entered.promise;
+      const second = switchTransport({ env: 'webusb', Transport: stale });
+      const rejected = Promise.all([
+        expect(first).rejects.toMatchObject({ errorCode: HardwareErrorCode.NotInitialized }),
+        expect(second).rejects.toMatchObject({ errorCode: HardwareErrorCode.NotInitialized }),
+      ]);
+      rejected.catch(() => undefined);
+      let initializing: ReturnType<typeof init> | undefined;
+      try {
+        if (lifecycle === 'dispose/reinit') {
+          const disposing = core.dispose();
+          closing.resolve();
+          await disposing;
+        }
+        if (lifecycle === 'initCore') {
+          TransportManager.transport = fresh as never;
+          DataManager.settings = { ...settings, env: 'desktop-web-ble' };
+          core = initCore();
+          initConnector();
+        } else {
+          initializing = init({ ...settings, env: 'desktop-web-ble' }, Fresh);
+          if (lifecycle === 'init') {
+            closing.resolve();
+            await rejected;
+          }
+          loading.resolve();
+          const initialized = await initializing;
+          if (!initialized) throw new Error('Core initialization failed');
+          core = initialized;
+        }
+        await switchTransport({
+          env: 'emulator',
+          Transport: function Current() {
+            return current;
+          },
+        });
+        closing.resolve();
+        await rejected;
+        expect(intermediate).not.toHaveBeenCalled();
+        expect(stale).not.toHaveBeenCalled();
+        expect(TransportManager.transport).toBe(current);
+        expect(DataManager.getSettings('env')).toBe('emulator');
+        expect(fresh.stop).toHaveBeenCalledTimes(1);
+        expect(current.stop).not.toHaveBeenCalled();
+      } finally {
+        closing.resolve();
+        loading.resolve();
+        await initializing;
+        await Promise.allSettled([first, second, rejected]);
+        await core.dispose();
+        TransportManager.transport = previous;
+        DataManager.settings = settings;
+      }
+    }
+  );
 });

package/__tests__/core-error-output.test.ts

@@ -45,6 +45,23 @@ describe('Core 错误输出边界', () => {
     });
   });
 
+  test.each([
+    [HardwareErrorCode.TransportProtocolProbeFailed, { expectedProtocol: 'V1' }],
+    [
+      HardwareErrorCode.TransportProtocolMismatch,
+      { expectedProtocol: 'V2', detectedProtocol: 'V1' },
+    ],
+  ] as const)(
+    'preserves protocol error %s and structured context across the public boundary',
+    (code, params) => {
+      const error = ERRORS.TypedError(code, undefined, params);
+      expect(JSON.parse(JSON.stringify(createErrorMessage(error)))).toEqual({
+        success: false,
+        payload: { code, error: error.message, params },
+      });
+    }
+  );
+
   test.each([
     ['webusb', false],
     ['desktop-webusb', false],
@@ -129,6 +146,8 @@ describe('Core 错误输出边界', () => {
     HardwareErrorCode.BleUnsupported,
     HardwareErrorCode.BridgeNeedsPermission,
     HardwareErrorCode.WebUsbDeviceAccessError,
+    HardwareErrorCode.TransportProtocolProbeFailed,
+    HardwareErrorCode.TransportProtocolMismatch,
   ])(
     'preserves terminal transport error %s in the public response without polling again',
     async errorCode => {
@@ -138,6 +157,8 @@ describe('Core 错误输出边界', () => {
           [
             HardwareErrorCode.BridgeNeedsPermission,
             HardwareErrorCode.WebUsbDeviceAccessError,
+            HardwareErrorCode.TransportProtocolProbeFailed,
+            HardwareErrorCode.TransportProtocolMismatch,
           ].includes(errorCode)
             ? ('desktop-webusb' as never)
             : ('react-native' as never)

package/__tests__/device-connector-protocol.test.ts

@@ -75,8 +75,11 @@ describe('DeviceConnector protocol validation', () => {
     });
     const connector = new DeviceConnector();
 
-    await expect(connector.acquire('classic-id', undefined, undefined, 'V2')).rejects.toThrow(
-      'Device protocol mismatch: expected V2, detected V1'
+    await expect(connector.acquire('classic-id', undefined, undefined, 'V2')).rejects.toMatchObject(
+      {
+        errorCode: HardwareErrorCode.TransportProtocolMismatch,
+        params: { expectedProtocol: 'V2', detectedProtocol: 'V1' },
+      }
     );
   });