@onekeyfe/hd-core 1.2.0-alpha.9 → 1.2.0-alpha.90

package/__tests__/firmware-update/firmware-artifact-source.test.ts

@@ -0,0 +1,119 @@
+import {
+  MAX_FIRMWARE_ARTIFACT_READ_BYTES,
+  openFirmwareByteSource,
+  writeFirmwareByteSource,
+} from '../../src/api/firmware/FirmwareArtifactSource';
+
+import type { FirmwareArtifactReader } from '../../src/types/api/firmwareUpdate';
+
+const artifact = {
+  artifactRef: `fw:${'a'.repeat(64)}`,
+  size: 6,
+  sha256: 'b'.repeat(64),
+};
+
+const createReader = () => {
+  const open = jest.fn(() => Promise.resolve({ readerId: 'reader-1', size: artifact.size }));
+  const read = jest.fn(({ offset, length }: { readerId: string; offset: number; length: number }) =>
+    Promise.resolve({
+      data: Uint8Array.from([1, 2, 3, 4, 5, 6]).slice(offset, offset + length).buffer,
+      bytesRead: length,
+      eof: offset + length === artifact.size,
+    })
+  );
+  const close = jest.fn(() => Promise.resolve());
+  const reader: FirmwareArtifactReader = { open, read, close };
+  return { reader, open, read, close };
+};
+
+describe('FirmwareArtifactSource', () => {
+  it('reads an opaque artifact through bounded sequential reads', async () => {
+    const { reader, close } = createReader();
+    const source = await openFirmwareByteSource({ artifact, reader });
+    if (!source) {
+      throw new Error('Expected a firmware byte source');
+    }
+
+    const writes: Array<{ offset: number; data: number[] }> = [];
+    await writeFirmwareByteSource({
+      source,
+      chunkSize: 4,
+      write: ({ data, sourceOffset, length }) => {
+        writes.push({
+          offset: sourceOffset,
+          data: Array.from(new Uint8Array(data)),
+        });
+        return Promise.resolve(length);
+      },
+    });
+    await source.close();
+
+    expect(writes).toEqual([
+      { offset: 0, data: [1, 2, 3, 4] },
+      { offset: 4, data: [5, 6] },
+    ]);
+    expect(close).toHaveBeenCalledWith({ readerId: 'reader-1' });
+  });
+
+  it('rejects a reader whose opened size differs from the receipt', async () => {
+    const { reader, open, close } = createReader();
+    open.mockResolvedValue({
+      readerId: 'reader-1',
+      size: artifact.size + 1,
+    });
+
+    await expect(openFirmwareByteSource({ artifact, reader })).rejects.toMatchObject({
+      params: {
+        firmwareUpdateCode: 'FirmwareArtifactReceiptMismatch',
+      },
+    });
+    expect(close).toHaveBeenCalledWith({ readerId: 'reader-1' });
+  });
+
+  it('rejects paths and over-limit reads before invoking the host', async () => {
+    const { reader, read } = createReader();
+    await expect(
+      openFirmwareByteSource({
+        artifact: { ...artifact, artifactRef: '/tmp/firmware.bin' },
+        reader,
+      })
+    ).rejects.toMatchObject({
+      params: {
+        firmwareUpdateCode: 'FirmwareArtifactReceiptMismatch',
+      },
+    });
+
+    const source = await openFirmwareByteSource({ artifact, reader });
+    if (!source) {
+      throw new Error('Expected a firmware byte source');
+    }
+    await expect(
+      writeFirmwareByteSource({
+        source,
+        chunkSize: MAX_FIRMWARE_ARTIFACT_READ_BYTES + 1,
+        write: ({ length }) => Promise.resolve(length),
+      })
+    ).rejects.toMatchObject({
+      params: {
+        firmwareUpdateCode: 'FirmwareArtifactReadTooLarge',
+      },
+    });
+    expect(read).not.toHaveBeenCalled();
+    await source.close();
+  });
+
+  it('closes stale readers when open returns invalid metadata', async () => {
+    const { reader, open, close } = createReader();
+    open.mockResolvedValue({
+      readerId: '',
+      size: artifact.size,
+    });
+
+    await expect(openFirmwareByteSource({ artifact, reader })).rejects.toMatchObject({
+      params: {
+        firmwareUpdateCode: 'FirmwareArtifactReceiptMismatch',
+      },
+    });
+    expect(close).not.toHaveBeenCalled();
+  });
+});

