@onekeyfe/hd-core 1.2.0-alpha.3 → 1.2.0-alpha.31

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/unlockPolicy.ts

@@ -0,0 +1,105 @@
+export type UnlockPolicy = 'none' | 'unlock-before-run' | 'retry-on-locked';
+
+/**
+ * Protocol V2 methods that are safe to replay after a locked response.
+ *
+ * Keep this as an exact allowlist. Name-pattern matching can silently make a new
+ * state-changing method replayable when it happens to share a suffix.
+ */
+export const PROTOCOL_V2_RETRY_ON_LOCKED_METHODS = [
+  'cipherKeyValue',
+  'allNetworkGetAddress',
+  'allNetworkGetAddressByLoop',
+  'btcGetAddress',
+  'btcGetPublicKey',
+  'btcSignMessage',
+  'btcSignPsbt',
+  'btcSignTransaction',
+  'btcVerifyMessage',
+  'confluxGetAddress',
+  'confluxSignMessage',
+  'confluxSignTransaction',
+  'evmGetAddress',
+  'evmGetPublicKey',
+  'evmSignMessage',
+  'evmSignTransaction',
+  'evmSignTypedData',
+  'evmVerifyMessage',
+  'starcoinGetAddress',
+  'starcoinGetPublicKey',
+  'starcoinSignMessage',
+  'starcoinSignTransaction',
+  'starcoinVerifyMessage',
+  'nemGetAddress',
+  'nemSignTransaction',
+  'solGetAddress',
+  'solSignTransaction',
+  'solSignOffchainMessage',
+  'solSignMessage',
+  'stellarGetAddress',
+  'stellarSignTransaction',
+  'tronGetAddress',
+  'tronSignMessage',
+  'tronSignTransaction',
+  'nearGetAddress',
+  'nearSignTransaction',
+  'aptosGetAddress',
+  'aptosGetPublicKey',
+  'aptosSignTransaction',
+  'aptosSignMessage',
+  'aptosSignInMessage',
+  'algoGetAddress',
+  'algoSignTransaction',
+  'cosmosGetAddress',
+  'cosmosGetPublicKey',
+  'cosmosSignTransaction',
+  'xrpGetAddress',
+  'xrpSignTransaction',
+  'suiGetAddress',
+  'suiGetPublicKey',
+  'suiSignMessage',
+  'suiSignTransaction',
+  'cardanoGetAddress',
+  'cardanoGetPublicKey',
+  'cardanoSignTransaction',
+  'cardanoSignMessage',
+  'filecoinGetAddress',
+  'filecoinSignTransaction',
+  'polkadotGetAddress',
+  'polkadotSignTransaction',
+  'kaspaGetAddress',
+  'kaspaSignTransaction',
+  'nexaGetAddress',
+  'nexaSignTransaction',
+  'nostrGetPublicKey',
+  'nostrSignEvent',
+  'nostrEncryptMessage',
+  'nostrDecryptMessage',
+  'nostrSignSchnorr',
+  'lnurlAuth',
+  'nervosGetAddress',
+  'nervosSignTransaction',
+  'dnxGetAddress',
+  'dnxSignTransaction',
+  'tonGetAddress',
+  'tonSignMessage',
+  'tonSignProof',
+  'tonSignData',
+  'scdoGetAddress',
+  'scdoSignTransaction',
+  'scdoSignMessage',
+  'alephiumGetAddress',
+  'alephiumSignTransaction',
+  'alephiumSignMessage',
+  'benfenGetAddress',
+  'benfenGetPublicKey',
+  'benfenSignMessage',
+  'benfenSignTransaction',
+  'neoGetAddress',
+  'neoSignTransaction',
+] as const;
+
+const retryOnLockedMethods = new Set<string>(PROTOCOL_V2_RETRY_ON_LOCKED_METHODS);
+
+export const getProtocolV2UnlockPolicy = (methodName: string): UnlockPolicy =>
+  retryOnLockedMethods.has(methodName) ? 'retry-on-locked' : 'none';

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

