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

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

@@ -0,0 +1,210 @@
+import { UI_REQUEST, createUiMessage } from '../../events';
+
+import type { CoreMessage, ProtocolV2UiCompletion } from '../../events';
+import type { Device } from '../../device/Device';
+import type { KnownDevice } from '../../types';
+
+export type ProtocolV2InteractionDescriptor = {
+  request: 'button' | 'pin';
+  source: 'method-lifecycle';
+  reason:
+    | 'change-pin'
+    | 'device-unlock'
+    | 'settings-page'
+    | 'address-confirmation'
+    | 'public-key-confirmation'
+    | 'signing-confirmation'
+    | 'device-management';
+  completion: ProtocolV2UiCompletion;
+  deviceOnly: true;
+  page?: string | number;
+  operation?: string;
+};
+
+type ProtocolV2InteractionMethod = {
+  name?: string;
+  params?: unknown;
+  payload?: unknown;
+  protocolV2UiInteraction?: ProtocolV2InteractionDescriptor;
+};
+
+type InteractionDevice = Pick<Device, 'isProtocolV2' | 'toMessageObject'>;
+type PostMessage = (message: CoreMessage) => void;
+
+export const isProtocolV2UiEnabled = (method: { protocolV2UiMode?: 'auto' | 'none' }) =>
+  method.protocolV2UiMode !== 'none';
+
+const getDisplayState = (value: unknown) => {
+  const visited = new Set<object>();
+  let seen = false;
+  let enabled = false;
+
+  const visit = (current: unknown) => {
+    if (current == null || typeof current !== 'object') return;
+    if (visited.has(current)) return;
+    visited.add(current);
+
+    if (Array.isArray(current)) {
+      current.forEach(visit);
+      return;
+    }
+
+    Object.entries(current).forEach(([key, item]) => {
+      if ((key === 'show_display' || key === 'showOnOneKey') && typeof item === 'boolean') {
+        seen = true;
+        enabled ||= item;
+        return;
+      }
+      visit(item);
+    });
+  };
+
+  visit(value);
+  return { seen, enabled };
+};
+
+const createMethodInteraction = (
+  reason: 'address-confirmation' | 'public-key-confirmation' | 'signing-confirmation',
+  operation: string
+): ProtocolV2InteractionDescriptor => ({
+  request: 'button',
+  source: 'method-lifecycle',
+  reason,
+  completion: 'operation-completed',
+  deviceOnly: true,
+  operation,
+});
+
+const hasCipherConfirmation = (value: unknown): boolean => {
+  if (Array.isArray(value)) return value.some(hasCipherConfirmation);
+  if (value == null || typeof value !== 'object') return false;
+
+  const params = value as {
+    encrypt?: boolean;
+    ask_on_encrypt?: boolean;
+    ask_on_decrypt?: boolean;
+  };
+  return params.encrypt === true ? params.ask_on_encrypt === true : params.ask_on_decrypt === true;
+};
+
+/**
+ * Protocol V2 no longer relies on firmware ButtonRequest, so the SDK synthesizes
+ * compatible UI events. Explicit descriptors win; address/public-key prompts appear
+ * only when displayed, while signing emits one prompt.
+ */
+export const resolveProtocolV2UiInteraction = (
+  method: ProtocolV2InteractionMethod
+): ProtocolV2InteractionDescriptor | undefined => {
+  if (method.protocolV2UiInteraction) return method.protocolV2UiInteraction;
+
+  const operation = method.name;
+  if (!operation) return undefined;
+
+  const isAddress = /getAddress(?:ByLoop)?$/i.test(operation);
+  const isPublicKey = /getPublicKey$/i.test(operation);
+  if (isAddress || isPublicKey) {
+    const paramsDisplay = getDisplayState(method.params);
+    const payloadDisplay = getDisplayState(method.payload);
+    const display = paramsDisplay.seen ? paramsDisplay : payloadDisplay;
+
+    // Address methods usually display by default; public-key methods may be silent.
+    const shouldDisplay = display.seen ? display.enabled : isAddress;
+    if (!shouldDisplay) return undefined;
+
+    return createMethodInteraction(
+      isAddress ? 'address-confirmation' : 'public-key-confirmation',
+      operation
+    );
+  }
+
+  if (/sign/i.test(operation) || /verifyMessage$/i.test(operation) || operation === 'lnurlAuth') {
+    return createMethodInteraction('signing-confirmation', operation);
+  }
+
+  if (operation === 'nostrEncryptMessage' || operation === 'nostrDecryptMessage') {
+    const display = getDisplayState(method.params);
+    if (!display.enabled) return undefined;
+    return createMethodInteraction('signing-confirmation', operation);
+  }
+
+  if (operation === 'cipherKeyValue' && hasCipherConfirmation(method.params)) {
+    return createMethodInteraction('signing-confirmation', operation);
+  }
+
+  return undefined;
+};
+
+export class ProtocolV2UiInteractionCoordinator {
+  private readonly device: InteractionDevice;
+
+  private readonly postMessage: PostMessage;
+
+  private methodInteraction?: ProtocolV2InteractionDescriptor;
+
+  private currentPhase?: string;
+
+  private opened = false;
+
+  private closed = false;
+
+  constructor(device: InteractionDevice, postMessage: PostMessage) {
+    this.device = device;
+    this.postMessage = postMessage;
+  }
+
+  enterMethodInteraction(interaction?: ProtocolV2InteractionDescriptor) {
+    this.methodInteraction = interaction;
+    if (!interaction) return;
+    const { request, ...metadata } = interaction;
+
+    this.emit(
+      request === 'pin' ? UI_REQUEST.REQUEST_PIN : UI_REQUEST.REQUEST_BUTTON,
+      {
+        device: this.device.toMessageObject() as KnownDevice,
+        ...metadata,
+      },
+      `method:${request}:${interaction.reason}:${interaction.page ?? ''}:${
+        interaction.operation ?? ''
+      }`
+    );
+  }
+
+  enterUnlockInteraction(method?: string) {
+    this.emit(
+      UI_REQUEST.REQUEST_PIN,
+      {
+        device: this.device.toMessageObject() as KnownDevice,
+        source: 'unlock-coordinator',
+        reason: 'device-locked',
+        deviceOnly: true,
+        method,
+      },
+      `unlock:${method ?? ''}`
+    );
+  }
+
+  resumeMethodInteraction() {
+    this.enterMethodInteraction(this.methodInteraction);
+  }
+
+  close() {
+    if (!this.device.isProtocolV2() || !this.opened || this.closed) return;
+    this.closed = true;
+    this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_WINDOW));
+  }
+
+  private emit(
+    type: typeof UI_REQUEST.REQUEST_BUTTON | typeof UI_REQUEST.REQUEST_PIN,
+    payload: any,
+    phase: string
+  ) {
+    if (!this.device.isProtocolV2() || this.closed || this.currentPhase === phase) return;
+    this.currentPhase = phase;
+    this.opened = true;
+    const message =
+      type === UI_REQUEST.REQUEST_BUTTON
+        ? createUiMessage(UI_REQUEST.REQUEST_BUTTON, payload)
+        : createUiMessage(UI_REQUEST.REQUEST_PIN, payload);
+    this.postMessage(message);
+  }
+}

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

