@onekeyfe/hd-core 1.2.0-alpha.1 → 1.2.0-alpha.100

package/src/api/firmware/FirmwarePreparedResourceArchive.ts

@@ -0,0 +1,187 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+import JSZip from 'jszip';
+
+import { readVerifiedFirmwareArtifact } from './FirmwareArtifactSource';
+import { getFirmwareUpdateResourceName } from './FirmwareUpdatePreparedPlan';
+
+import type { FirmwareArtifactReader } from '../../types/api/firmwareUpdate';
+import type { FirmwareUpdatePreparedPlan } from '../../types/api/firmwareUpdatePreparedPlan';
+
+const PREPARED_RESOURCE_ARCHIVE_MAX_BYTES = 256 * 1024 * 1024;
+const PREPARED_RESOURCE_ENTRY_MAX_COUNT = 512;
+
+type JSZipSizedEntry = JSZip.JSZipObject & {
+  _data?: {
+    compressedSize?: unknown;
+    uncompressedSize?: unknown;
+  };
+};
+
+export type VerifiedPreparedResourceEntry = {
+  entryName: string;
+  binary: ArrayBuffer;
+};
+
+const resourceArchiveError = (
+  message: string,
+  firmwareUpdateCode: 'FirmwareArtifactsNotPrepared' | 'FirmwareArtifactReceiptMismatch'
+): never => {
+  throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, message, { firmwareUpdateCode });
+};
+
+const getZipEntrySizes = (entry: JSZip.JSZipObject) => {
+  const { compressedSize, uncompressedSize } = (entry as JSZipSizedEntry)._data ?? {};
+  if (
+    !Number.isSafeInteger(compressedSize) ||
+    Number(compressedSize) < 0 ||
+    !Number.isSafeInteger(uncompressedSize) ||
+    Number(uncompressedSize) <= 0
+  ) {
+    return resourceArchiveError(
+      `Firmware prepared resource ZIP entry size is invalid: ${entry.name}`,
+      'FirmwareArtifactsNotPrepared'
+    );
+  }
+  return {
+    compressedSize: Number(compressedSize),
+    uncompressedSize: Number(uncompressedSize),
+  };
+};
+
+/**
+ * 从 PreparedPlan 批准的 ZIP 本体生成资源条目。
+ * 宿主提供的 materializedEntries 仅作为 receipt，设备写入始终使用 ZIP 内的规范字节。
+ */
+export const readVerifiedPreparedResourceArchive = async ({
+  preparedPlan,
+  reader,
+}: {
+  preparedPlan: FirmwareUpdatePreparedPlan;
+  reader: FirmwareArtifactReader | undefined;
+}): Promise<VerifiedPreparedResourceEntry[]> => {
+  const resourceArtifacts = preparedPlan.artifacts.filter(
+    artifact => artifact.target === 'resource'
+  );
+  if (!preparedPlan.targetsToUpdate.includes('resource')) {
+    if (resourceArtifacts.length > 0) {
+      return resourceArchiveError(
+        'Firmware prepared resource artifact is outside the approved targets',
+        'FirmwareArtifactsNotPrepared'
+      );
+    }
+    return [];
+  }
+  if (resourceArtifacts.length !== 1) {
+    return resourceArchiveError(
+      'Firmware prepared plan must contain exactly one materialized resource ZIP',
+      'FirmwareArtifactsNotPrepared'
+    );
+  }
+
+  const archiveArtifact = resourceArtifacts[0];
+  const preparedEntries = archiveArtifact.materializedEntries;
+  if (
+    archiveArtifact.role !== 'resource' ||
+    archiveArtifact.container !== 'zip' ||
+    !preparedEntries?.length
+  ) {
+    return resourceArchiveError(
+      'Firmware prepared plan must contain exactly one materialized resource ZIP',
+      'FirmwareArtifactsNotPrepared'
+    );
+  }
+  if (archiveArtifact.artifact.size > PREPARED_RESOURCE_ARCHIVE_MAX_BYTES) {
+    return resourceArchiveError(
+      'Firmware prepared resource ZIP exceeds the archive size limit',
+      'FirmwareArtifactsNotPrepared'
+    );
+  }
+
+  const archiveBinary = await readVerifiedFirmwareArtifact({
+    artifact: archiveArtifact.artifact,
+    reader,
+  });
+
+  let zip: JSZip;
+  try {
+    zip = await JSZip.loadAsync(archiveBinary);
+  } catch {
+    return resourceArchiveError(
+      'Firmware prepared resource ZIP cannot be parsed',
+      'FirmwareArtifactsNotPrepared'
+    );
+  }
+  const zipEntries = Object.values(zip.files);
+  if (
+    zipEntries.some(entry => entry.unsafeOriginalName && entry.unsafeOriginalName !== entry.name)
+  ) {
+    return resourceArchiveError(
+      'Firmware prepared resource ZIP contains an unsafe entry path',
+      'FirmwareArtifactsNotPrepared'
+    );
+  }
+  const files = zipEntries.filter(entry => !entry.dir);
+  if (files.length === 0 || files.length > PREPARED_RESOURCE_ENTRY_MAX_COUNT) {
+    return resourceArchiveError(
+      'Firmware prepared resource ZIP entry set is invalid',
+      'FirmwareArtifactsNotPrepared'
+    );
+  }
+
+  let totalSize = 0;
+  const canonicalNames = new Set<string>();
+  for (const entry of files) {
+    const { compressedSize, uncompressedSize } = getZipEntrySizes(entry);
+    const resourceName = getFirmwareUpdateResourceName(entry.name);
+    const canonicalName = resourceName.toLowerCase();
+    totalSize += uncompressedSize;
+    if (
+      compressedSize > archiveBinary.byteLength ||
+      uncompressedSize > PREPARED_RESOURCE_ARCHIVE_MAX_BYTES ||
+      totalSize > PREPARED_RESOURCE_ARCHIVE_MAX_BYTES ||
+      canonicalNames.has(canonicalName)
+    ) {
+      return resourceArchiveError(
+        `Firmware prepared resource ZIP entry bounds are invalid: ${entry.name}`,
+        'FirmwareArtifactsNotPrepared'
+      );
+    }
+    canonicalNames.add(canonicalName);
+  }
+
+  const preparedEntriesByName = new Map(
+    preparedEntries.map(entry => [entry.entryName, entry] as const)
+  );
+  if (preparedEntriesByName.size !== files.length || preparedEntries.length !== files.length) {
+    return resourceArchiveError(
+      'Firmware prepared resource entries do not match the approved ZIP',
+      'FirmwareArtifactReceiptMismatch'
+    );
+  }
+
+  const verifiedEntries: VerifiedPreparedResourceEntry[] = [];
+  for (const entry of files) {
+    const { uncompressedSize } = getZipEntrySizes(entry);
+    const binary = await entry.async('arraybuffer');
+    const preparedEntry = preparedEntriesByName.get(entry.name);
+    const digest = bytesToHex(sha256(new Uint8Array(binary)));
+    if (
+      binary.byteLength !== uncompressedSize ||
+      !preparedEntry ||
+      preparedEntry.artifact.size !== binary.byteLength ||
+      preparedEntry.artifact.sha256.toLowerCase() !== digest
+    ) {
+      return resourceArchiveError(
+        `Firmware prepared resource entry does not match the approved ZIP: ${entry.name}`,
+        'FirmwareArtifactReceiptMismatch'
+      );
+    }
+    verifiedEntries.push({
+      entryName: getFirmwareUpdateResourceName(entry.name),
+      binary,
+    });
+  }
+  return verifiedEntries;
+};

