@onekeyfe/hd-core 1.1.34-alpha.2 → 1.1.34-alpha.3

package/src/types/api/firmwareUpdate.ts

@@ -1,14 +1,84 @@
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
 import type { PROTO } from '../../constants';
 import type { Params, Response } from '../params';
+import type { FirmwareUpdatePreparedPlan } from './firmwareUpdatePreparedPlan';
 
 type IUpdateType = 'firmware' | 'ble';
 
+export interface FirmwareArtifactReference {
+  artifactRef: string;
+  size: number;
+  sha256: string;
+}
+
+export interface FirmwareArtifactReader {
+  open(input: { artifactRef: string }): Promise<{
+    readerId: string;
+    size: number;
+  }>;
+  read(input: { readerId: string; offset: number; length: number }): Promise<{
+    data: ArrayBuffer;
+    bytesRead: number;
+    eof: boolean;
+  }>;
+  close(input: { readerId: string }): Promise<void>;
+}
+
+export type FirmwareCheckpointStage =
+  | 'EPOCH_STARTED'
+  | 'EPOCH_COMPLETED'
+  | 'BEFORE_DEVICE_MODE_CHANGE'
+  | 'FILE_TRANSFER_STARTED'
+  | 'FILE_TRANSFER_COMPLETED'
+  | 'INSTALL_REQUESTED'
+  | 'INSTALL_ACCEPTED'
+  | 'FINAL_VERIFIED';
+
+export interface FirmwareCheckpoint {
+  schemaVersion: 1;
+  sequence: number;
+  stage: FirmwareCheckpointStage;
+  destructiveActionStarted: boolean;
+  target?: string;
+  epoch?: number;
+}
+
+export interface FirmwareCheckpointSink {
+  commit(checkpoint: FirmwareCheckpoint): Promise<void>;
+}
+
+export interface FirmwareUpdateHostBinding {
+  artifactReader: FirmwareArtifactReader;
+  checkpointSink: FirmwareCheckpointSink;
+}
+
+export interface FirmwareCheckpointParams {
+  hostBindingGeneration?: number;
+  checkpointSink?: FirmwareCheckpointSink;
+  checkpointSequenceStart?: number;
+  resumeCheckpoint?: FirmwareCheckpoint;
+}
+
 export interface FirmwareUpdateBinaryParams {
   binary: ArrayBuffer;
   updateType: IUpdateType;
 }
 