@@ -0,0 +1,76 @@
+import { LoggerNames, getLogger } from '../../utils';
+import { isDeviceLockedError } from './lockedError';
+import { isProtocolV2UiEnabled, resolveProtocolV2UiInteraction } from './uiInteraction';
+
+import type { BaseMethod } from '../../api/BaseMethod';
+import type { Device } from '../../device/Device';
+import type { ProtocolV2UiInteractionCoordinator } from './uiInteraction';
+
+const Log = getLogger(LoggerNames.Core);
+
+type RunnableMethod = Pick<
+  BaseMethod,
+  'run' | 'unlockPolicy' | 'protocolV2UiInteraction' | 'protocolV2UiMode' | 'params' | 'payload'
+> & { name?: string };
+type UnlockableDevice = Pick<Device, 'isProtocolV2' | 'unlockDevice' | 'features'>;
+type UiInteractionCoordinator = Pick<
+  ProtocolV2UiInteractionCoordinator,
+  'enterMethodInteraction' | 'enterUnlockInteraction' | 'resumeMethodInteraction'
+>;
+
+export async function runMethodWithUnlockRetry(
+  method: RunnableMethod,
+  device: UnlockableDevice,
+  uiCoordinator?: UiInteractionCoordinator
+) {
+  const shouldEmitUi = isProtocolV2UiEnabled(method);
+  const shouldUnlockBeforeRun =
+    device.isProtocolV2() &&
+    method.unlockPolicy === 'retry-on-locked' &&
+    device.features?.unlocked === false;
+
+  if (shouldUnlockBeforeRun) {
+    if (shouldEmitUi) {
+      uiCoordinator?.enterUnlockInteraction(method.name);
+    }
+    await device.unlockDevice();
+    Log.debug('Protocol V2 pre-unlock completed', { method: method.name });
+    if (shouldEmitUi) {
+      uiCoordinator?.enterMethodInteraction(resolveProtocolV2UiInteraction(method));
+    }
+    return method.run();
+  }
+
+  if (shouldEmitUi) {
+    uiCoordinator?.enterMethodInteraction(resolveProtocolV2UiInteraction(method));
+  }
+  try {
+    return await method.run();
+  } catch (error) {
+    if (
+      !device.isProtocolV2() ||
+      method.unlockPolicy !== 'retry-on-locked' ||
+      !isDeviceLockedError(error)
+    ) {
+      throw error;
+    }
+
+    Log.debug('Protocol V2 unlock retry triggered', { method: method.name });
+    if (shouldEmitUi) {
+      uiCoordinator?.enterUnlockInteraction(method.name);
+    }
+    await device.unlockDevice();
+    Log.debug('Protocol V2 unlock completed', { method: method.name });
+    if (shouldEmitUi) {
+      uiCoordinator?.resumeMethodInteraction();
+    }
+    try {
+      const response = await method.run();
+      Log.debug('Protocol V2 method retry completed', { method: method.name, success: true });
+      return response;
+    } catch (retryError) {
+      Log.debug('Protocol V2 method retry completed', { method: method.name, success: false });
+      throw retryError;
+    }
+  }
+}

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

