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

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,202 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import { DEVICE, type PassphraseRequestPayload } from '../../events';
+import { assertCompleteDeviceSession } from './deviceSession';
+import { isDeviceLockedError } from './lockedError';
+
+import type { DeviceSessionOpen } from '@onekeyfe/hd-transport';
+import type { Device } from '../../device/Device';
+import type { PassphrasePromptResponse } from '../../device/DeviceCommands';
+
+export const isProtocolV2InvalidSessionError = (error: unknown) =>
+  error !== null &&
+  typeof error === 'object' &&
+  'errorCode' in error &&
+  error.errorCode === HardwareErrorCode.WalletSessionInvalid;
+
+const normalizeHostPassphrase = (passphrase: string | undefined) => {
+  const normalized = (passphrase ?? '').normalize('NFKD');
+  if (!normalized || normalized.includes('\0') || normalized.length > 50) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.CallMethodInvalidParameter,
+      'Invalid hidden wallet passphrase.'
+    );
+  }
+  return normalized;
+};
+
+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 openDeviceSession = async (device: Device, request: DeviceSessionOpen) => {
+  try {
+    return await device.commands.typedCall('DeviceSessionOpen', 'DeviceSession', request);
+  } catch (error) {
+    if (!isDeviceLockedError(error)) {
+      throw error;
+    }
+    await device.unlockDevice();
+    return device.commands.typedCall('DeviceSessionOpen', 'DeviceSession', request);
+  }
+};
+
+const createHiddenWalletRequest = (
+  response: PassphrasePromptResponse
+): {
+  request: DeviceSessionOpen;
+  deviceEvent?: typeof DEVICE.PASSPHRASE_ON_DEVICE | typeof DEVICE.ATTACH_PIN_ON_DEVICE;
+} => {
+  if (response.attachPinOnDevice) {
+    return {
+      request: {
+        select: {
+          attach_pin_on_device: {},
+        },
+      },
+      deviceEvent: DEVICE.ATTACH_PIN_ON_DEVICE,
+    };
+  }
+
+  if (response.passphraseOnDevice) {
+    return {
+      request: {
+        select: {
+          passphrase_on_device: {},
+        },
+      },
+      deviceEvent: DEVICE.PASSPHRASE_ON_DEVICE,
+    };
+  }
+
+  return {
+    request: {
+      select: {
+        host_passphrase: { passphrase: normalizeHostPassphrase(response.passphrase) },
+      },
+    },
+  };
+};
+
+const openSelectedHiddenWallet = async (
+  device: Device,
+  promptPayload: PassphraseRequestPayload
+) => {
+  const response = await device.commands.promptPassphrase(promptPayload, {
+    cancelDeviceOnReject: false,
+  });
+  const { request, deviceEvent } = createHiddenWalletRequest(response);
+
+  if (deviceEvent) {
+    device.emit(deviceEvent, device, promptPayload);
+  }
+
+  return openDeviceSession(device, request);
+};
+
+export async function getProtocolV2WalletSession(
+  device: Device,
+  options?: {
+    initSession?: boolean;
+    expectedPassphraseState?: string;
+    onlyMainPin?: boolean;
+    recoverInvalidSession?: boolean;
+  }
+) {
+  if (options?.initSession) {
+    device.clearInternalState();
+  }
+
+  const expectedPassphraseState = options?.expectedPassphraseState ?? device.passphraseState;
+
+  try {
+    // Unlock with PIN first. The unlock flow refreshes DeviceStatus so wallet
+    // selection uses confirmed passphrase and attach-to-PIN state.
+    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 recoveryFailed = false;
+    let resumed = false;
+
+    if (cachedSessionId && expectedPassphraseState) {
+      try {
+        response = await openDeviceSession(device, {
+          resume: { session_id: cachedSessionId },
+        });
+        resumed = true;
+      } catch (error) {
+        if (!isProtocolV2InvalidSessionError(error)) {
+          throw error;
+        }
+        device.clearInternalState();
+        if (options?.recoverInvalidSession === false) {
+          throw error;
+        }
+        recoveryFailed = true;
+      }
+    }
+
+    if (!response) {
+      const promptPayload: PassphraseRequestPayload = {
+        source: 'wallet-session-coordinator',
+        reason: recoveryFailed ? 'session-recovery' : 'open-wallet',
+        expectedPassphraseState,
+        existsAttachPinUser: device.features?.attachToPinEnabled === true,
+      };
+      response = await openSelectedHiddenWallet(device, promptPayload);
+    }
+
+    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,
+    };
+  } catch (error) {
+    if (isProtocolV2InvalidSessionError(error)) {
+      device.clearInternalState();
+    }
+    throw error;
+  }
+}

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,12 +47,17 @@ export const topLevelInject = () => {
       lowLevelApi?.removeAllListeners(type);
     },
 