+export interface FirmwareUpdateArtifactParams extends FirmwareCheckpointParams {
+  preparedPlan: FirmwareUpdatePreparedPlan;
+  hostBindingGeneration: number;
+  artifact: FirmwareArtifactReference;
+  resourceArtifact?: FirmwareArtifactReference;
+  resourceEntries?: Array<{
+    entryName: string;
+    artifact: FirmwareArtifactReference;
+  }>;
+  updateType: IUpdateType;
+  forcedUpdateRes?: boolean;
+  isUpdateBootloader?: boolean;
+  firmwareType?: EFirmwareType;
+}
+
 export interface FirmwareUpdateParams {
   version?: number[];
   updateType: IUpdateType;
@@ -37,10 +107,16 @@ export declare function firmwareUpdateV2(
   connectId: string | undefined,
   params: Params<FirmwareUpdateBinaryParams & Platform>
 ): Response<PROTO.Success>;
+export declare function firmwareUpdateV2(
+  connectId: string | undefined,
+  params: Params<FirmwareUpdateArtifactParams & Platform>
+): Response<PROTO.Success>;
 
-export interface FirmwareUpdateV3Params {
+export interface FirmwareUpdateV3Params extends FirmwareCheckpointParams {
+  preparedPlan?: FirmwareUpdatePreparedPlan;
   bleVersion?: number[];
   bleBinary?: ArrayBuffer;
+  chunkSize?: number;
 
   firmwareVersion?: number[];
   firmwareBinary?: ArrayBuffer;
@@ -54,8 +130,85 @@ export interface FirmwareUpdateV3Params {
   firmwareType?: EFirmwareType;
 
   platform: IPlatform;
+
+  artifactReader?: FirmwareArtifactReader;
+  artifacts?: {
+    ble?: FirmwareArtifactReference;
+    firmware?: FirmwareArtifactReference;
+    bootloader?: FirmwareArtifactReference;
+    resourceEntries?: Array<{
+      entryName: string;
+      artifact: FirmwareArtifactReference;
+    }>;
+  };
+}
+
+/**
+ * firmwareUpdateV4 target binaries grouped by DeviceFirmwareTargetType.
+ * Except for romloader, each field maps to a target accepted by bootloader.
+ */
+export type FirmwareUpdateV4Target =
+  | 'boot'
+  | 'app_v1'
+  | 'app_v2'
+  | 'coprocessor'
+  | 'resource'
+  | 'se01'
+  | 'se02'
+  | 'se03'
+  | 'se04';
+
+export interface FirmwareUpdateV4Params extends FirmwareCheckpointParams {
+  preparedPlan?: FirmwareUpdatePreparedPlan;
+  platform: IPlatform;
+  expectedDeviceId?: string;
+  chunkSize?: number;
+  firmwareType?: EFirmwareType;
+  targetsToUpdate?: FirmwareUpdateV4Target[];
+  expectedTargetVersions?: Partial<Record<FirmwareUpdateV4Target, string>>;
+
+  /** FW_MGMT_TARGET_ROMLOADER = 2; Pro2 cannot install it through firmwareUpdateV4. */
+  romloaderBinary?: ArrayBuffer;
+  /** FW_MGMT_TARGET_BOOTLOADER = 3 */
+  bootloaderBinary?: ArrayBuffer;
+  /** FW_MGMT_TARGET_APPLICATION_P1 = 4 */
+  applicationP1Binary?: ArrayBuffer;
+  /** FW_MGMT_TARGET_APPLICATION_P2 = 5 */
+  applicationP2Binary?: ArrayBuffer;
+  /** FW_MGMT_TARGET_COPROCESSOR = 6 */
+  coprocessorBinary?: ArrayBuffer;
+  /** FW_MGMT_TARGET_SE01-04 = 7-10 */
+  se01Binary?: ArrayBuffer;
+  se02Binary?: ArrayBuffer;
+  se03Binary?: ArrayBuffer;
+  se04Binary?: ArrayBuffer;
+  forcedUpdateRes?: boolean;
+  /**
+   * RESC bundle okpkg files written directly to devicePath through FilesystemFileWrite.
+   * Manual mode installs them without version comparison.
+   */
+  resourceBundleFiles?: Array<{
+    binary: ArrayBuffer;
+    devicePath: string;
+  }>;
+  artifactReader?: FirmwareArtifactReader;
+  componentArtifacts?: Partial<
+    Record<Exclude<FirmwareUpdateV4Target, 'resource'>, FirmwareArtifactReference>
+  >;
+  resourceBundleArtifacts?: Array<{
+    name: string;
+    artifact: FirmwareArtifactReference;
+  }>;
 }
 
+export declare function registerFirmwareUpdateHostBinding(
+  binding: FirmwareUpdateHostBinding
+): number;
+
+export declare function unregisterFirmwareUpdateHostBinding(generation?: number): boolean;
+
+export declare function getFirmwareUpdateHostBindingGeneration(): number;
+
 export declare function firmwareUpdateV3(
   connectId: string | undefined,
   params: Params<FirmwareUpdateV3Params>
@@ -64,3 +217,12 @@ export declare function firmwareUpdateV3(
   firmwareVersion: string;
   bootloaderVersion: string;
 }>;
+
+export declare function firmwareUpdateV4(
+  connectId: string | undefined,
+  params: Params<FirmwareUpdateV4Params>
+): Response<{
+  bleVersion: string;
+  firmwareVersion: string;
+  bootloaderVersion: string;
+}>;

package/src/types/api/firmwareUpdateCapabilities.ts

@@ -0,0 +1,13 @@
+export interface FirmwareUpdateCapabilities {
+  planSchemaVersion: 1;
+  preparedPlanSchemaVersion: 1;
+  hostBindingProtocolVersion: 1;
+  checkpointSchemaVersion: 1;
+  manifestModes: Array<'external-only' | 'sdk-managed'>;
+  supportsArtifactReader: true;
+  supportsAwaitableCheckpoint: true;
+  supportsResume: true;
+  supportsReconciliation: true;
+}
+
+export declare function getFirmwareUpdateCapabilities(): FirmwareUpdateCapabilities;

package/src/types/api/firmwareUpdatePlan.ts

@@ -0,0 +1,52 @@
+import type { FirmwareUpdateV4Target } from './firmwareUpdate';
+import type { EFirmwareType } from '@onekeyfe/hd-shared';
+
+export type FirmwareUpdatePlanArtifactRole =
+  | 'firmware'
+  | 'ble'
+  | 'bootloader'
+  | 'resource'
+  | 'component'
+  | 'resourceBundle';
+
+export type FirmwareUpdatePlanTarget = 'firmware' | 'ble' | 'bootloader' | FirmwareUpdateV4Target;
+
+export interface FirmwareUpdatePlanArtifact {
+  artifactId: string;
+  role: FirmwareUpdatePlanArtifactRole;
+  target: FirmwareUpdatePlanTarget;
+  url: string;
+  container: 'raw' | 'zip';
+  logicalName?: string;
+  expectedSize?: number;
+  expectedSha256?: string;
+  targetVersion?: string;
+}
+
+export type FirmwareUpdatePlanEpochKind =
+  | 'legacy-update'
+  | 'resource-sync'
+  | 'bootloader-install'
+  | 'bootloader-verify'
+  | 'component-install'
+  | 'final-verify';
+
+export interface FirmwareUpdatePlanEpoch {
+  epoch: number;
+  kind: FirmwareUpdatePlanEpochKind;
+  artifactIds: string[];
+  targets: FirmwareUpdatePlanTarget[];
+}
+
+export interface FirmwareUpdatePlan {
+  schemaVersion: 1;
+  planDigest: string;
+  executor: 'v2' | 'v3' | 'v4';
+  deviceIdentity: string;
+  deviceModel: string;
+  firmwareType: EFirmwareType;
+  platform: 'native' | 'desktop' | 'ext' | 'web' | 'web-embed';
+  artifacts: FirmwareUpdatePlanArtifact[];
+  epochs: FirmwareUpdatePlanEpoch[];
+  targetsToUpdate: FirmwareUpdatePlanTarget[];
+}

package/src/types/api/firmwareUpdatePreparedPlan.ts

@@ -0,0 +1,55 @@
+import type { FirmwareArtifactReference } from './firmwareUpdate';
+import type {
+  FirmwareUpdatePlan,
+  FirmwareUpdatePlanArtifactRole,
+  FirmwareUpdatePlanEpoch,
+  FirmwareUpdatePlanTarget,
+} from './firmwareUpdatePlan';
+
+export interface FirmwareUpdatePreparedEntry {
+  entryName: string;
+  artifact: FirmwareArtifactReference;
+}
+
+export interface FirmwareUpdatePreparedArtifactInput {
+  artifactId: string;
+  artifact: FirmwareArtifactReference;
+  materializedEntries?: FirmwareUpdatePreparedEntry[];
+}
+
+export interface FirmwareUpdatePreparedArtifact {
+  artifactId: string;
+  role: FirmwareUpdatePlanArtifactRole;
+  target: FirmwareUpdatePlanTarget;
+  container: 'raw' | 'zip';
+  logicalName?: string;
+  targetVersion?: string;
+  artifact: FirmwareArtifactReference;
+  materializedEntries?: FirmwareUpdatePreparedEntry[];
+}
+
+export interface FirmwareUpdatePreparedPlan {
+  schemaVersion: 1;
+  preparedPlanDigest: string;
+  planDigest: string;
+  networkPolicy: 'forbid';
+  executor: FirmwareUpdatePlan['executor'];
+  deviceIdentity: string;
+  deviceModel: string;
+  firmwareType: FirmwareUpdatePlan['firmwareType'];
+  platform: FirmwareUpdatePlan['platform'];
+  leaseRef: string;
+  artifacts: FirmwareUpdatePreparedArtifact[];
+  epochs: FirmwareUpdatePlanEpoch[];
+  targetsToUpdate: FirmwareUpdatePlanTarget[];
+}
+
+export declare function prepareFirmwareUpdatePlan(input: {
+  plan: FirmwareUpdatePlan;
+  leaseRef: string;
+  artifacts: FirmwareUpdatePreparedArtifactInput[];
+}): FirmwareUpdatePreparedPlan;
+
+export declare function validateFirmwareUpdatePreparedPlan(
+  value: unknown
+): FirmwareUpdatePreparedPlan;

package/src/types/api/getDeviceState.ts

@@ -0,0 +1,19 @@
+import type { DeviceState, DeviceStateSection } from '../device';
+import type { CommonParams, Response } from '../params';
+
+export type DeviceStateScope = 'runtime' | 'settings' | 'firmware';
+
+export type GetDeviceStateParams = CommonParams & {
+  scope?: DeviceStateScope;
+};
+
+/** Internal state-read options, not part of the public CoreApi. */
+export type DeviceStateReadOptions = {
+  refreshSections?: DeviceStateSection[];
+  includeRaw?: boolean;
+};
+
+export declare function getDeviceState(
+  connectId?: string,
+  params?: GetDeviceStateParams
+): Response<DeviceState>;

package/src/types/api/getFeatures.ts

@@ -1,4 +1,7 @@
 import type { CommonParams, Response } from '../params';
 import type { Features } from '../device';
 
+/**
+ * @deprecated Use `getDeviceState` for both Protocol V1 and Protocol V2 devices.
+ */
 export declare function getFeatures(connectId?: string, params?: CommonParams): Response<Features>;

package/src/types/api/getOnekeyFeatures.ts

@@ -1,6 +1,9 @@
 import type { CommonParams, Response } from '../params';
 import type { OnekeyFeatures } from '../device';
 
+/**
+ * @deprecated Use `getDeviceState(connectId, { scope: 'firmware' })`.
+ */
 export declare function getOnekeyFeatures(
   connectId?: string,
   params?: CommonParams

package/src/types/api/getPassphraseState.ts

@@ -1,6 +1,14 @@
 import type { CommonParams, Response } from '../params';
 
+export type GetPassphraseStateParams = CommonParams;
+
+/**
+ * Legacy Protocol V1 wallet API.
+ *
+ * This remains supported for Protocol V1 integrations. New cross-protocol integrations
+ * and all Protocol V2 callers should use `openWalletSession`.
+ */
 export declare function getPassphraseState(
   connectId?: string,
-  params?: CommonParams
-): Response<string>;
+  params?: GetPassphraseStateParams
+): Response<string | undefined>;

package/src/types/api/index.ts

@@ -1,9 +1,37 @@
+import type {
+  deviceFactoryInfoGet,
+  deviceFactoryInfoSet,
+  deviceFirmwareUpdate,
+  deviceGetFirmwareUpdateStatus,
+  deviceGetOnboardingStatus,
+  deviceInfoGet,
+  deviceReboot,
+  deviceSessionOpen,
+  deviceSettingsGet,
+  deviceSettingsPageShow,
+  deviceSettingsSet,
+  deviceStatusGet,
+  deviceUploadWallpaper,
+  dirList,
+  dirMake,
+  dirRemove,
+  fileDelete,
+  fileRead,
+  fileWrite,
+  filesystemFormat,
+  filesystemPermissionFix,
+  pathInfo,
+  ping,
+  protocolInfoRequest,
+  uploadPortfolio,
+} from './protocolV2';
 import type { off, on, removeAllListeners } from './event';
 import type { uiResponse } from './uiResponse';
 import type { init, updateSettings } from './init';
 import type { testInitializeDeviceDuration } from './testInitializeDeviceDuration';
 import type { preInitialize } from './preInitialize';
 import type { getLogs } from './getLogs';
+import type { clearSessionCache } from './sessionCache';
 import type { checkBridgeStatus } from './checkBridgeStatus';
 import type { checkBridgeRelease } from './checkBridgeRelease';
 import type { checkBootloaderRelease } from './checkBootloaderRelease';
@@ -11,11 +39,26 @@ import type { checkAllFirmwareRelease } from './checkAllFirmwareRelease';
 import type { checkFirmwareTypeAvailable } from './checkFirmwareTypeAvailable';
 import type { searchDevices } from './searchDevices';
 import type { getFeatures } from './getFeatures';
+import type { getDeviceState } from './getDeviceState';
 import type { getOnekeyFeatures } from './getOnekeyFeatures';
 import type { getPassphraseState } from './getPassphraseState';
+import type { openWalletSession } from './openWalletSession';
 import type { checkFirmwareRelease } from './checkFirmwareRelease';
 import type { checkBLEFirmwareRelease } from './checkBLEFirmwareRelease';
-import type { firmwareUpdate, firmwareUpdateV2, firmwareUpdateV3 } from './firmwareUpdate';
+import type {
+  firmwareUpdate,
+  firmwareUpdateV2,
+  firmwareUpdateV3,
+  firmwareUpdateV4,
+  getFirmwareUpdateHostBindingGeneration,
+  registerFirmwareUpdateHostBinding,
+  unregisterFirmwareUpdateHostBinding,
+} from './firmwareUpdate';
+import type { getFirmwareUpdateCapabilities } from './firmwareUpdateCapabilities';
+import type {
+  prepareFirmwareUpdatePlan,
+  validateFirmwareUpdatePreparedPlan,
+} from './firmwareUpdatePreparedPlan';
 import type { promptWebDeviceAccess } from './promptWebDeviceAccess';
 import type { deviceReset } from './deviceReset';
 import type { deviceRecovery } from './deviceRecovery';
@@ -131,6 +174,10 @@ import type { neoSignTransaction } from './neoSignTransaction';
 import type { ConnectSettings } from '../settings';
 
 export * from './export';
+export type { DeviceStateScope, GetDeviceStateParams } from './getDeviceState';
+export type { GetPassphraseStateParams } from './getPassphraseState';
+export type { OpenWalletSessionParams, OpenWalletSessionPayload } from './openWalletSession';
+export type { ClearSessionCacheParams, ClearSessionCachePayload } from './sessionCache';
 
 export type CoreApi = {
   /**
@@ -141,13 +188,15 @@ export type CoreApi = {
   off: typeof off;
   emit: (event: string, ...args: any[]) => void;
   removeAllListeners: typeof removeAllListeners;
-  dispose: () => void;
+  dispose: () => void | Promise<void>;
   call: (params: any) => Promise<any>;
   uiResponse: typeof uiResponse;
   cancel: (connectId?: string) => void;
+  cancelOperation: (operationId: string) => void;
   updateSettings: typeof updateSettings;
   switchTransport: (env: ConnectSettings['env']) => Promise<{ success: boolean }>;
   getLogs: typeof getLogs;
+  clearSessionCache: typeof clearSessionCache;
 
   /**
    * Test function
@@ -170,8 +219,10 @@ export type CoreApi = {
   searchDevices: typeof searchDevices;
   promptWebDeviceAccess: typeof promptWebDeviceAccess;
   getFeatures: typeof getFeatures;
+  getDeviceState: typeof getDeviceState;
   getOnekeyFeatures: typeof getOnekeyFeatures;
   getPassphraseState: typeof getPassphraseState;
+  openWalletSession: typeof openWalletSession;
   deviceBackup: typeof deviceBackup;
   deviceChangePin: typeof deviceChangePin;
   deviceFlags: typeof deviceFlags;
@@ -197,8 +248,44 @@ export type CoreApi = {
   firmwareUpdate: typeof firmwareUpdate;
   firmwareUpdateV2: typeof firmwareUpdateV2;
   firmwareUpdateV3: typeof firmwareUpdateV3;
+  firmwareUpdateV4: typeof firmwareUpdateV4;
+  registerFirmwareUpdateHostBinding: typeof registerFirmwareUpdateHostBinding;
+  unregisterFirmwareUpdateHostBinding: typeof unregisterFirmwareUpdateHostBinding;
+  getFirmwareUpdateHostBindingGeneration: typeof getFirmwareUpdateHostBindingGeneration;
+  getFirmwareUpdateCapabilities: typeof getFirmwareUpdateCapabilities;
+  prepareFirmwareUpdatePlan: typeof prepareFirmwareUpdatePlan;
+  validateFirmwareUpdatePreparedPlan: typeof validateFirmwareUpdatePreparedPlan;
   cipherKeyValue: typeof cipherKeyValue;
 
+  /**
+   * Pro2 business API
+   */
+  deviceReboot: typeof deviceReboot;
+  deviceGetOnboardingStatus: typeof deviceGetOnboardingStatus;
+  deviceUploadWallpaper: typeof deviceUploadWallpaper;
+  deviceInfoGet: typeof deviceInfoGet;
+  deviceStatusGet: typeof deviceStatusGet;
+  deviceSettingsGet: typeof deviceSettingsGet;
+  protocolInfoRequest: typeof protocolInfoRequest;
+  ping: typeof ping;
+  deviceSessionOpen: typeof deviceSessionOpen;
+  deviceFirmwareUpdate: typeof deviceFirmwareUpdate;
+  deviceGetFirmwareUpdateStatus: typeof deviceGetFirmwareUpdateStatus;
+  deviceFactoryInfoSet: typeof deviceFactoryInfoSet;
+  deviceFactoryInfoGet: typeof deviceFactoryInfoGet;
+  deviceSettingsSet: typeof deviceSettingsSet;
+  deviceSettingsPageShow: typeof deviceSettingsPageShow;
+  filesystemPermissionFix: typeof filesystemPermissionFix;
+  filesystemFormat: typeof filesystemFormat;
+  uploadPortfolio: typeof uploadPortfolio;
+  fileRead: typeof fileRead;
+  fileWrite: typeof fileWrite;
+  fileDelete: typeof fileDelete;
+  dirList: typeof dirList;
+  dirMake: typeof dirMake;
+  dirRemove: typeof dirRemove;
+  pathInfo: typeof pathInfo;
+
   /**
    * All network function
    */

package/src/types/api/openWalletSession.ts

@@ -0,0 +1,54 @@
+import type { CommonParams, Response } from '../params';
+
+export type OpenWalletSessionParams =
+  | {
+      mode: 'standard';
+      deviceId?: never;
+      passphraseState?: never;
+      useEmptyPassphrase?: never;
+      initSession?: never;
+    }
+  | {
+      mode: 'select-hidden';
+      deviceId?: never;
+      passphraseState?: never;
+      useEmptyPassphrase?: never;
+      initSession?: never;
+    }
+  | {
+      mode: 'resume-hidden';
+      deviceId: string;
+      passphraseState: string;
+      useEmptyPassphrase?: never;
+      initSession?: never;
+    }
+  | {
+      /**
+       * Compatibility form. `useEmptyPassphrase: true` opens the standard wallet;
+       * otherwise `initSession: true` starts a fresh hidden-wallet selection, a
+       * complete wallet binding resumes a hidden wallet, and no binding starts the
+       * hidden-wallet selection flow.
+       */
+      mode?: undefined;
+      useEmptyPassphrase?: boolean;
+      initSession?: boolean;
+      deviceId?: string;
+      passphraseState?: string;
+    };
+
+export type OpenWalletSessionPayload = {
+  protocol: 'V1' | 'V2';
+  walletType: 'standard' | 'hidden';
+  deviceId: string;
+  passphraseState: string | null;
+  resumed: boolean;
+};
+
+/**
+ * Opens the standard, hidden, or Attach-to-PIN wallet flow through a unified
+ * Protocol V1/V2 API.
+ */
+export declare function openWalletSession(
+  connectId: string,
+  params: CommonParams & OpenWalletSessionParams
+): Response<OpenWalletSessionPayload>;