@onekeyfe/hd-core 1.2.0-alpha.2 → 1.2.0-alpha.21

package/src/events/ui-request.ts

@@ -49,6 +49,23 @@ export const UI_REQUEST = {
   NOT_USE_ONEKEY_DEVICE: 'ui-device_please_use_onekey_device',
 } as const;
 
+export type ProtocolV2UiEventSource =
+  | 'unlock-coordinator'
+  | 'wallet-session-coordinator'
+  | 'method-lifecycle';
+
+export type ProtocolV2UiCompletion = 'page-accepted' | 'operation-completed';
+
+export type ProtocolV2UiEventMetadata = {
+  source?: ProtocolV2UiEventSource;
+  reason?: string;
+  deviceOnly?: boolean;
+  completion?: ProtocolV2UiCompletion;
+  method?: string;
+  page?: string | number;
+  operation?: string;
+};
+
 export interface UiRequestWithoutPayload {
   type:
     | typeof UI_REQUEST.CLOSE_UI_WINDOW
@@ -73,7 +90,7 @@ export interface UiRequestFirmwareProgressing {
 
 export type UiRequestDeviceAction = {
   type: typeof UI_REQUEST.REQUEST_PIN;
-  payload: {
+  payload: ProtocolV2UiEventMetadata & {
     device: Device;
     type?: PROTO.PinMatrixRequestType | 'ButtonRequest_PinEntry' | 'ButtonRequest_AttachPin';
   };
@@ -81,7 +98,7 @@ export type UiRequestDeviceAction = {
 
 export interface UiRequestButton {
   type: typeof UI_REQUEST.REQUEST_BUTTON;
-  payload: DeviceButtonRequest['payload'];
+  payload: DeviceButtonRequest['payload'] & ProtocolV2UiEventMetadata;
 }
 
 export interface UiRequestPassphrase {
@@ -90,6 +107,9 @@ export interface UiRequestPassphrase {
     device: Device;
     passphraseState?: string;
     existsAttachPinUser?: boolean;
+    source?: 'wallet-session-coordinator';
+    reason?: 'open-wallet' | 'session-recovery';
+    expectedPassphraseState?: string;
   };
 }
 
@@ -98,6 +118,8 @@ export interface UiRequestPassphraseOnDevice {
   payload: {
     device: Device;
     passphraseState?: string;
+    source?: 'wallet-session-coordinator';
+    reason?: 'open-wallet' | 'session-recovery';
   };
 }
 

package/src/inject.ts

@@ -100,6 +100,7 @@ export const createCoreApi = (
   | 'switchTransport'
 > => ({
   getLogs: () => call({ method: 'getLogs' }),
+  clearSessionCache: params => call({ ...params, method: 'clearSessionCache' }),
   /**
    * 搜索设备
    */
@@ -109,7 +110,10 @@ export const createCoreApi = (
    * 获取设备信息
    */
   getFeatures: (connectId, params) => call({ ...params, connectId, method: 'getFeatures' }),
-  getDeviceInfo: (connectId, params) => call({ ...params, connectId, method: 'getDeviceInfo' }),
+  getDeviceState: (connectId, params) => {
+    const { refresh: _refresh, includeRaw: _includeRaw, ...commonParams } = (params ?? {}) as any;
+    return call({ ...commonParams, connectId, method: 'getDeviceState' });
+  },
   getOnekeyFeatures: (connectId, params) =>
     call({ ...params, connectId, method: 'getOnekeyFeatures' }),
 
@@ -150,29 +154,29 @@ export const createCoreApi = (
   deviceRebootToBoardloader: connectId => call({ connectId, method: 'deviceRebootToBoardloader' }),
   deviceRebootToBootloader: connectId => call({ connectId, method: 'deviceRebootToBootloader' }),
 
-  // File system & device control API (Protocol V2 only)
-  getProtoVersion: (connectId, params) => call({ ...params, connectId, method: 'getProtoVersion' }),
-  ping: (connectId, params) => call({ ...params, connectId, method: 'ping' }),
+  // Pro2 business API
   deviceReboot: (connectId, params) => call({ ...params, connectId, method: 'deviceReboot' }),
-  deviceGetDeviceInfo: (connectId, params) =>
-    call({ ...params, connectId, method: 'deviceGetDeviceInfo' }),
   deviceGetOnboardingStatus: (connectId, params) =>
     call({ ...params, connectId, method: 'deviceGetOnboardingStatus' }),
+  deviceUploadWallpaper: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceUploadWallpaper' }),
+  deviceInfoGet: (connectId, params) => call({ ...params, connectId, method: 'deviceInfoGet' }),
+  deviceStatusGet: (connectId, params) => call({ ...params, connectId, method: 'deviceStatusGet' }),
+  protocolInfoRequest: (connectId, params) =>
+    call({ ...params, connectId, method: 'protocolInfoRequest' }),
+  ping: (connectId, params) => call({ ...params, connectId, method: 'ping' }),
   deviceFirmwareUpdate: (connectId, params) =>
     call({ ...params, connectId, method: 'deviceFirmwareUpdate' }),
   deviceGetFirmwareUpdateStatus: (connectId, params) =>
     call({ ...params, connectId, method: 'deviceGetFirmwareUpdateStatus' }),
-  devReboot: (connectId, params) => call({ ...params, connectId, method: 'devReboot' }),
-  devGetDeviceInfo: (connectId, params) =>
-    call({ ...params, connectId, method: 'devGetDeviceInfo' }),
-  devFirmwareUpdate: (connectId, params) =>
-    call({ ...params, connectId, method: 'devFirmwareUpdate' }),
-  devGetFirmwareUpdateStatus: (connectId, params) =>
-    call({ ...params, connectId, method: 'devGetFirmwareUpdateStatus' }),
-  factoryDeviceInfoSettings: (connectId, params) =>
-    call({ ...params, connectId, method: 'factoryDeviceInfoSettings' }),
-  factoryGetDeviceInfo: connectId => call({ connectId, method: 'factoryGetDeviceInfo' }),
-  filesystemFixPermission: connectId => call({ connectId, method: 'filesystemFixPermission' }),
+  deviceFactoryInfoSet: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceFactoryInfoSet' }),
+  deviceFactoryInfoGet: (connectId, params) =>
+    call({ ...params, connectId, method: 'deviceFactoryInfoGet' }),
+  filesystemPermissionFix: (connectId, params) =>
+    call({ ...params, connectId, method: 'filesystemPermissionFix' }),
+  filesystemFormat: connectId => call({ connectId, method: 'filesystemFormat' }),
+  uploadPortfolio: (connectId, params) => call({ ...params, connectId, method: 'uploadPortfolio' }),
   fileRead: (connectId, params) => call({ ...params, connectId, method: 'fileRead' }),
   fileWrite: (connectId, params) => call({ ...params, connectId, method: 'fileWrite' }),
   fileDelete: (connectId, params) => call({ ...params, connectId, method: 'fileDelete' }),
@@ -180,23 +184,6 @@ export const createCoreApi = (
   dirMake: (connectId, params) => call({ ...params, connectId, method: 'dirMake' }),
   dirRemove: (connectId, params) => call({ ...params, connectId, method: 'dirRemove' }),
   pathInfo: (connectId, params) => call({ ...params, connectId, method: 'pathInfo' }),
-  filesystemFileRead: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemFileRead' }),
-  filesystemFileWrite: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemFileWrite' }),
-  filesystemFileDelete: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemFileDelete' }),
-  filesystemDirList: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemDirList' }),
-  filesystemDirMake: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemDirMake' }),
-  filesystemDirRemove: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemDirRemove' }),
-  filesystemPathInfoQuery: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemPathInfoQuery' }),
-  filesystemFormat: connectId => call({ connectId, method: 'filesystemFormat' }),
-  filesystemDiskControl: (connectId, params) =>
-    call({ ...params, connectId, method: 'filesystemDiskControl' }),
   deviceRecovery: (connectId, params) => call({ ...params, connectId, method: 'deviceRecovery' }),
   deviceReset: (connectId, params) => call({ ...params, connectId, method: 'deviceReset' }),
   deviceSettings: (connectId, params) => call({ ...params, connectId, method: 'deviceSettings' }),
@@ -212,6 +199,8 @@ export const createCoreApi = (
     call({ ...params, connectId, method: 'deviceUpdateBootloader' }),
   getPassphraseState: (connectId, params) =>
     call({ ...params, connectId, method: 'getPassphraseState' }),
+  openWalletSession: (connectId, params) =>
+    call({ ...params, connectId, method: 'openWalletSession' }),
   deviceCancel: (connectId, params) => call({ ...params, connectId, method: 'deviceCancel' }),
   deviceLock: (connectId, params) => call({ ...params, connectId, method: 'deviceLock' }),
   deviceUnlock: (connectId, params) =>

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

@@ -0,0 +1,24 @@
+import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import type { DeviceSession } from '@onekeyfe/hd-transport';
+
+export type CompleteDeviceSession = DeviceSession & {
+  session_id: string;
+  btc_test_address: string;
+};
+
+export function assertCompleteDeviceSession(
+  message: DeviceSession
+): asserts message is CompleteDeviceSession {
+  if (
+    typeof message.session_id !== 'string' ||
+    !message.session_id ||
+    typeof message.btc_test_address !== 'string' ||
+    !message.btc_test_address
+  ) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'DeviceSessionGet returned an incomplete DeviceSession response.'
+    );
+  }
+}

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

@@ -1,19 +1,23 @@
-import { DevSEState, DevSeType } from '@onekeyfe/hd-transport';
-
-import type { DeviceGetDeviceInfo, DevSEInfo, ProtocolV2DeviceInfo } from '@onekeyfe/hd-transport';
+import { DeviceSEState, DeviceSeType } from '@onekeyfe/hd-transport';
+
+import type {
+  DeviceInfoGet,
+  DeviceSEInfo,
+  DeviceStatus,
+  ProtocolV2DeviceInfo,
+} from '@onekeyfe/hd-transport';
 import type { DeviceCommands } from '../../device/DeviceCommands';
 
-// 单源类型：直接使用 hd-transport 生成的 ProtocolV2DeviceInfo / DevSEInfo /
-// DevFirmwareImageInfo（与 firmware-pro2 proto 一致），不再维护手写副本。
+// Use hd-transport generated Protocol V2 types as the single source of truth.
 export type { ProtocolV2DeviceInfo };
-export type { DevFirmwareImageInfo as ProtocolV2FirmwareImageInfo } from '@onekeyfe/hd-transport';
-export type { DevSEInfo as ProtocolV2SEInfo } from '@onekeyfe/hd-transport';
+export type { DeviceFirmwareImageInfo as ProtocolV2FirmwareImageInfo } from '@onekeyfe/hd-transport';
+export type { DeviceSEInfo as ProtocolV2SEInfo } from '@onekeyfe/hd-transport';
 
 export type ProtocolV2SeStateLabel = 'BOOT' | 'APP_FACTORY' | 'APP';
 
 /**
- * 传输层解码会把 proto 枚举输出为名称字符串（见 hd-transport 的 messageToJSON），
- * 但生成类型声明为数值枚举；这里统一兼容两种形态。
+ * 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,
@@ -26,11 +30,11 @@ const normalizeEnumValue = <T extends Record<string | number, string | number>>(
 };
 
 /**
- * DevSEInfo.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?: DevSEInfo): ProtocolV2SeStateLabel | null => {
-  const label = normalizeEnumValue(DevSEState, se?.state);
+export const getProtocolV2SeState = (se?: DeviceSEInfo): ProtocolV2SeStateLabel | null => {
+  const label = normalizeEnumValue(DeviceSEState, se?.state);
   switch (label) {
     case 'BOOT':
       return 'BOOT';
@@ -44,36 +48,41 @@ export const getProtocolV2SeState = (se?: DevSEInfo): ProtocolV2SeStateLabel | n
 };
 
 /**
- * DevSEInfo.type → 可读标签（如 'THD89'）。DeviceProfile / Features
- * 的 SE 类型归一化从这里取。
+ * Map DeviceSEInfo.type to a readable label such as `THD89`.
  */
-export const getProtocolV2SeType = (se?: DevSEInfo): string | null =>
-  normalizeEnumValue(DevSeType, se?.type);
+export const getProtocolV2SeType = (se?: DeviceSEInfo): string | null =>
+  normalizeEnumValue(DeviceSeType, se?.type);
 
-export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
-  targets: {
-    hw: true,
-    fw: true,
-    bt: true,
-    status: true,
-  },
-  types: {
-    version: true,
-    specific: true,
-  },
-};
+export type ProtocolV2RuntimeMode = 'normal' | 'bootloader';
 
 /**
- * 轻量状态刷新请求（每次 run 前使用）。
+ * TODO: Once firmware-pro2 exposes ProtocolInfo.build_fingerprint, parse the running
+ * binary name and remove the temporary DeviceStatusGet-failure heuristic. romloader
+ * is a separate recovery flow and is excluded until its contract is defined.
  *
- * status 提供 init_states / label / passphrase_protection 等会在设备端变化的字段；
- * hw / bt 提供 serialNo / bleName 等身份字段；不含 fw/SE targets，单帧请求开销很小。
+ * The temporary contract has two states: DeviceStatusGet success means normal and
+ * failure means bootloader. Do not infer mode from application/SE/romloader fields.
  */
-export const PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST = {
+export const getProtocolV2RuntimeMode = ({
+  deviceInfo: _deviceInfo,
+  deviceStatusAvailable,
+}: {
+  deviceInfo?: ProtocolV2DeviceInfo | null;
+  deviceStatusAvailable: boolean;
+}): ProtocolV2RuntimeMode => {
+  if (deviceStatusAvailable) return 'normal';
+  return 'bootloader';
+};
+
+export const PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
-    bt: true,
-    status: true,
+    fw: true,
+    coprocessor: true,
+    se1: true,
+    se2: true,
+    se3: true,
+    se4: true,
   },
   types: {
     version: true,
@@ -81,16 +90,19 @@ export const PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST = {
   },
 };
 
+/**
+ * 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,
-    bt: true,
+    coprocessor: true,
     se1: true,
     se2: true,
     se3: true,
     se4: true,
-    status: true,
   },
   types: {
     version: true,
@@ -102,12 +114,11 @@ export const PROTOCOL_V2_FULL_DEVICE_INFO_REQUEST = {
   targets: {
     hw: true,
     fw: true,
-    bt: true,
+    coprocessor: true,
     se1: true,
     se2: true,
     se3: true,
     se4: true,
-    status: true,
   },
   types: {
     version: true,
@@ -120,42 +131,6 @@ 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;
 
-/**
- * 临时开关（默认开启）：当前 Pro2 测试固件 / 早期工程板尚未实现 DevGetDeviceInfo，
- * 真实调用只会超时失败。开启时跳过 wire 调用，直接返回 mock DeviceInfo；
- * DevGetDeviceInfo 尚未返回的字段保持为空，不再用 transport path 兜底成设备身份。
- *
- * 固件实现 DevGetDeviceInfo 后：把默认值改回 false（或直接删除开关与 mock）。
- * 注意：开启期间 FirmwareUpdateV4 的“升级完成版本比对”拿到的也是 mock 版本，
- * 不能作为升级成功的依据。
- */
-let protocolV2DeviceInfoMockEnabled = true;
-
-export const setProtocolV2DeviceInfoMock = (enabled: boolean) => {
-  protocolV2DeviceInfoMockEnabled = enabled;
-};
-
-export const isProtocolV2DeviceInfoMockEnabled = () => protocolV2DeviceInfoMockEnabled;
-
-/** 每次调用返回新对象，避免调用方原地修改互相污染。 */
-export const buildMockProtocolV2DeviceInfo = (): ProtocolV2DeviceInfo => ({
-  protocol_version: 2,
-  hw: {
-    // 留空：协议未上报时 SDK 不再用 transport path 伪造身份字段
-    serial_no: '',
-  },
-  fw: {
-    app: { version: '0.1.0' },
-  },
-  bt: {},
-  status: {
-    init_states: true,
-    language: 'en_US',
-    passphrase_protection: false,
-    bt_enable: true,
-  },
-});
-
 export async function requestProtocolV2DeviceInfo({
   commands,
   timeoutMs = PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
@@ -163,15 +138,26 @@ export async function requestProtocolV2DeviceInfo({
 }: {
   commands: DeviceCommands;
   timeoutMs?: number;
-  request?: DeviceGetDeviceInfo;
+  request?: DeviceInfoGet;
 }): Promise<ProtocolV2DeviceInfo> {
-  if (protocolV2DeviceInfoMockEnabled) {
-    return buildMockProtocolV2DeviceInfo();
-  }
-  const { message } = await commands.typedCall('DevGetDeviceInfo', 'DeviceInfo', request, {
+  const { message } = await commands.typedCall('DeviceInfoGet', 'DeviceInfo', request, {
     timeoutMs,
   });
-  // 'DeviceInfo' 在生成类型里是 V1 DeviceInfo | ProtocolV2DeviceInfo 的合并；
-  // DevGetDeviceInfo 是 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 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,43 +1,19 @@
 /**
- * 当前 firmware-pro2 子模块的 DevFirmwareTargetType。
- *
- * 注意：仓库里的 hd-transport 生成物暂时仍带旧 target 名称；这里显式按
- * submodules/firmware-pro2/sys/protobuf/onekey_protocol/latest/messages_device.proto
- * 对齐当前子模块，避免运行时取到 undefined。
+ * DeviceFirmwareTargetType from the current firmware-pro2 submodule.
  */
 export const ProtocolV2FirmwareTargetType = {
-  TARGET_MAIN_APP: 0,
-  TARGET_MAIN_BOOT: 1,
-  TARGET_BT: 2,
-  TARGET_SE1: 3,
-  TARGET_SE2: 4,
-  TARGET_SE3: 5,
-  TARGET_SE4: 6,
-  TARGET_RESOURCE: 10,
+  FW_MGMT_TARGET_INVALID: 0,
+  FW_MGMT_TARGET_CRATE: 1,
+  FW_MGMT_TARGET_ROMLOADER: 2,
+  FW_MGMT_TARGET_BOOTLOADER: 3,
+  FW_MGMT_TARGET_APPLICATION_P1: 4,
+  FW_MGMT_TARGET_APPLICATION_P2: 5,
+  FW_MGMT_TARGET_COPROCESSOR: 6,
+  FW_MGMT_TARGET_SE01: 7,
+  FW_MGMT_TARGET_SE02: 8,
+  FW_MGMT_TARGET_SE03: 9,
+  FW_MGMT_TARGET_SE04: 10,
 } as const;
 
 export type ProtocolV2FirmwareTargetType =
   (typeof ProtocolV2FirmwareTargetType)[keyof typeof ProtocolV2FirmwareTargetType];
-
-/**
- * Map Protocol V2 firmware file name to DevFirmwareUpdate target_id.
- */
-export function protocolV2FileNameToTargetId(fileName: string): ProtocolV2FirmwareTargetType {
-  const normalized = fileName.toLowerCase();
-  if (normalized.includes('bootloader') || normalized.includes('update_rom')) {
-    return ProtocolV2FirmwareTargetType.TARGET_MAIN_BOOT;
-  }
-  if (
-    normalized.includes('coprocessor') ||
-    normalized.includes('ble') ||
-    normalized.includes('bluetooth') ||
-    normalized.includes('bt')
-  ) {
-    return ProtocolV2FirmwareTargetType.TARGET_BT;
-  }
-  if (normalized.includes('se4')) return ProtocolV2FirmwareTargetType.TARGET_SE4;
-  if (normalized.includes('se3')) return ProtocolV2FirmwareTargetType.TARGET_SE3;
-  if (normalized.includes('se2')) return ProtocolV2FirmwareTargetType.TARGET_SE2;
-  if (normalized.includes('se')) return ProtocolV2FirmwareTargetType.TARGET_SE1;
-  return ProtocolV2FirmwareTargetType.TARGET_MAIN_APP;
-}

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

@@ -2,8 +2,8 @@ export {
   PROTOCOL_V2_DEVICE_INFO_REQUEST,
   PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,
   PROTOCOL_V2_FEATURES_DEVICE_INFO_REQUEST,
-  PROTOCOL_V2_STATUS_DEVICE_INFO_REQUEST,
   PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
+  getProtocolV2RuntimeMode,
   getProtocolV2SeState,
   getProtocolV2SeType,
 } from './features';
@@ -12,5 +12,7 @@ export type {
   ProtocolV2FirmwareImageInfo,
   ProtocolV2SEInfo,
   ProtocolV2SeStateLabel,
+  ProtocolV2RuntimeMode,
 } from './features';
 export * from './firmware';
+export * from './walletSession';

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

@@ -0,0 +1,10 @@
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+export function isDeviceLockedError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'errorCode' in error &&
+    error.errorCode === HardwareErrorCode.DeviceLocked
+  );
+}

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

@@ -0,0 +1,61 @@
+import type { DeviceSettings, DeviceSettingsPage } from '@onekeyfe/hd-transport';
+import type { UnlockPolicy } from '../../api/BaseMethod';
+import type { ProtocolV2InteractionDescriptor } from './uiInteraction';
+
+const LOCK_FREE_DEVICE_SETTINGS = new Set<keyof DeviceSettings>([
+  'label',
+  'language',
+  'brightness',
+  'haptic_feedback',
+]);
+
+export const getProtocolV2SettingsUnlockPolicy = (settings: DeviceSettings): UnlockPolicy =>
+  Object.keys(settings).every(key => LOCK_FREE_DEVICE_SETTINGS.has(key as keyof DeviceSettings))
+    ? 'none'
+    : 'retry-on-locked';
+
+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: 'retry-on-locked',
+      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,
+  };
+};