@onekeyfe/hd-core 1.1.26 → 1.1.27-alpha.31

package/__tests__/protocol-v2.test.ts

@@ -0,0 +1,1096 @@
+import JSZip from 'jszip';
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
+import { DeviceRebootType } from '@onekeyfe/hd-transport';
+
+import ConfluxSignTransaction from '../src/api/conflux/ConfluxSignTransaction';
+import DnxGetAddress from '../src/api/dynex/DnxGetAddress';
+import DnxSignTransaction from '../src/api/dynex/DnxSignTransaction';
+import FileRead from '../src/api/FileRead';
+import FileWrite from '../src/api/FileWrite';
+import DeviceFirmwareUpdate from '../src/api/protocol-v2/DeviceFirmwareUpdate';
+import DeviceGetOnboardingStatus from '../src/api/protocol-v2/DeviceGetOnboardingStatus';
+import FirmwareUpdateV3 from '../src/api/FirmwareUpdateV3';
+import FirmwareUpdateV4 from '../src/api/FirmwareUpdateV4';
+import GetOnekeyFeatures from '../src/api/GetOnekeyFeatures';
+import { batchGetPublickeys } from '../src/api/helpers/batchGetPublickeys';
+import KaspaGetAddress from '../src/api/kaspa/KaspaGetAddress';
+import TronSignMessage from '../src/api/tron/TronSignMessage';
+import XrpSignTransaction from '../src/api/xrp/XrpSignTransaction';
+import { DataManager } from '../src/data-manager';
+import { Device } from '../src/device/Device';
+import { UI_REQUEST } from '../src/events/ui-request';
+import { getProtocolV2Features, normalizeProtocolV2Features } from '../src/protocols/protocol-v2';
+import { shouldSkipMethodSupportCheck } from '../src/utils';
+
+import type { DeviceCommands } from '../src/device/DeviceCommands';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+const descriptor = {
+  id: 'ble-id',
+  path: 'usb-path',
+};
+
+describe('Protocol V2 feature adapter', () => {
+  test('normalizes Protocol V2 DeviceInfo into existing Features fields', () => {
+    const features = normalizeProtocolV2Features(descriptor as any, {
+      hw: {
+        serial_no: 'PR2SERIAL',
+      },
+      fw: {
+        board: {
+          version: '0.1.0',
+          hash: [1, 2, 255],
+        },
+        boot: {
+          version: '0.2.0',
+          build_id: 'boot-build',
+          hash: new Uint8Array([10, 11]),
+        },
+        app: {
+          version: '1.2.3',
+          build_id: 'app-build',
+          hash: 'abc123',
+        },
+      },
+      bt: {
+        app: {
+          version: '4.5.6',
+          build_id: 'bt-build',
+          hash: [12, 13],
+        },
+        adv_name: 'Pro2 BLE',
+      },
+      se1: {
+        app: {
+          version: '7.8.9',
+          build_id: 'se-build',
+          hash: [14, 15],
+        },
+        state: 85,
+      },
+      se2: {
+        app: {
+          version: '8.0.0',
+        },
+        state: 0,
+      },
+      status: {
+        label: 'My Pro2',
+        language: 'en-US',
+        bt_enable: true,
+        init_states: false,
+        backup_required: true,
+        passphrase_protection: true,
+      },
+    });
+
+    expect(features.device_id).toBe('PR2SERIAL');
+    expect(features.serial_no).toBe('PR2SERIAL');
+    expect(features.onekey_serial_no).toBe('PR2SERIAL');
+    expect(features.onekey_device_type).toBe('pro2');
+    expect(features.major_version).toBe(1);
+    expect(features.minor_version).toBe(2);
+    expect(features.patch_version).toBe(3);
+    expect(features.onekey_firmware_version).toBe('1.2.3');
+    expect(features.onekey_firmware_build_id).toBe('app-build');
+    expect(features.onekey_firmware_hash).toBe('abc123');
+    expect(features.bootloader_version).toBe('0.2.0');
+    expect(features.onekey_boot_build_id).toBe('boot-build');
+    expect(features.onekey_boot_hash).toBe('0a0b');
+    expect(features.onekey_board_hash).toBe('0102ff');
+    expect(features.ble_name).toBe('Pro2 BLE');
+    expect(features.onekey_ble_version).toBe('4.5.6');
+    expect(features.onekey_ble_hash).toBe('0c0d');
+    expect(features.onekey_se01_version).toBe('7.8.9');
+    expect(features.onekey_se01_hash).toBe('0e0f');
+    expect(features.onekey_se01_state).toBe('APP');
+    expect(features.onekey_se02_state).toBe('BOOT');
+    expect(features.label).toBe('My Pro2');
+    expect(features.language).toBe('en-US');
+    expect(features.initialized).toBe(false);
+    expect(features.needs_backup).toBe(true);
+    expect(features.passphrase_protection).toBe(true);
+    expect(features.ble_enable).toBe(true);
+  });
+
+  test('marks fallback features as unavailable when DeviceInfo is missing', () => {
+    const features = normalizeProtocolV2Features(descriptor as any);
+
+    expect(features.device_id).toBe('usb-path');
+    expect(features.serial_no).toBe('usb-path');
+    expect(features.onekey_serial_no).toBe('usb-path');
+    expect(features.initialized).toBe(false);
+    expect(features.unlocked).toBe(false);
+    expect(features.firmware_present).toBe(false);
+  });
+
+  test('bypasses legacy method support checks for Protocol V2 fallback features', () => {
+    const features = normalizeProtocolV2Features({
+      ...descriptor,
+      protocolType: 'V2',
+    } as any);
+
+    expect(shouldSkipMethodSupportCheck(features, 'V2')).toBe(true);
+    expect(shouldSkipMethodSupportCheck(features)).toBe(true);
+  });
+
+  test('initializes Protocol V2 features with Ping only while DeviceGetDeviceInfo is disabled', async () => {
+    const commands = {
+      typedCall: jest
+        .fn()
+        .mockResolvedValueOnce({ type: 'Success', message: { message: 'pong' } }),
+    };
+
+    const features = await getProtocolV2Features({
+      commands: commands as unknown as DeviceCommands,
+      descriptor: descriptor as any,
+    });
+
+    expect(features.device_id).toBe('usb-path');
+    expect(commands.typedCall).toHaveBeenNthCalledWith(1, 'Ping', 'Success', { message: 'init' });
+    expect(commands.typedCall).toHaveBeenCalledTimes(1);
+  });
+
+  test('does not block method-level legacy version checks on Protocol V2', async () => {
+    const method = new KaspaGetAddress({
+      id: 1,
+      payload: {
+        method: 'kaspaGetAddress',
+        path: "m/44'/111111'/0'/0/0",
+        prefix: 'kaspa',
+        showOnOneKey: false,
+        useTweak: false,
+      },
+    });
+    const typedCall = jest.fn().mockResolvedValue({
+      type: 'KaspaAddress',
+      message: {
+        address: 'kaspa:test-address',
+      },
+    });
+
+    method.init();
+    method.postMessage = jest.fn();
+    (method as any).device = {
+      originalDescriptor: { protocolType: 'V2' },
+      features: normalizeProtocolV2Features({ ...descriptor, protocolType: 'V2' } as any),
+      commands: { typedCall },
+      toMessageObject: jest.fn(() => ({})),
+    };
+
+    await expect(method.run()).resolves.toMatchObject({
+      address: 'kaspa:test-address',
+    });
+    expect(typedCall).toHaveBeenCalledWith('KaspaGetAddress', 'KaspaAddress', expect.any(Object));
+  });
+
+  test('does not block legacy batch public key support checks on Protocol V2', async () => {
+    const paths = [{ address_n: [0x8000002c, 0x80000000, 0x80000000] }] as any;
+    const typedCall = jest.fn().mockResolvedValue({
+      type: 'EcdsaPublicKeys',
+      message: {
+        root_fingerprint: 123,
+        public_keys: [],
+        hd_nodes: [{}],
+      },
+    });
+    const device = {
+      originalDescriptor: { protocolType: 'V2' },
+      features: normalizeProtocolV2Features({ ...descriptor, protocolType: 'V2' } as any),
+      commands: { typedCall },
+    };
+
+    await expect(
+      batchGetPublickeys(device as any, paths, 'secp256k1', 0, { includeNode: true })
+    ).resolves.toMatchObject({
+      root_fingerprint: 123,
+      hd_nodes: [{}],
+    });
+    expect(typedCall).toHaveBeenCalledWith('BatchGetPublickeys', 'EcdsaPublicKeys', {
+      paths,
+      ecdsa_curve_name: 'secp256k1',
+      include_node: true,
+    });
+  });
+
+  test('returns Protocol V2 oneKey fields without calling legacy OnekeyGetFeatures', async () => {
+    const method = new GetOnekeyFeatures({
+      id: 1,
+      payload: {
+        method: 'getOnekeyFeatures',
+      },
+    });
+    const typedCall = jest.fn();
+
+    (method as any).device = {
+      originalDescriptor: { protocolType: 'V2' },
+      commands: { typedCall },
+      features: {
+        label: 'ignored label',
+        onekey_device_type: 'pro2',
+        onekey_firmware_version: '1.2.3',
+        onekey_firmware_build_id: 'app-build',
+        onekey_serial_no: 'PR2SERIAL',
+        onekey_ble_name: 'Pro2 BLE',
+      },
+    };
+
+    const message = await method.run();
+
+    expect(typedCall).not.toHaveBeenCalled();
+    expect(message).toMatchObject({
+      onekey_device_type: 'pro2',
+      onekey_firmware_version: '1.2.3',
+      onekey_firmware_build_id: 'app-build',
+      onekey_serial_no: 'PR2SERIAL',
+      onekey_ble_name: 'Pro2 BLE',
+    });
+    expect(message).not.toHaveProperty('label');
+  });
+
+  test('reuses cached Protocol V2 features after the first initialization', async () => {
+    const device = Device.fromDescriptor({
+      path: 'usb-path',
+      protocolType: 'V2',
+    } as any);
+    const typedCall = jest
+      .fn()
+      .mockResolvedValueOnce({ type: 'Success', message: { message: 'init' } });
+
+    (device as any).commands = { typedCall };
+
+    await device.initialize();
+    await device.initialize();
+
+    expect(device.features?.device_id).toBe('usb-path');
+    expect(typedCall).toHaveBeenCalledTimes(1);
+    expect(typedCall).toHaveBeenNthCalledWith(
+      1,
+      'Ping',
+      'Success',
+      { message: 'init' },
+      {
+        timeoutMs: 10000,
+      }
+    );
+  });
+});
+
+describe('API compatibility handling', () => {
+  test('returns a typed unsupported error for Tron sign message V1 before device binding', () => {
+    const method = new TronSignMessage({
+      id: 1,
+      payload: {
+        method: 'tronSignMessage',
+        path: "m/44'/195'/0'/0/0",
+        messageHex: '0x1234',
+        messageType: 'V1',
+      },
+    });
+
+    expect(() => method.init()).toThrow(
+      expect.objectContaining({
+        errorCode: HardwareErrorCode.DeviceNotSupportMethod,
+      })
+    );
+  });
+
+  test('accepts string XRP payment amount values', () => {
+    const method = new XrpSignTransaction({
+      id: 1,
+      payload: {
+        method: 'xrpSignTransaction',
+        path: "m/44'/144'/0'/0/0",
+        transaction: {
+          fee: '100000',
+          flags: 2147483648,
+          sequence: 25,
+          maxLedgerVersion: 8820051,
+          payment: {
+            amount: '100000000',
+            destination: 'rBKz5MC2iXdoS3XgnNSYmF69K1Yo4NS3Ws',
+          },
+        },
+      },
+    });
+
+    expect(() => method.init()).not.toThrow();
+    expect(method.params.payment?.amount).toBe('100000000');
+  });
+
+  test('accepts Conflux base32 recipient addresses without hex formatting them', () => {
+    const to = 'cfx:aak2rra2njvd77ezwjvx04kkds9fzagfe6ku8scz91';
+    const method = new ConfluxSignTransaction({
+      id: 1,
+      payload: {
+        method: 'confluxSignTransaction',
+        path: "m/44'/503'/0'/0/0",
+        transaction: {
+          to,
+          value: '0x0',
+          data: '0x',
+          chainId: 1,
+          nonce: '0x00',
+          epochHeight: '0x00',
+          gasLimit: '0x5208',
+          storageLimit: '0x5208',
+          gasPrice: '0xbebc200',
+        },
+      },
+    });
+
+    expect(() => method.init()).not.toThrow();
+    expect(method.formattedTx?.to).toBe(to);
+  });
+
+  test('returns a typed unsupported error for Dynex signing on Protocol V2', async () => {
+    const method = new DnxSignTransaction({
+      id: 1,
+      payload: {
+        method: 'dnxSignTransaction',
+        path: "m/44'/29538'/0'/0/0",
+        inputs: [
+          {
+            prevIndex: 1,
+            globalIndex: 1,
+            txPubkey: '00',
+            prevOutPubkey: '00',
+            amount: '1',
+          },
+        ],
+        toAddress: 'dnx-address',
+        amount: '1',
+        fee: '1',
+      },
+    });
+
+    method.init();
+    (method as any).device = {
+      originalDescriptor: { protocolType: 'V2' },
+      features: normalizeProtocolV2Features({ ...descriptor, protocolType: 'V2' } as any),
+    };
+
+    await expect(method.run()).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.DeviceNotSupportMethod,
+    });
+  });
+
+  test('returns a typed unsupported error for Dynex address on Protocol V2', async () => {
+    const method = new DnxGetAddress({
+      id: 1,
+      payload: {
+        method: 'dnxGetAddress',
+        path: "m/44'/29538'/0'/0/0",
+        showOnOneKey: false,
+      },
+    });
+
+    method.init();
+    (method as any).device = {
+      originalDescriptor: { protocolType: 'V2' },
+      features: normalizeProtocolV2Features({ ...descriptor, protocolType: 'V2' } as any),
+    };
+
+    await expect(method.run()).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.DeviceNotSupportMethod,
+    });
+  });
+});
+
+describe('Protocol V2 firmware update targets', () => {
+  test('keeps Protocol V2 firmware updates off the legacy firmwareUpdateV3 path', async () => {
+    const method = new FirmwareUpdateV3({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV3',
+      },
+    });
+    (method as any).device = {
+      originalDescriptor: { protocolType: 'V2' },
+    };
+
+    await expect(method.run()).rejects.toThrow('firmwareUpdateV4');
+  });
+
+  test('uses Protocol V2 features after BLE final reconnect without legacy Initialize', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const acquire = jest.fn().mockResolvedValue({ uuid: 'ble-session' });
+    const typedCall = jest.fn().mockImplementation((name: string) => {
+      if (name === 'Ping') {
+        return Promise.resolve({ type: 'Success', message: { message: 'init' } });
+      }
+      return Promise.reject(new Error(`unexpected call ${name}`));
+    });
+    const commands = { typedCall };
+
+    (method as any).isBleReconnect = jest.fn(() => true);
+    (method as any).device = {
+      originalDescriptor: { id: 'ble-id', path: 'ble-path', protocolType: 'V2' },
+      deviceConnector: { acquire },
+      getCommands: () => commands,
+      _updateFeatures: jest.fn(),
+    };
+
+    const versions = await (method as any).waitForProtocolV2FinalFeatures();
+
+    expect(acquire).toHaveBeenCalledWith('ble-id', null, true, 'V2');
+    expect(typedCall).toHaveBeenNthCalledWith(
+      1,
+      'Ping',
+      'Success',
+      { message: 'init' },
+      { timeoutMs: 5000 }
+    );
+    expect(typedCall).toHaveBeenCalledTimes(1);
+    expect(typedCall).not.toHaveBeenCalledWith('Initialize', 'Features', {});
+    expect(versions).toEqual({
+      bootloaderVersion: '0.0.0',
+      bleVersion: '0.0.0',
+      firmwareVersion: '0.0.0',
+    });
+  });
+
+  test('runs Protocol V2 upload and install without rebooting to bootloader first', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    method.init();
+
+    (method as any).device = {
+      originalDescriptor: { id: 'ble-id', path: 'ble-path', protocolType: 'V2' },
+      features: { capabilities: [] },
+    };
+    (method as any).prepareResourceBinary = jest.fn().mockResolvedValue(null);
+    (method as any).prepareFirmwareAndBleBinary = jest.fn().mockResolvedValue([
+      {
+        fileName: 'ble-firmware.bin',
+        binary: new Uint8Array([1, 2, 3]).buffer,
+      },
+    ]);
+    (method as any).prepareBootloaderBinary = jest.fn().mockResolvedValue(null);
+    (method as any).executeProtocolV2Update = jest.fn().mockResolvedValue(undefined);
+    (method as any).exitProtocolV2BootloaderToNormal = jest.fn().mockResolvedValue(undefined);
+    (method as any).waitForProtocolV2FinalFeatures = jest.fn().mockResolvedValue({
+      bootloaderVersion: '0.2.0',
+      bleVersion: '4.5.6',
+      firmwareVersion: '1.2.3',
+    });
+    (method as any).protocolV2Reboot = jest.fn();
+    method.postTipMessage = jest.fn();
+
+    await method.run();
+
+    expect((method as any).executeProtocolV2Update).toHaveBeenCalledWith({
+      resourceBinary: null,
+      fwBinaryMap: [
+        {
+          fileName: 'ble-firmware.bin',
+          binary: expect.any(ArrayBuffer),
+        },
+      ],
+      bootloaderBinary: null,
+    });
+    expect((method as any).protocolV2Reboot).not.toHaveBeenCalledWith(DeviceRebootType.Bootloader);
+    expect(method.postTipMessage).not.toHaveBeenCalledWith('AutoRebootToBootloader');
+  });
+
+  test('reboots Protocol V2 firmware flow back to normal before final feature polling', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    method.postTipMessage = jest.fn();
+    (method as any).protocolV2Reboot = jest.fn().mockResolvedValue({
+      message: 'Device rebooted successfully',
+    });
+
+    await (method as any).exitProtocolV2BootloaderToNormal();
+
+    expect(method.postTipMessage).toHaveBeenCalledWith('SwitchFirmwareReconnectDevice');
+    expect((method as any).protocolV2Reboot).toHaveBeenCalledWith(DeviceRebootType.Normal);
+  });
+
+  test('treats iOS BLE RxError 6 during Protocol V2 reboot as expected disconnect', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const typedCall = jest
+      .fn()
+      .mockRejectedValue(
+        new Error("The operation couldn't be completed. (MultiplatformBleAdapter.RxError error 6.)")
+      );
+
+    (method as any).device = {
+      getCommands: () => ({ typedCall }),
+    };
+
+    await expect((method as any).protocolV2Reboot(DeviceRebootType.Normal)).resolves.toEqual({
+      message: 'Device rebooted successfully',
+    });
+  });
+
+  test('treats direct disconnect during Protocol V2 normal reboot as expected', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const typedCall = jest
+      .fn()
+      .mockRejectedValue(new Error('Connection error has occured: Device disconnected'));
+
+    (method as any).device = {
+      getCommands: () => ({ typedCall }),
+    };
+
+    await expect((method as any).protocolV2Reboot(DeviceRebootType.Normal)).resolves.toEqual({
+      message: 'Device rebooted successfully',
+    });
+  });
+
+  test('continues Protocol V2 install polling through temporary expected V2 probe failures', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const typedCall = jest
+      .fn()
+      .mockRejectedValueOnce(
+        new Error(
+          'Device protocol mismatch: expected V2, but device did not respond to expected protocol'
+        )
+      )
+      .mockResolvedValueOnce({
+        type: 'DeviceFirmwareUpdateStatus',
+        message: {
+          targets: [{ target_id: 2, status: 0 }],
+        },
+      });
+    const reconnectProtocolV2Device = jest.fn().mockResolvedValue(undefined);
+
+    (method as any).device = {
+      getCommands: () => ({ typedCall }),
+    };
+    (method as any).reconnectProtocolV2Device = reconnectProtocolV2Device;
+    method.postProgressMessage = jest.fn();
+
+    await (method as any).waitForProtocolV2FirmwareUpdateComplete([
+      { target_id: 2, path: 'vol1:ble-firmware.bin' },
+    ]);
+
+    expect(reconnectProtocolV2Device).toHaveBeenCalledTimes(1);
+    expect(typedCall).toHaveBeenCalledTimes(2);
+  });
+
+  test('passes resource, bootloader, BLE, SE and app files to DeviceFirmwareUpdate targets', async () => {
+    const resourceZip = new JSZip();
+    resourceZip.file('icons/home.png', new Uint8Array([1, 2, 3]));
+    const resourceBinary = await resourceZip.generateAsync({ type: 'arraybuffer' });
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+
+    const writtenPaths: string[] = [];
+    method.postTipMessage = jest.fn();
+    (method as any).protocolV2CreateFolder = jest.fn().mockResolvedValue(undefined);
+    (method as any).protocolV2CommonUpdateProcess = jest.fn().mockImplementation(params => {
+      writtenPaths.push(params.filePath);
+      return Number(params.processedSize ?? 0) + Number(params.payload.byteLength);
+    });
+    (method as any).protocolV2StartFirmwareUpdate = jest.fn().mockResolvedValue(undefined);
+    (method as any).waitForProtocolV2FirmwareUpdateComplete = jest
+      .fn()
+      .mockResolvedValue(undefined);
+
+    await (method as any).executeProtocolV2Update({
+      resourceBinary,
+      bootloaderBinary: new Uint8Array([4, 5]).buffer,
+      fwBinaryMap: [
+        {
+          fileName: 'ble-firmware.bin',
+          binary: new Uint8Array([6]).buffer,
+        },
+        {
+          fileName: 'se1-firmware.bin',
+          binary: new Uint8Array([7]).buffer,
+        },
+        {
+          fileName: 'firmware.bin',
+          binary: new Uint8Array([8]).buffer,
+        },
+      ],
+    });
+
+    expect((method as any).protocolV2CreateFolder).toHaveBeenCalledWith('vol1:res/');
+    expect(writtenPaths).toEqual([
+      'vol1:res/home.png',
+      'vol1:bootloader.bin',
+      'vol1:ble-firmware.bin',
+      'vol1:se1-firmware.bin',
+      'vol1:firmware.bin',
+    ]);
+    expect((method as any).protocolV2StartFirmwareUpdate).toHaveBeenCalledWith({
+      targets: [
+        { target_id: 10, path: 'vol1:res/' },
+        { target_id: 2, path: 'vol1:bootloader.bin' },
+        { target_id: 5, path: 'vol1:ble-firmware.bin' },
+        { target_id: 6, path: 'vol1:se1-firmware.bin' },
+        { target_id: 3, path: 'vol1:firmware.bin' },
+      ],
+    });
+    expect((method as any).waitForProtocolV2FirmwareUpdateComplete).toHaveBeenCalled();
+  });
+
+  test('uses absolute processed_byte offsets and disables append for firmware file writes', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const typedCall = jest.fn(
+      (
+        _name: string,
+        _resType: string,
+        params: { file: { offset: number; data: { byteLength: number } } }
+      ) =>
+        Promise.resolve({
+          type: 'FilesystemFile',
+          message: {
+            processed_byte: params.file.offset + params.file.data.byteLength,
+          },
+        })
+    );
+
+    (method as any).device = {
+      getCommands: () => ({ typedCall }),
+    };
+    method.postProgressMessage = jest.fn();
+
+    await (method as any).protocolV2CommonUpdateProcess({
+      payload: new Uint8Array(4097).buffer,
+      filePath: 'vol1:firmware.bin',
+      processedSize: 0,
+      totalSize: 4097,
+      transferStartTime: Date.now() - 1000,
+    });
+
+    const writePayloads = typedCall.mock.calls.map(call => call[2]);
+    expect(writePayloads.map(payload => payload.file.offset)).toEqual([0, 4096]);
+    expect(writePayloads.map(payload => payload.file.data.byteLength)).toEqual([4096, 1]);
+    expect(writePayloads.map(payload => payload.overwrite)).toEqual([true, false]);
+    expect(writePayloads.every(payload => payload.append === false)).toBe(true);
+    expect(method.postProgressMessage).toHaveBeenLastCalledWith(
+      99,
+      'transferData',
+      expect.objectContaining({
+        transferredBytes: 4097,
+        totalBytes: 4097,
+        rateBytesPerSecond: expect.any(Number),
+        elapsedMs: expect.any(Number),
+      })
+    );
+  });
+
+  test('caps native BLE firmware upload chunks below the WebUSB limit', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const typedCall = jest.fn(
+      (
+        _name: string,
+        _resType: string,
+        params: { file: { offset: number; data: { byteLength: number } } }
+      ) =>
+        Promise.resolve({
+          type: 'FilesystemFile',
+          message: {
+            processed_byte: params.file.offset + params.file.data.byteLength,
+          },
+        })
+    );
+
+    (method as any).params = {
+      platform: 'native',
+      chunkSize: 4096,
+    };
+    (method as any).device = {
+      getCommands: () => ({ typedCall }),
+    };
+    method.postProgressMessage = jest.fn();
+
+    await (method as any).protocolV2CommonUpdateProcess({
+      payload: new Uint8Array(1801).buffer,
+      filePath: 'vol1:ble-firmware.bin',
+      processedSize: 0,
+      totalSize: 1801,
+    });
+
+    const writePayloads = typedCall.mock.calls.map(call => call[2]);
+    expect(writePayloads.map(payload => payload.file.offset)).toEqual([0, 1800]);
+    expect(writePayloads.map(payload => payload.file.data.byteLength)).toEqual([1800, 1]);
+  });
+
+  test('consumes Protocol V2 install progress before final update success', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const typedCall = jest.fn().mockResolvedValue({ type: 'Success', message: { message: 'ok' } });
+
+    (method as any).device = {
+      getCommands: () => ({ typedCall }),
+    };
+    method.postProgressMessage = jest.fn();
+    method.postTipMessage = jest.fn();
+
+    await (method as any).protocolV2StartFirmwareUpdate({
+      targets: [{ target_id: 0, path: 'vol1:firmware.bin' }],
+    });
+
+    const callOptions = typedCall.mock.calls[0][3];
+    expect(typedCall.mock.calls[0][1]).toEqual(['Success', 'DeviceFirmwareUpdateStatus']);
+    expect(callOptions.intermediateTypes).toEqual(['DeviceFirmwareInstallProgress']);
+    callOptions.onIntermediateResponse({
+      type: 'DeviceFirmwareInstallProgress',
+      message: { target_id: 0, progress: 42 },
+    });
+
+    expect(method.postProgressMessage).toHaveBeenCalledWith(42, 'installingFirmware');
+  });
+
+  test('accepts Protocol V2 firmware update status as start response', async () => {
+    const method = new FirmwareUpdateV4({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV4',
+      },
+    });
+    const typedCall = jest.fn().mockResolvedValue({
+      type: 'DeviceFirmwareUpdateStatus',
+      message: { targets: [{ target_id: 0, status: 1 }] },
+    });
+
+    (method as any).device = {
+      getCommands: () => ({ typedCall }),
+    };
+    method.postProgressMessage = jest.fn();
+    method.postTipMessage = jest.fn();
+
+    await (method as any).protocolV2StartFirmwareUpdate({
+      targets: [{ target_id: 0, path: 'vol1:firmware.bin' }],
+    });
+
+    expect(typedCall.mock.calls[0][1]).toEqual(['Success', 'DeviceFirmwareUpdateStatus']);
+    expect(method.postTipMessage).toHaveBeenCalledWith('FirmwareUpdating');
+  });
+});
+
+describe('Protocol V2 firmware update method', () => {
+  test('returns DeviceFirmwareUpdateStatus from low-level update trigger', async () => {
+    const method = new DeviceFirmwareUpdate({
+      id: 1,
+      payload: {
+        method: 'deviceFirmwareUpdate',
+        path: 'vol0:firmware.bin',
+      },
+    });
+    method.init();
+
+    const typedCall = jest.fn().mockResolvedValue({
+      type: 'DeviceFirmwareUpdateStatus',
+      message: { targets: [{ target_id: 0, status: 1 }] },
+    });
+
+    (method as any).device = {
+      commands: { typedCall },
+    };
+
+    await expect(method.run()).resolves.toEqual({
+      targets: [{ target_id: 0, status: 1 }],
+    });
+    expect(typedCall.mock.calls[0][1]).toEqual(['Success', 'DeviceFirmwareUpdateStatus']);
+  });
+});
+
+describe('Protocol V2 onboarding status method', () => {
+  test('returns DeviceOnboardingStatus from low-level status query', async () => {
+    const method = new DeviceGetOnboardingStatus({
+      id: 1,
+      payload: {
+        method: 'deviceGetOnboardingStatus',
+      },
+    });
+    method.init();
+
+    const typedCall = jest.fn().mockResolvedValue({
+      type: 'DeviceOnboardingStatus',
+      message: {
+        page_index: 2,
+        page_count: 5,
+        page_name: 'backup',
+      },
+    });
+
+    (method as any).device = {
+      commands: { typedCall },
+    };
+
+    await expect(method.run()).resolves.toEqual({
+      page_index: 2,
+      page_count: 5,
+      page_name: 'backup',
+    });
+    expect(typedCall).toHaveBeenCalledWith('DeviceGetOnboardingStatus', 'DeviceOnboardingStatus', {});
+  });
+});
+
+describe('Protocol V2 file write method', () => {
+  test('uses demo-aligned overwrite and append defaults', async () => {
+    const typedCall = jest.fn().mockResolvedValue({ message: { processed_byte: 1 } });
+    const method = new FileWrite({
+      id: 1,
+      payload: {
+        method: 'fileWrite',
+        path: 'vol1:test.bin',
+        offset: 1,
+        totalSize: 2,
+        data: new Uint8Array([1]),
+      },
+    });
+    (method as any).device = { commands: { typedCall } };
+    method.postMessage = jest.fn();
+
+    method.init();
+    await method.run();
+
+    expect(typedCall).toHaveBeenCalledWith('FilesystemFileWrite', 'FilesystemFile', {
+      file: {
+        path: 'vol1:test.bin',
+        offset: 1,
+        total_size: 2,
+        data: new Uint8Array([1]),
+      },
+      overwrite: false,
+      append: false,
+      ui_percentage: 99,
+    });
+    expect(method.postMessage).toHaveBeenCalledWith({
+      event: 'UI_EVENT',
+      type: UI_REQUEST.DEVICE_PROGRESS,
+      payload: expect.objectContaining({
+        progress: 100,
+        transferredBytes: 1,
+        totalBytes: 1,
+        elapsedMs: expect.any(Number),
+      }),
+    });
+  });
+
+  test('splits data larger than the Protocol V2 file payload limit', async () => {
+    const data = new Uint8Array(4097);
+    const typedCall = jest.fn().mockResolvedValue({ message: {} });
+    const method = new FileWrite({
+      id: 1,
+      payload: {
+        method: 'fileWrite',
+        path: 'vol1:test.bin',
+        offset: 0,
+        totalSize: 4097,
+        data,
+      },
+    });
+    (method as any).device = { commands: { typedCall } };
+    method.postMessage = jest.fn();
+
+    method.init();
+    const result = await method.run();
+
+    expect(typedCall).toHaveBeenCalledTimes(2);
+    expect(typedCall).toHaveBeenNthCalledWith(1, 'FilesystemFileWrite', 'FilesystemFile', {
+      file: {
+        path: 'vol1:test.bin',
+        offset: 0,
+        total_size: 4097,
+        data: data.slice(0, 4096),
+      },
+      overwrite: true,
+      append: false,
+      ui_percentage: 99,
+    });
+    expect(typedCall).toHaveBeenNthCalledWith(2, 'FilesystemFileWrite', 'FilesystemFile', {
+      file: {
+        path: 'vol1:test.bin',
+        offset: 4096,
+        total_size: 4097,
+        data: data.slice(4096),
+      },
+      overwrite: false,
+      append: false,
+      ui_percentage: 99,
+    });
+    expect(result).toMatchObject({
+      path: 'vol1:test.bin',
+      processed_byte: 4097,
+      chunks: 2,
+    });
+    expect(method.postMessage).toHaveBeenNthCalledWith(1, {
+      event: 'UI_EVENT',
+      type: UI_REQUEST.DEVICE_PROGRESS,
+      payload: expect.objectContaining({
+        progress: 99,
+        transferredBytes: 4096,
+        totalBytes: 4097,
+        elapsedMs: expect.any(Number),
+      }),
+    });
+    expect(method.postMessage).toHaveBeenNthCalledWith(2, {
+      event: 'UI_EVENT',
+      type: UI_REQUEST.DEVICE_PROGRESS,
+      payload: expect.objectContaining({
+        progress: 100,
+        transferredBytes: 4097,
+        totalBytes: 4097,
+        elapsedMs: expect.any(Number),
+      }),
+    });
+  });
+
+  test('uses the BLE chunk limit by default in BLE environments', async () => {
+    const getSettingsSpy = jest.spyOn(DataManager, 'getSettings').mockReturnValue('react-native');
+    const data = new Uint8Array(1801);
+    const typedCall = jest.fn().mockResolvedValue({ message: {} });
+    const method = new FileWrite({
+      id: 1,
+      payload: {
+        method: 'fileWrite',
+        path: 'vol1:test.bin',
+        offset: 0,
+        totalSize: 1801,
+        data,
+      },
+    });
+    (method as any).device = { commands: { typedCall } };
+    method.postMessage = jest.fn();
+
+    try {
+      method.init();
+      await method.run();
+    } finally {
+      getSettingsSpy.mockRestore();
+    }
+
+    expect(typedCall).toHaveBeenCalledTimes(2);
+    expect(typedCall.mock.calls[0][2].file.data.byteLength).toBe(1800);
+    expect(typedCall.mock.calls[1][2].file.offset).toBe(1800);
+    expect(typedCall.mock.calls[1][2].file.data.byteLength).toBe(1);
+  });
+});
+
+describe('Protocol V2 file read method', () => {
+  test('reads full file in chunks when read length is 0', async () => {
+    const firstChunk = new Uint8Array(64).fill(1);
+    const typedCall = jest
+      .fn()
+      .mockResolvedValueOnce({ message: { exist: true, size: 65, directory: false } })
+      .mockResolvedValueOnce({ message: { data: firstChunk } })
+      .mockResolvedValueOnce({ message: { data: new Uint8Array([2]) } });
+    const method = new FileRead({
+      id: 1,
+      payload: {
+        method: 'fileRead',
+        path: 'vol1:test.bin',
+        offset: 0,
+        totalSize: 0,
+        chunkLen: 64,
+      },
+    });
+    (method as any).device = { commands: { typedCall } };
+
+    method.init();
+    const result = await method.run();
+
+    expect(typedCall).toHaveBeenNthCalledWith(1, 'FilesystemPathInfoQuery', 'FilesystemPathInfo', {
+      path: 'vol1:test.bin',
+    });
+    expect(typedCall).toHaveBeenNthCalledWith(2, 'FilesystemFileRead', 'FilesystemFile', {
+      file: {
+        path: 'vol1:test.bin',
+        offset: 0,
+        total_size: 0,
+      },
+      chunk_len: 64,
+      ui_percentage: 99,
+    });
+    expect(typedCall).toHaveBeenNthCalledWith(3, 'FilesystemFileRead', 'FilesystemFile', {
+      file: {
+        path: 'vol1:test.bin',
+        offset: 64,
+        total_size: 0,
+      },
+      chunk_len: 1,
+      ui_percentage: 99,
+    });
+    expect(result.data.byteLength).toBe(65);
+    expect(result.data[0]).toBe(1);
+    expect(result.data[64]).toBe(2);
+    expect(result).toMatchObject({
+      path: 'vol1:test.bin',
+      offset: 0,
+      total_size: 65,
+      chunks: 2,
+    });
+  });
+
+  test('decodes protobuf bytes hex string returned by transport', async () => {
+    const typedCall = jest.fn().mockResolvedValue({
+      message: {
+        data: '0102ff',
+      },
+    });
+    const method = new FileRead({
+      id: 1,
+      payload: {
+        method: 'fileRead',
+        path: 'vol0:test.bin',
+        offset: 0,
+        totalSize: 3,
+        chunkLen: 512,
+      },
+    });
+    (method as any).device = { commands: { typedCall } };
+
+    method.init();
+    const result = await method.run();
+
+    expect(result.data).toEqual(new Uint8Array([1, 2, 255]));
+  });
+});