@onekeyfe/hd-core 1.2.0-alpha.21 → 1.2.0-alpha.23

package/src/api/BaseMethod.ts

@@ -23,8 +23,12 @@ import type { CoreMessage } from '../events';
 import type { ProtocolV2InteractionDescriptor } from '../protocols/protocol-v2/uiInteraction';
 import type { RequestContext } from '../utils/tracing';
 import type { CoreContext } from '../core';
+import {
+  getProtocolV2UnlockPolicy,
+  type UnlockPolicy,
+} from '../protocols/protocol-v2/unlockPolicy';
 
-export type UnlockPolicy = 'none' | 'retry-on-locked';
+export type { UnlockPolicy } from '../protocols/protocol-v2/unlockPolicy';
 export type ProtocolV2UiMode = 'auto' | 'none';
 
 const Log = getLogger(LoggerNames.Method);
@@ -171,8 +175,8 @@ export abstract class BaseMethod<Params = undefined> {
    */
   requireProtocolV2 = false;
 
-  /** Core unlocks and retries Protocol V2 business methods once when the device is locked. */
-  unlockPolicy: UnlockPolicy = 'retry-on-locked';
+  /** Core unlocks and retries only explicitly replay-safe Protocol V2 methods. */
+  unlockPolicy: UnlockPolicy = 'none';
 
   /** Non-blocking Protocol V2 interaction synthesized by the SDK. */
   protocolV2UiInteraction?: ProtocolV2InteractionDescriptor;
@@ -206,6 +210,7 @@ export abstract class BaseMethod<Params = undefined> {
     this.useDevice = true;
     this.allowDeviceMode = [UI_REQUEST.NOT_INITIALIZE];
     this.requireDeviceMode = [];
+    this.unlockPolicy = getProtocolV2UnlockPolicy(this.name);
   }
 
   abstract init(): void;

package/src/api/CheckAllFirmwareRelease.ts

@@ -5,6 +5,7 @@ import {
   getBootloaderReleaseInfo,
   getFirmwareReleaseInfo,
 } from './firmware/releaseHelper';
+import { buildFirmwareUpdatePlan } from './firmware/FirmwareUpdatePlan';
 import { getBridgeReleaseInfo } from '../utils/bridgeUpdate';
 import { getDeviceFirmwareVersion, getDeviceType, getFirmwareType } from '../utils';
 
@@ -22,8 +23,11 @@ export default class CheckAllFirmwareRelease extends BaseMethod {
 
   async run() {
     const { features } = this.device;
-    const { checkBridgeRelease, firmwareType: firmwareTypeParams } = this
-      .payload as CheckAllFirmwareReleaseParams;
+    const {
+      checkBridgeRelease,
+      firmwareType: firmwareTypeParams,
+      platform,
+    } = this.payload as CheckAllFirmwareReleaseParams;
 
     if (!features) {
       return Promise.resolve(null);
@@ -54,6 +58,21 @@ export default class CheckAllFirmwareRelease extends BaseMethod {
       firmwareType,
     });
     const bleFirmwareReleaseInfo = getBleFirmwareReleaseInfo(features);
+    let firmwareUpdatePlan;
+    try {
+      firmwareUpdatePlan = buildFirmwareUpdatePlan({
+        features,
+        firmwareType,
+        platform: platform ?? 'web',
+        firmware: firmwareRelease,
+        ble: bleFirmwareReleaseInfo,
+        bootloader: bootloaderRelease,
+      });
+    } catch {
+      // A Plan is an optional external-host capability. Release checks remain
+      // available for legacy and recovery flows when a Plan cannot be built.
+      firmwareUpdatePlan = undefined;
+    }
 
     return {
       firmware: firmwareRelease,
@@ -68,6 +87,7 @@ export default class CheckAllFirmwareRelease extends BaseMethod {
           }
         : undefined,
       features,
-    } as AllFirmwareRelease;
+      firmwareUpdatePlan,
+    } as unknown as AllFirmwareRelease;
   }
 }

package/src/api/ClearSessionCache.ts

@@ -1,10 +1,14 @@
 import { BaseMethod } from './BaseMethod';
