feat: harden prepared firmware updates

docs/architecture/decisions.md

@@ -230,6 +230,25 @@ Pro2 acquire 后的初始化、重连和固件升级重连统一读取 `Protocol
 - `packages/core/src/device/Device.ts`
 - `packages/core/src/api/FirmwareUpdateV4.ts`
 
+## Prepared 固件 Artifact 完整性边界
+
+Prepared 固件更新将 artifact 获取与设备执行分离，完整性责任按以下边界划分：
+
+- 外部固件 Host（例如 App 的 native/desktop artifact store）负责从可信发布元数据取得预期大小和
+  SHA-256，对实际下载字节完成校验，并在首次设备变异前生成 receipt。
+- `artifactRef` 必须引用已经校验的内容寻址对象；Host 必须在 lease 和 reader 生命周期内保持对象
+  不可变，并在对象缺失或损坏时让 `open` 失败。
+- SDK 负责校验 Plan、PreparedPlan 和 receipt 的元数据绑定、artifact 大小、读取范围与 EOF，
+  但不在执行期重新计算 artifact 内容的 SHA-256。`FirmwareArtifactReceiptMismatch` 表示绑定或
+  reader 契约不匹配，不表示 SDK 已独立认证实际字节内容。
+- “首次设备变异前已完成完整性校验”的保证依赖外部 Host 履行上述契约。设备端固件签名校验是
+  独立防线，不能替代 Host 对资源 artifact 的完整性校验。
+
+主要实现：
+
+- `packages/core/src/api/firmware/FirmwareUpdatePreparedPlan.ts`
+- `packages/core/src/api/firmware/FirmwareArtifactSource.ts`
+
 ## 维护规则
 
 - 只有持续影响多个模块、不能仅从代码局部理解的规则才进入本文。

packages/connect-examples/electron-example/package.json

@@ -2,7 +2,7 @@
   "name": "hardware-example",
   "productName": "HardwareExample",
   "executableName": "onekey-hardware-example",
-  "version": "1.2.0-alpha.75",
+  "version": "1.2.0-alpha.76",
   "author": "OneKey",
   "description": "OneKey Hardware SDK Electron BLE example",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "ts:check": "yarn tsc --noEmit"
   },
   "dependencies": {
-    "@onekeyfe/hd-transport-electron": "1.2.0-alpha.75",
+    "@onekeyfe/hd-transport-electron": "1.2.0-alpha.76",
     "@stoprocent/noble": "2.3.16",
     "debug": "4.3.4",
     "electron-is-dev": "^3.0.1",

packages/connect-examples/expo-example/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-example",
-  "version": "1.2.0-alpha.75",
+  "version": "1.2.0-alpha.76",
   "scripts": {
     "start": "yarn expo start --dev-client",
     "android": "yarn expo run:android",
@@ -19,11 +19,11 @@
     "@noble/ed25519": "^2.1.0",
     "@noble/hashes": "^1.3.3",
     "@noble/secp256k1": "^1.7.1",
-    "@onekeyfe/hd-ble-sdk": "1.2.0-alpha.75",
-    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.75",
-    "@onekeyfe/hd-core": "1.2.0-alpha.75",
-    "@onekeyfe/hd-shared": "1.2.0-alpha.75",
-    "@onekeyfe/hd-transport": "1.2.0-alpha.75",
+    "@onekeyfe/hd-ble-sdk": "1.2.0-alpha.76",
+    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.76",
+    "@onekeyfe/hd-core": "1.2.0-alpha.76",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.76",
+    "@onekeyfe/hd-transport": "1.2.0-alpha.76",
     "@onekeyfe/react-native-ble-utils": "^0.1.3",
     "@polkadot/util-crypto": "13.1.1",
     "@react-native-async-storage/async-storage": "1.21.0",

packages/connect-examples/expo-playground/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onekey-hardware-playground",
-  "version": "1.2.0-alpha.75",
+  "version": "1.2.0-alpha.76",
   "private": true,
   "sideEffects": [
     "app/utils/shim.js",
@@ -18,10 +18,10 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.8.0",
-    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.75",
-    "@onekeyfe/hd-core": "1.2.0-alpha.75",
-    "@onekeyfe/hd-shared": "1.2.0-alpha.75",
-    "@onekeyfe/hd-transport": "1.2.0-alpha.75",
+    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.76",
+    "@onekeyfe/hd-core": "1.2.0-alpha.76",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.76",
+    "@onekeyfe/hd-transport": "1.2.0-alpha.76",
     "@radix-ui/react-checkbox": "^1.3.2",
     "@radix-ui/react-dialog": "^1.1.14",
     "@radix-ui/react-dropdown-menu": "^2.1.15",

packages/connect-examples/hwk-demo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hwk-demo",
-  "version": "1.2.0-alpha.75",
+  "version": "1.2.0-alpha.76",
   "private": true,
   "main": "index.js",
   "scripts": {

packages/core/__tests__/connectSettings.test.ts

@@ -1,19 +1,59 @@
+import DataManager from '../src/data-manager/DataManager';
 import { parseConnectSettings } from '../src/data-manager/connectSettings';
 
+import type { RemoteConfigResponse } from '../src/types';
+
+jest.mock('axios', () => ({
+  get: jest.fn(),
+}));
+
 jest.mock('../src/data/config', () => ({
   getSDKVersion: jest.fn(() => '1.0.0'),
   DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
 }));
 
+const mockAxiosGet: jest.Mock = jest.requireMock('axios').get;
+
 describe('parseConnectSettings', () => {
-  it('keeps custom configFetcher in parsed settings', () => {
-    const configFetcher = jest.fn();
+  const preloadedConfig = {
+    bridge: {},
+    classic: { firmware: [], ble: [] },
+    classic1s: { firmware: [], ble: [] },
+    classicpure: { firmware: [], ble: [] },
+    mini: { firmware: [], ble: [] },
+    touch: { firmware: [], ble: [] },
+    pro: { firmware: [], ble: [] },
+    pro2: { firmware: [], ble: [] },
+  } as unknown as RemoteConfigResponse;
+
+  it('keeps a serializable preloaded config in parsed settings', () => {
+    const settings = parseConnectSettings({
+      firmwareManifestMode: 'sdk-managed',
+      preloadedConfig,
+    });
+
+    expect(settings.firmwareManifestMode).toBe('sdk-managed');
+    expect(settings.preloadedConfig).toBe(preloadedConfig);
+  });
+
+  it('uses the preloaded config before the SDK network client', async () => {
+    const settings = parseConnectSettings({
+      firmwareManifestMode: 'sdk-managed',
+      preloadedConfig,
+    });
+
+    await DataManager.load(settings);
+
+    expect(mockAxiosGet).not.toHaveBeenCalled();
+    expect(DataManager.deviceMap.classic).toEqual({ firmware: [], ble: [] });
+  });
 
+  it('keeps the SDK offline and available without an external manifest snapshot', async () => {
     const settings = parseConnectSettings({
-      fetchConfig: true,
-      configFetcher,
+      firmwareManifestMode: 'external-only',
     });
 
-    expect(settings.configFetcher).toBe(configFetcher);
+    await expect(DataManager.load(settings)).resolves.toBe(false);
+    expect(mockAxiosGet).not.toHaveBeenCalled();
   });
 });

packages/core/__tests__/device-initialize-timeout.test.ts

@@ -0,0 +1,56 @@
+import { Device } from '../src/device/Device';
+import TransportManager from '../src/data-manager/TransportManager';
+
+jest.mock('../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+function buildV1Device() {
+  const device = Object.create(Device.prototype) as Device;
+  const typedCall = jest.fn(() => Promise.resolve({ message: { device_id: 'device' } }));
+  Object.assign(device, {
+    commands: { typedCall },
+    stateStore: { getState: () => undefined },
+    isProtocolV2: () => false,
+    _updateFeatures: jest.fn(),
+    getInternalState: jest.fn(() => undefined),
+  });
+  return { device, typedCall };
+}
+
+describe('Device.initialize Protocol V1 timeout', () => {
+  beforeEach(() => {
+    jest.spyOn(TransportManager, 'reconfigure').mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('passes a custom Initialize timeout through to typedCall', async () => {
+    const { device, typedCall } = buildV1Device();
+
+    await device.initialize({ timeoutMs: 2500 });
+
+    expect(typedCall).toHaveBeenCalledWith(
+      'Initialize',
+      'Features',
+      expect.objectContaining({ is_contains_attach: true }),
+      { timeoutMs: 2500 }
+    );
+  });
+
+  test('keeps the 25s Initialize timeout by default', async () => {
+    const { device, typedCall } = buildV1Device();
+
+    await device.initialize();
+
+    expect(typedCall).toHaveBeenCalledWith(
+      'Initialize',
+      'Features',
+      expect.objectContaining({ is_contains_attach: true }),
+      { timeoutMs: 25 * 1000 }
+    );
+  });
+});

packages/core/__tests__/firmware-update/check-all-firmware-release.test.ts

@@ -0,0 +1,175 @@
+import { EDeviceType, EFirmwareType, ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import CheckAllFirmwareRelease from '../../src/api/CheckAllFirmwareRelease';
+import { buildFirmwareUpdatePlan } from '../../src/api/firmware/FirmwareUpdatePlan';
+import {
+  getBleFirmwareReleaseInfo,
+  getBootloaderReleaseInfo,
+  getFirmwareReleaseInfo,
+} from '../../src/api/firmware/releaseHelper';
+
+jest.mock('../../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+jest.mock('../../src/api/firmware/FirmwareUpdatePlan', () => ({
+  buildFirmwareUpdatePlan: jest.fn(),
+  validateFirmwareUpdatePlanForceTargets: jest.fn(value => value ?? []),
+}));
+
+jest.mock('../../src/api/firmware/releaseHelper', () => ({
+  getBleFirmwareReleaseInfo: jest.fn(),
+  getBootloaderReleaseInfo: jest.fn(),
+  getFirmwareReleaseInfo: jest.fn(),
+}));
+
+const mockBuildFirmwareUpdatePlan = buildFirmwareUpdatePlan as jest.MockedFunction<
+  typeof buildFirmwareUpdatePlan
+>;
+const mockGetBleFirmwareReleaseInfo = getBleFirmwareReleaseInfo as jest.MockedFunction<
+  typeof getBleFirmwareReleaseInfo
+>;
+const mockGetBootloaderReleaseInfo = getBootloaderReleaseInfo as jest.MockedFunction<
+  typeof getBootloaderReleaseInfo
+>;
+const mockGetFirmwareReleaseInfo = getFirmwareReleaseInfo as jest.MockedFunction<
+  typeof getFirmwareReleaseInfo
+>;
+
+const noUpdate = {
+  status: 'valid' as const,
+  release: undefined,
+};
+
+const createMethod = (serialNo = 'device-id') => {
+  const method = new CheckAllFirmwareRelease({
+    id: 1,
+    payload: {
+      method: 'checkAllFirmwareRelease',
+      platform: 'native',
+    },
+  });
+  method.init();
+  method.device = {
+    isProtocolV2: jest.fn(() => false),
+    features: {
+      deviceType: EDeviceType.Classic1s,
+      serialNo,
+      firmwareType: EFirmwareType.Universal,
+      firmwareVersion: '1.0.0',
+      bootloaderVersion: '1.0.0',
+    },
+  } as typeof method.device;
+  return method;
+};
+
+const createMethodWithForceTargets = () => {
+  const method = createMethod();
+  method.payload = {
+    ...method.payload,
+    forceUpdateTargets: ['firmware', 'resource'],
+  };
+  return method;
+};
+
+describe('CheckAllFirmwareRelease', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockGetFirmwareReleaseInfo.mockReturnValue(noUpdate);
+    mockGetBootloaderReleaseInfo.mockReturnValue(noUpdate);
+    mockGetBleFirmwareReleaseInfo.mockReturnValue(noUpdate);
+  });
+
+  test('keeps release information available when an optional Plan cannot be built', async () => {
+    const firmware = {
+      status: 'outdated' as const,
+      release: {
+        url: 'https://firmware.onekey.so/classic/firmware.bin',
+        version: [3, 0, 0],
+      },
+    };
+    mockGetFirmwareReleaseInfo.mockReturnValue(firmware);
+    mockBuildFirmwareUpdatePlan.mockImplementation(() => {
+      throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Plan cannot be built', {
+        firmwareUpdateCode: 'FirmwarePlanInvalid',
+      });
+    });
+
+    await expect(createMethod('').run()).resolves.toEqual(
+      expect.objectContaining({
+        firmware,
+        bootloader: noUpdate,
+        ble: noUpdate,
+        firmwareUpdatePlan: undefined,
+      })
+    );
+  });
+
+  test('returns an optional Plan when the builder succeeds', async () => {
+    const plan = {
+      schemaVersion: 2 as const,
+      planDigest: 'a'.repeat(64),
+      executor: 'v3' as const,
+      deviceIdentity: 'device-id',
+      deviceModel: EDeviceType.Classic1s,
+      firmwareType: EFirmwareType.Universal,
+      platform: 'native' as const,
+      artifacts: [],
+      targetsToUpdate: [],
+    };
+    mockBuildFirmwareUpdatePlan.mockReturnValue(plan);
+
+    await expect(createMethod().run()).resolves.toEqual(
+      expect.objectContaining({
+        firmwareUpdatePlan: plan,
+      })
+    );
+  });
+
+  test('passes host-selected update targets to the Plan builder', async () => {
+    mockBuildFirmwareUpdatePlan.mockReturnValue({
+      schemaVersion: 2,
+      planDigest: 'a'.repeat(64),
+      executor: 'v2',
+      deviceIdentity: 'device-id',
+      deviceModel: EDeviceType.Classic1s,
+      firmwareType: EFirmwareType.Universal,
+      platform: 'native',
+      artifacts: [],
+      targetsToUpdate: [],
+    });
+
+    await createMethodWithForceTargets().run();
+
+    expect(mockBuildFirmwareUpdatePlan).toHaveBeenCalledWith(
+      expect.objectContaining({
+        forceUpdateTargets: ['firmware', 'resource'],
+      })
+    );
+  });
+
+  test('does not hide a Plan failure for an explicitly forced target', async () => {
+    const planError = ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Forced firmware target is unavailable',
+      {
+        firmwareUpdateCode: 'FirmwarePlanInvalid',
+      }
+    );
+    mockBuildFirmwareUpdatePlan.mockImplementation(() => {
+      throw planError;
+    });
+
+    await expect(createMethodWithForceTargets().run()).rejects.toBe(planError);
+  });
+
+  test('does not hide unexpected Plan builder failures', async () => {
+    const unexpectedError = new Error('unexpected builder failure');
+    mockBuildFirmwareUpdatePlan.mockImplementation(() => {
+      throw unexpectedError;
+    });
+
+    await expect(createMethod().run()).rejects.toBe(unexpectedError);
+  });
+});