package/__tests__/firmware-update/firmware-host-binding.test.ts

@@ -0,0 +1,79 @@
+import {
+  getFirmwareUpdateHostBindingGeneration,
+  registerFirmwareUpdateHostBinding,
+  resolveFirmwareUpdateHostBinding,
+  unregisterFirmwareUpdateHostBinding,
+} from '../../src/api/firmware/FirmwareHostBinding';
+
+const createBinding = () => ({
+  preparedPlanDigest: 'a'.repeat(64),
+  artifactReader: {
+    open: jest.fn(() => Promise.resolve({ readerId: 'reader-1', size: 4 })),
+    read: jest.fn(() =>
+      Promise.resolve({
+        data: new ArrayBuffer(4),
+        bytesRead: 4,
+        eof: true,
+      })
+    ),
+    close: jest.fn(() => Promise.resolve()),
+  },
+});
+
+describe('firmware host binding generation', () => {
+  afterEach(() => {
+    unregisterFirmwareUpdateHostBinding();
+  });
+
+  test('invalidates callbacks from a replaced generation', async () => {
+    const staleBinding = createBinding();
+    const staleGeneration = registerFirmwareUpdateHostBinding(staleBinding);
+    const stale = resolveFirmwareUpdateHostBinding(staleGeneration);
+    const activeGeneration = registerFirmwareUpdateHostBinding(createBinding());
+
+    expect(activeGeneration).toBeGreaterThan(staleGeneration);
+    expect(getFirmwareUpdateHostBindingGeneration()).toBe(activeGeneration);
+    await expect(
+      stale.artifactReader.read({
+        readerId: 'reader-1',
+        offset: 0,
+        length: 4,
+      })
+    ).rejects.toMatchObject({
+      params: {
+        firmwareUpdateCode: 'FirmwareArtifactReaderInvalid',
+      },
+    });
+    expect(unregisterFirmwareUpdateHostBinding(staleGeneration)).toBe(false);
+    expect(getFirmwareUpdateHostBindingGeneration()).toBe(activeGeneration);
+  });
+
+  test('closes an artifact opened during a generation race', async () => {
+    const binding = createBinding();
+    binding.artifactReader.open.mockImplementationOnce(() => {
+      registerFirmwareUpdateHostBinding(createBinding());
+      return Promise.resolve({ readerId: 'stale-reader', size: 4 });
+    });
+    const generation = registerFirmwareUpdateHostBinding(binding);
+    const guarded = resolveFirmwareUpdateHostBinding(generation);
+
+    await expect(
+      guarded.artifactReader.open({ artifactRef: `fw:${'a'.repeat(64)}` })
+    ).rejects.toMatchObject({
+      params: {
+        firmwareUpdateCode: 'FirmwareArtifactReaderInvalid',
+      },
+    });
+    expect(binding.artifactReader.close).toHaveBeenCalledWith({
+      readerId: 'stale-reader',
+    });
+  });
+
+  test('rejects a prepared plan from another host generation before opening artifacts', () => {
+    const generation = registerFirmwareUpdateHostBinding(createBinding());
+
+    expect(() => resolveFirmwareUpdateHostBinding(generation, 'b'.repeat(64))).toThrow(
+      'does not match the prepared plan'
+    );
+  });
+});

package/__tests__/firmware-update/firmware-preparation-error.test.ts