+import { invalidParameter } from './helpers/paramsValidator';
 import { deviceWalletSessionStore } from '../device/DeviceWalletSessionStore';
 
 import type { ClearSessionCacheParams } from '../types/api/sessionCache';
 
 export default class ClearSessionCache extends BaseMethod<ClearSessionCacheParams> {
   init() {
+    if (this.payload.passphraseState !== undefined && !this.payload.deviceId) {
+      throw invalidParameter('Parameter [deviceId] is required with [passphraseState].');
+    }
     this.useDevice = false;
     this.useDevicePassphraseState = false;
     this.skipForceUpdateCheck = true;

package/src/api/FirmwareUpdate.ts

@@ -182,7 +182,7 @@ export default class FirmwareUpdate extends BaseMethod<Params> {
       }
     }
 
-    let binary;
+    let binary: ArrayBuffer | undefined;
     try {
       if (params.binary) {
         binary = this.params.binary;
@@ -207,6 +207,13 @@ export default class FirmwareUpdate extends BaseMethod<Params> {
       throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateDownloadFailed, err.message ?? err);
     }
 
+    if (!binary) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.FirmwareUpdateDownloadFailed,
+        'Firmware binary is unavailable'
+      );
+    }
+
     await this.device.acquire();
 
     const response = await uploadFirmware(

package/src/api/FirmwareUpdateV2.ts

@@ -14,18 +14,43 @@ import { BaseMethod } from './BaseMethod';
 import { validateParams } from './helpers/paramsValidator';
 import { DevicePool } from '../device/DevicePool';
 import { getBinary, getInfo, getSysResourceBinary } from './firmware/getBinary';
-import { updateResources, uploadFirmware } from './firmware/uploadFirmware';
-import { LoggerNames, getLogger, wait } from '../utils';
+import {
+  updateResources,
+  updateResourcesFromSources,
+  uploadFirmwareFromSource,
+} from './firmware/uploadFirmware';
+import { LoggerNames, getDeviceUUID, getLogger, wait } from '../utils';
 import { FirmwareUpdateTipMessage, createUiMessage } from '../events/ui-request';
 import { DeviceModelToTypes } from '../types';
 import { DataManager } from '../data-manager';
 import { DEVICE } from '../events';
+import { type FirmwareByteSource, openFirmwareByteSource } from './firmware/FirmwareArtifactSource';
+import { resolveFirmwareUpdateHostBinding } from './firmware/FirmwareHostBinding';
+import {
+  assertFirmwareUpdatePreparedPlanDeviceIdentity,
+  assertFirmwareUpdatePreparedPlanBinding,
+  getFirmwareUpdateResourceName,
+} from './firmware/FirmwareUpdatePreparedPlan';
 
 import type { Features, KnownDevice } from '../types';
 import type { FirmwareBinary } from './firmware/getBinary';
+import type {
+  FirmwareArtifactReader,
+  FirmwareArtifactReference,
+} from '../types/api/firmwareUpdate';
+import type { FirmwareUpdatePreparedPlan } from '../types/api/firmwareUpdatePreparedPlan';
 
 type Params = {
   binary?: ArrayBuffer;
+  artifact?: FirmwareArtifactReference;
+  resourceArtifact?: FirmwareArtifactReference;
+  resourceEntries?: Array<{
+    entryName: string;
+    artifact: FirmwareArtifactReference;
+  }>;
+  artifactReader?: FirmwareArtifactReader;
+  preparedPlan?: FirmwareUpdatePreparedPlan;
+  platform?: FirmwareUpdatePreparedPlan['platform'];
   version?: number[];
   updateType: 'firmware' | 'ble';
   forcedUpdateRes?: boolean;
@@ -106,6 +131,13 @@ const normalizeFirmwareBinary = (binary: unknown): FirmwareBinary | undefined =>
   return normalized.buffer;
 };
 
+const toArrayBuffer = (binary: FirmwareBinary): ArrayBuffer => {
+  if (binary instanceof ArrayBuffer) {
+    return binary;
+  }
+  return new Uint8Array(binary.buffer, binary.byteOffset, binary.byteLength).slice().buffer;
+};
+
 export default class FirmwareUpdateV2 extends BaseMethod<Params> {
   checkPromise: Deferred<any> | null = null;
 
@@ -152,6 +184,38 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
         binary: payload.binary,
       };
     }