@@ -0,0 +1,98 @@
+import { LoggerNames, getLogger } from '../../utils';
+import { isDeviceLockedError } from './lockedError';
+import { isProtocolV2UiEnabled, resolveProtocolV2UiInteraction } from './uiInteraction';
+import { restoreProtocolV2WalletSession } from './walletSession';
+
+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'
+  | 'useDevicePassphraseState'
+> & { name?: string };
+type UiInteractionCoordinator = Pick<
+  ProtocolV2UiInteractionCoordinator,
+  'enterMethodInteraction' | 'enterUnlockInteraction' | 'resumeMethodInteraction'
+>;
+
+const restoreExpectedWalletSessionAfterUnlock = async (method: RunnableMethod, device: Device) => {
+  const expectedPassphraseState = method.payload?.useEmptyPassphrase
+    ? undefined
+    : method.payload?.passphraseState ?? device.passphraseState;
+  if (
+    !method.useDevicePassphraseState ||
+    typeof expectedPassphraseState !== 'string' ||
+    expectedPassphraseState.length === 0
+  ) {
+    return;
+  }
+
+  await restoreProtocolV2WalletSession(device, expectedPassphraseState);
+  Log.debug('Protocol V2 wallet session restored after unlock', { method: method.name });
+};
+
+export async function runMethodWithUnlockRetry(
+  method: RunnableMethod,
+  device: Device,
+  uiCoordinator?: UiInteractionCoordinator
+) {
+  const shouldEmitUi = isProtocolV2UiEnabled(method);
+  const shouldUnlockBeforeRun =
+    device.isProtocolV2() && method.unlockPolicy !== 'none' && 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 });
+    await restoreExpectedWalletSessionAfterUnlock(method, device);
+    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 });
+    await restoreExpectedWalletSessionAfterUnlock(method, device);
+    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,202 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
+
+import { DEVICE } from '../../events';
+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 negotiateEventlessWalletSession = async (device: Device) => {
+  await device.commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+    eventless_wallet_session: true,
+  });
+};
+
+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(DeviceSessionPinType.Main);
+    return device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
+  }
+};
+
+const askDevicePassphrase = async (device: Device, passphrase?: string) => {
+  const request = () =>
+    device.commands.typedCall(
+      'DeviceSessionAskPassphrase',
+      'Success',
+      passphrase ? { passphrase } : {}
+    );
+  try {
+    return await request();
+  } catch (error) {
+    if (!isDeviceLockedError(error)) {
+      throw error;
+    }
+    await device.unlockDevice(DeviceSessionPinType.Main);
+    return request();
+  }
+};
+
+const selectDeviceSession = async (device: Device) => {
+  const existsAttachPinUser = device.features?.attachToPinEnabled === true;
+  const metadata = {
+    source: 'wallet-session-coordinator' as const,
+    reason: 'open-wallet' as const,
+  };
+  const response = await device.commands.promptPassphrase(
+    {
+      existsAttachPinUser,
+      ...metadata,
+    },
+    { cancelDeviceOnReject: false }
+  );
+  const hasHostPassphrase =
+    typeof response.passphrase === 'string' && response.passphrase.length > 0;
+  const selections = [
+    hasHostPassphrase,
+    response.passphraseOnDevice === true,
+    response.attachPinOnDevice === true,
+  ].filter(Boolean).length;
+
+  if (selections !== 1) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Wallet selection must contain exactly one passphrase access mode.'
+    );
+  }
+
+  if (response.attachPinOnDevice) {
+    if (!existsAttachPinUser) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        'Attach PIN wallet selection is unavailable on this device.'
+      );
+    }
+    device.emit(DEVICE.ATTACH_PIN_ON_DEVICE, device, metadata);
+    await device.unlockDevice(DeviceSessionPinType.AttachToPin);
+    return getDeviceSession(device, {});
+  }
+
+  if (hasHostPassphrase) {
+    await askDevicePassphrase(device, response.passphrase);
+    return getDeviceSession(device, {});
+  }
+
+  device.emit(DEVICE.PASSPHRASE_ON_DEVICE, device, metadata);
+  await askDevicePassphrase(device);
+  return getDeviceSession(device, {});
+};
+
+export async function getProtocolV2WalletSession(
+  device: Device,
+  options?: {
+    initSession?: boolean;
+    expectedPassphraseState?: string;
+    onlyMainPin?: boolean;
+    resumeOnly?: boolean;
+  }
+) {
+  if (options?.initSession) {
+    device.clearInternalState();
+    device.passphraseState = undefined;
+  }
+
+  await negotiateEventlessWalletSession(device);
+
+  if (options?.onlyMainPin) {
+    device.passphraseState = undefined;
+  }
+  const expectedPassphraseState = options?.onlyMainPin
+    ? undefined
+    : options?.expectedPassphraseState ?? device.passphraseState;
+
+  if (device.features?.unlocked === false) {
+    await device.unlockDevice(DeviceSessionPinType.Main);
+  }
+
+  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) {
+    if (options?.resumeOnly) {
+      device.clearInternalState();
+      throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
+    }
+    response = await selectDeviceSession(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 : cachedSessionId ?? null
+  );
+
+  return {
+    passphraseState: message.btc_test_address,
+    newSession: message.session_id,
+    unlockedAttachPin: device.features?.unlockedAttachPin ?? undefined,
+    resumed,
+  };
+}
+
+export async function restoreProtocolV2WalletSession(
+  device: Device,
+  expectedPassphraseState: string
+) {
+  return getProtocolV2WalletSession(device, {
+    expectedPassphraseState,
+    resumeOnly: true,
+  });
+}

package/src/topLevelInject.ts

@@ -1,6 +1,7 @@
 import EventEmitter from 'events';
 
 import { createCoreApi } from './inject';
+import { unregisterFirmwareUpdateHostBinding } from './api/firmware/FirmwareHostBinding';
 
 import type { ConnectSettings } from './types/settings';
 import type { CoreApi } from './types/api';
@@ -46,7 +47,10 @@ export const topLevelInject = () => {
       lowLevelApi?.removeAllListeners(type);
     },
 
-    dispose: () => lowLevelApi?.dispose(),
+    dispose: async () => {
+      unregisterFirmwareUpdateHostBinding();
+      await lowLevelApi?.dispose();
+    },
 
     uiResponse: response => lowLevelApi?.uiResponse(response),
 

package/src/types/api/checkAllFirmwareRelease.ts

@@ -1,8 +1,8 @@
 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';
+import type { FirmwareUpdatePlan, FirmwareUpdatePlanForceTarget } from './firmwareUpdatePlan';
 
 export type FirmwareRelease = {
   shouldUpdate?: boolean;
@@ -21,11 +21,14 @@ export type AllFirmwareRelease = {
   bootloader?: FirmwareRelease;
   bridge?: FirmwareRelease;
   features?: Features;
+  firmwareUpdatePlan?: FirmwareUpdatePlan;
 };
 
 export type CheckAllFirmwareReleaseParams = {
   checkBridgeRelease?: boolean;
   firmwareType?: EFirmwareType;
+  platform?: 'native' | 'desktop' | 'ext' | 'web' | 'web-embed';
+  forceUpdateTargets?: FirmwareUpdatePlanForceTarget[];
 };
 
 export declare function checkAllFirmwareRelease(