package/src/api/firmware/FirmwareUpdateBaseMethod.ts

@@ -8,13 +8,15 @@ import {
 
 import { FirmwareUpdateTipMessage, UI_REQUEST, createUiMessage } from '../../events/ui-request';
 import { DevicePool } from '../../device/DevicePool';
-import { LoggerNames, getDeviceUUID, getLogger, wait } from '../../utils';
+import { LoggerNames, getLogger, wait } from '../../utils';
 import { DeviceModelToTypes } from '../../types';
 import { DataManager } from '../../data-manager';
 import { BaseMethod } from '../BaseMethod';
 import { DEVICE } from '../../events';
+import { writeFirmwareByteSource } from './FirmwareArtifactSource';
 
 import type {
+  FirmwareProgress,
   IFirmwareUpdateProgressType,
   IFirmwareUpdateTipMessage,
 } from '../../events/ui-request';
@@ -23,11 +25,27 @@ import type { RebootType } from '@onekeyfe/hd-transport';
 import type { Deferred } from '@onekeyfe/hd-shared';
 import type { KnownDevice } from '../../types';
 import type { TypedResponseMessage } from '../../device/DeviceCommands';
+import type { FirmwareByteSource } from './FirmwareArtifactSource';
 
 const Log = getLogger(LoggerNames.Method);
 const SESSION_ERROR = 'session not found';
 const FIRMWARE_UPDATE_CONFIRM = 'Firmware install confirmed';
 
+/**
+ * Response timeout for each Initialize probe while polling a rebooting device over BLE.
+ * Overlap safety comes from the poll's in-flight guard, not from this value. Keep it
+ * well below the 30s reboot budget so several attempts fit: a probe written into the
+ * dying pre-reboot connection is never answered, and its timeout tears that stale link
+ * down so the next tick reconnects fresh. Raise it only if a device model is proven to
+ * answer bootloader Initialize slower than this on a fresh connection.
+ */
+export const BOOTLOADER_POLL_INITIALIZE_TIMEOUT_MS = 5000;
+
+type FirmwareTransferMetrics = Pick<
+  FirmwareProgress['payload'],
+  'transferredBytes' | 'totalBytes' | 'rateBytesPerSecond' | 'elapsedMs'
+>;
+
 const isDeviceDisconnectedError = (error: unknown) => {
   const message = error instanceof Error ? error.message : String(error ?? '');
   return (
@@ -82,12 +100,17 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
    * @description Post the progress message
    * @param progress Post the percentage of the progress
    */
-  postProgressMessage = (progress: number, progressType: IFirmwareUpdateProgressType) => {
+  postProgressMessage = (
+    progress: number,
+    progressType: IFirmwareUpdateProgressType,
+    metrics?: FirmwareTransferMetrics
+  ) => {
     this.postMessage(
       createUiMessage(UI_REQUEST.FIRMWARE_PROGRESS, {
         device: this.device.toMessageObject() as KnownDevice,
         progress,
         progressType,
+        ...metrics,
       })
     );
   };
@@ -132,83 +155,153 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
     this.checkPromise = createDeferred();
     const env = DataManager.getSettings('env');
     const isBleReconnect = connectId && DataManager.isBleConnect(env);
+    // Tracks the in-flight BLE probe so interval ticks never overlap: a superseded
+    // Initialize left pending on the V1 transport is exactly what later times out
+    // and used to tear down the connection mid-firmware-upload.
+    let bleProbeInFlight = false;
 
     Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] isBleReconnect: ', isBleReconnect);
 
     // check device goto bootloader mode
     let isFirstCheck = true;
     let checkCount = 0;
-    // eslint-disable-next-line prefer-const
+    let hasPromptedWebDevice = false;
+    let isPromptingWebDevice = false;
+    let isFinished = false;
+    let intervalTimer: ReturnType<typeof setInterval> | undefined;
     let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
 
     const isTouchOrProDevice =
       this?.device?.getCurrentDeviceType() === EDeviceType.Touch ||
       this?.device?.getCurrentDeviceType() === EDeviceType.Pro;
 
-    const intervalTimer: ReturnType<typeof setInterval> | undefined = setInterval(
-      async () => {
-        checkCount += 1;
-        Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] isFirstCheck: ', isFirstCheck);
-        if (isTouchOrProDevice && isFirstCheck) {
-          isFirstCheck = false;
-          Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] wait 3000ms');
-          await wait(3000);
-        }
+    const clearPollingTimers = () => {
+      if (intervalTimer !== undefined) {
+        clearInterval(intervalTimer);
+        intervalTimer = undefined;
+      }
+      if (timeoutTimer !== undefined) {
+        clearTimeout(timeoutTimer);
+        timeoutTimer = undefined;
+      }
+    };
 
-        if (
-          checkCount > 4 &&
-          DataManager.isBrowserWebUsb(DataManager.getSettings('env')) &&
-          !this.payload.skipWebDevicePrompt
-        ) {
-          clearInterval(intervalTimer);
-          clearTimeout(timeoutTimer);
-
-          try {
-            this.postTipMessage(FirmwareUpdateTipMessage.SelectDeviceInBootloaderForWebDevice);
-            const confirmed = await this._promptDeviceInBootloaderForWebDevice();
-            if (confirmed) {
-              await this._checkDeviceInBootloaderMode(connectId, intervalTimer, timeoutTimer);
-            }
-          } catch (e) {
-            Log.log(
-              'FirmwareUpdateBaseMethod [checkDeviceToBootloader] _promptDeviceInBootloaderForWebDevice failed: ',
-              e
-            );
-            this.checkPromise?.reject(e);
+    const checkForBootloader = async (clearActiveTimers: boolean) => {
+      const found = await this._checkDeviceInBootloaderMode(
+        connectId,
+        clearActiveTimers ? intervalTimer : undefined,
+        clearActiveTimers ? timeoutTimer : undefined
+      );
+      if (found) {
+        isFinished = true;
+        clearPollingTimers();
+      }
+      return found;
+    };
+
+    let startPolling: () => void = () => undefined;
+    const pollForBootloader = async () => {
+      if (isFinished || isPromptingWebDevice) return;
+      checkCount += 1;
+      Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] isFirstCheck: ', isFirstCheck);
+      if (isTouchOrProDevice && isFirstCheck) {
+        isFirstCheck = false;
+        Log.log('FirmwareUpdateBaseMethod [checkDeviceToBootloader] wait 3000ms');
+        await wait(3000);
+      }
+
+      if (
+        checkCount > 4 &&
+        DataManager.isBrowserWebUsb(DataManager.getSettings('env')) &&
+        !this.payload.skipWebDevicePrompt &&
+        !hasPromptedWebDevice &&
+        !isPromptingWebDevice
+      ) {
+        clearPollingTimers();
+        isPromptingWebDevice = true;
+        try {
+          this.postTipMessage(FirmwareUpdateTipMessage.SelectDeviceInBootloaderForWebDevice);
+          const confirmed = await this._promptDeviceInBootloaderForWebDevice();
+          hasPromptedWebDevice = true;
+          if (confirmed) {
+            await checkForBootloader(false);
           }
-          return;
+          // WebUSB enumeration can still be empty immediately after the chooser
+          // resolves. Resume a fresh bounded polling window instead of leaving the
+          // deferred check pending forever after the original timers were paused.
+          if (!isFinished) {
+            startPolling();
+          }
+        } catch (e) {
+          isFinished = true;
+          clearPollingTimers();
+          Log.log(
+            'FirmwareUpdateBaseMethod [checkDeviceToBootloader] _promptDeviceInBootloaderForWebDevice failed: ',
+            e
+          );
+          this.checkPromise?.reject(e);
+        } finally {
+          isPromptingWebDevice = false;
         }
+        return;
+      }
 
-        if (isBleReconnect) {
-          try {
-            await this.device.deviceConnector?.acquire(
-              this.device.originalDescriptor.id,
-              null,
-              true
-            );
-            await this.device.initialize();
-            if (this.device.isBootloader()) {
-              clearInterval(intervalTimer);
-              this.checkPromise?.resolve(true);
-            }
-          } catch (e) {
-            // ignore error because of device is not connected
-            Log.log('catch Bluetooth error when device is restarting: ', e);
+      if (isBleReconnect) {
+        if (bleProbeInFlight) return;
+        bleProbeInFlight = true;
+        try {
+          await this.device.deviceConnector?.acquire(
+            this.device.originalDescriptor.id,
+            null,
+            true,
+            this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType
+          );
+          // Bound each probe so a request the rebooting device never received
+          // frees the slot for the next tick instead of hanging into the
+          // 30s reboot budget.
+          await this.device.initialize({ timeoutMs: BOOTLOADER_POLL_INITIALIZE_TIMEOUT_MS });
+          if (this.device.isBootloader()) {
+            isFinished = true;
+            clearPollingTimers();
+            this.checkPromise?.resolve(true);
           }
-        } else {
-          await this._checkDeviceInBootloaderMode(connectId, intervalTimer, timeoutTimer);
+        } catch (e) {
+          // ignore error because of device is not connected
+          Log.log('catch Bluetooth error when device is restarting: ', e);
+        } finally {
+          bleProbeInFlight = false;
         }
-      },
-      isBleReconnect ? 3000 : 2000
-    );
-
-    // check goto bootloader mode timeout and throw error
-    timeoutTimer = setTimeout(() => {
-      if (this.checkPromise) {
-        clearInterval(intervalTimer);
-        this.checkPromise.reject(new Error());
+      } else {
+        await checkForBootloader(true);
       }
-    }, 30000);
+    };
+
+    startPolling = () => {
+      if (isFinished) return;
+      clearPollingTimers();
+      intervalTimer = setInterval(
+        () => {
+          pollForBootloader().catch(error => {
+            if (isFinished) return;
+            isFinished = true;
+            clearPollingTimers();
+            this.checkPromise?.reject(error);
+          });
+        },
+        isBleReconnect ? 3000 : 2000
+      );
+      // Each automatic polling phase is bounded. Time spent in the browser's
+      // permission chooser is intentionally excluded from this deadline.
+      timeoutTimer = setTimeout(() => {
+        if (!isFinished && this.checkPromise) {
+          isFinished = true;
+          clearPollingTimers();
+          this.checkPromise.reject(new Error());
+        }
+      }, 30000);
+    };
+
+    startPolling();
   }
 
   private async _checkDeviceInBootloaderMode(
@@ -218,7 +311,9 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
   ) {
     const deviceDiff = await this.device.deviceConnector?.enumerate();
     const devicesDescriptor = deviceDiff?.descriptors ?? [];
-    const { deviceList } = await DevicePool.getDevices(devicesDescriptor, connectId);
+    const { deviceList } = await DevicePool.getDevices(devicesDescriptor, connectId, {
+      connectProtocol: this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType,
+    });
 
     if (deviceList.length === 1 && deviceList[0]?.isBootloader()) {
       // should update current device from cache
@@ -237,7 +332,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
   async enterBootloaderMode() {
     const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
     if (this.device.features && !this.device.isBootloader()) {
-      const uuid = getDeviceUUID(this.device.features);
+      const serialNo = this.device.getCurrentSerialNo();
       const deviceType = this.device.getCurrentDeviceType();
       // auto go to bootloader mode
       try {
@@ -252,7 +347,7 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
 
         // force clean classic device cache so that the device can initialize again
         if (DeviceModelToTypes.model_classic.includes(deviceType)) {
-          DevicePool.clearDeviceCache(uuid);
+          DevicePool.clearDeviceCache(serialNo);
         }
         delete DevicePool.devicesCache[''];
         await this.checkPromise?.promise;
@@ -373,6 +468,54 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
     return totalSize !== undefined ? (processedSize ?? 0) + payload.byteLength : 0;
   }
 
+  async emmcCommonUpdateProcessFromSource({
+    source,
+    filePath,
+    processedSize,
+    totalSize,
+  }: {
+    source: FirmwareByteSource;
+    filePath: string;
+    processedSize?: number;
+    totalSize?: number;
+  }) {
+    if (!filePath.startsWith('0:')) {
+      throw new Error('filePath must start with 0:');
+    }
+    const env = DataManager.getSettings('env');
+    const chunkSize = 1024 * (DataManager.isBleConnect(env) ? 16 : 128);
+
+    await writeFirmwareByteSource({
+      source,
+      chunkSize,
+      write: async ({ data, sourceOffset, length, first }) => {
+        const progress =
+          totalSize !== undefined && processedSize !== undefined
+            ? Math.min(Math.ceil(((processedSize + sourceOffset + length) / totalSize) * 100), 99)
+            : Math.min(Math.ceil(((sourceOffset + length) / source.size) * 100), 99);
+        const writeRes = await this.emmcFileWriteWithRetry(
+          filePath,
+          length,
+          sourceOffset,
+          data,
+          first,
+          progress
+        );
+        if (!writeRes) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.EmmcFileWriteFirmwareError,
+            'transfer data error'
+          );
+        }
+        const processedBytes = Number(writeRes.message.processed_byte);
+        this.postProgressMessage(progress, 'transferData');
+        return Number.isFinite(processedBytes) ? processedBytes : length;
+      },
+    });
+
+    return totalSize !== undefined ? (processedSize ?? 0) + source.size : 0;
+  }
+
   async emmcFileWriteWithRetry(
     filePath: string,
     chunkLength: number,
@@ -427,7 +570,12 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
         const env = DataManager.getSettings('env');
         if (DataManager.isBleConnect(env)) {
           await wait(3000);
-          await this.device.deviceConnector?.acquire(this.device.originalDescriptor.id, null, true);
+          await this.device.deviceConnector?.acquire(
+            this.device.originalDescriptor.id,
+            null,
+            true,
+            this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType
+          );
           await this.device.initialize();
         } else if (
           error?.message?.indexOf(SESSION_ERROR) > -1 ||
@@ -435,7 +583,10 @@ export class FirmwareUpdateBaseMethod<Params> extends BaseMethod<Params> {
         ) {
           const deviceDiff = await this.device.deviceConnector?.enumerate();
           const devicesDescriptor = deviceDiff?.descriptors ?? [];
-          const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined);
+          const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined, {
+            connectProtocol:
+              this.payload.connectProtocol ?? this.device.originalDescriptor.protocolType,
+          });
           if (deviceList.length === 1 && deviceList[0]?.isBootloader()) {
             this.device.updateFromCache(deviceList[0]);
             await this.device.acquire();

package/src/api/firmware/FirmwareUpdateCapabilities.ts

@@ -0,0 +1,9 @@
+import type { FirmwareUpdateCapabilities } from '../../types/api/firmwareUpdateCapabilities';
+
+export const getFirmwareUpdateCapabilities = (): FirmwareUpdateCapabilities => ({
+  planSchemaVersion: 2,
+  preparedPlanSchemaVersion: 2,
+  hostBindingProtocolVersion: 2,
+  manifestModes: ['external-only', 'sdk-managed'],
+  supportsArtifactReader: true,
+});