@onekeyfe/hd-core 1.2.0-alpha.18 → 1.2.0-alpha.181

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

@@ -4,12 +4,12 @@ import type {
   DeviceInfoGet,
   DeviceSEInfo,
   DeviceStatus,
+  ProtocolInfo,
   ProtocolV2DeviceInfo,
 } from '@onekeyfe/hd-transport';
 import type { DeviceCommands } from '../../device/DeviceCommands';
 
-// 单源类型：直接使用 hd-transport 生成的 ProtocolV2DeviceInfo / DeviceSEInfo /
-// DeviceFirmwareImageInfo（与 firmware-pro2 proto 一致），不再维护手写副本。
+// 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';
@@ -17,8 +17,8 @@ export type { DeviceSEInfo as ProtocolV2SEInfo } from '@onekeyfe/hd-transport';
 export type ProtocolV2SeStateLabel = 'BOOT' | 'APP_FACTORY' | 'APP';
 
 /**
- * 传输层沿用历史 decode 语义：单值 proto enum 输出为名称字符串。
- * 这里按 SDK decode 后的字符串语义处理，同时接受数字枚举，便于低层调用复用。
+ * 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,
@@ -31,8 +31,8 @@ const normalizeEnumValue = <T extends Record<string | number, string | number>>(
 };
 
 /**
- * DeviceSEInfo.state → 可读标签。SDK 内唯一的 SE 状态映射实现，
- * DeviceProfile 与标准 Features 构建都从这里取。
+ * 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);
@@ -49,45 +49,80 @@ export const getProtocolV2SeState = (se?: DeviceSEInfo): ProtocolV2SeStateLabel
 };
 
 /**
- * DeviceSEInfo.type → 可读标签（如 'THD89'）。DeviceProfile / Features
- * 的 SE 类型归一化从这里取。
+ * 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' | 'romloader';
+
+export type ProtocolV2ProtocolInfo = ProtocolInfo & {
+  /** Present only when hd-transport decoded the pre-build-fingerprint wire layout. */
+  protobuf_definition?: string | null;
+};
+
+export const isLegacyProtocolV2ProtocolInfo = (
+  protocolInfo: ProtocolInfo
+): protocolInfo is ProtocolV2ProtocolInfo & { protobuf_definition: string | null } =>
+  Object.prototype.hasOwnProperty.call(protocolInfo, 'protobuf_definition');
+
 /**
- * 兼容尚未提供显式 runtime mode 的 Protocol V2 固件。
- *
- * 当前 romloader 只上报 hw、fw.romloader 和 fw.bootloader；bootloader
- * 还会上报 application/application_data、coprocessor 或 SE 信息。
+ * Protocol V2 fingerprints use:
+ * <binary>__<version>__<commit>__<PROD|DEV>__<DEBUG|RELEASE>
  */
-export const isProtocolV2RomloaderDeviceInfo = (
-  deviceInfo?: ProtocolV2DeviceInfo | null,
-  deviceStatus?: DeviceStatus | null
-) =>
-  !!deviceInfo &&
-  deviceStatus == null &&
-  deviceInfo.fw?.romloader != null &&
-  deviceInfo.fw?.application == null &&
-  deviceInfo.fw?.application_data == null &&
-  deviceInfo.coprocessor == null &&
-  deviceInfo.se1 == null &&
-  deviceInfo.se2 == null &&
-  deviceInfo.se3 == null &&
-  deviceInfo.se4 == null;
-
-export const isProtocolV2BootloaderDeviceInfo = (
-  deviceInfo?: ProtocolV2DeviceInfo | null,
-  deviceStatus?: DeviceStatus | null
-) =>
-  !!deviceInfo &&
-  deviceStatus == null &&
-  !isProtocolV2RomloaderDeviceInfo(deviceInfo, deviceStatus);
+export type ProtocolV2BuildFingerprint = {
+  binary: 'application' | 'bootloader' | 'romloader';
+  version: string;
+  commit: string;
+  environment: 'PROD' | 'DEV';
+  buildType: 'DEBUG' | 'RELEASE';
+};
+
+export const parseProtocolV2BuildFingerprint = (
+  buildFingerprint: string | null | undefined
+): ProtocolV2BuildFingerprint | null => {
+  if (!buildFingerprint) return null;
+  const [binary, version, commit, environment, buildType, ...extra] = buildFingerprint.split('__');
+  if (
+    extra.length > 0 ||
+    (binary !== 'application' && binary !== 'bootloader' && binary !== 'romloader') ||
+    !version ||
+    !commit ||
+    (environment !== 'PROD' && environment !== 'DEV') ||
+    (buildType !== 'DEBUG' && buildType !== 'RELEASE')
+  ) {
+    return null;
+  }
+  return { binary, version, commit, environment, buildType };
+};
+
+export const getProtocolV2RuntimeMode = (
+  protocolInfo: ProtocolInfo,
+  deviceInfo?: ProtocolV2DeviceInfo
+): ProtocolV2RuntimeMode | undefined => {
+  const binary = parseProtocolV2BuildFingerprint(protocolInfo.build_fingerprint)?.binary;
+  if (binary === 'application') return 'normal';
+  if (binary) return binary;
+
+  if (isLegacyProtocolV2ProtocolInfo(protocolInfo) && !deviceInfo?.main_mcu?.application) {
+    if (deviceInfo?.main_mcu?.romloader) return 'romloader';
+    if (deviceInfo?.main_mcu?.bootloader) return 'bootloader';
+  }
+  return undefined;
+};
+
+// MessageType_DeviceStatusGet in the Protocol V2 protobuf registry.
+export const PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE = 60602;
+
+export const supportsProtocolV2Message = (
+  protocolInfo: ProtocolInfo,
+  messageType: number
+): boolean => protocolInfo.supported_messages.includes(messageType);
 
 export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
