@onekeyfe/hd-core 1.2.0-alpha.11 → 1.2.0-alpha.13

package/__tests__/protocol-v2-bootloader-mode.test.ts

@@ -0,0 +1,37 @@
+import { Device } from '../src/device/Device';
+import { UI_REQUEST } from '../src/events/ui-request';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+const createBootloaderDevice = (protocolType: 'V1' | 'V2') => {
+  const device = Device.fromDescriptor({
+    id: `${protocolType.toLowerCase()}-bootloader`,
+    path: `${protocolType.toLowerCase()}-bootloader`,
+    protocolType,
+  } as any);
+
+  (device as any).features = {
+    bootloaderMode: true,
+    initialized: true,
+    noBackup: false,
+  };
+
+  return device;
+};
+
+describe('Pro2 bootloader mode', () => {
+  test('does not block Protocol V2 methods in bootloader mode', () => {
+    const device = createBootloaderDevice('V2');
+
+    expect(device.hasUnexpectedMode([], [])).toBeNull();
+  });
+
+  test('keeps the Protocol V1 bootloader restriction', () => {
+    const device = createBootloaderDevice('V1');
+
+    expect(device.hasUnexpectedMode([], [])).toBe(UI_REQUEST.BOOTLOADER);
+  });
+});

package/__tests__/protocol-v2.test.ts

@@ -12,6 +12,7 @@ import DeviceFactoryInfoGet from '../src/api/protocol-v2/DeviceFactoryInfoGet';
 import DeviceFactoryInfoSet from '../src/api/protocol-v2/DeviceFactoryInfoSet';
 import DeviceFirmwareUpdate from '../src/api/protocol-v2/DeviceFirmwareUpdate';
 import DeviceGetFirmwareUpdateStatus from '../src/api/protocol-v2/DeviceGetFirmwareUpdateStatus';
+import DeviceGetOnboardingStatus from '../src/api/protocol-v2/DeviceGetOnboardingStatus';
 import DeviceInfoGet from '../src/api/protocol-v2/DeviceInfoGet';
 import DeviceReboot from '../src/api/protocol-v2/DeviceReboot';
 import DeviceSettingsGet from '../src/api/protocol-v2/DeviceSettingsGet';
@@ -26,7 +27,7 @@ import ProtocolInfoRequest from '../src/api/protocol-v2/ProtocolInfoRequest';
 import EVMSignTypedData from '../src/api/evm/EVMSignTypedData';
 import EVMSignMessageEIP712 from '../src/api/evm/EVMSignMessageEIP712';
 import FirmwareUpdateV3 from '../src/api/FirmwareUpdateV3';
-import FirmwareUpdateV4 from '../src/api/FirmwareUpdateV4';
+import FirmwareUpdateV4, { assertProtocolV2ReconnectIdentity } from '../src/api/FirmwareUpdateV4';
 import GetDeviceInfo from '../src/api/GetDeviceInfo';
 import GetPassphraseState from '../src/api/GetPassphraseState';
 import GetOnekeyFeatures from '../src/api/GetOnekeyFeatures';
@@ -62,7 +63,11 @@ import {
   refreshProtocolV2DeviceStatus,
 } from '../src/protocols/protocol-v2/walletSession';
 import { runMethodWithUnlockRetry } from '../src/protocols/protocol-v2/unlockRetry';
