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

package/src/events/ui-request.ts

@@ -49,6 +49,23 @@ export const UI_REQUEST = {
   NOT_USE_ONEKEY_DEVICE: 'ui-device_please_use_onekey_device',
 } as const;
 
+export type ProtocolV2UiEventSource =
+  | 'unlock-coordinator'
+  | 'wallet-session-coordinator'
+  | 'method-lifecycle';
+
+export type ProtocolV2UiCompletion = 'page-accepted' | 'operation-completed';
+
+export type ProtocolV2UiEventMetadata = {
+  source?: ProtocolV2UiEventSource;
+  reason?: string;
+  deviceOnly?: boolean;
+  completion?: ProtocolV2UiCompletion;
+  method?: string;
+  page?: string | number;
+  operation?: string;
+};
+
 export interface UiRequestWithoutPayload {
   type:
     | typeof UI_REQUEST.CLOSE_UI_WINDOW
@@ -73,7 +90,7 @@ export interface UiRequestFirmwareProgressing {
 
 export type UiRequestDeviceAction = {
   type: typeof UI_REQUEST.REQUEST_PIN;
-  payload: {
+  payload: ProtocolV2UiEventMetadata & {
     device: Device;
     type?: PROTO.PinMatrixRequestType | 'ButtonRequest_PinEntry' | 'ButtonRequest_AttachPin';
   };
@@ -81,7 +98,7 @@ export type UiRequestDeviceAction = {
 
 export interface UiRequestButton {
   type: typeof UI_REQUEST.REQUEST_BUTTON;
-  payload: DeviceButtonRequest['payload'];
+  payload: DeviceButtonRequest['payload'] & ProtocolV2UiEventMetadata;
 }
 
 export interface UiRequestPassphrase {
@@ -90,6 +107,9 @@ export interface UiRequestPassphrase {
     device: Device;
     passphraseState?: string;
     existsAttachPinUser?: boolean;
+    source?: 'wallet-session-coordinator';
+    reason?: 'open-wallet' | 'session-recovery';
+    expectedPassphraseState?: string;
   };
 }
 
@@ -98,6 +118,8 @@ export interface UiRequestPassphraseOnDevice {
   payload: {
     device: Device;
     passphraseState?: string;
+    source?: 'wallet-session-coordinator';
+    reason?: 'open-wallet' | 'session-recovery';
   };
 }
 
@@ -129,6 +151,10 @@ export interface FirmwareProgress {
     device: Device;
     progress: number;
     progressType: IFirmwareUpdateProgressType;
+    transferredBytes?: number;
+    totalBytes?: number;
+    rateBytesPerSecond?: number;
+    elapsedMs?: number;
   };
 }
 
@@ -144,6 +170,10 @@ export interface DeviceProgress {
   type: typeof UI_REQUEST.DEVICE_PROGRESS;
   payload: {
     progress?: number;
+    transferredBytes?: number;
+    totalBytes?: number;
+    rateBytesPerSecond?: number;
+    elapsedMs?: number;
   };
 }
 

package/src/index.ts

@@ -19,6 +19,11 @@ export * from './types';
 export { whitelist, whitelistExtension } from './data/config';
 export { executeCallback, cleanupCallback };
 export { preloadSessionCache } from './device/Device';
+export {
+  getFirmwareUpdateHostBindingGeneration,
+  registerFirmwareUpdateHostBinding,
+  unregisterFirmwareUpdateHostBinding,
+} from './api/firmware/FirmwareHostBinding';
 
 const HardwareSdk = ({
   init,
@@ -27,6 +32,7 @@ const HardwareSdk = ({
   eventEmitter,
   uiResponse,
   cancel,
+  cancelOperation,
   updateSettings,
   switchTransport,
 }: InjectApi): CoreApi =>
@@ -37,6 +43,7 @@ const HardwareSdk = ({
     eventEmitter,
     uiResponse,
     cancel,
+    cancelOperation,
     updateSettings,
     switchTransport,
   });
@@ -49,6 +56,7 @@ const HardwareSDKLowLevel = ({
   addHardwareGlobalEventListener,
   uiResponse,
   cancel,
+  cancelOperation,
   updateSettings,
   switchTransport,
 }: LowLevelInjectApi): LowLevelCoreApi =>
@@ -60,6 +68,7 @@ const HardwareSDKLowLevel = ({
     addHardwareGlobalEventListener,
     uiResponse,
     cancel,
+    cancelOperation,
     updateSettings,
     switchTransport,
   });

package/src/inject.ts

@@ -1,6 +1,17 @@
-import type { Unsuccessful } from './types';
+import { getFirmwareUpdateCapabilities } from './api/firmware/FirmwareUpdateCapabilities';
+import {
+  prepareFirmwareUpdatePlan,
+  validateFirmwareUpdatePreparedPlan,
+} from './api/firmware/FirmwareUpdatePreparedPlan';
+import {
+  getFirmwareUpdateHostBindingGeneration,
+  registerFirmwareUpdateHostBinding,
+  unregisterFirmwareUpdateHostBinding,
+} from './api/firmware/FirmwareHostBinding';
+
 import type { EventEmitter } from 'events';
 import type { CallMethod } from './events';
+import type { Unsuccessful } from './types';
 import type { CoreApi } from './types/api';
 import type { AllNetworkAddress } from './types/api/allNetworkGetAddress';
 
@@ -36,12 +47,14 @@ export interface InjectApi {
   dispose: CoreApi['dispose'];
   uiResponse: CoreApi['uiResponse'];
   cancel: CoreApi['cancel'];
+  cancelOperation: CoreApi['cancelOperation'];
   switchTransport: CoreApi['switchTransport'];
 }
 
 export const inject = ({
   call,
   cancel,
+  cancelOperation,
   dispose,
   eventEmitter,
   init,
@@ -68,11 +81,15 @@ export const inject = ({
 
     call,
 
-    dispose,
+    dispose: async () => {
+      unregisterFirmwareUpdateHostBinding();
+      await dispose();
+    },
 
     uiResponse,
 
     cancel,
+    cancelOperation,
 
     updateSettings,
 
@@ -96,19 +113,31 @@ export const createCoreApi = (
   | 'dispose'
   | 'uiResponse'
   | 'cancel'
+  | 'cancelOperation'
   | 'updateSettings'
   | 'switchTransport'
 > => ({
+  getFirmwareUpdateCapabilities,
+  registerFirmwareUpdateHostBinding,
+  unregisterFirmwareUpdateHostBinding,
+  getFirmwareUpdateHostBindingGeneration,
+  prepareFirmwareUpdatePlan,
+  validateFirmwareUpdatePreparedPlan,
   getLogs: () => call({ method: 'getLogs' }),
+  clearSessionCache: params => call({ ...params, method: 'clearSessionCache' }),
   /**
    * 搜索设备
    */
-  searchDevices: () => call({ method: 'searchDevices' }),
+  searchDevices: params => call({ ...params, method: 'searchDevices' }),
 
   /**
    * 获取设备信息
    */
   getFeatures: (connectId, params) => call({ ...params, connectId, method: 'getFeatures' }),
+  getDeviceState: (connectId, params) => {
+    const { refresh: _refresh, includeRaw: _includeRaw, ...commonParams } = (params ?? {}) as any;
+    return call({ ...commonParams, connectId, method: 'getDeviceState' });
+  },
   getOnekeyFeatures: (connectId, params) =>
     call({ ...params, connectId, method: 'getOnekeyFeatures' }),
 
@@ -148,6 +177,45 @@ export const createCoreApi = (
   deviceFlags: (connectId, params) => call({ ...params, connectId, method: 'deviceFlags' }),
   deviceRebootToBoardloader: connectId => call({ connectId, method: 'deviceRebootToBoardloader' }),
   deviceRebootToBootloader: connectId => call({ connectId, method: 'deviceRebootToBootloader' }),
+
+  // Pro2 business API
+  deviceReboot: (connectId, params) => call({ ...params, connectId, method: 'deviceReboot' }),
+  deviceGetOnboardingStatus: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceGetOnboardingStatus' }),
+  deviceUploadWallpaper: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceUploadWallpaper' }),
+  deviceInfoGet: (connectId, params) => call({ ...params, connectId, method: 'deviceInfoGet' }),
+  deviceStatusGet: (connectId, params) => call({ ...params, connectId, method: 'deviceStatusGet' }),
+  deviceSettingsGet: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceSettingsGet' }),
+  protocolInfoRequest: (connectId, params) =>
+    call({ ...params, connectId, method: 'protocolInfoRequest' }),
+  ping: (connectId, params) => call({ ...params, connectId, method: 'ping' }),
+  deviceSessionOpen: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceSessionOpen' }),
+  deviceFirmwareUpdate: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceFirmwareUpdate' }),
+  deviceGetFirmwareUpdateStatus: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceGetFirmwareUpdateStatus' }),
+  deviceFactoryInfoSet: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceFactoryInfoSet' }),
+  deviceFactoryInfoGet: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceFactoryInfoGet' }),
+  deviceSettingsSet: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceSettingsSet' }),
+  deviceSettingsPageShow: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceSettingsPageShow' }),
+  filesystemPermissionFix: (connectId, params) =>
+    call({ ...params, connectId, method: 'filesystemPermissionFix' }),
+  filesystemFormat: connectId => call({ connectId, method: 'filesystemFormat' }),
+  uploadPortfolio: (connectId, params) => call({ ...params, connectId, method: 'uploadPortfolio' }),
+  fileRead: (connectId, params) => call({ ...params, connectId, method: 'fileRead' }),
+  fileWrite: (connectId, params) => call({ ...params, connectId, method: 'fileWrite' }),
+  fileDelete: (connectId, params) => call({ ...params, connectId, method: 'fileDelete' }),
+  dirList: (connectId, params) => call({ ...params, connectId, method: 'dirList' }),
+  dirMake: (connectId, params) => call({ ...params, connectId, method: 'dirMake' }),
+  dirRemove: (connectId, params) => call({ ...params, connectId, method: 'dirRemove' }),
+  pathInfo: (connectId, params) => call({ ...params, connectId, method: 'pathInfo' }),
   deviceRecovery: (connectId, params) => call({ ...params, connectId, method: 'deviceRecovery' }),
   deviceReset: (connectId, params) => call({ ...params, connectId, method: 'deviceReset' }),
   deviceSettings: (connectId, params) => call({ ...params, connectId, method: 'deviceSettings' }),
@@ -163,6 +231,8 @@ export const createCoreApi = (
     call({ ...params, connectId, method: 'deviceUpdateBootloader' }),
   getPassphraseState: (connectId, params) =>
     call({ ...params, connectId, method: 'getPassphraseState' }),
+  openWalletSession: (connectId, params) =>
+    call({ ...params, connectId, method: 'openWalletSession' }),
   deviceCancel: (connectId, params) => call({ ...params, connectId, method: 'deviceCancel' }),
   deviceLock: (connectId, params) => call({ ...params, connectId, method: 'deviceLock' }),
   deviceUnlock: (connectId, params) =>
@@ -260,6 +330,8 @@ export const createCoreApi = (
     call({ ...params, connectId, method: 'firmwareUpdateV2' }),
   firmwareUpdateV3: (connectId, params) =>
     call({ ...params, connectId, method: 'firmwareUpdateV3' }),
+  firmwareUpdateV4: (connectId, params) =>
+    call({ ...params, connectId, method: 'firmwareUpdateV4' }),
   promptWebDeviceAccess: params => call({ ...params, method: 'promptWebDeviceAccess' }),
 
   tronGetAddress: (connectId, deviceId, params) =>

package/src/lowLevelInject.ts

@@ -1,4 +1,5 @@
 import { createCoreApi } from './inject';
+import { unregisterFirmwareUpdateHostBinding } from './api/firmware/FirmwareHostBinding';
 
 import type { EventEmitter } from 'events';
 import type { CallMethod, CoreMessage } from './events';
@@ -13,6 +14,7 @@ export interface LowLevelInjectApi {
   dispose: CoreApi['dispose'];
   uiResponse: CoreApi['uiResponse'];
   cancel: CoreApi['cancel'];
+  cancelOperation: CoreApi['cancelOperation'];
   updateSettings: CoreApi['updateSettings'];
   switchTransport: CoreApi['switchTransport'];
   addHardwareGlobalEventListener: (listener: IAddHardwareGlobalEventListener) => void;
@@ -25,6 +27,7 @@ export type LowLevelCoreApi = Omit<CoreApi, 'on' | 'off'> & {
 export const lowLevelInject = ({
   call,
   cancel,
+  cancelOperation,
   dispose,
   eventEmitter,
   init,
@@ -43,11 +46,15 @@ export const lowLevelInject = ({
 
     call,
 
-    dispose,
+    dispose: async () => {
+      unregisterFirmwareUpdateHostBinding();
+      await dispose();
+    },
 
     uiResponse,
 
     cancel,
+    cancelOperation,
 
     updateSettings,
 

package/src/protocols/protocol-v2/deviceSession.ts

@@ -0,0 +1,24 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import type { DeviceSession } from '@onekeyfe/hd-transport';
+
+export type CompleteDeviceSession = DeviceSession & {
+  session_id: string;
+  btc_test_address: string;
+};
+
+export function assertCompleteDeviceSession(
+  message: DeviceSession
+): asserts message is CompleteDeviceSession {
+  if (
+    typeof message.session_id !== 'string' ||
+    !message.session_id ||
+    typeof message.btc_test_address !== 'string' ||
+    !message.btc_test_address
+  ) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'DeviceSessionOpen returned an incomplete DeviceSession response.'
+    );
+  }
+}

package/src/protocols/protocol-v2/features.ts

@@ -0,0 +1,163 @@
+import { DeviceSEState, DeviceSeType } from '@onekeyfe/hd-transport';
+
+import type {
+  DeviceInfoGet,
+  DeviceSEInfo,
+  DeviceStatus,
+  ProtocolV2DeviceInfo,
+} from '@onekeyfe/hd-transport';
+import type { DeviceCommands } from '../../device/DeviceCommands';
+
+// Use hd-transport generated Protocol V2 types as the single source of truth.
+export type { ProtocolV2DeviceInfo };
+export type { DeviceFirmwareImageInfo as ProtocolV2FirmwareImageInfo } from '@onekeyfe/hd-transport';
+export type { DeviceSEInfo as ProtocolV2SEInfo } from '@onekeyfe/hd-transport';
+
+export type ProtocolV2SeStateLabel = 'BOOT' | 'APP_FACTORY' | 'APP';
+
+/**
+ * The transport historically decodes scalar proto enums as name strings.
+ * Accept both that SDK representation and numeric enums for low-level callers.
+ */
+const normalizeEnumValue = <T extends Record<string | number, string | number>>(
+  enumObject: T,
+  value: number | string | null | undefined
+): string | null => {
+  if (value == null) return null;
+  if (typeof value === 'string') return value;
+  const label = enumObject[value];
+  return typeof label === 'string' ? label : null;
+};
+
+/**
+ * Map DeviceSEInfo.state to a readable label. This is the SDK's canonical mapping
+ * used by DeviceState and the legacy Features projection.
+ */
+export const getProtocolV2SeState = (se?: DeviceSEInfo): ProtocolV2SeStateLabel | null => {
+  const label = normalizeEnumValue(DeviceSEState, se?.state);
+  switch (label) {
+    case 'BOOT':
+      return 'BOOT';
+    case 'APP_FACTORY':
+      return 'APP_FACTORY';
+    case 'APP':
+      return 'APP';
+    default:
+      return null;
+  }
+};
+
+/**
+ * Map DeviceSEInfo.type to a readable label such as `THD89`.
+ */
+export const getProtocolV2SeType = (se?: DeviceSEInfo): string | null =>
+  normalizeEnumValue(DeviceSeType, se?.type);
+
+export type ProtocolV2RuntimeMode = 'normal' | 'bootloader';
+
+/**
+ * TODO: Once firmware-pro2 exposes ProtocolInfo.build_fingerprint, parse the running
+ * binary name and remove the temporary DeviceStatusGet-failure heuristic. romloader
+ * is a separate recovery flow and is excluded until its contract is defined.
+ *
+ * The temporary contract has two states: DeviceStatusGet success means normal and
+ * failure means bootloader. Do not infer mode from application/SE/romloader fields.
+ */
+export const getProtocolV2RuntimeMode = ({
+  deviceInfo: _deviceInfo,
+  deviceStatusAvailable,
+}: {
+  deviceInfo?: ProtocolV2DeviceInfo | null;
+  deviceStatusAvailable: boolean;
+}): ProtocolV2RuntimeMode => {
+  if (deviceStatusAvailable) return 'normal';
+  return 'bootloader';
+};
+
+export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
+  targets: {
+    hw: true,
+    fw: true,
+    coprocessor: true,
+    se1: true,
+    se2: true,
+    se3: true,
+    se4: true,
+  },
+  types: {
+    version: true,
+    specific: true,
+  },
+};
+
+/**
+ * Version probe used after firmware update completion.
+ * It reads hardware and firmware component data without requesting DeviceStatus.
+ */
+export const PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST = {
+  targets: {
+    hw: true,
+    fw: true,
+    coprocessor: true,
+    se1: true,
+    se2: true,
+    se3: true,
+    se4: true,
+  },
+  types: {
+    version: true,
+    specific: true,
+  },
+};
+
+export const PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST = {
+  targets: {
+    hw: true,
+    fw: true,
+    coprocessor: true,
+    se1: true,
+    se2: true,
+    se3: true,
+    se4: true,
+  },
+  types: {
+    version: true,
+    build_id: true,
+    hash: true,
+    specific: true,
+  },
+};
+
+export const PROTOCOL_V2_DEVICE_INFO_REQUEST = PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST;
+export const PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS = 10 * 1000;
+
+export async function requestProtocolV2DeviceInfo({
+  commands,
+  timeoutMs = PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
+  request = PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST,
+}: {
+  commands: DeviceCommands;
+  timeoutMs?: number;
+  request?: DeviceInfoGet;
+}): Promise<ProtocolV2DeviceInfo> {
+  const { message } = await commands.typedCall('DeviceInfoGet', 'DeviceInfo', request, {
+    timeoutMs,
+  });
+  // Generated DeviceInfo is a V1/V2 union; DeviceInfoGet narrows it to the V2 shape.
+  return message as ProtocolV2DeviceInfo;
+}
+
+export async function requestProtocolV2DeviceStatus({
+  commands,
+  timeoutMs,
+}: {
+  commands: DeviceCommands;
+  timeoutMs?: number;
+}): Promise<DeviceStatus> {
+  const response =
+    timeoutMs === undefined
+      ? await commands.typedCall('DeviceStatusGet', 'DeviceStatus', {})
+      : await commands.typedCall('DeviceStatusGet', 'DeviceStatus', {}, { timeoutMs });
+  const { message } = response;
+  return message;
+}

package/src/protocols/protocol-v2/firmware.ts

@@ -0,0 +1,21 @@
+/**
+ * DeviceFirmwareTargetType from the current firmware-pro2 submodule.
+ */
+export const ProtocolV2FirmwareTargetType = {
+  FW_MGMT_TARGET_INVALID: 0,
+  FW_MGMT_TARGET_CRATE: 1,
+  FW_MGMT_TARGET_ROMLOADER: 2,
+  FW_MGMT_TARGET_BOOTLOADER: 3,
+  FW_MGMT_TARGET_APPLICATION_P1: 4,
+  FW_MGMT_TARGET_APPLICATION_P2: 5,
+  FW_MGMT_TARGET_COPROCESSOR: 6,
+  FW_MGMT_TARGET_SE01: 7,
+  FW_MGMT_TARGET_SE02: 8,
+  FW_MGMT_TARGET_SE03: 9,
+  FW_MGMT_TARGET_SE04: 10,
+} as const;
+
+// 常量和值类型共享导出名，保留现有公开 API。
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type ProtocolV2FirmwareTargetType =
+  (typeof ProtocolV2FirmwareTargetType)[keyof typeof ProtocolV2FirmwareTargetType];

package/src/protocols/protocol-v2/index.ts

@@ -0,0 +1,18 @@
+export {
+  PROTOCOL_V2_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
+  PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST,
+  PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
+  getProtocolV2RuntimeMode,
+  getProtocolV2SeState,
+  getProtocolV2SeType,
+} from './features';
+export type {
+  ProtocolV2DeviceInfo,
+  ProtocolV2FirmwareImageInfo,
+  ProtocolV2SEInfo,
+  ProtocolV2SeStateLabel,
+  ProtocolV2RuntimeMode,
+} from './features';
+export * from './firmware';
+export * from './walletSession';

package/src/protocols/protocol-v2/lockedError.ts

@@ -0,0 +1,10 @@
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+export function isDeviceLockedError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'errorCode' in error &&
+    error.errorCode === HardwareErrorCode.DeviceLocked
+  );
+}

package/src/protocols/protocol-v2/settingsUnlockPolicy.ts

@@ -0,0 +1,61 @@
+import type { DeviceSettings, DeviceSettingsPage } from '@onekeyfe/hd-transport';
+import type { UnlockPolicy } from '../../api/BaseMethod';
+import type { ProtocolV2InteractionDescriptor } from './uiInteraction';
+
+const LOCK_FREE_DEVICE_SETTINGS = new Set<keyof DeviceSettings>([
+  'label',
+  'language',
+  'brightness',
+  'haptic_feedback',
+]);
+
+export const getProtocolV2SettingsUnlockPolicy = (settings: DeviceSettings): UnlockPolicy =>
+  Object.keys(settings).every(key => LOCK_FREE_DEVICE_SETTINGS.has(key as keyof DeviceSettings))
+    ? 'none'
+    : 'retry-on-locked';
+
+export type ProtocolV2SettingsOperation =
+  | {
+      kind: 'direct';
+      settings: DeviceSettings;
+    }
+  | {
+      kind: 'page';
+      page: DeviceSettingsPage;
+    };
+
+export const getProtocolV2SettingsBehavior = (
+  operation: ProtocolV2SettingsOperation
+): {
+  unlockPolicy: UnlockPolicy;
+  uiInteraction?: ProtocolV2InteractionDescriptor;
+} => {
+  if (operation.kind === 'page') {
+    return {
+      unlockPolicy: 'retry-on-locked',
+      uiInteraction: {
+        request: 'button',
+        source: 'method-lifecycle',
+        reason: 'settings-page',
+        completion: 'operation-completed',
+        deviceOnly: true,
+        page: operation.page,
+      },
+    };
+  }
+
+  return {
+    unlockPolicy: getProtocolV2SettingsUnlockPolicy(operation.settings),
+    uiInteraction:
+      typeof operation.settings.label === 'string'
+        ? {
+            request: 'button',
+            source: 'method-lifecycle',
+            reason: 'device-management',
+            completion: 'operation-completed',
+            deviceOnly: true,
+            operation: 'change-label',
+          }
+        : undefined,
+  };
+};