@@ -0,0 +1,107 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import { assertCompleteDeviceSession } from './deviceSession';
+import { isDeviceLockedError } from './lockedError';
+
+import type { DeviceSessionGet } from '@onekeyfe/hd-transport';
+import type { Device } from '../../device/Device';
+
+export async function requestProtocolV2DeviceStatus(device: Device) {
+  const { message } = await device.commands.typedCall('DeviceStatusGet', 'DeviceStatus', {});
+  return message;
+}
+
+export async function refreshProtocolV2DeviceStatus(device: Device) {
+  const status = await requestProtocolV2DeviceStatus(device);
+  return device.updateProtocolV2Status(status);
+}
+
+const getDeviceSession = async (device: Device, request: DeviceSessionGet) => {
+  try {
+    return await device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
+  } catch (error) {
+    if (!isDeviceLockedError(error)) {
+      throw error;
+    }
+    await device.unlockDevice();
+    return device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
+  }
+};
+
+export async function getProtocolV2WalletSession(
+  device: Device,
+  options?: {
+    initSession?: boolean;
+    expectedPassphraseState?: string;
+    onlyMainPin?: boolean;
+  }
+) {
+  if (options?.initSession) {
+    device.clearInternalState();
+  }
+
+  const expectedPassphraseState = options?.expectedPassphraseState ?? device.passphraseState;
+
+  // Unlock with PIN first. DeviceSessionGet operates on the wallet selected by
+  // the device unlock flow; Protocol V2 does not accept a host passphrase here.
+  if (device.features?.unlocked === false) {
+    await device.unlockDevice();
+  }
+
+  // A standard wallet needs no DeviceSession. After unlock confirms passphrase is
+  // disabled, do not create or forward a hidden-wallet passphraseState.
+  if (options?.onlyMainPin || device.getCurrentPassphraseProtection() === false) {
+    return {
+      passphraseState: undefined,
+      newSession: undefined,
+      unlockedAttachPin: device.features?.unlockedAttachPin ?? false,
+      resumed: false,
+    };
+  }
+
+  const cachedSessionId =
+    typeof device.getInternalState === 'function' ? device.getInternalState() : undefined;
+  let response;
+  let resumed = false;
+
+  if (cachedSessionId && expectedPassphraseState) {
+    try {
+      response = await getDeviceSession(device, { session_id: cachedSessionId });
+      resumed = true;
+    } catch (error) {
+      device.clearInternalState();
+      throw error;
+    }
+  }
+
+  if (!response) {
+    response = await getDeviceSession(device, {});
+  }
+
+  const { message } = response;
+  try {
+    assertCompleteDeviceSession(message);
+  } catch (error) {
+    device.clearInternalState();
+    throw error;
+  }
+  if (expectedPassphraseState && expectedPassphraseState !== message.btc_test_address) {
+    device.clearInternalState();
+    throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
+  }
+
+  device.updateInternalState(
+    true,
+    message.btc_test_address,
+    device.getCurrentDeviceId(),
+    message.session_id,
+    options?.initSession ? null : device.features?.sessionId ?? null
+  );
+
+  return {
+    passphraseState: message.btc_test_address,
+    newSession: message.session_id,
+    unlockedAttachPin: device.features?.unlockedAttachPin ?? undefined,
+    resumed,
+  };
+}