+
+    if ('artifact' in payload) {
+      const hostBinding = resolveFirmwareUpdateHostBinding(payload.hostBindingGeneration);
+      const target = payload.isUpdateBootloader ? 'bootloader' : payload.updateType;
+      const resourceBindings = [
+        ...(payload.resourceArtifact
+          ? [{ target: 'resource' as const, artifact: payload.resourceArtifact }]
+          : []),
+        ...(payload.resourceEntries ?? []).map(
+          (entry: { entryName: string; artifact: FirmwareArtifactReference }) => ({
+            target: 'resource' as const,
+            entryName: entry.entryName,
+            artifact: entry.artifact,
+          })
+        ),
+      ];
+      assertFirmwareUpdatePreparedPlanBinding({
+        preparedPlan: payload.preparedPlan,
+        executor: 'v2',
+        platform: payload.platform,
+        scopeTargets: [target, ...(target === 'firmware' ? (['resource'] as const) : [])],
+        bindings: [{ target, artifact: payload.artifact }, ...resourceBindings],
+      });
+      this.params = {
+        ...this.params,
+        preparedPlan: payload.preparedPlan,
+        artifact: payload.artifact,
+        resourceArtifact: payload.resourceArtifact,
+        resourceEntries: payload.resourceEntries,
+        artifactReader: hostBinding.artifactReader,
+      };
+    }
   }
 
   postTipMessage = (message: string) => {
@@ -348,152 +412,260 @@ export default class FirmwareUpdateV2 extends BaseMethod<Params> {
         'Protocol V2 firmware update must use firmwareUpdateV4'
       );
     }
+    if (params.preparedPlan) {
+      assertFirmwareUpdatePreparedPlanDeviceIdentity({
+        preparedPlan: params.preparedPlan,
+        deviceIdentity: getDeviceUUID(features) || undefined,
+      });
+    }
 
     const deviceFirmwareType = device.getCurrentFirmwareType();
     const firmwareType = params.firmwareType ?? deviceFirmwareType;
 
     this.checkVersionForCopyTouchResource(features, firmwareType);
 