-import { buildProfileFromProtocolV2, buildProtocolV2FeaturesPayload } from '../src/deviceProfile';
+import {
+  buildProfileFromProtocolV2,
+  buildProtocolV1FeaturesPayload,
+  buildProtocolV2FeaturesPayload,
+} from '../src/deviceProfile';
 import {
   getDeviceType,
   getFirmwareType,
@@ -92,9 +97,12 @@ describe('DeviceUploadWallpaper', () => {
     const typedCall = jest.fn().mockImplementation((request, _response, params) => {
       if (request === 'FilesystemDirMake') return { message: { message: 'directory ready' } };
       if (request === 'FilesystemFileWrite') {
-        return { message: { processed_byte: params.file.offset + params.file.data.byteLength } };
+        const file = params.file as { data: Uint8Array; offset: number };
+        return { message: { processed_byte: file.offset + file.data.byteLength } };
+      }
+      if (request === 'DeviceSettingsSet') {
+        return { message: { message: 'wallpaper applied' } };
       }
-      if (request === 'SetWallpaper') return { message: { message: 'wallpaper applied' } };
       throw new Error(`Unexpected request: ${request}`);
     });
     const method = new DeviceUploadWallpaper({
@@ -102,32 +110,66 @@ describe('DeviceUploadWallpaper', () => {
       payload: { method: 'deviceUploadWallpaper', width: 604, height: 1024, rgba },
     });
     (method as any).device = stubDevice({ commands: { typedCall } });
+    method.postMessage = jest.fn();
 
     method.init();
     const result = await method.run();
 
     expect(method.requireProtocolV2).toBe(true);
     expect(method.unlockPolicy).toBe('retry-on-locked');
-    expect(typedCall).toHaveBeenNthCalledWith(
-      1,
-      'FilesystemDirMake',
-      'Success',
-      { path: 'vol0:/wallpapers/user' }
-    );
+    expect(typedCall).toHaveBeenNthCalledWith(1, 'FilesystemDirMake', 'Success', {
+      path: 'vol0:/wallpapers/user',
+    });
     const fileWriteCall = typedCall.mock.calls.find(call => call[0] === 'FilesystemFileWrite');
     expect(fileWriteCall?.[2]).toMatchObject({
       file: { path: expect.stringMatching(/^vol0:\/wallpapers\/user\/wallpaper-[a-f0-9]+\.bin$/) },
       overwrite: true,
       append: false,
     });
-    expect(typedCall).toHaveBeenLastCalledWith('SetWallpaper', 'Success', {
-      target: 1,
-      path: result.path,
+    expect(typedCall).toHaveBeenLastCalledWith('DeviceSettingsSet', 'Success', {
+      settings: { wallpaper_path: result.path },
     });
+    expect(typedCall.mock.calls.some(call => call[0] === 'SetWallpaper')).toBe(false);
     expect(result).toMatchObject({ colorFormat: 'RGB565', message: 'wallpaper applied' });
+    const fileWriteCallCount = typedCall.mock.calls.filter(
+      call => call[0] === 'FilesystemFileWrite'
+    ).length;
+    expect(method.postMessage).toHaveBeenCalledTimes(fileWriteCallCount);
+    expect(method.postMessage).toHaveBeenLastCalledWith({
+      event: 'UI_EVENT',
+      type: UI_REQUEST.DEVICE_PROGRESS,
+      payload: expect.objectContaining({
+        progress: 100,
+        transferredBytes: result.size,
+        totalBytes: result.size,
+        elapsedMs: expect.any(Number),
+      }),
+    });
   });
 
-  test('rejects unsafe filenames before device communication', async () => {
+  test('文件上传失败时不修改 wallpaper_path', async () => {
+    const typedCall = jest.fn().mockImplementation(request => {
+      if (request === 'FilesystemDirMake') return { message: {} };
+      if (request === 'FilesystemFileWrite') throw new Error('write failed');
+      return { message: {} };
+    });
+    const method = new DeviceUploadWallpaper({
+      id: 1,
+      payload: {
+        method: 'deviceUploadWallpaper',
+        width: 604,
+        height: 1024,
+        rgba: new Uint8Array(604 * 1024 * 4),
+      },
+    });
+    (method as any).device = stubDevice({ commands: { typedCall } });
+    method.init();
+
+    await expect(method.run()).rejects.toThrow('write failed');
+    expect(typedCall.mock.calls.some(call => call[0] === 'DeviceSettingsSet')).toBe(false);
+  });
+
+  test('rejects unsafe filenames before device communication', () => {
     const method = new DeviceUploadWallpaper({
       id: 1,
       payload: {
@@ -208,9 +250,9 @@ describe('UploadPortfolio', () => {
   test('stops after the acknowledged chunk when the operation is aborted', async () => {
     const packageBytes = new Uint8Array(4001);
     const abortController = new AbortController();
-    const typedCall = jest.fn().mockImplementationOnce(async () => {
+    const typedCall = jest.fn().mockImplementationOnce(() => {
       abortController.abort();
-      return { message: { processed_byte: 2048 } };
+      return Promise.resolve({ message: { processed_byte: 2048 } });
     });
     const method = new UploadPortfolio({
       id: 1,
@@ -297,6 +339,38 @@ async function requestProtocolV2Features({
 }
 
 describe('Protocol V2 feature adapter', () => {
+  test('keeps legacy snake_case feature fields for existing SDK consumers', () => {
+    const protocolV1 = buildProtocolV1FeaturesPayload({
+      device_id: 'v1-device',
+      session_id: 'v1-session',
+      ble_name: 'Classic BLE',
+      passphrase_protection: true,
+      unlocked: true,
+    } as any);
+    const protocolV2 = buildProtocolV2FeaturesPayload({
+      hw: { serial_no: 'P2-001' },
+      coprocessor: { bt_adv_name: 'Pro 2 BLE' },
+      status: {
+        device_id: 'v2-device',
+        unlocked: true,
+        passphrase_enabled: true,
+      },
+    } as any);
+
+    expect(protocolV1).toMatchObject({
+      device_id: 'v1-device',
+      session_id: 'v1-session',
+      ble_name: 'Classic BLE',
+      passphrase_protection: true,
+    });
+    expect(protocolV2).toMatchObject({
+      device_id: 'v2-device',
+      ble_name: 'Pro 2 BLE',
+      onekey_device_type: 'PRO2',
+      passphrase_protection: true,
+    });
+  });
+
   test('normalizes Protocol V2 DeviceInfo into existing Features fields', () => {
     const features = normalizeProtocolV2Features(descriptor as any, {
       protocol_version: 1,
@@ -304,10 +378,16 @@ describe('Protocol V2 feature adapter', () => {
         serial_no: 'PR2SERIAL',
       },
       fw: {
-        application_data: {
+        romloader: {
           version: '0.1.0',
+          build_id: 'rom-build',
           hash: [1, 2, 255],
         },
+        application_data: {
+          version: '9.8.7',
+          build_id: 'app-data-build',
+          hash: [9, 8, 7],
+        },
         bootloader: {
           version: '0.2.0',
           build_id: 'boot-build',
@@ -362,6 +442,8 @@ describe('Protocol V2 feature adapter', () => {
     expect(features.bootloaderVersion).toBe('0.2.0');
     expect(features.verify?.bootloaderBuildId).toBe('boot-build');
     expect(features.verify?.bootloaderHash).toBe('0a0b');
+    expect(features.boardVersion).toBe('0.1.0');
+    expect(features.verify?.boardBuildId).toBe('rom-build');
     expect(features.verify?.boardHash).toBe('0102ff');
     expect(features.bleName).toBe('Pro2 BLE');
     expect(features.bleVersion).toBe('4.5.6');
@@ -401,6 +483,32 @@ describe('Protocol V2 feature adapter', () => {
     expect(profile.status.bootloaderMode).toBe(true);
   });
 
+  test('marks current romloader-shaped Protocol V2 DeviceInfo as romloader mode', () => {
+    const deviceInfo = {
+      protocol_version: 1,
+      hw: {
+        serial_no: 'PR2ROM',
+      },
+      fw: {
+        romloader: {
+          version: '1.0.0',
+        },
+        bootloader: {
+          version: '2.0.0',
+        },
+      },
+    };
+    const features = normalizeProtocolV2Features(descriptor as any, deviceInfo);
+    const profile = buildProfileFromProtocolV2({ deviceInfo });
+
+    expect(features.mode).toBe('romloader');
+    expect(features.bootloaderMode).toBe(false);
+    expect(features.boardVersion).toBe('1.0.0');
+    expect(profile.status.mode).toBe('romloader');
+    expect(profile.status.bootloaderMode).toBe(false);
+    expect(profile.versions.board).toBe('1.0.0');
+  });
+
   test('uses DeviceSessionGet for Protocol V2 passphrase sessions', async () => {
     const features = normalizeProtocolV2Features(descriptor as any);
     features.firmwareVersion = '1.2.3';
@@ -460,6 +568,32 @@ describe('Protocol V2 feature adapter', () => {
     expect(updateProtocolV2Features).not.toHaveBeenCalled();
   });
 
+  test('deviceGetOnboardingStatus returns the real Protocol V2 onboarding stage', async () => {
+    const typedCall = jest.fn().mockResolvedValue({
+      type: 'DevOnboardingStatus',
+      message: { stage: 2, status_code: 3, detail_code: 4 },
+    });
+    const method = new DeviceGetOnboardingStatus({
+      payload: {
+        method: 'deviceGetOnboardingStatus',
+        connectId: 'connect-id',
+      },
+    });
+    method.init();
+    method.device = stubDevice({
+      originalDescriptor: { ...descriptor, protocolType: 'V2' },
+      commands: { typedCall },
+    }) as any;
+
+    await expect(method.run()).resolves.toEqual({
+      stage: 2,
+      status_code: 3,
+      detail_code: 4,
+    });
+    expect(typedCall).toHaveBeenCalledWith('DevGetOnboardingStatus', 'DevOnboardingStatus', {});
+    expect(method.requireProtocolV2).toBe(true);
+  });
+
   test('deviceSessionGet sends an empty request and does not mutate wallet cache', async () => {
     const typedCall = jest.fn().mockResolvedValue({
       type: 'DeviceSession',
@@ -492,6 +626,7 @@ describe('Protocol V2 feature adapter', () => {
     const api = createCoreApi(call as any);
 
     await api.deviceStatusGet('connect-id', { retryCount: 1 });
+    await api.deviceGetOnboardingStatus('connect-id', { retryCount: 1 });
     await api.deviceSessionGet('connect-id', { retryCount: 1 });
 
     expect(call).toHaveBeenNthCalledWith(1, {
@@ -500,6 +635,11 @@ describe('Protocol V2 feature adapter', () => {
       retryCount: 1,
     });
     expect(call).toHaveBeenNthCalledWith(2, {
+      method: 'deviceGetOnboardingStatus',
+      connectId: 'connect-id',
+      retryCount: 1,
+    });
+    expect(call).toHaveBeenNthCalledWith(3, {
       method: 'deviceSessionGet',
       connectId: 'connect-id',
       retryCount: 1,
@@ -1540,7 +1680,7 @@ describe('Protocol V2 feature adapter', () => {
       }),
       expect.anything()
     );
-    expect(message).toEqual({});
+    expect(message).toEqual({ onekey_device_type: 'PRO2' });
     expect(message).not.toHaveProperty('label');
   });
 
@@ -1748,11 +1888,17 @@ describe('Protocol V2 feature adapter', () => {
     const typedCall = jest.fn().mockImplementation(requestType => {
       if (requestType === 'DeviceSessionAskPin') {
         return {
-          type: 'DeviceSessionPinResult',
+          type: 'Success',
+          message: { message: 'ok' },
+        };
+      }
+      if (requestType === 'DeviceStatusGet') {
+        return {
+          type: 'DeviceStatus',
           message: {
             unlocked: true,
-            unlocked_attach_pin: true,
-            passphrase_protection: true,
+            unlocked_by_attach_to_pin: true,
+            passphrase_enabled: true,
           },
         };
       }
@@ -1773,7 +1919,10 @@ describe('Protocol V2 feature adapter', () => {
 
     const features = await device.unlockDevice();
 
-    expect(typedCall.mock.calls).toEqual([['DeviceSessionAskPin', 'DeviceSessionPinResult']]);
+    expect(typedCall.mock.calls).toEqual([
+      ['DeviceSessionAskPin', 'Success'],
+      ['DeviceStatusGet', 'DeviceStatus', {}],
+    ]);
     expect(typedCall).not.toHaveBeenCalledWith('GetAddress', 'Address', expect.anything());
     expect(typedCall).not.toHaveBeenCalledWith('GetFeatures', 'Features', {});
     expect(features).toMatchObject({
@@ -1790,7 +1939,7 @@ describe('Protocol V2 feature adapter', () => {
     });
   });
 
-  test('syncs Protocol V2 features passphrase state from DeviceSessionPinResult after unlock', async () => {
+  test('syncs Protocol V2 features passphrase state from DeviceStatus after unlock', async () => {
     const device = Device.fromDescriptor({ ...descriptor, protocolType: 'V2' } as any);
     (device as any).features = normalizeProtocolV2Features(
       { ...descriptor, protocolType: 'V2' } as any,
@@ -1803,11 +1952,17 @@ describe('Protocol V2 feature adapter', () => {
     const typedCall = jest.fn().mockImplementation(requestType => {
       if (requestType === 'DeviceSessionAskPin') {
         return {
-          type: 'DeviceSessionPinResult',
+          type: 'Success',
+          message: { message: 'ok' },
+        };
+      }
+      if (requestType === 'DeviceStatusGet') {
+        return {
+          type: 'DeviceStatus',
           message: {
             unlocked: true,
-            unlocked_attach_pin: true,
-            passphrase_protection: true,
+            unlocked_by_attach_to_pin: true,
+            passphrase_enabled: true,
           },
         };
       }
@@ -1817,7 +1972,10 @@ describe('Protocol V2 feature adapter', () => {
 
     await device.unlockDevice();
 
-    expect(typedCall.mock.calls).toEqual([['DeviceSessionAskPin', 'DeviceSessionPinResult']]);
+    expect(typedCall.mock.calls).toEqual([
+      ['DeviceSessionAskPin', 'Success'],
+      ['DeviceStatusGet', 'DeviceStatus', {}],
+    ]);
     expect((device as any).profile).toBeUndefined();
     expect(device.features?.unlocked).toBe(true);
     expect(device.features?.passphraseProtection).toBe(true);
@@ -1844,7 +2002,7 @@ describe('Protocol V2 feature adapter', () => {
       })
     );
     expect(typedCall).toHaveBeenCalledTimes(1);
-    expect(typedCall.mock.calls).toEqual([['DeviceSessionAskPin', 'DeviceSessionPinResult']]);
+    expect(typedCall.mock.calls).toEqual([['DeviceSessionAskPin', 'Success']]);
     expect(typedCall).not.toHaveBeenCalledWith(
       'DeviceSessionGet',
       'DeviceSession',
@@ -3465,7 +3623,7 @@ describe('Protocol V2 firmware update targets', () => {
     expect(writeOffsets).toEqual([0, 4000, 0, 4000, 8000]);
   });
 
-  test('continues to DeviceFirmwareUpdate when FilesystemFileWrite returns processed chunk length', async () => {
+  test('rejects a chunk-relative processed_byte during firmware staging', async () => {
     const method = new FirmwareUpdateV4({
       id: 1,
       payload: {
@@ -3481,23 +3639,6 @@ describe('Protocol V2 firmware update targets', () => {
           },
         });
       }
-      if (name === 'FilesystemPathInfoQuery') {
-        return Promise.resolve({
-          type: 'FilesystemPathInfo',
-          message: { exist: true, directory: false, size: 4097 },
-        });
-      }
-      if (name === 'DeviceFirmwareUpdateRequest') {
-        return Promise.resolve({ type: 'Success', message: { message: 'ok' } });
-      }
-      if (name === 'DeviceFirmwareUpdateStatusGet') {
-        return Promise.resolve({
-          type: 'DeviceFirmwareUpdateStatus',
-          message: {
-            records: [{ target_id: 4, status: 2 }],
-          },
-        });
-      }
       return Promise.reject(new Error(`unexpected call ${name}`));
     });
 
@@ -3507,27 +3648,15 @@ describe('Protocol V2 firmware update targets', () => {
     method.postProgressMessage = jest.fn();
     method.postTipMessage = jest.fn();
 
-    await (method as any).executeProtocolV2Update({
-      bootloaderBinary: null,
-      fwBinaryMap: [
-        {
-          fileName: 'firmware.bin',
-          binary: new Uint8Array(4097).buffer,
-          targetId: 4,
-        },
-      ],
-    });
-
-    expect(typedCall).toHaveBeenCalledWith(
-      'DeviceFirmwareUpdateRequest',
-      ['Success', 'DeviceFirmwareUpdateStatus'],
-      {
-        targets: [{ target_id: 4, path: 'vol0:/firmware.bin' }],
-      },
-      expect.objectContaining({
-        timeoutMs: 3 * 60 * 1000,
+    await expect(
+      (method as any).protocolV2WriteWholeFile({
+        payload: new Uint8Array(4097).buffer,
+        filePath: 'vol0:/firmware.bin',
+        processedSize: 0,
+        totalSize: 4097,
       })
-    );
+    ).rejects.toMatchObject({ errorCode: HardwareErrorCode.EmmcFileWriteFirmwareError });
+    expect(typedCall).toHaveBeenCalledTimes(2);
   });
 
   test('caps native BLE firmware upload chunks below the WebUSB limit', async () => {
@@ -3689,6 +3818,26 @@ describe('Protocol V2 firmware update method', () => {
     });
   });
 
+  test('does not report a generic USB transfer failure as a started firmware update', async () => {
+    const method = new DeviceFirmwareUpdate({
+      id: 1,
+      payload: {
+        method: 'deviceFirmwareUpdate',
+        targetId: 4,
+        path: 'vol0:firmware.bin',
+      },
+    });
+    method.init();
+    const error = new Error(
+      "Failed to execute 'transferOut' on 'USBDevice': A transfer error has occurred"
+    );
+    (method as any).device = stubDevice({
+      commands: { typedCall: jest.fn().mockRejectedValue(error) },
+    });
+
+    await expect(method.run()).rejects.toBe(error);
+  });
+
   test('rejects missing or invalid firmware targets before transport call', async () => {
     const typedCall = jest.fn();
     const method = new DeviceFirmwareUpdate({
@@ -3820,6 +3969,20 @@ describe('Protocol V2 firmware update method', () => {
   });
 });
 
+describe('Protocol V2 firmware reconnect identity', () => {
+  test('rejects a different device before firmware transfer resumes', () => {
+    expect(() => assertProtocolV2ReconnectIdentity('expected-device', 'other-device')).toThrow(
+      'identity mismatch'
+    );
+    expect(() => assertProtocolV2ReconnectIdentity('expected-device', undefined)).toThrow(
+      'identity unavailable'
+    );
+    expect(() =>
+      assertProtocolV2ReconnectIdentity('expected-device', 'expected-device')
+    ).not.toThrow();
+  });
+});
+
 describe('Protocol V2 reboot methods', () => {
   test('sends DeviceReboot from deviceReboot', async () => {
     const typedCall = jest.fn().mockResolvedValue({ message: { message: 'ok' } });
@@ -3853,19 +4016,20 @@ describe('Protocol V2 protected method execution', () => {
       unlockPolicy: 'retry-on-locked',
       run: jest
         .fn()
-        .mockImplementationOnce(async () => {
+        .mockImplementationOnce(() => {
           calls.push('run-1');
-          throw deviceLockedError();
+          return Promise.reject(deviceLockedError());
         })
-        .mockImplementationOnce(async () => {
+        .mockImplementationOnce(() => {
           calls.push('run-2');
-          return { message: 'ok' };
+          return Promise.resolve({ message: 'ok' });
         }),
     };
     const device = {
       isProtocolV2: () => true,
-      unlockDevice: jest.fn(async () => {
+      unlockDevice: jest.fn(() => {
         calls.push('unlock');
+        return Promise.resolve();
       }),
     };
 
@@ -3883,9 +4047,7 @@ describe('Protocol V2 protected method execution', () => {
       const error = deviceLockedError();
       const method = {
         unlockPolicy,
-        run: jest.fn(async () => {
-          throw error;
-        }),
+        run: jest.fn().mockRejectedValue(error),
       };
       const device = {
         isProtocolV2: () => isProtocolV2,
@@ -3903,15 +4065,11 @@ describe('Protocol V2 protected method execution', () => {
     const unlockError = new Error('PIN cancelled');
     const unlockFailMethod = {
       unlockPolicy: 'retry-on-locked',
-      run: jest.fn(async () => {
-        throw initialError;
-      }),
+      run: jest.fn().mockRejectedValue(initialError),
     };
     const unlockFailDevice = {
       isProtocolV2: () => true,
-      unlockDevice: jest.fn(async () => {
-        throw unlockError;
-      }),
+      unlockDevice: jest.fn().mockRejectedValue(unlockError),
     };
 
     await expect(
@@ -3926,7 +4084,7 @@ describe('Protocol V2 protected method execution', () => {
     };
     const retryFailDevice = {
       isProtocolV2: () => true,
-      unlockDevice: jest.fn(async () => undefined),
+      unlockDevice: jest.fn().mockResolvedValue(undefined),
     };
 
     await expect(
@@ -4244,7 +4402,7 @@ 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 typedCall = jest.fn().mockResolvedValue({ message: { processed_byte: 2 } });
     const method = new FileWrite({
       id: 1,
       payload: {

package/__tests__/protocolV2FileWrite.test.ts

@@ -0,0 +1,67 @@
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import { writeProtocolV2File } from '../src/api/helpers/protocolV2FileWrite';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+describe('writeProtocolV2File', () => {
+  test('按分片写入并只在首片设置 overwrite', async () => {
+    const data = new Uint8Array(4097);
+    const typedCall = jest.fn().mockResolvedValue({ message: {} });
+    const onProgress = jest.fn();
+
+    const result = await writeProtocolV2File({
+      commands: { typedCall } as any,
+      path: 'vol0:/wallpapers/user/test.bin',
+      data,
+      totalSize: data.byteLength,
+      overwrite: true,
+      onProgress,
+    });
+
+    expect(typedCall).toHaveBeenCalledTimes(2);
+    expect(typedCall.mock.calls[0][2]).toMatchObject({
+      file: { offset: 0, total_size: 4097, data: data.slice(0, 4000) },
+      overwrite: true,
+      append: false,
+      ui_percentage: 0,
+    });
+    expect(typedCall.mock.calls[1][2]).toMatchObject({
+      file: { offset: 4000, total_size: 4097, data: data.slice(4000) },
+      overwrite: false,
+      append: false,
+      ui_percentage: 100,
+    });
+    expect(result).toMatchObject({ processed_byte: 4097, chunks: 2 });
+    expect(onProgress).toHaveBeenLastCalledWith(
+      expect.objectContaining({ progress: 100, transferredBytes: 4097, totalBytes: 4097 })
+    );
+  });
+
+  test('拒绝越过文件末尾的 processed_byte', async () => {
+    const typedCall = jest.fn().mockResolvedValue({ message: { processed_byte: 10 } });
+
+    await expect(
+      writeProtocolV2File({
+        commands: { typedCall } as any,
+        path: 'vol0:/wallpapers/user/test.bin',
+        data: new Uint8Array([1]),
+      })
+    ).rejects.toMatchObject({ errorCode: HardwareErrorCode.RuntimeError });
+  });
+
+  test('设备返回未前进的绝对 processed_byte 时立即失败', async () => {
+    const typedCall = jest.fn().mockResolvedValue({ message: { processed_byte: 0 } });
+
+    await expect(
+      writeProtocolV2File({
+        commands: { typedCall } as any,
+        path: 'vol0:/wallpapers/user/test.bin',
+        data: new Uint8Array([1, 2, 3]),
+      })
+    ).rejects.toMatchObject({ errorCode: HardwareErrorCode.RuntimeError });
+  });
+});

package/dist/api/FileWrite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileWrite.d.ts","sourceRoot":"","sources":["../../src/api/FileWrite.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAW1C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B,CAAC;AA2EF,MAAM,CAAC,OAAO,OAAO,SAAU,SAAQ,UAAU,CAAC,eAAe,CAAC;IAChE,IAAI;IAsBE,GAAG;;;;;;;CA8GV"}
+{"version":3,"file":"FileWrite.d.ts","sourceRoot":"","sources":["../../src/api/FileWrite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAW1C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,OAAO,OAAO,SAAU,SAAQ,UAAU,CAAC,eAAe,CAAC;IAChE,IAAI;IAsBE,GAAG;;;;;;;CAqBV"}

package/dist/api/FirmwareUpdateV4.d.ts

@@ -1,6 +1,8 @@
 import { FirmwareUpdateBaseMethod } from './firmware/FirmwareUpdateBaseMethod';
 import type { FirmwareUpdateV4Params } from '../types/api/firmwareUpdate';
+export declare const assertProtocolV2ReconnectIdentity: (expectedDeviceId?: string, actualDeviceId?: string) => void;
 export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareUpdateV4Params> {
+    private protocolV2ExpectedDeviceId?;
     init(): void;
     private getProtocolV2FirmwareChunkSize;
     run(): Promise<{