@onekeyfe/hd-core 1.2.0-alpha.16 → 1.2.0-alpha.17

package/src/api/GetPassphraseState.ts

@@ -19,10 +19,13 @@ export default class GetPassphraseState extends BaseMethod {
 
     const passphraseProtection = this.device.getCurrentPassphraseProtection();
     const deviceType = this.device.getCurrentDeviceType();
-    const isProSeries = deviceType === EDeviceType.Pro || deviceType === EDeviceType.Pro2;
+
+    if (deviceType === EDeviceType.Pro2) {
+      return Promise.resolve(passphraseProtection === true ? passphraseState : undefined);
+    }
 
     return Promise.resolve(
-      isProSeries || passphraseProtection === true ? passphraseState : undefined
+      deviceType === EDeviceType.Pro || passphraseProtection === true ? passphraseState : undefined
     );
   }
 }

package/src/api/UploadPortfolio.ts

@@ -25,6 +25,8 @@ export default class UploadPortfolio extends FileWrite {
     };
     super.init();
     this.unlockPolicy = 'retry-on-locked';
+    // Portfolio 是后台数据写入与应用流程，设备不需要用户确认；包括自动解锁阶段在内均不合成 UI Event。
+    this.protocolV2UiMode = 'none';
   }
 
   async run() {

package/src/api/device/DeviceCancel.ts

@@ -5,6 +5,7 @@ import type { Cancel } from '@onekeyfe/hd-transport';
 export default class DeviceCancel extends BaseMethod<Cancel> {
   init() {
     this.useDevicePassphraseState = false;
+    this.unlockPolicy = 'none';
   }
 
   async run() {

package/src/api/device/DeviceChangePin.ts

@@ -1,5 +1,8 @@
+import { DeviceSettingsPage } from '@onekeyfe/hd-transport';
+
 import { BaseMethod } from '../BaseMethod';
 import { validateParams } from '../helpers/paramsValidator';
+import { invalidParameter } from '../helpers/filesystemValidation';
 
 import type { ChangePin } from '@onekeyfe/hd-transport';
 
@@ -13,9 +16,29 @@ export default class DeviceChangePin extends BaseMethod<ChangePin> {
     this.params = {
       remove: this.payload.remove,
     };
+    this.protocolV2UiInteraction = {
+      request: 'button',
+      source: 'method-lifecycle',
+      reason: 'change-pin',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      page: DeviceSettingsPage.DevicePinChange,
+    };
   }
 
   async run() {
+    if (this.device.isProtocolV2()) {
+      if (this.params.remove) {
+        throw invalidParameter(
+          'Parameter [remove=true] is not supported by the Pro2 device PIN page.'
+        );
+      }
+      const res = await this.device.commands.typedCall('DeviceSettingsPageShow', 'Success', {
+        page: DeviceSettingsPage.DevicePinChange,
+      });
+      return Promise.resolve(res.message);
+    }
+
     const res = await this.device.commands.typedCall('ChangePin', 'Success', {
       ...this.params,
     });

package/src/api/device/DeviceLock.ts

@@ -5,6 +5,7 @@ import type { LockDevice } from '@onekeyfe/hd-transport';
 export default class DeviceLock extends BaseMethod<LockDevice> {
   init() {
     this.useDevicePassphraseState = false;
+    this.unlockPolicy = 'none';
   }
 
   async run() {

package/src/api/device/DeviceUnlock.ts

@@ -5,6 +5,15 @@ import type { LockDevice } from '@onekeyfe/hd-transport';
 export default class DeviceUnlock extends BaseMethod<LockDevice> {
   init() {
     this.useDevicePassphraseState = false;
+    this.unlockPolicy = 'none';
+    this.protocolV2UiInteraction = {
+      request: 'pin',
+      source: 'method-lifecycle',
+      reason: 'device-unlock',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      operation: 'unlock-device',
+    };
   }
 
   async run() {

package/src/api/device/DeviceWipe.ts

@@ -1,3 +1,5 @@
+import { DeviceSettingsPage } from '@onekeyfe/hd-transport';
+
 import { BaseMethod } from '../BaseMethod';
 
 import type { WipeDevice } from '@onekeyfe/hd-transport';
@@ -5,9 +7,25 @@ import type { WipeDevice } from '@onekeyfe/hd-transport';
 export default class DeviceWipe extends BaseMethod<WipeDevice> {
   init() {
     this.useDevicePassphraseState = false;
+    this.protocolV2UiInteraction = {
+      request: 'button',
+      source: 'method-lifecycle',
+      reason: 'device-management',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      page: DeviceSettingsPage.DeviceReset,
+      operation: 'wipe-device',
+    };
   }
 
   async run() {
+    if (this.device.isProtocolV2()) {
+      const res = await this.device.commands.typedCall('DeviceSettingsPageShow', 'Success', {
+        page: DeviceSettingsPage.DeviceReset,
+      });
+      return Promise.resolve(res.message);
+    }
+
     const res = await this.device.commands.typedCall('WipeDevice', 'Success');
 
     return Promise.resolve(res.message);

package/src/api/helpers/protocolV2FileWrite.ts

@@ -30,12 +30,23 @@ export type ProtocolV2FileWriteOptions = {
   append?: boolean;
   uiPercentage?: number;
   timeoutMs?: number;
+  maxChunkRetries?: number;
   throwIfAborted?: () => void;
   onProgress?: (progress: ProtocolV2FileWriteProgress) => void;
 };
 
 const MIN_FILE_CHUNK_SIZE = 64;
 
+function isRetryableFileWriteTimeout(error: unknown) {
+  if (!error || typeof error !== 'object') return false;
+  const candidate = error as { errorCode?: number; code?: number; message?: string };
+  const code = candidate.errorCode ?? candidate.code;
+  return (
+    code === HardwareErrorCode.BleTimeoutError ||
+    /Lowlevel response timeout/i.test(candidate.message ?? '')
+  );
+}
+
 function getProtocolV2FileChunkLimit() {
   const env = DataManager.getSettings('env');
   return env && DataManager.isBleConnect(env)
@@ -116,17 +127,30 @@ export async function writeProtocolV2File(options: ProtocolV2FileWriteOptions) {
     const progress =
       options.uiPercentage ??
       getDeviceTransferProgress(offset, offset + chunk.byteLength, totalSize);
-    const response = await options.commands.typedCall(
-      'FilesystemFileWrite',
-      'FilesystemFile',
-      {
-        file: { path: options.path, offset, total_size: totalSize, data: chunk },
-        overwrite: chunks === 0 ? options.overwrite ?? false : false,
-        append: options.append ?? false,
-        ui_percentage: progress,
-      },
-      { timeoutMs: options.timeoutMs }
-    );
+    const request = {
+      file: { path: options.path, offset, total_size: totalSize, data: chunk },
+      overwrite: chunks === 0 ? options.overwrite ?? false : false,
+      append: options.append ?? false,
+      ui_percentage: progress,
+    };
+    const maxChunkRetries = Math.max(Math.floor(options.maxChunkRetries ?? 0), 0);
+    let retryCount = 0;
+    let response;
+    while (true) {
+      try {
+        response = await options.commands.typedCall(
+          'FilesystemFileWrite',
+          'FilesystemFile',
+          request,
+          { timeoutMs: options.timeoutMs }
+        );
+        break;
+      } catch (error) {
+        if (retryCount >= maxChunkRetries || !isRetryableFileWriteTimeout(error)) throw error;
+        retryCount += 1;
+        options.throwIfAborted?.();
+      }
+    }
     options.throwIfAborted?.();
     lastMessage = response.message;
     const rawProcessedByte = response.message?.processed_byte;

package/src/api/index.ts

@@ -50,7 +50,7 @@ export { default as deviceReboot } from './protocol-v2/DeviceReboot';
 export { default as deviceInfoGet } from './protocol-v2/DeviceInfoGet';
 export { default as deviceStatusGet } from './protocol-v2/DeviceStatusGet';
 export { default as deviceGetOnboardingStatus } from './protocol-v2/DeviceGetOnboardingStatus';
-export { default as deviceSessionGet } from './protocol-v2/DeviceSessionGet';
+export { default as deviceSessionOpen } from './protocol-v2/DeviceSessionOpen';
 export { default as deviceFirmwareUpdate } from './protocol-v2/DeviceFirmwareUpdate';
 export { default as deviceGetFirmwareUpdateStatus } from './protocol-v2/DeviceGetFirmwareUpdateStatus';
 export { default as deviceFactoryInfoSet } from './protocol-v2/DeviceFactoryInfoSet';

package/src/api/protocol-v2/DeviceInfoGet.ts

@@ -45,7 +45,6 @@ const DEFAULT_TARGETS: DeviceInfoGetTargets = {
   hw: true,
   fw: true,
   coprocessor: true,
-  status: true,
 };
 
 const DEFAULT_TYPES: DeviceInfoGetTypes = {

package/src/api/protocol-v2/DeviceSessionOpen.ts

@@ -0,0 +1,100 @@
+import { BaseMethod } from '../BaseMethod';
+import { invalidParameter } from '../helpers/filesystemValidation';
+
+import type {
+  DeviceAttachPinOnDevice,
+  DeviceHostPassphrase,
+  DevicePassphraseOnDevice,
+  DeviceSessionResume,
+} from '@onekeyfe/hd-transport';
+
+type HiddenWalletSelection =
+  | {
+      host_passphrase: DeviceHostPassphrase;
+      passphrase_on_device?: never;
+      attach_pin_on_device?: never;
+    }
+  | {
+      host_passphrase?: never;
+      passphrase_on_device: DevicePassphraseOnDevice;
+      attach_pin_on_device?: never;
+    }
+  | {
+      host_passphrase?: never;
+      passphrase_on_device?: never;
+      attach_pin_on_device: DeviceAttachPinOnDevice;
+    };
+
+export type DeviceSessionOpenParams =
+  | { resume: DeviceSessionResume; select?: never }
+  | { resume?: never; select: HiddenWalletSelection };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
+const normalizeParams = (payload: Record<string, unknown>): DeviceSessionOpenParams => {
+  const hasResume = payload.resume !== undefined;
+  const hasSelect = payload.select !== undefined;
+  if (hasResume === hasSelect) {
+    throw invalidParameter('DeviceSessionOpen requires exactly one of [resume] or [select].');
+  }
+
+  if (hasResume) {
+    if (!isRecord(payload.resume) || typeof payload.resume.session_id !== 'string') {
+      throw invalidParameter('Parameter [resume.session_id] must be a non-empty string.');
+    }
+    const sessionId = payload.resume.session_id.trim();
+    if (!sessionId) {
+      throw invalidParameter('Parameter [resume.session_id] must be a non-empty string.');
+    }
+    return { resume: { session_id: sessionId } };
+  }
+
+  if (!isRecord(payload.select)) {
+    throw invalidParameter('Parameter [select] must be a hidden-wallet selection object.');
+  }
+  const { select } = payload;
+  const accessKeys = ['host_passphrase', 'passphrase_on_device', 'attach_pin_on_device'] as const;
+  const selected = accessKeys.filter(key => select[key] !== undefined);
+  const unknown = Object.keys(select).filter(
+    key => !accessKeys.includes(key as (typeof accessKeys)[number])
+  );
+  if (unknown.length > 0 || selected.length !== 1) {
+    throw invalidParameter('Parameter [select] requires exactly one hidden-wallet access mode.');
+  }
+
+  if (selected[0] === 'host_passphrase') {
+    const host = select.host_passphrase;
+    if (!isRecord(host) || typeof host.passphrase !== 'string') {
+      throw invalidParameter('Parameter [select.host_passphrase.passphrase] is required.');
+    }
+    const passphrase = host.passphrase.normalize('NFKD');
+    if (!passphrase || passphrase.includes('\0') || passphrase.length > 50) {
+      throw invalidParameter('Parameter [select.host_passphrase.passphrase] is invalid.');
+    }
+    return { select: { host_passphrase: { passphrase } } };
+  }
+
+  if (selected[0] === 'passphrase_on_device') {
+    return { select: { passphrase_on_device: {} } };
+  }
+  return { select: { attach_pin_on_device: {} } };
+};
+
+export default class DeviceSessionOpen extends BaseMethod<DeviceSessionOpenParams> {
+  init() {
+    this.requireProtocolV2 = true;
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+    this.params = normalizeParams(this.payload as unknown as Record<string, unknown>);
+  }
+
+  async run() {
+    const { message } = await this.device.commands.typedCall(
+      'DeviceSessionOpen',
+      'DeviceSession',
+      this.params
+    );
+    return message;
+  }
+}

package/src/api/protocol-v2/DeviceSettingsPageShow.ts

@@ -26,7 +26,7 @@ const SUPPORTED_PAGES = new Set<number>([
 function normalizePage(value: DeviceSettingsPageShowParams['page']): SupportedDeviceSettingsPage {
   const page = typeof value === 'string' ? DeviceSettingsPage[value] : value;
   if (page !== undefined && SUPPORTED_PAGES.has(page)) {
-    return page as SupportedDeviceSettingsPage;
+    return page;
   }
   throw invalidParameter(
     'Parameter [page] must be DeviceReset, DevicePinChange, DevicePassphrase, or DeviceAirgap.'
@@ -46,6 +46,14 @@ export default class DeviceSettingsPageShow extends BaseMethod<{
       page: normalizePage(this.payload.page),
       field_name: this.payload.field_name ?? this.payload.fieldName,
     };
+    this.protocolV2UiInteraction = {
+      request: 'button',
+      source: 'method-lifecycle',
+      reason: 'settings-page',
+      completion: 'operation-completed',
+      deviceOnly: true,
+      page: this.params.page,
+    };
   }
 
   async run() {

package/src/api/protocol-v2/DeviceSettingsSet.ts

@@ -11,7 +11,7 @@ export default class DeviceSettingsSet extends BaseMethod<{
   settings: Omit<DeviceSettings, 'passphrase_enable' | 'airgap_mode'>;
 }> {
   init() {
-    const settings = this.payload.settings;
+    const { settings } = this.payload;
     if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
       throw invalidParameter('Parameter [settings] must be an object.');
     }
@@ -30,6 +30,16 @@ export default class DeviceSettingsSet extends BaseMethod<{
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
     this.params = { settings: supported };
+    if (typeof supported.label === 'string') {
+      this.protocolV2UiInteraction = {
+        request: 'button',
+        source: 'method-lifecycle',
+        reason: 'device-management',
+        completion: 'operation-completed',
+        deviceOnly: true,
+        operation: 'change-label',
+      };
+    }
   }
 
   async run() {

package/src/api/protocol-v2/DeviceStatusGet.ts

@@ -9,6 +9,7 @@ export default class DeviceStatusGet extends BaseMethod {
 
   async run() {
     const { message } = await this.device.commands.typedCall('DeviceStatusGet', 'DeviceStatus', {});
+    this.device.updateProtocolV2Status(message);
     return message;
   }
 }

package/src/api/protocol-v2/DeviceUploadWallpaper.ts

@@ -27,7 +27,7 @@ export type DeviceUploadWallpaperResponse = {
   message?: string;
 };
 
-const WALLPAPER_DIRECTORY = 'vol0:/wallpapers/user';
+const WALLPAPER_DIRECTORY = 'vol1:/wallpapers';
 const SAFE_FILE_NAME = /^[A-Za-z0-9_-]+(?:\.bin)?$/;
 
 function normalizeFileName(fileName: string | undefined, data: Uint8Array): string {
@@ -100,6 +100,7 @@ export default class DeviceUploadWallpaper extends BaseMethod<DeviceUploadWallpa
       data: encoded.data,
       totalSize: encoded.data.byteLength,
       chunkSize: this.params.chunkSize,
+      maxChunkRetries: 3,
       overwrite: true,
       append: false,
       throwIfAborted: () => this.throwIfAborted(),

package/src/core/deviceEventRegistration.ts

@@ -7,6 +7,7 @@ export type HardwareUiEventHandlers = {
   button: (...event: DeviceEvents[typeof DEVICE.BUTTON]) => void;
   passphrase: (...event: DeviceEvents[typeof DEVICE.PASSPHRASE]) => void;
   passphraseOnDevice: (...event: DeviceEvents[typeof DEVICE.PASSPHRASE_ON_DEVICE]) => void;
+  attachPinOnDevice: (...event: DeviceEvents[typeof DEVICE.ATTACH_PIN_ON_DEVICE]) => void;
 };
 
 export function registerHardwareUiEventListeners(
@@ -17,5 +18,6 @@ export function registerHardwareUiEventListeners(
   device.on(DEVICE.BUTTON, handlers.button);
   device.on(DEVICE.PASSPHRASE, handlers.passphrase);
   device.on(DEVICE.PASSPHRASE_ON_DEVICE, handlers.passphraseOnDevice);
+  device.on(DEVICE.ATTACH_PIN_ON_DEVICE, handlers.attachPinOnDevice);
   return true;
 }

package/src/core/index.ts

@@ -58,6 +58,10 @@ import RequestQueue from './RequestQueue';
 import { registerHardwareUiEventListeners } from './deviceEventRegistration';
 import { getSynchronize } from '../utils/getSynchronize';
 import { runMethodWithUnlockRetry } from '../protocols/protocol-v2/unlockRetry';
+import {
+  ProtocolV2UiInteractionCoordinator,
+  isProtocolV2UiEnabled,
+} from '../protocols/protocol-v2/uiInteraction';
 
 import type { ConnectSettings, Features, KnownDevice } from '../types';
 import type { CoreMessage, IFrameCallMessage, UiPromise, UiPromiseResponse } from '../events';
@@ -403,12 +407,15 @@ const onCallDevice = async (
       ? onEmptyPassphraseHandler
       : onDevicePassphraseHandler,
     passphraseOnDevice: onEnterPassphraseOnDeviceHandler,
+    attachPinOnDevice: onEnterAttachPinOnDeviceHandler,
   });
   device.on(DEVICE.FEATURES, onDeviceFeaturesHandler);
   device.on(
     DEVICE.SELECT_DEVICE_IN_BOOTLOADER_FOR_WEB_DEVICE,
     onSelectDeviceInBootloaderForWebDeviceHandler
   );
+
+  const protocolV2UiCoordinator = new ProtocolV2UiInteractionCoordinator(device, postMessage);
   device.on(
     DEVICE.SELECT_DEVICE_FOR_SWITCH_FIRMWARE_WEB_DEVICE,
     onSelectDeviceForSwitchFirmwareWebDeviceHandler
@@ -619,7 +626,11 @@ const onCallDevice = async (
       method.device?.commands?.checkDisposed();
 
       try {
-        const response: object = await runMethodWithUnlockRetry(method, device);
+        const response: object = await runMethodWithUnlockRetry(
+          method,
+          device,
+          protocolV2UiCoordinator
+        );
         messageResponse = createResponseMessage(method.responseID, true, response);
         requestQueue.resolveRequest(method.responseID, messageResponse);
         completeMethodRequestContext(method);
@@ -636,6 +647,8 @@ const onCallDevice = async (
         ) {
           throw error;
         }
+      } finally {
+        protocolV2UiCoordinator.close();
       }
     };
     Log.debug('Call API - Device Run: ', device.mainId);
@@ -689,7 +702,9 @@ const onCallDevice = async (
 
     requestQueue.releaseTask(method.responseID);
 
-    closePopup();
+    if (isProtocolV2UiEnabled(method)) {
+      closePopup();
+    }
 
     cleanup();
 
@@ -1235,6 +1250,9 @@ const onDevicePassphraseHandler = async (
       device: device.toMessageObject() as KnownDevice,
       passphraseState: device.passphraseState,
       existsAttachPinUser: requestPayload.existsAttachPinUser,
+      source: requestPayload.source,
+      reason: requestPayload.reason,
+      expectedPassphraseState: requestPayload.expectedPassphraseState,
     })
   );
   // wait for passphrase
@@ -1256,12 +1274,27 @@ const onEmptyPassphraseHandler = (...[_, , callback]: DeviceEvents['passphrase']
 };
 
 const onEnterPassphraseOnDeviceHandler = (
-  ...[device]: [...DeviceEvents['passphrase_on_device']]
+  ...[device, requestPayload]: [...DeviceEvents['passphrase_on_device']]
 ) => {
   postMessage(
     createUiMessage(UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE, {
       device: device.toMessageObject() as KnownDevice,
       passphraseState: device.passphraseState,
+      source: requestPayload?.source,
+      reason: requestPayload?.reason,
+    })
+  );
+};
+
+const onEnterAttachPinOnDeviceHandler = (
+  ...[device, requestPayload]: [...DeviceEvents['attach_pin_on_device']]
+) => {
+  postMessage(
+    createUiMessage(UI_REQUEST.REQUEST_PIN, {
+      device: device.toMessageObject() as KnownDevice,
+      type: 'ButtonRequest_AttachPin',
+      source: requestPayload?.source,
+      reason: requestPayload?.reason,
     })
   );
 };