-    fw: true,
+    main_mcu: true,
     coprocessor: true,
   },
   types: {
@@ -97,15 +132,13 @@ export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
 };
 
 /**
- * 轻量状态刷新请求（每次 run 前使用）。
- *
- * status 提供 init_states / passphrase_enabled 等会在设备端变化的字段；
- * hw / coprocessor 提供 serialNo / bleName 等身份字段；不含 fw/SE targets，单帧请求开销很小。
+ * 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,
+    main_mcu: true,
     coprocessor: true,
     se1: true,
     se2: true,
@@ -121,7 +154,7 @@ export const PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST = {
 export const PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
-    fw: true,
+    main_mcu: true,
     coprocessor: true,
     se1: true,
     se2: true,
@@ -137,7 +170,28 @@ export const PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST = {
 };
 
 export const PROTOCOL_V2_DEVICE_INFO_REQUEST = PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST;
-export const PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS = 10 * 1000;
+export const PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS = 30 * 1000;
+
+export async function requestProtocolV2ProtocolInfo({
+  commands,
+  timeoutMs,
+}: {
+  commands: DeviceCommands;
+  timeoutMs?: number;
+}): Promise<ProtocolInfo> {
+  const response =
+    timeoutMs === undefined
+      ? await commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+          eventless_wallet_session: true,
+        })
+      : await commands.typedCall(
+          'ProtocolInfoRequest',
+          'ProtocolInfo',
+          { eventless_wallet_session: true },
+          { timeoutMs }
+        );
+  return response.message;
+}
 
 export async function requestProtocolV2DeviceInfo({
   commands,
@@ -151,16 +205,21 @@ export async function requestProtocolV2DeviceInfo({
   const { message } = await commands.typedCall('DeviceInfoGet', 'DeviceInfo', request, {
     timeoutMs,
   });
-  // 'DeviceInfo' 在生成类型里是 V1 DeviceInfo | ProtocolV2DeviceInfo 的合并；
-  // DeviceInfoGet 是 V2-only 消息，这里收窄到 V2 形态。
+  // 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 { message } = await commands.typedCall('DeviceStatusGet', '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

@@ -1,5 +1,5 @@
 /**
- * 当前 firmware-pro2 子模块的 DeviceFirmwareTargetType。
+ * DeviceFirmwareTargetType from the current firmware-pro2 submodule.
  */
 export const ProtocolV2FirmwareTargetType = {
   FW_MGMT_TARGET_INVALID: 0,
@@ -15,5 +15,7 @@ export const ProtocolV2FirmwareTargetType = {
   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

@@ -1,18 +1,25 @@
 export {
   PROTOCOL_V2_DEVICE_INFO_REQUEST,
   PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
+  PROTOCOL_V2_DEVICE_STATUS_GET_MESSAGE_TYPE,
   PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST,
   PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
-  isProtocolV2BootloaderDeviceInfo,
-  isProtocolV2RomloaderDeviceInfo,
+  getProtocolV2RuntimeMode,
   getProtocolV2SeState,
   getProtocolV2SeType,
+  isLegacyProtocolV2ProtocolInfo,
+  parseProtocolV2BuildFingerprint,
+  requestProtocolV2ProtocolInfo,
+  supportsProtocolV2Message,
 } from './features';
 export type {
+  ProtocolV2BuildFingerprint,
   ProtocolV2DeviceInfo,
   ProtocolV2FirmwareImageInfo,
   ProtocolV2SEInfo,
   ProtocolV2SeStateLabel,
+  ProtocolV2RuntimeMode,
+  ProtocolV2ProtocolInfo,
 } from './features';
 export * from './firmware';
 export * from './walletSession';

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

@@ -0,0 +1,173 @@
+import { bytesToHex } from '@noble/hashes/utils';
+
+import type { IProtocolV2Resources, IVersionArray } from '../../types';
+
+export const PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH =
+  'vol0:/loaders/bootloader/boot_resource.okpkg';
+export const PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_STAGING_PATH = `${PROTOCOL_V2_BOOT_RESOURCE_PACKAGE_PATH}.staging`;
+export const PROTOCOL_V2_ROM_PARAMS_PACKAGE_PATH = 'vol0:/loaders/rom/params.okpkg';
+export const PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_SIZE = 0x5f90;
+
+const PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_VERSION = 1;
+const PROTOCOL_V2_RESOURCE_PACKAGE_FLEXIBLE_OFFSET = 0x6c;
+const PROTOCOL_V2_RESOURCE_PACKAGE_FLEXIBLE_SIZE = 64;
+const PROTOCOL_V2_RESOURCE_PACKAGE_PAYLOAD_HASH_OFFSET = 0x200;
+const PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_HASH_OFFSET = 0x240;
+const PROTOCOL_V2_RESOURCE_PACKAGE_HASH_SIZE = 64;
+const PROTOCOL_V2_RESOURCE_PACKAGE_TYPE = 'RESC';
+
+/** Validate a complete Pro2 stable resource set from remote configuration. */
+export function parseProtocolV2Resources(value: unknown): IProtocolV2Resources | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object') {
+    throw new Error('Invalid Pro2 resources config');
+  }
+  const { source } = value as { source?: unknown };
+  if (!source || typeof source !== 'object') {
+    throw new Error('Invalid Pro2 resources config: source is required');
+  }
+  const { archiveUrl, archiveSha256, archiveSize } = source as {
+    archiveUrl?: unknown;
+    archiveSha256?: unknown;
+    archiveSize?: unknown;
+  };
+  if (typeof archiveUrl !== 'string' || !archiveUrl.startsWith('https://')) {
+    throw new Error('Invalid Pro2 resources config: source.archiveUrl must use HTTPS');
+  }
+  if (typeof archiveSha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(archiveSha256)) {
+    throw new Error('Invalid Pro2 resources config: source.archiveSha256 must be a SHA-256 digest');
+  }
+  if (!Number.isSafeInteger(archiveSize) || (archiveSize as number) <= 0) {
+    throw new Error('Invalid Pro2 resources config: source.archiveSize must be a positive integer');
+  }
+  return {
+    source: {
+      archiveUrl,
+      archiveSha256: archiveSha256.toLowerCase(),
+      archiveSize: archiveSize as number,
+    },
+  };
+}
+
+export function isProtocolV2ResourceArchiveEntryName(entryName: string): boolean {
+  const normalized = entryName.replace(/\\/g, '/');
+  if (!normalized.toLowerCase().endsWith('.okpkg')) {
+    return false;
+  }
+  const parts = normalized.split('/');
+  const fileName = parts[parts.length - 1] ?? '';
+  return (
+    fileName.length > 0 &&
+    !fileName.startsWith('.') &&
+    !parts.some(
+      part =>
+        !part ||
+        part === '.' ||
+        part === '..' ||
+        part === '.DS_Store' ||
+        part.startsWith('._') ||
+        part.toUpperCase() === '__MACOSX'
+    )
+  );
+}
+
+function isSafeResourceDevicePath(path: string): boolean {
+  return !(
+    path.includes('\\') ||
+    path.includes('//') ||
+    [...path].some(char => {
+      const code = char.charCodeAt(0);
+      return code <= 0x1f || code === 0x7f;
+    }) ||
+    path.split('/').some(part => part === '.' || part === '..')
+  );
+}
+
+function readAscii(bytes: Uint8Array, offset: number, length: number): string {
+  return Array.from(bytes.slice(offset, offset + length))
+    .map(byte => String.fromCharCode(byte))
+    .join('');
+}
+
+function readResourceDevicePath(bytes: Uint8Array): string {
+  const metadata = bytes.slice(
+    PROTOCOL_V2_RESOURCE_PACKAGE_FLEXIBLE_OFFSET,
+    PROTOCOL_V2_RESOURCE_PACKAGE_FLEXIBLE_OFFSET + PROTOCOL_V2_RESOURCE_PACKAGE_FLEXIBLE_SIZE
+  );
+  const terminator = metadata.indexOf(0);
+  const pathBytes = terminator === -1 ? metadata : metadata.slice(0, terminator);
+  const padding = terminator === -1 ? new Uint8Array(0) : metadata.slice(terminator);
+  if (
+    pathBytes.byteLength === 0 ||
+    Array.from(pathBytes).some(byte => byte < 0x20 || byte > 0x7e) ||
+    Array.from(padding).some(byte => byte !== 0)
+  ) {
+    throw new Error('Invalid Pro2 RESOURCE package device path metadata');
+  }
+  const path = readAscii(pathBytes, 0, pathBytes.byteLength);
+  if (!isSafeResourceDevicePath(path)) {
+    throw new Error(`Invalid Pro2 RESOURCE package device path: ${path}`);
+  }
+  return path;
+}
+
+export type ProtocolV2ResourcePackageHeader = {
+  version: IVersionArray;
+  payloadLength: number;
+  devicePath: string;
+  payloadHash: string;
+  headerHash: string;
+};
+
+export function parseProtocolV2ResourcePackageHeader(
+  bytes: Uint8Array,
+  packageSize: number
+): ProtocolV2ResourcePackageHeader {
+  if (bytes.byteLength < PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_SIZE) {
+    throw new Error('Pro2 RESOURCE package is shorter than its header');
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const headerVersion = view.getUint32(0x04, true);
+  const headerLength = view.getUint32(0x0c, true);
+  const payloadLength = view.getUint32(0x14, true);
+  if (
+    readAscii(bytes, 0, 4) !== 'OKPP' ||
+    readAscii(bytes, 0x08, 4) !== PROTOCOL_V2_RESOURCE_PACKAGE_TYPE ||
+    headerVersion !== PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_VERSION ||
+    headerLength !== PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_SIZE ||
+    payloadLength <= 0 ||
+    headerLength + payloadLength !== packageSize
+  ) {
+    throw new Error('Invalid Pro2 RESOURCE package header');
+  }
+
+  const packedVersion = view.getUint32(0x10, true);
+  return {
+    version: [
+      Math.floor(packedVersion / 0x10000) % 0x100,
+      Math.floor(packedVersion / 0x100) % 0x100,
+      packedVersion % 0x100,
+    ],
+    payloadLength,
+    devicePath: readResourceDevicePath(bytes),
+    payloadHash: bytesToHex(
+      bytes.slice(
+        PROTOCOL_V2_RESOURCE_PACKAGE_PAYLOAD_HASH_OFFSET,
+        PROTOCOL_V2_RESOURCE_PACKAGE_PAYLOAD_HASH_OFFSET + PROTOCOL_V2_RESOURCE_PACKAGE_HASH_SIZE
+      )
+    ),
+    headerHash: bytesToHex(
+      bytes.slice(
+        PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_HASH_OFFSET,
+        PROTOCOL_V2_RESOURCE_PACKAGE_HEADER_HASH_OFFSET + PROTOCOL_V2_RESOURCE_PACKAGE_HASH_SIZE
+      )
+    ),
+  };
+}
+
+export function parseProtocolV2ResourcePackage(
+  binary: ArrayBuffer | Uint8Array
+): ProtocolV2ResourcePackageHeader {
+  const bytes = binary instanceof Uint8Array ? binary : new Uint8Array(binary);
+  return parseProtocolV2ResourcePackageHeader(bytes, bytes.byteLength);
+}

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

@@ -0,0 +1,65 @@
+import type { DeviceSettings, DeviceSettingsPage } from '@onekeyfe/hd-transport';
+import type { UnlockPolicy } from '../../api/BaseMethod';
+import type { ProtocolV2InteractionDescriptor } from './uiInteraction';
+
+export const PROTOCOL_V2_LOCK_FREE_DEVICE_SETTINGS = [
+  'language',
+  'brightness',
+  'animation_enable',
+  'tap_to_wake',
+  'haptic_feedback',
+  'device_name_display_enabled',
+] as const satisfies readonly (keyof DeviceSettings)[];
+
+const lockFreeDeviceSettings = new Set<keyof DeviceSettings>(PROTOCOL_V2_LOCK_FREE_DEVICE_SETTINGS);
+
+export const getProtocolV2SettingsUnlockPolicy = (settings: DeviceSettings): UnlockPolicy =>
+  Object.keys(settings).every(key => lockFreeDeviceSettings.has(key as keyof DeviceSettings))
+    ? 'none'
+    : 'unlock-before-run';
+
+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: 'unlock-before-run',
+      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,
+  };
+};

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