@@ -0,0 +1,27 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import { normalizeFirmwarePreparationError } from '../../src/api/firmware/FirmwarePreparationError';
+
+describe('normalizeFirmwarePreparationError', () => {
+  test('preserves structured firmware invariant errors', () => {
+    const error = ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Firmware must be prepared by the external firmware host',
+      {
+        firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
+        artifactName: 'firmware',
+      }
+    );
+
+    expect(normalizeFirmwarePreparationError(error)).toBe(error);
+  });
+
+  test('wraps ordinary preparation failures as firmware download errors', () => {
+    const error = normalizeFirmwarePreparationError(new Error('request failed'));
+
+    expect(error).toMatchObject({
+      errorCode: HardwareErrorCode.FirmwareUpdateDownloadFailed,
+      message: 'request failed',
+    });
+  });
+});

package/__tests__/firmware-update/firmware-prepared-host-digest.test.ts

@@ -0,0 +1,209 @@
+import { EDeviceType, EFirmwareType } from '@onekeyfe/hd-shared';
+
+import FirmwareUpdateV2 from '../../src/api/FirmwareUpdateV2';
+import FirmwareUpdateV3 from '../../src/api/FirmwareUpdateV3';
+import DeviceUpdateBootloader from '../../src/api/device/DeviceUpdateBootloader';
+import {
+  registerFirmwareUpdateHostBinding,
+  unregisterFirmwareUpdateHostBinding,
+} from '../../src/api/firmware/FirmwareHostBinding';
+import { prepareFirmwareUpdatePlan } from '../../src/api/firmware/FirmwareUpdatePreparedPlan';
+import { buildFirmwareUpdatePlan } from '../../src/api/firmware/FirmwareUpdatePlan';
+
+import type { FirmwareArtifactReference } from '../../src/types/api/firmwareUpdate';
+import type { Features } from '../../src/types';
+
+jest.mock('../../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+const noUpdate = {
+  status: 'valid' as const,
+  release: undefined,
+};
+
+const createPreparedPlan = ({
+  executor,
+  target,
+}: {
+  executor: 'v2' | 'v3';
+  target: 'firmware' | 'bootloader';
+}) => {
+  const sha256 = target === 'firmware' ? 'a'.repeat(64) : 'b'.repeat(64);
+  const artifact: FirmwareArtifactReference = {
+    artifactRef: `fw:${sha256}`,
+    size: 4,
+    sha256,
+  };
+  const isV3 = executor === 'v3';
+  const plan = buildFirmwareUpdatePlan({
+    features: {
+      deviceType: isV3 ? EDeviceType.Pro : EDeviceType.Classic1s,
+      serialNo: isV3 ? 'pro-device-id' : 'classic-device-id',
+      firmwareVersion: '1.0.0',
+      bootloaderVersion: isV3 ? '2.8.0' : '1.0.0',
+    } as Features,
+    firmwareType: EFirmwareType.Universal,
+    platform: 'desktop',
+    firmware:
+      target === 'firmware'
+        ? {
+            status: 'outdated',
+            release: {
+              url: 'https://firmware.onekey.so/firmware.bin',
+              expectedSize: artifact.size,
+              fingerprint: artifact.sha256,
+              version: [3, 0, 0],
+            },
+          }
+        : noUpdate,
+    ble: noUpdate,
+    bootloader:
+      target === 'bootloader'
+        ? {
+            status: 'outdated',
+            shouldUpdate: true,
+            release: {
+              bootloaderResource: 'https://firmware.onekey.so/bootloader.bin',
+              bootloaderExpectedSize: artifact.size,
+              bootloaderFingerprint: artifact.sha256,
+              bootloaderVersion: [2, 0, 0],
+            },
+          }
+        : noUpdate,
+  });
+  expect(plan.executor).toBe(executor);
+  const preparedPlan = prepareFirmwareUpdatePlan({
+    plan,
+    leaseRef: `fwlease:${executor}:${target}`,
+    artifacts: [{ artifactId: target, artifact }],
+  });
+  return { artifact, preparedPlan };
+};
+
+const registerMismatchedHost = () => {
+  const artifactReader = {
+    open: jest.fn(),
+    read: jest.fn(),
+    close: jest.fn(),
+  };
+  const hostBindingGeneration = registerFirmwareUpdateHostBinding({
+    preparedPlanDigest: 'f'.repeat(64),
+    artifactReader,
+  });
+  return { artifactReader, hostBindingGeneration };
+};
+
+describe('prepared firmware host digest binding', () => {
+  afterEach(() => {
+    unregisterFirmwareUpdateHostBinding();
+    jest.restoreAllMocks();
+  });
+
+  test('FirmwareUpdateV2 rejects a host registered for another prepared plan', () => {
+    const { artifact, preparedPlan } = createPreparedPlan({
+      executor: 'v2',
+      target: 'firmware',
+    });
+    const { artifactReader, hostBindingGeneration } = registerMismatchedHost();
+    const method = new FirmwareUpdateV2({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV2',
+        platform: 'desktop',
+        updateType: 'firmware',
+        artifact,
+        preparedPlan,
+        hostBindingGeneration,
+      },
+    });
+
+    expect(() => method.init()).toThrow('does not match the prepared plan');
+    expect(artifactReader.open).not.toHaveBeenCalled();
+  });
+
+  test('FirmwareUpdateV3 rejects a host registered for another prepared plan', () => {
+    const { artifact, preparedPlan } = createPreparedPlan({
+      executor: 'v3',
+      target: 'firmware',
+    });
+    const { artifactReader, hostBindingGeneration } = registerMismatchedHost();
+    const method = new FirmwareUpdateV3({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV3',
+        platform: 'desktop',
+        artifacts: { firmware: artifact },
+        preparedPlan,
+        hostBindingGeneration,
+      },
+    });
+
+    expect(() => method.init()).toThrow('does not match the prepared plan');
+    expect(artifactReader.open).not.toHaveBeenCalled();
+  });
+
+  test('DeviceUpdateBootloader rejects a host registered for another prepared plan', async () => {
+    const { artifact, preparedPlan } = createPreparedPlan({
+      executor: 'v2',
+      target: 'bootloader',
+    });
+    const { artifactReader, hostBindingGeneration } = registerMismatchedHost();
+    const method = new DeviceUpdateBootloader({
+      id: 1,
+      payload: {
+        method: 'deviceUpdateBootloader',
+        artifact,
+        preparedPlan,
+        hostBindingGeneration,
+      },
+    });
+    method.device = {
+      features: {
+        deviceType: EDeviceType.Classic1s,
+        serialNo: 'classic-device-id',
+      },
+    } as any;
+
+    await expect(method.run()).rejects.toThrow('does not match the prepared plan');
+    expect(artifactReader.open).not.toHaveBeenCalled();
+  });
+
+  test('keeps non-prepared direct binary calls on the legacy paths', async () => {
+    const v2 = new FirmwareUpdateV2({
+      id: 1,
+      payload: {
+        method: 'firmwareUpdateV2',
+        platform: 'desktop',
+        updateType: 'firmware',
+        binary: new ArrayBuffer(4),
+      },
+    });
+    const v3 = new FirmwareUpdateV3({
+      id: 2,
+      payload: {
+        method: 'firmwareUpdateV3',
+        platform: 'desktop',
+        firmwareBinary: new ArrayBuffer(4),
+      },
+    });
+    const bootloader = new DeviceUpdateBootloader({
+      id: 3,
+      payload: {
+        method: 'deviceUpdateBootloader',
+        binary: new ArrayBuffer(4),
+      },
+    });
+    bootloader.device = {
+      features: {},
+      getCurrentDeviceType: () => EDeviceType.Touch,
+      getCurrentFirmwareType: () => EFirmwareType.Universal,
+    } as any;
+    jest.spyOn(bootloader, 'updateTouchBootloader').mockResolvedValue(true);
+
+    expect(() => v2.init()).not.toThrow();
+    expect(() => v3.init()).not.toThrow();
+    await expect(bootloader.run()).resolves.toBe(true);
+  });
+});