package/src/types/api/checkAllFirmwareRelease.ts

@@ -1,8 +1,7 @@
 import type { IBLEFirmwareReleaseInfo } from '../settings';
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
-import type { Features } from '@onekeyfe/hd-transport';
 import type { CommonParams, Response } from '../params';
-import type { IDeviceBLEFirmwareStatus, IDeviceFirmwareStatus } from '../device';
+import type { Features, IDeviceBLEFirmwareStatus, IDeviceFirmwareStatus } from '../device';
 
 export type FirmwareRelease = {
   shouldUpdate?: boolean;

package/src/types/api/deviceSettings.ts

@@ -1,20 +1,44 @@
-import type { SafetyCheckLevel, Success } from '@onekeyfe/hd-transport';
+import type { Enum_SafetyCheckLevel, Success } from '@onekeyfe/hd-transport';
 import type { CommonParams, Response } from '../params';
 
 export type DeviceSettingsParams = {
   language?: string;
   label?: string;
   usePassphrase?: boolean;
+  /** Protocol V1 only. */
   homescreen?: string;
+  /** Protocol V1 only. */
   passphraseSource?: number;
   autoLockDelayMs?: number;
+  /** Protocol V1 only. */
   displayRotation?: number;
+  /** Protocol V1 only. */
   passphraseAlwaysOnDevice?: boolean;
-  safetyChecks?: SafetyCheckLevel;
+  /** Protocol V1 only. Uses Enum_SafetyCheckLevel numeric values. */
+  safetyChecks?: Enum_SafetyCheckLevel;
+  /** Protocol V1 only; the current Protocol V2 schema has no matching field. */
   experimentalFeatures?: boolean;
   autoShutdownDelayMs?: number;
+  /** Protocol V1 only; opens the legacy device-side brightness flow. */
   changeBrightness?: boolean;
+  /** Protocol V2 only. */
+  brightness?: number;
   hapticFeedback?: boolean;
+  bluetoothEnabled?: boolean;
+  /** Protocol V2 only; changed through an on-device confirmation page. */
+  airgapMode?: boolean;
+  /** Protocol V2 only. */
+  animationEnabled?: boolean;
+  /** Protocol V2 only. */
+  tapToWake?: boolean;
+  /** Protocol V2 only. */
+  deviceNameDisplayEnabled?: boolean;
+  /** Protocol V2 only. */
+  fidoEnabled?: boolean;
+  /** Protocol V2 only. */
+  usbLockEnabled?: boolean;
+  /** Protocol V2 only. */
+  randomKeypad?: boolean;
 };
 
 export declare function deviceSettings(

package/src/types/api/deviceUnlock.ts

@@ -1,4 +1,7 @@
-import type { Features } from '@onekeyfe/hd-transport';
+import type { DeviceState } from '../device';
 import type { CommonParams, Response } from '../params';
 
-export declare function deviceUnlock(connectId: string, params?: CommonParams): Response<Features>;
+export declare function deviceUnlock(
+  connectId: string,
+  params?: CommonParams
+): Response<DeviceState>;

package/src/types/api/firmwareUpdate.ts

@@ -58,42 +58,50 @@ export interface FirmwareUpdateV3Params {
 }
 
 /**
- * firmwareUpdateV4（Protocol V2）按 DevFirmwareTargetType 拆分的目标二进制。
- * 每个字段对应一个固件升级 target，可单独更新，也可任意组合一次更新。
+ * 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 {
   platform: IPlatform;
   chunkSize?: number;
   firmwareType?: EFirmwareType;
+  targetsToUpdate?: FirmwareUpdateV4Target[];
 
-  /** TARGET_MAIN_BOOT = 1 */
+  /** FW_MGMT_TARGET_ROMLOADER = 2; Pro2 cannot install it through firmwareUpdateV4. */
   romloaderBinary?: ArrayBuffer;
-  /** TARGET_MAIN_BOOT = 1 */
+  /** FW_MGMT_TARGET_BOOTLOADER = 3 */
   bootloaderBinary?: ArrayBuffer;
-  /** TARGET_MAIN_APP = 0 */
+  /** FW_MGMT_TARGET_APPLICATION_P1 = 4 */
   applicationP1Binary?: ArrayBuffer;
-  /** TARGET_MAIN_APP = 0 */
+  /** FW_MGMT_TARGET_APPLICATION_P2 = 5 */
   applicationP2Binary?: ArrayBuffer;
-  /** TARGET_BT = 2 */
+  /** FW_MGMT_TARGET_COPROCESSOR = 6 */
   coprocessorBinary?: ArrayBuffer;
-  /** TARGET_SE1-4 = 3-6 */
+  /** FW_MGMT_TARGET_SE01-04 = 7-10 */
   se01Binary?: ArrayBuffer;
   se02Binary?: ArrayBuffer;
   se03Binary?: ArrayBuffer;
   se04Binary?: ArrayBuffer;
-  /** TARGET_RESOURCE = 10（zip 包，解压后逐文件上传） */
-  resourceBinary?: ArrayBuffer;
   forcedUpdateRes?: boolean;
-
-  /** 按 release 配置自动下载 */
-  firmwareVersion?: number[];
-  bleVersion?: number[];
-  bootloaderVersion?: number[];
-
-  /** legacy 别名：等价 applicationP1Binary */
-  firmwareBinary?: ArrayBuffer;
-  /** legacy 别名：等价 coprocessorBinary */
-  bleBinary?: ArrayBuffer;
+  /**
+   * RESC bundle okpkg files written directly to devicePath through FilesystemFileWrite.
+   * Manual mode installs them without version comparison.
+   */
+  resourceBundleFiles?: Array<{
+    binary: ArrayBuffer;
+    devicePath: string;
+  }>;
 }
 
 export declare function firmwareUpdateV3(

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,17 +1,14 @@
 import type { CommonParams, Response } from '../params';
 
-export type GetPassphraseStatePayload = {
-  passphrase_state?: string;
-  session_id?: string;
-  unlocked_attach_pin?: boolean;
-  passphrase_protection?: boolean | null;
-};
-
-export type GetPassphraseStateParams = CommonParams & {
-  allowCreateAttachPin?: boolean;
-};
+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?: GetPassphraseStateParams
-): Response<GetPassphraseStatePayload>;
+): Response<string | undefined>;