-    let preparedBinary: FirmwareBinary | undefined;
-    const acquireFirmwareBinary = async (): Promise<FirmwareBinary> => {
-      try {
-        if (preparedBinary) {
-          return preparedBinary;
-        }
-
-        if (params.binary !== undefined) {
-          preparedBinary = normalizeFirmwareBinary(params.binary);
-          if (!preparedBinary) {
-            throw new Error('firmware binary is empty or invalid');
+    let preparedSource: FirmwareByteSource | undefined;
+    try {
+      const acquireFirmwareSource = async (): Promise<FirmwareByteSource> => {
+        try {
+          if (preparedSource) {
+            return preparedSource;
           }
-          return preparedBinary;
-        }
 
-        if (!device.features) {
-          throw ERRORS.TypedError(
-            HardwareErrorCode.RuntimeError,
-            'no features found for this device'
-          );
-        }
-
-        this.postTipMessage('DownloadFirmware');
-        const firmware = await getBinary({
-          features: device.features,
-          version: params.version,
-          updateType: params.updateType,
-          isUpdateBootloader: params.isUpdateBootloader,
-          firmwareType,
-          requestOptions: FIRMWARE_DOWNLOAD_REQUEST_OPTIONS,
-        });
-        preparedBinary = normalizeFirmwareBinary(firmware.binary);
-        if (!preparedBinary) {
-          throw new Error('downloaded firmware binary is empty or invalid');
-        }
-        this.postTipMessage('DownloadFirmwareSuccess');
-        return preparedBinary;
-      } catch (err) {
-        throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateDownloadFailed, err.message ?? err);
-      }
-    };
+          if (params.binary !== undefined) {
+            const binary = normalizeFirmwareBinary(params.binary);
+            if (!binary) {
+              throw new Error('firmware binary is empty or invalid');
+            }
+            const source = await openFirmwareByteSource({
+              binary: toArrayBuffer(binary),
+            });
+            if (!source) {
+              throw new Error('firmware binary is empty or invalid');
+            }
+            preparedSource = source;
+            return source;
+          }
 
-    if (!device.isBootloader() && features) {
-      const serialNo = device.getCurrentSerialNo();
-      // should go to bootloader mode manually
-      if (this.isEnteredManuallyBoot()) {
-        return Promise.reject(ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateManuallyEnterBoot));
-      }
+          if (params.artifact) {
+            const source = await openFirmwareByteSource({
+              artifact: params.artifact,
+              reader: params.artifactReader,
+            });
+            if (!source) {
+              throw new Error('firmware artifact is not prepared');
+            }
+            preparedSource = source;
+            return source;
+          }
 
-      // check & upgrade firmware resource
-      if (this.isSupportResourceUpdate(params.updateType)) {
-        this.postTipMessage('CheckLatestUiResource');
-        const resourceUrl = DataManager.getSysResourcesLatestRelease({
-          features,
-          forcedUpdateRes: params.forcedUpdateRes,
-          firmwareType,
-        });
-        if (resourceUrl) {
-          this.postTipMessage('DownloadLatestUiResource');
-          const resource = await getSysResourceBinary(resourceUrl);
-          this.postTipMessage('DownloadLatestUiResourceSuccess');
-          if (resource) {
-            await updateResources(
-              this.device.getCommands().typedCall.bind(this.device.getCommands()),
-              this.postMessage,
-              device,
-              resource.binary
+          if (!device.features) {
+            throw ERRORS.TypedError(
+              HardwareErrorCode.RuntimeError,
+              'no features found for this device'
             );
           }
-        }
-      }
 
-      // check if the device commands has been disposed
-      this.device?.commands?.checkDisposed();
-
-      // A failed firmware download must leave the device in normal mode.
-      await acquireFirmwareBinary();
+          if (
+            params.artifactReader ||
+            DataManager.getSettings('firmwareManifestMode') === 'external-only'
+          ) {
+            throw ERRORS.TypedError(
+              HardwareErrorCode.RuntimeError,
+              'Firmware must be prepared by the external firmware host',
+              {
+                firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
+                artifactName: 'firmware',
+              }
+            );
+          }
 
-      // The request may outlive the current transport command instance.
-      this.device?.commands?.checkDisposed();
+          this.postTipMessage('DownloadFirmware');
+          const firmware = await getBinary({
+            features: device.features,
+            version: params.version,
+            updateType: params.updateType,
+            isUpdateBootloader: params.isUpdateBootloader,
+            firmwareType,
+            requestOptions: FIRMWARE_DOWNLOAD_REQUEST_OPTIONS,
+          });
+          const binary = normalizeFirmwareBinary(firmware.binary);
+          if (!binary) {
+            throw new Error('downloaded firmware binary is empty or invalid');
+          }
+          const source = await openFirmwareByteSource({
+            binary: toArrayBuffer(binary),
+          });
+          if (!source) {
+            throw new Error('downloaded firmware binary is empty or invalid');
+          }
+          preparedSource = source;
+          this.postTipMessage('DownloadFirmwareSuccess');
+          return source;
+        } catch (err) {
+          throw ERRORS.TypedError(
+            HardwareErrorCode.FirmwareUpdateDownloadFailed,
+            err.message ?? err
+          );
+        }
+      };
 
-      // auto go to bootloader mode
-      try {
-        this.postTipMessage('AutoRebootToBootloader');
-        const bootRes = await commands.typedCall('DeviceBackToBoot', 'Success');
-        // @ts-expect-error
-        if (bootRes.type === 'CallMethodError') {
-          throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateAutoEnterBootFailure);
+      if (!device.isBootloader() && features) {
+        const serialNo = device.getCurrentSerialNo();
+        // should go to bootloader mode manually
+        if (this.isEnteredManuallyBoot()) {
+          throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateManuallyEnterBoot);
         }
-        this.postTipMessage('GoToBootloaderSuccess');
-        this.checkDeviceToBootloader(this.payload.connectId);
 
-        // force clean classic device cache so that the device can initialize again
-        if (DeviceModelToTypes.model_classic.includes(deviceType)) {
-          DevicePool.clearDeviceCache(serialNo);
+        // All network-backed input must be ready before the first device mutation.
+        await acquireFirmwareSource();
+
+        // check & upgrade firmware resource
+        if (this.isSupportResourceUpdate(params.updateType)) {
+          this.postTipMessage('CheckLatestUiResource');
+          const resourceUrl = DataManager.getSysResourcesLatestRelease({
+            features,
+            forcedUpdateRes: params.forcedUpdateRes,
+            firmwareType,
+          });
+          if (resourceUrl) {
+            this.postTipMessage('DownloadLatestUiResource');
+            if (params.resourceEntries?.length) {
+              const sources: Array<{
+                entryName: string;
+                source: FirmwareByteSource;
+              }> = [];
+              try {
+                for (const entry of params.resourceEntries) {
+                  const resourceName = getFirmwareUpdateResourceName(entry.entryName);
+                  const source = await openFirmwareByteSource({
+                    artifact: entry.artifact,
+                    reader: params.artifactReader,
+                  });
+                  if (!source) {
+                    throw new Error('Firmware resource entry is not prepared');
+                  }
+                  sources.push({ entryName: resourceName, source });
+                }
+                await updateResourcesFromSources(
+                  this.device.getCommands().typedCall.bind(this.device.getCommands()),
+                  this.postMessage,
+                  device,
+                  sources.map(entry => ({
+                    entryName: entry.entryName,
+                    source: entry.source,
+                  }))
+                );
+              } finally {
+                await Promise.all(
+                  sources.map(entry => entry.source.close().catch(() => undefined))
+                );
+              }
+              this.postTipMessage('DownloadLatestUiResourceSuccess');
+            } else {
+              let resourceBinary: ArrayBuffer | Buffer;
+              if (params.resourceArtifact) {
+                throw ERRORS.TypedError(
+                  HardwareErrorCode.RuntimeError,
+                  'Firmware resource archive must be materialized into prepared entries',
+                  {
+                    firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
+                    artifactName: 'resource',
+                  }
+                );
+              } else {
+                if (
+                  params.artifactReader ||
+                  DataManager.getSettings('firmwareManifestMode') === 'external-only'
+                ) {
+                  throw ERRORS.TypedError(
+                    HardwareErrorCode.RuntimeError,
+                    'Firmware resource must be prepared by the external firmware host',
+                    {
+                      firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
+                      artifactName: 'resource',
+                    }
+                  );
+                }
+                resourceBinary = (await getSysResourceBinary(resourceUrl)).binary;
+              }
+              this.postTipMessage('DownloadLatestUiResourceSuccess');
+              await updateResources(
+                this.device.getCommands().typedCall.bind(this.device.getCommands()),
+                this.postMessage,
+                device,
+                resourceBinary
+              );
+            }
+          }
         }
-        delete DevicePool.devicesCache[''];
-        await this.checkPromise?.promise;
-        this.checkPromise = null;
 
-        // check if the device commands has been disposed
+        // The request may outlive the current transport command instance.
         this.device?.commands?.checkDisposed();
 
-        /**
-         * Touch 1 with bootloader v2.5.0 issue: BLE chip need more time for looking up name, here change the delay time to 3000ms after rebooting.
-         */
-        const isTouch = DeviceModelToTypes.model_touch.includes(deviceType);
-        await wait(isTouch ? 3000 : 1500);
-      } catch (e) {
-        if (e instanceof HardwareError) {
-          return Promise.reject(e);
+        // auto go to bootloader mode
+        try {
+          this.postTipMessage('AutoRebootToBootloader');
+          const bootRes = await commands.typedCall('DeviceBackToBoot', 'Success');
+          // @ts-expect-error
+          if (bootRes.type === 'CallMethodError') {
+            throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateAutoEnterBootFailure);
+          }
+          this.postTipMessage('GoToBootloaderSuccess');
+          this.checkDeviceToBootloader(this.payload.connectId);
+
+          // force clean classic device cache so that the device can initialize again
+          if (DeviceModelToTypes.model_classic.includes(deviceType)) {
+            DevicePool.clearDeviceCache(serialNo);
+          }
+          delete DevicePool.devicesCache[''];
+          await this.checkPromise?.promise;
+          this.checkPromise = null;
+
+          // check if the device commands has been disposed
+          this.device?.commands?.checkDisposed();
+
+          /**
+           * Touch 1 with bootloader v2.5.0 issue: BLE chip need more time for looking up name, here change the delay time to 3000ms after rebooting.
+           */
+          const isTouch = DeviceModelToTypes.model_touch.includes(deviceType);
+          await wait(isTouch ? 3000 : 1500);
+        } catch (e) {
+          if (e instanceof HardwareError) {
+            return Promise.reject(e);
+          }
+          console.log('auto go to bootloader mode failed: ', e);
+          return Promise.reject(
+            ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateAutoEnterBootFailure)
+          );
         }
-        console.log('auto go to bootloader mode failed: ', e);
-        return Promise.reject(
-          ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateAutoEnterBootFailure)
-        );
       }
-    }
 
-    // Devices already in bootloader mode still acquire through the same helper.
-    const binary = await acquireFirmwareBinary();
+      // Devices already in bootloader mode still acquire through the same helper.
+      const source = await acquireFirmwareSource();
 
-    // check if the device commands has been disposed
-    this.device?.commands?.checkDisposed();
+      // check if the device commands has been disposed
+      this.device?.commands?.checkDisposed();
 
-    await this.device.acquire();
+      await this.device.acquire();
 
-    const response = await uploadFirmware(
-      params.updateType,
-      this.device.getCommands().typedCall.bind(this.device.getCommands()),
-      this.postMessage,
-      device,
-      { payload: binary, rebootOnSuccess: true },
-      params.isUpdateBootloader
-    );
+      const response = await uploadFirmwareFromSource(
+        params.updateType,
+        this.device.getCommands().typedCall.bind(this.device.getCommands()),
+        this.postMessage,
+        device,
+        source,
+        true,
+        params.isUpdateBootloader
+      );
 
-    if (this.connectId) {
-      DevicePool.clearDeviceCache(this.connectId);
-    }
+      if (this.connectId) {
+        DevicePool.clearDeviceCache(this.connectId);
+      }
 
-    return response;
+      return response;
+    } finally {
+      await preparedSource?.close().catch(() => undefined);
+    }
   }
 }