package/__tests__/firmware-update/firmware-update-bootloader-poll.test.ts

@@ -0,0 +1,200 @@
+import FirmwareUpdate from '../../src/api/FirmwareUpdate';
+import FirmwareUpdateV2 from '../../src/api/FirmwareUpdateV2';
+import FirmwareUpdateV3 from '../../src/api/FirmwareUpdateV3';
+import { BOOTLOADER_POLL_INITIALIZE_TIMEOUT_MS } from '../../src/api/firmware/FirmwareUpdateBaseMethod';
+import { DataManager } from '../../src/data-manager';
+
+import type { Device } from '../../src/device/Device';
+
+jest.mock('../../src/data/config', () => ({
+  getSDKVersion: jest.fn(() => '1.0.0'),
+  DEFAULT_DOMAIN: 'https://jssdk.onekey.so/1.0.0/',
+}));
+
+const BLE_ID = 'ble-device';
+
+const flush = () =>
+  new Promise(resolve => {
+    setImmediate(resolve);
+  });
+
+describe.each([
+  [
+    'FirmwareUpdateV2',
+    () =>
+      new FirmwareUpdateV2({
+        id: 1,
+        payload: { method: 'firmwareUpdateV2', connectId: BLE_ID },
+      }),
+  ],
+  [
+    'FirmwareUpdateV3 (base method)',
+    () =>
+      new FirmwareUpdateV3({
+        id: 1,
+        payload: { method: 'firmwareUpdateV3', connectId: BLE_ID },
+      }),
+  ],
+  [
+    'FirmwareUpdate (legacy)',
+    () =>
+      new FirmwareUpdate({
+        id: 1,
+        payload: { method: 'firmwareUpdate', connectId: BLE_ID },
+      }),
+  ],
+])('%s BLE bootloader reboot polling', (_name, buildMethod) => {
+  beforeAll(() => {
+    jest.useFakeTimers({ doNotFake: ['setImmediate', 'performance'] });
+  });
+
+  afterAll(() => {
+    jest.useRealTimers();
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.restoreAllMocks();
+  });
+
+  test('probes serially with a short timeout and survives a slow reboot', async () => {
+    jest.spyOn(DataManager, 'getSettings').mockReturnValue('react-native' as never);
+    jest.spyOn(DataManager, 'isBleConnect').mockReturnValue(true);
+
+    const method = buildMethod();
+
+    let deviceBack = false;
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const probeTimeouts: Array<number | undefined> = [];
+
+    const initialize = jest.fn((options?: { timeoutMs?: number }) => {
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      probeTimeouts.push(options?.timeoutMs);
+      return new Promise<void>((resolve, reject) => {
+        if (deviceBack) {
+          inFlight -= 1;
+          resolve();
+          return;
+        }
+        if (options?.timeoutMs) {
+          setTimeout(() => {
+            inFlight -= 1;
+            reject(Object.assign(new Error('BLE response timeout'), { errorCode: 713 }));
+          }, options.timeoutMs);
+        }
+        // Without a per-probe timeout this promise never settles, matching a device
+        // that never received the request while rebooting.
+      });
+    });
+
+    method.device = {
+      originalDescriptor: { id: BLE_ID },
+      deviceConnector: { acquire: jest.fn(() => Promise.resolve()) },
+      initialize,
+      isBootloader: jest.fn(() => deviceBack),
+      getCurrentDeviceType: jest.fn(() => 'classic1s'),
+    } as unknown as Device;
+
+    // The device re-enumerates in bootloader mode 7 seconds after "reboot start".
+    setTimeout(() => {
+      deviceBack = true;
+    }, 7000);
+
+    method.checkDeviceToBootloader(BLE_ID);
+    const resolved = jest.fn();
+    method.checkPromise?.promise.then(resolved);
+
+    for (let elapsed = 0; elapsed < 15000; elapsed += 500) {
+      jest.advanceTimersByTime(500);
+      // eslint-disable-next-line no-await-in-loop
+      await flush();
+      if (resolved.mock.calls.length) break;
+    }
+
+    // Must detect bootloader mode well inside the 30s reboot budget.
+    expect(resolved).toHaveBeenCalledWith(true);
+    expect(initialize).toHaveBeenCalled();
+    // Probes must never overlap: an unanswered Initialize left in flight is what
+    // the transport later times out and used to tear the connection down with.
+    expect(maxInFlight).toBe(1);
+    // Every probe must carry the bounded poll timeout so a silent device frees the
+    // slot promptly; the 30s reboot budget must fit several attempts.
+    expect(BOOTLOADER_POLL_INITIALIZE_TIMEOUT_MS).toBeLessThanOrEqual(10000);
+    for (const timeoutMs of probeTimeouts) {
+      expect(timeoutMs).toBe(BOOTLOADER_POLL_INITIALIZE_TIMEOUT_MS);
+    }
+  });
+
+  test('skips ticks while a probe hangs in acquire', async () => {
+    jest.spyOn(DataManager, 'getSettings').mockReturnValue('react-native' as never);
+    jest.spyOn(DataManager, 'isBleConnect').mockReturnValue(true);
+
+    const method = buildMethod();
+
+    let deviceBack = false;
+    let activeProbes = 0;
+    let maxActiveProbes = 0;
+
+    // The first acquire hangs for 7s (BLE reconnect while the device reboots);
+    // later acquires resolve immediately.
+    let acquireCalls = 0;
+    const acquire = jest.fn(() => {
+      activeProbes += 1;
+      maxActiveProbes = Math.max(maxActiveProbes, activeProbes);
+      acquireCalls += 1;
+      if (acquireCalls === 1) {
+        return new Promise<void>(resolve => {
+          setTimeout(resolve, 7000);
+        });
+      }
+      return Promise.resolve();
+    });
+
+    const initialize = jest.fn(
+      (options?: { timeoutMs?: number }) =>
+        new Promise<void>((resolve, reject) => {
+          if (deviceBack) {
+            activeProbes -= 1;
+            resolve();
+            return;
+          }
+          if (options?.timeoutMs) {
+            setTimeout(() => {
+              activeProbes -= 1;
+              reject(Object.assign(new Error('BLE response timeout'), { errorCode: 713 }));
+            }, options.timeoutMs);
+          }
+        })
+    );
+
+    method.device = {
+      originalDescriptor: { id: BLE_ID },
+      deviceConnector: { acquire },
+      initialize,
+      isBootloader: jest.fn(() => deviceBack),
+      getCurrentDeviceType: jest.fn(() => 'classic1s'),
+    } as unknown as Device;
+
+    setTimeout(() => {
+      deviceBack = true;
+    }, 7000);
+
+    method.checkDeviceToBootloader(BLE_ID);
+    const resolved = jest.fn();
+    method.checkPromise?.promise.then(resolved);
+
+    for (let elapsed = 0; elapsed < 15000; elapsed += 500) {
+      jest.advanceTimersByTime(500);
+      // eslint-disable-next-line no-await-in-loop
+      await flush();
+      if (resolved.mock.calls.length) break;
+    }
+
+    expect(resolved).toHaveBeenCalledWith(true);
+    // While the first probe hangs inside acquire, interval ticks must be skipped —
+    // overlapping probes are the exact mechanism from the incident.
+    expect(maxActiveProbes).toBe(1);
+  });
+});

package/__tests__/firmware-update/firmware-update-capabilities.test.ts

@@ -0,0 +1,13 @@
+import { getFirmwareUpdateCapabilities } from '../../src/api/firmware/FirmwareUpdateCapabilities';
+
+describe('getFirmwareUpdateCapabilities', () => {
+  it('advertises only the prepared artifact contract', () => {
+    expect(getFirmwareUpdateCapabilities()).toEqual({
+      planSchemaVersion: 2,
+      preparedPlanSchemaVersion: 2,
+      hostBindingProtocolVersion: 2,
+      manifestModes: ['external-only', 'sdk-managed'],
+      supportsArtifactReader: true,
+    });
+  });
+});