-    dispose: () => lowLevelApi?.dispose(),
+    dispose: async () => {
+      unregisterFirmwareUpdateHostBinding();
+      await lowLevelApi?.dispose();
+    },
 
     uiResponse: response => lowLevelApi?.uiResponse(response),
 
     cancel: (connectId?: string) => lowLevelApi?.cancel(connectId),
 
+    cancelOperation: (operationId: string) => lowLevelApi?.cancelOperation(operationId),
+
     updateSettings: settings => lowLevelApi?.updateSettings(settings) ?? Promise.resolve(false),
 
     switchTransport: (env: ConnectSettings['env']) =>

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 } from './firmwareUpdatePlan';
 
 export type FirmwareRelease = {
   shouldUpdate?: boolean;
@@ -21,11 +21,13 @@ 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';
 };
 
 export declare function checkAllFirmwareRelease(

package/src/types/api/deviceSettings.ts

@@ -14,7 +14,16 @@ export type DeviceSettingsParams = {
   experimentalFeatures?: boolean;
   autoShutdownDelayMs?: number;
   changeBrightness?: boolean;
+  brightness?: number;
   hapticFeedback?: boolean;
+  bluetoothEnabled?: boolean;
+  airgapMode?: boolean;
+  animationEnabled?: boolean;
+  tapToWake?: boolean;
+  deviceNameDisplayEnabled?: boolean;
+  fidoEnabled?: boolean;
+  usbLockEnabled?: boolean;
+  randomKeypad?: boolean;
 };
 
 export declare function deviceSettings(

package/src/types/api/deviceUnlock.ts

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

package/src/types/api/deviceUpdateBootloader.ts

@@ -1,9 +1,18 @@
 import type { Success } from '@onekeyfe/hd-transport';
 import type { EFirmwareType } from '@onekeyfe/hd-shared';
+import type {
+  FirmwareArtifactReader,
+  FirmwareArtifactReference,
+  FirmwareCheckpointParams,
+} from './firmwareUpdate';
+import type { FirmwareUpdatePreparedPlan } from './firmwareUpdatePreparedPlan';
 import type { Response } from '../params';
 
-export type DeviceUpdateBootloaderParams = {
+export type DeviceUpdateBootloaderParams = FirmwareCheckpointParams & {
+  preparedPlan?: FirmwareUpdatePreparedPlan;
   binary?: ArrayBuffer;
+  artifact?: FirmwareArtifactReference;
+  artifactReader?: FirmwareArtifactReader;
   firmwareType?: EFirmwareType;
 };
 

package/src/types/api/export.ts

@@ -25,10 +25,35 @@ export type {
   DeviceUploadResourceResponse,
 } from './deviceUploadResource';
 export type {
+  FirmwareArtifactReader,
+  FirmwareArtifactReference,
+  FirmwareCheckpoint,
+  FirmwareCheckpointParams,
+  FirmwareCheckpointSink,
+  FirmwareCheckpointStage,
+  FirmwareUpdateHostBinding,
+  FirmwareUpdateArtifactParams,
   FirmwareUpdateParams,
   FirmwareUpdateBinaryParams,
   FirmwareUpdateV3Params,
+  FirmwareUpdateV4Params,
+  FirmwareUpdateV4Target,
 } from './firmwareUpdate';
+export type {
+  FirmwareUpdatePlan,
+  FirmwareUpdatePlanArtifact,
+  FirmwareUpdatePlanArtifactRole,
+  FirmwareUpdatePlanEpoch,
+  FirmwareUpdatePlanEpochKind,
+  FirmwareUpdatePlanTarget,
+} from './firmwareUpdatePlan';
+export type {
+  FirmwareUpdatePreparedArtifact,
+  FirmwareUpdatePreparedArtifactInput,
+  FirmwareUpdatePreparedEntry,
+  FirmwareUpdatePreparedPlan,
+} from './firmwareUpdatePreparedPlan';
+export type { FirmwareUpdateCapabilities } from './firmwareUpdateCapabilities';
 export type { AllFirmwareRelease } from './checkAllFirmwareRelease';
 
 export type { AllNetworkAddressParams, AllNetworkGetAddressParams } from './allNetworkGetAddress';