@@ -1,6 +1,6 @@
 import { UI_REQUEST, createUiMessage } from '../../events';
 
-import type { CoreMessage, ProtocolV2UiCompletion } from '../../events';
+import type { CoreMessage, HardwareUiInteractionMeta, ProtocolV2UiCompletion } from '../../events';
 import type { Device } from '../../device/Device';
 import type { KnownDevice } from '../../types';
 
@@ -28,7 +28,15 @@ type ProtocolV2InteractionMethod = {
   protocolV2UiInteraction?: ProtocolV2InteractionDescriptor;
 };
 
-type InteractionDevice = Pick<Device, 'isProtocolV2' | 'toMessageObject'>;
+type InteractionDevice = Pick<Device, 'isProtocolV2' | 'toMessageObject'> &
+  Partial<
+    Pick<
+      Device,
+      | 'createProtocolV2UiPhaseMetadata'
+      | 'finishProtocolV2UiInteraction'
+      | 'hasOpenProtocolV2UiInteraction'
+    >
+  >;
 type PostMessage = (message: CoreMessage) => void;
 
 export const isProtocolV2UiEnabled = (method: { protocolV2UiMode?: 'auto' | 'none' }) =>
@@ -88,8 +96,9 @@ const hasCipherConfirmation = (value: unknown): boolean => {
 };
 
 /**
- * Protocol V2 不再依赖固件 ButtonRequest，因此在统一层根据业务方法生成兼容 UI Event。
- * 显式声明始终优先；地址和公钥只在设备实际展示时提示，签名统一提示一次。
+ * 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
@@ -106,7 +115,7 @@ export const resolveProtocolV2UiInteraction = (
     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;
 
@@ -155,12 +164,17 @@ export class ProtocolV2UiInteractionCoordinator {
     this.methodInteraction = interaction;
     if (!interaction) return;
     const { request, ...metadata } = interaction;
+    const interactionMeta = this.device.createProtocolV2UiPhaseMetadata?.(
+      request === 'pin' ? 'pin' : 'button',
+      'start'
+    );
 
     this.emit(
       request === 'pin' ? UI_REQUEST.REQUEST_PIN : UI_REQUEST.REQUEST_BUTTON,
       {
         device: this.device.toMessageObject() as KnownDevice,
         ...metadata,
+        ...(interactionMeta ? { interaction: interactionMeta } : {}),
       },
       `method:${request}:${interaction.reason}:${interaction.page ?? ''}:${
         interaction.operation ?? ''
@@ -168,7 +182,8 @@ export class ProtocolV2UiInteractionCoordinator {
     );
   }
 
-  enterUnlockInteraction(method?: string) {
+  enterUnlockInteraction(method?: string): HardwareUiInteractionMeta | undefined {
+    const interaction = this.device.createProtocolV2UiPhaseMetadata?.('pin', 'start');
     this.emit(
       UI_REQUEST.REQUEST_PIN,
       {
@@ -177,19 +192,45 @@ export class ProtocolV2UiInteractionCoordinator {
         reason: 'device-locked',
         deviceOnly: true,
         method,
+        ...(interaction ? { interaction } : {}),
       },
       `unlock:${method ?? ''}`
     );
+    return interaction;
   }
 
   resumeMethodInteraction() {
     this.enterMethodInteraction(this.methodInteraction);
   }
 
-  close() {
-    if (!this.device.isProtocolV2() || !this.opened || this.closed) return;
+  close(
+    options: {
+      ensureOperationClose?: boolean;
+      protocolV2Operation?: boolean;
+    } = {}
+  ): boolean {
+    if (
+      (!options.protocolV2Operation && !this.device.isProtocolV2()) ||
+      (!options.ensureOperationClose &&
+        !this.opened &&
+        !this.device.hasOpenProtocolV2UiInteraction?.()) ||
+      this.closed
+    )
+      return false;
     this.closed = true;
-    this.postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_WINDOW));
+    const interaction = this.device.finishProtocolV2UiInteraction?.('succeeded', {
+      ensureMetadata: options.ensureOperationClose,
+    });
+    const device = this.device.toMessageObject();
+    this.postMessage(
+      interaction
+        ? createUiMessage(UI_REQUEST.CLOSE_UI_WINDOW, {
+            ...interaction,
+            ...(device ? { device } : {}),
+          })
+        : createUiMessage(UI_REQUEST.CLOSE_UI_WINDOW)
+    );
+    return true;
   }
 
   private emit(

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

@@ -0,0 +1 @@
+export type UnlockPolicy = 'none' | 'unlock-before-run';