@onekeyfe/hd-core 1.2.0-alpha.52 → 1.2.0-alpha.53

package/src/index.ts

@@ -19,11 +19,6 @@ export * from './types';
 export { whitelist, whitelistExtension } from './data/config';
 export { executeCallback, cleanupCallback };
 export { preloadSessionCache } from './device/Device';
-export {
-  getFirmwareUpdateHostBindingGeneration,
-  registerFirmwareUpdateHostBinding,
-  unregisterFirmwareUpdateHostBinding,
-} from './api/firmware/FirmwareHostBinding';
 
 const HardwareSdk = ({
   init,

package/src/inject.ts

@@ -1,17 +1,7 @@
-import { getFirmwareUpdateCapabilities } from './api/firmware/FirmwareUpdateCapabilities';
-import {
-  prepareFirmwareUpdatePlan,
-  validateFirmwareUpdatePreparedPlan,
-} from './api/firmware/FirmwareUpdatePreparedPlan';
-import {
-  getFirmwareUpdateHostBindingGeneration,
-  registerFirmwareUpdateHostBinding,
-  unregisterFirmwareUpdateHostBinding,
-} from './api/firmware/FirmwareHostBinding';
-
+import type { HardwareConnectProtocol } from '@onekeyfe/hd-shared';
+import type { Unsuccessful } from './types';
 import type { EventEmitter } from 'events';
 import type { CallMethod } from './events';
-import type { Unsuccessful } from './types';
 import type { CoreApi } from './types/api';
 import type { AllNetworkAddress } from './types/api/allNetworkGetAddress';
 
@@ -50,6 +40,50 @@ export interface InjectApi {
   switchTransport: CoreApi['switchTransport'];
 }
 
+const normalizeConnectId = (connectId: string) => connectId.trim().toLowerCase();
+
+/**
+ * Keeps verified protocols isolated per transport endpoint and injects them at
+ * the single public call boundary, including APIs that do not expose params.
+ */
+export const createProtocolAwareCall = (rawCall: CoreApi['call']) => {
+  const protocolByConnectId = new Map<string, HardwareConnectProtocol>();
+
+  const setDeviceConnectProtocol: CoreApi['setDeviceConnectProtocol'] = (
+    connectId,
+    connectProtocol
+  ) => {
+    const normalizedConnectId = normalizeConnectId(connectId);
+    if (!normalizedConnectId) return;
+    if (connectProtocol) {
+      protocolByConnectId.set(normalizedConnectId, connectProtocol);
+    } else {
+      protocolByConnectId.delete(normalizedConnectId);
+    }
+  };
+
+  const call: CoreApi['call'] = params => {
+    if (!params || typeof params !== 'object') {
+      return rawCall(params);
+    }
+
+    const connectId = typeof params.connectId === 'string' ? params.connectId : undefined;
+    const boundProtocol = connectId
+      ? protocolByConnectId.get(normalizeConnectId(connectId))
+      : undefined;
+    if (
+      boundProtocol &&
+      params.connectProtocol === undefined &&
+      params.forceProtocolDetection !== true
+    ) {
+      return rawCall({ ...params, connectProtocol: boundProtocol });
+    }
+    return rawCall(params);
+  };
+
+  return { call, setDeviceConnectProtocol };
+};
+
 export const inject = ({
   call,
   cancel,
@@ -60,6 +94,7 @@ export const inject = ({
   switchTransport,
   uiResponse,
 }: InjectApi): CoreApi => {
+  const protocolAwareCall = createProtocolAwareCall(call);
   const api: CoreApi = {
     on: <T extends string, P extends (...args: any[]) => any>(type: T, fn: P) => {
       eventEmitter.on(type, fn);
@@ -77,12 +112,11 @@ export const inject = ({
 
     init,
 
-    call,
+    call: protocolAwareCall.call,
 
-    dispose: async () => {
-      unregisterFirmwareUpdateHostBinding();
-      await dispose();
-    },
+    setDeviceConnectProtocol: protocolAwareCall.setDeviceConnectProtocol,
+
+    dispose,
 
     uiResponse,
 
@@ -92,7 +126,7 @@ export const inject = ({
 
     switchTransport,
 
-    ...createCoreApi(call),
+    ...createCoreApi(protocolAwareCall.call),
   };
   return api;
 };
@@ -107,24 +141,25 @@ export const createCoreApi = (
   | 'removeAllListeners'
   | 'init'
   | 'call'
+  | 'setDeviceConnectProtocol'
   | 'dispose'
   | 'uiResponse'
   | 'cancel'
   | 'updateSettings'
   | 'switchTransport'
 > => ({
-  getFirmwareUpdateCapabilities,
-  registerFirmwareUpdateHostBinding,
-  unregisterFirmwareUpdateHostBinding,
-  getFirmwareUpdateHostBindingGeneration,
-  prepareFirmwareUpdatePlan,
-  validateFirmwareUpdatePreparedPlan,
   getLogs: () => call({ method: 'getLogs' }),
   clearSessionCache: params => call({ ...params, method: 'clearSessionCache' }),
   /**
    * 搜索设备
    */
   searchDevices: params => call({ ...params, method: 'searchDevices' }),
+  detectDeviceConnectProtocol: connectId =>
+    call({
+      connectId,
+      method: 'detectDeviceConnectProtocol',
+      forceProtocolDetection: true,
+    }),
 
   /**
    * 获取设备信息
@@ -182,6 +217,7 @@ export const createCoreApi = (
     call({ ...params, connectId, method: 'deviceGetOnboardingStatus' }),
   deviceUploadWallpaper: (connectId, params) =>
     call({ ...params, connectId, method: 'deviceUploadWallpaper' }),
+  deviceUploadNft: (connectId, params) => call({ ...params, connectId, method: 'deviceUploadNft' }),
   uploadPortfolio: (connectId, params) => call({ ...params, connectId, method: 'uploadPortfolio' }),
   deviceRecovery: (connectId, params) => call({ ...params, connectId, method: 'deviceRecovery' }),
   deviceReset: (connectId, params) => call({ ...params, connectId, method: 'deviceReset' }),

package/src/lowLevelInject.ts

@@ -1,5 +1,4 @@
-import { createCoreApi } from './inject';
-import { unregisterFirmwareUpdateHostBinding } from './api/firmware/FirmwareHostBinding';
+import { createCoreApi, createProtocolAwareCall } from './inject';
 
 import type { EventEmitter } from 'events';
 import type { CallMethod, CoreMessage } from './events';
@@ -34,6 +33,7 @@ export const lowLevelInject = ({
   switchTransport,
   addHardwareGlobalEventListener,
 }: LowLevelInjectApi): LowLevelCoreApi => {
+  const protocolAwareCall = createProtocolAwareCall(call);
   const api: LowLevelCoreApi = {
     addHardwareGlobalEventListener,
     removeAllListeners: type => {
@@ -42,12 +42,11 @@ export const lowLevelInject = ({
 
     init,
 
-    call,
+    call: protocolAwareCall.call,
 
-    dispose: async () => {
-      unregisterFirmwareUpdateHostBinding();
-      await dispose();
-    },
+    setDeviceConnectProtocol: protocolAwareCall.setDeviceConnectProtocol,
+
+    dispose,
 
     uiResponse,
 
@@ -59,7 +58,7 @@ export const lowLevelInject = ({
 
     emit: () => {},
 
-    ...createCoreApi(call),
+    ...createCoreApi(protocolAwareCall.call),
   };
   return api;
 };

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

@@ -157,7 +157,7 @@ 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,
@@ -168,8 +168,15 @@ export async function requestProtocolV2ProtocolInfo({
 }): Promise<ProtocolInfo> {
   const response =
     timeoutMs === undefined
-      ? await commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {})
-      : await commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {}, { timeoutMs });
+      ? await commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {
+          eventless_wallet_session: true,
+        })
+      : await commands.typedCall(
+          'ProtocolInfoRequest',
+          'ProtocolInfo',
+          { eventless_wallet_session: true },
+          { timeoutMs }
+        );
   return response.message;
 }
 

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

@@ -0,0 +1,359 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE } from '@onekeyfe/hd-transport';
+
+import type {
+  IProtocolV2BootResources,
+  IProtocolV2Resource,
+  IProtocolV2ResourceType,
+  IProtocolV2Resources,
+} from '../../types';
+import type { DeviceCommands } from '../../device/DeviceCommands';
+
+export const PROTOCOL_V2_RESOURCE_TYPES = [
+  'images',
+  'animation',
+  'wallpaper',
+  'translations',
+  'roobert',
+  'noto',
+] as const satisfies readonly IProtocolV2ResourceType[];
+
+export const PROTOCOL_V2_RESOURCE_DEVICE_PATHS: Readonly<Record<IProtocolV2ResourceType, string>> =
+  {
+    images: 'vol0:/bundles/images/images.okpkg',
+    animation: 'vol0:/bundles/images/animation.okpkg',
+    wallpaper: 'vol0:/bundles/images/wallpaper.okpkg',
+    translations: 'vol0:/bundles/translations/translations.okpkg',
+    roobert: 'vol0:/bundles/font/roobert.okpkg',
+    noto: 'vol0:/bundles/font/noto.okpkg',
+  };
+
+const RESOURCE_TYPE_SET = new Set<string>(PROTOCOL_V2_RESOURCE_TYPES);
+const SHA256_HEX_LENGTH = 64;
+const SHA3_512_HEX_LENGTH = 128;
+const PROTOCOL_V2_OKPP_HEADER_SIZE = 0x52a0;
+const PROTOCOL_V2_OKPP_TYPE_OFFSET = 0x08;
+const PROTOCOL_V2_OKPP_HEADER_LENGTH_OFFSET = 0x0c;
+const PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET = 0x240;
+const PROTOCOL_V2_OKPP_HASH_SIZE = 64;
+const PROTOCOL_V2_RESOURCE_IDENTITY_READ_SIZE =
+  PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE;
+const PROTOCOL_V2_MIN_FILE_READ_CHUNK_SIZE = 64;
+export const PROTOCOL_V2_RESOURCE_INVENTORY_TIMEOUT_MS = 5 * 1000;
+
+export type ProtocolV2ResourceInventoryItem = {
+  type: IProtocolV2ResourceType;
+  size: number;
+  headerHash: string;
+};
+
+export type ProtocolV2ResourceUpdateMode = 'application' | 'bootloader-recovery';
+
+export type ProtocolV2ResourceUpdatePlan = {
+  status: 'valid' | 'outdated' | 'unknown';
+  resources: IProtocolV2Resource[];
+};
+
+function toFiniteNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : undefined;
+  }
+  if (value && typeof value === 'object') {
+    const longLike = value as { toNumber?: () => number };
+    if (typeof longLike.toNumber === 'function') {
+      const numeric = longLike.toNumber();
+      return Number.isFinite(numeric) ? numeric : undefined;
+    }
+  }
+  return undefined;
+}
+
+function toUint8Array(value: unknown): Uint8Array {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (typeof value === 'string') {
+    const hex = value.replace(/^0x/i, '');
+    if (!hex || hex.length % 2 !== 0 || /[^0-9a-f]/i.test(hex)) {
+      return new Uint8Array(0);
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+  }
+  return new Uint8Array(0);
+}
+
+function readAscii(bytes: Uint8Array, offset: number, length: number): string {
+  return Array.from(bytes.slice(offset, offset + length), byte => String.fromCharCode(byte)).join(
+    ''
+  );
+}
+
+function parseProtocolV2ResourceHeaderHash(bytes: Uint8Array): string | undefined {
+  if (bytes.byteLength < PROTOCOL_V2_RESOURCE_IDENTITY_READ_SIZE) return undefined;
+  if (readAscii(bytes, 0, 4) !== 'OKPP') return undefined;
+  if (readAscii(bytes, PROTOCOL_V2_OKPP_TYPE_OFFSET, 4) !== 'RESC') return undefined;
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (
+    view.getUint32(PROTOCOL_V2_OKPP_HEADER_LENGTH_OFFSET, true) !== PROTOCOL_V2_OKPP_HEADER_SIZE
+  ) {
+    return undefined;
+  }
+  return bytesToHex(
+    bytes.slice(
+      PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET,
+      PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE
+    )
+  );
+}
+
+async function readProtocolV2ResourceIdentity({
+  commands,
+  resource,
+  chunkSize,
+  timeoutMs = PROTOCOL_V2_RESOURCE_INVENTORY_TIMEOUT_MS,
+}: {
+  commands: Pick<DeviceCommands, 'typedCall'>;
+  resource: IProtocolV2Resource;
+  chunkSize: number;
+  timeoutMs?: number;
+}): Promise<ProtocolV2ResourceInventoryItem | undefined> {
+  const path = PROTOCOL_V2_RESOURCE_DEVICE_PATHS[resource.type];
+  const pathInfo = await commands.typedCall(
+    'FilesystemPathInfoQuery',
+    'FilesystemPathInfo',
+    { path },
+    { timeoutMs }
+  );
+  const size = toFiniteNumber(pathInfo.message?.size);
+  if (
+    !pathInfo.message?.exist ||
+    pathInfo.message?.directory ||
+    !Number.isSafeInteger(size) ||
+    size !== resource.size ||
+    size < PROTOCOL_V2_OKPP_HEADER_SIZE
+  ) {
+    return undefined;
+  }
+
+  const header = new Uint8Array(PROTOCOL_V2_RESOURCE_IDENTITY_READ_SIZE);
+  let offset = 0;
+  while (offset < header.byteLength) {
+    const readLength = Math.min(chunkSize, header.byteLength - offset);
+    const response = await commands.typedCall(
+      'FilesystemFileRead',
+      'FilesystemFile',
+      {
+        file: { path, offset, total_size: 0 },
+        chunk_len: readLength,
+      },
+      { timeoutMs }
+    );
+    const data = toUint8Array(response.message?.data);
+    if (data.byteLength === 0) return undefined;
+    const copied = Math.min(data.byteLength, header.byteLength - offset);
+    header.set(data.subarray(0, copied), offset);
+    offset += copied;
+  }
+
+  const headerHash = parseProtocolV2ResourceHeaderHash(header);
+  return headerHash ? { type: resource.type, size, headerHash } : undefined;
+}
+
+/**
+ * 使用已发布 Pro2 固件支持的文件系统消息构建资源清单。
+ * 缺失、无法读取或格式错误的文件不会进入清单，因此会被选中重写。
+ */
+export async function readProtocolV2ResourceInventory({
+  commands,
+  resources,
+  chunkSize = PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE,
+  timeoutMs = PROTOCOL_V2_RESOURCE_INVENTORY_TIMEOUT_MS,
+}: {
+  commands: Pick<DeviceCommands, 'typedCall'>;
+  resources: readonly IProtocolV2Resource[];
+  chunkSize?: number;
+  timeoutMs?: number;
+}): Promise<ProtocolV2ResourceInventoryItem[]> {
+  const normalizedChunkSize = Number.isFinite(chunkSize)
+    ? Math.max(Math.floor(chunkSize), PROTOCOL_V2_MIN_FILE_READ_CHUNK_SIZE)
+    : PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE;
+  const inventory: ProtocolV2ResourceInventoryItem[] = [];
+  for (const resource of resources) {
+    try {
+      const item = await readProtocolV2ResourceIdentity({
+        commands,
+        resource,
+        chunkSize: normalizedChunkSize,
+        timeoutMs,
+      });
+      if (item) inventory.push(item);
+    } catch {
+      // 单个资源无法读取时按缺失处理，不阻断其余资源的增量检查。
+    }
+  }
+  return inventory;
+}
+
+function normalizeHex(value: unknown, expectedLength: number, field: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid Pro2 resource ${field}: expected a hexadecimal string`);
+  }
+  const normalized = value.replace(/^0x/i, '').toLowerCase();
+  if (normalized.length !== expectedLength || !/^[0-9a-f]+$/.test(normalized)) {
+    throw new Error(
+      `Invalid Pro2 resource ${field}: expected ${expectedLength} hexadecimal characters`
+    );
+  }
+  return normalized;
+}
+
+function validateResource(value: unknown, index: number): IProtocolV2Resource {
+  if (!value || typeof value !== 'object') {
+    throw new Error(`Invalid Pro2 resource at stable[${index}]`);
+  }
+  const resource = value as Partial<IProtocolV2Resource>;
+  if (typeof resource.type !== 'string' || !RESOURCE_TYPE_SET.has(resource.type)) {
+    throw new Error(`Invalid Pro2 resource type at stable[${index}]`);
+  }
+  if (typeof resource.url !== 'string' || !resource.url.startsWith('https://')) {
+    throw new Error(`Invalid Pro2 resource url at stable[${index}]`);
+  }
+  if (!Number.isSafeInteger(resource.size) || Number(resource.size) <= 0) {
+    throw new Error(`Invalid Pro2 resource size at stable[${index}]`);
+  }
+  return {
+    type: resource.type,
+    url: resource.url,
+    size: Number(resource.size),
+    fileHash: normalizeHex(resource.fileHash, SHA256_HEX_LENGTH, 'fileHash'),
+    headerHash: normalizeHex(resource.headerHash, SHA3_512_HEX_LENGTH, 'headerHash'),
+  };
+}
+
+function validateBootResources(value: unknown): IProtocolV2BootResources {
+  if (!value || typeof value !== 'object') {
+    throw new Error('Invalid Pro2 boot resources config');
+  }
+  const resource = value as Partial<IProtocolV2BootResources>;
+  if (resource.required !== false) {
+    throw new Error('Invalid Pro2 boot resources required flag: expected false');
+  }
+  if (resource.target !== 'CRATE') {
+    throw new Error('Invalid Pro2 boot resources target: expected CRATE');
+  }
+  if (typeof resource.url !== 'string' || !resource.url.startsWith('https://')) {
+    throw new Error('Invalid Pro2 boot resources url');
+  }
+  if (!Number.isSafeInteger(resource.size) || Number(resource.size) <= 0) {
+    throw new Error('Invalid Pro2 boot resources size');
+  }
+  return {
+    required: false,
+    target: 'CRATE',
+    url: resource.url,
+    size: Number(resource.size),
+    fileHash: normalizeHex(resource.fileHash, SHA256_HEX_LENGTH, 'boot fileHash'),
+    payloadHash: normalizeHex(resource.payloadHash, SHA3_512_HEX_LENGTH, 'boot payloadHash'),
+    headerHash: normalizeHex(resource.headerHash, SHA3_512_HEX_LENGTH, 'boot headerHash'),
+  };
+}
+
+/** 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' ||
+    !Array.isArray((value as { stable?: unknown }).stable)
+  ) {
+    throw new Error('Invalid Pro2 resources config: stable must be an array');
+  }
+
+  const config = value as { stable: unknown[]; boot?: unknown };
+  const stable = config.stable.map(validateResource);
+  const types = new Set(stable.map(resource => resource.type));
+  if (stable.length !== PROTOCOL_V2_RESOURCE_TYPES.length || types.size !== stable.length) {
+    throw new Error('Invalid Pro2 resources config: stable must contain six unique resource types');
+  }
+  for (const type of PROTOCOL_V2_RESOURCE_TYPES) {
+    if (!types.has(type)) {
+      throw new Error(`Invalid Pro2 resources config: stable is missing ${type}`);
+    }
+  }
+  const boot = config.boot === undefined ? undefined : validateBootResources(config.boot);
+  return {
+    stable: PROTOCOL_V2_RESOURCE_TYPES.map(type => {
+      const resource = stable.find(item => item.type === type);
+      if (!resource) {
+        throw new Error(`Invalid Pro2 resources config: stable is missing ${type}`);
+      }
+      return resource;
+    }),
+    ...(boot ? { boot } : undefined),
+  };
+}
+
+/** 比较文件系统资源清单；恢复模式无法取得清单时回退到全量更新。 */
+export function buildProtocolV2ResourceUpdatePlan({
+  resources,
+  inventory,
+  mode,
+  forced = false,
+}: {
+  resources: readonly IProtocolV2Resource[];
+  inventory?: readonly ProtocolV2ResourceInventoryItem[];
+  mode: ProtocolV2ResourceUpdateMode;
+  forced?: boolean;
+}): ProtocolV2ResourceUpdatePlan {
+  if (forced) {
+    return {
+      status: resources.length > 0 ? 'outdated' : 'valid',
+      resources: [...resources],
+    };
+  }
+  if (!inventory) {
+    return mode === 'bootloader-recovery'
+      ? {
+          status: resources.length > 0 ? 'outdated' : 'valid',
+          resources: [...resources],
+        }
+      : { status: 'unknown', resources: [] };
+  }
+
+  const inventoryByType = new Map(inventory.map(item => [item.type, item]));
+  const changedResources = resources.filter(resource => {
+    const current = inventoryByType.get(resource.type);
+    return (
+      !current ||
+      current.size !== resource.size ||
+      current.headerHash.toLowerCase() !== resource.headerHash.toLowerCase()
+    );
+  });
+
+  return {
+    status: changedResources.length === 0 ? 'valid' : 'outdated',
+    resources: changedResources,
+  };
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/** Verify the complete downloaded file before any device mutation. */
+export function isProtocolV2ResourceFileValid(
+  binary: ArrayBuffer,
+  resource: Pick<IProtocolV2Resource, 'size' | 'fileHash'>
+): boolean {
+  if (binary.byteLength !== resource.size) return false;
+  return bytesToHex(sha256(new Uint8Array(binary))) === resource.fileHash.toLowerCase();
+}

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' }) =>
@@ -156,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 ?? ''
@@ -169,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,
       {
@@ -178,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(