@onekeyfe/hd-core 1.2.0-alpha.33 → 1.2.0-alpha.35

package/src/events/logBlockEvent.ts

@@ -1,10 +1,68 @@
+import { UI_REQUEST } from './ui-request';
 import { UI_RESPONSE } from './ui-response';
 
 export const LogBlockEvent: Set<string> = new Set([
+  UI_REQUEST.REQUEST_PASSPHRASE,
+  UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE,
   UI_RESPONSE.RECEIVE_PIN,
   UI_RESPONSE.RECEIVE_PASSPHRASE,
 ]);
 
+const LogLabelMethod: Set<string> = new Set([
+  'openWalletSession',
+  'deviceUploadWallpaper',
+  'uploadPortfolio',
+  'fileWrite',
+  'fileRead',
+]);
+
+const SensitiveLogKeys: Set<string> = new Set([
+  'devicestate',
+  'entropy',
+  'expectedpassphrasestate',
+  'mnemonic',
+  'passphrase',
+  'passphrasestate',
+  'password',
+  'pin',
+  'privatekey',
+  'seed',
+  'session',
+  'sessionid',
+  'walletsessionid',
+  'xprv',
+]);
+
+const normalizeLogKey = (key: string) => key.replace(/[_-]/g, '').toLowerCase();
+
+const isSigningMethod = (methodName: string) => /sign/i.test(methodName);
+
+const redactLogValue = (value: unknown, seen: WeakSet<object>): unknown => {
+  if (ArrayBuffer.isView(value)) {
+    return `[BINARY:${value.byteLength}]`;
+  }
+  if (value instanceof ArrayBuffer) {
+    return `[BINARY:${value.byteLength}]`;
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => redactLogValue(item, seen));
+  }
+  if (!value || typeof value !== 'object') return value;
+  if (seen.has(value)) return '[CIRCULAR]';
+
+  seen.add(value);
+  const redacted = Object.fromEntries(
+    Object.entries(value as Record<string, unknown>).map(([key, item]) => [
+      key,
+      SensitiveLogKeys.has(normalizeLogKey(key)) && item !== null && item !== undefined
+        ? '[REDACTED]'
+        : redactLogValue(item, seen),
+    ])
+  );
+  seen.delete(value);
+  return redacted;
+};
+
 export function getLogBlockLabel(message: unknown): string | undefined {
   if (!message || typeof message !== 'object') return undefined;
 
@@ -19,5 +77,30 @@ export function getLogBlockLabel(message: unknown): string | undefined {
   }
 
   const methodName = method ?? payload?.method;
-  return methodName;
+  if (methodName && (LogLabelMethod.has(methodName) || isSigningMethod(methodName))) {
+    return methodName;
+  }
+
+  return undefined;
+}
+
+export function getSafeLogPayload(value: unknown, blockLabel?: string): unknown {
+  if (blockLabel && (LogBlockEvent.has(blockLabel) || isSigningMethod(blockLabel))) {
+    return { method: blockLabel, payload: '[REDACTED]' };
+  }
+
+  const redactedValue = redactLogValue(value, new WeakSet());
+  if (
+    blockLabel &&
+    redactedValue &&
+    typeof redactedValue === 'object' &&
+    !Array.isArray(redactedValue)
+  ) {
+    return { ...redactedValue, method: blockLabel };
+  }
+  return redactedValue;
+}
+
+export function formatLogMethodLabel(label: string, methodName?: string): string {
+  return methodName ? `${label} [${methodName}]` : label;
 }

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

@@ -18,7 +18,7 @@ export function assertCompleteDeviceSession(
   ) {
     throw ERRORS.TypedError(
       HardwareErrorCode.RuntimeError,
-      'DeviceSessionGet returned an incomplete DeviceSession response.'
+      'Device returned an incomplete DeviceSession response.'
     );
   }
 }

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

@@ -4,6 +4,7 @@ import type {
   DeviceInfoGet,
   DeviceSEInfo,
   DeviceStatus,
+  ProtocolInfo,
   ProtocolV2DeviceInfo,
 } from '@onekeyfe/hd-transport';
 import type { DeviceCommands } from '../../device/DeviceCommands';
@@ -53,27 +54,54 @@ export const getProtocolV2SeState = (se?: DeviceSEInfo): ProtocolV2SeStateLabel
 export const getProtocolV2SeType = (se?: DeviceSEInfo): string | null =>
   normalizeEnumValue(DeviceSeType, se?.type);
 
-export type ProtocolV2RuntimeMode = 'normal' | 'bootloader';
+export type ProtocolV2RuntimeMode = 'normal' | 'bootloader' | 'romloader';
 
 /**
- * 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.
- *
- * The temporary contract has two states: DeviceStatusGet success means normal and
- * failure means bootloader. Do not infer mode from application/SE/romloader fields.
+ * Protocol V2 fingerprints use:
+ * <binary>__<version>__<commit>__<PROD|DEV>__<DEBUG|RELEASE>
  */
-export const getProtocolV2RuntimeMode = ({
-  deviceInfo: _deviceInfo,
-  deviceStatusAvailable,
-}: {
-  deviceInfo?: ProtocolV2DeviceInfo | null;
-  deviceStatusAvailable: boolean;
-}): ProtocolV2RuntimeMode => {
-  if (deviceStatusAvailable) return 'normal';
-  return 'bootloader';
+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
+): ProtocolV2RuntimeMode | undefined => {
+  const binary = parseProtocolV2BuildFingerprint(protocolInfo.build_fingerprint)?.binary;
+  if (binary === 'application') return 'normal';
+  return binary;
+};
+
+// 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,
@@ -131,6 +159,20 @@ 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 async function requestProtocolV2ProtocolInfo({
+  commands,
+  timeoutMs,
+}: {
+  commands: DeviceCommands;
+  timeoutMs?: number;
+}): Promise<ProtocolInfo> {
+  const response =
+    timeoutMs === undefined
+      ? await commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {})
+      : await commands.typedCall('ProtocolInfoRequest', 'ProtocolInfo', {}, { timeoutMs });
+  return response.message;
+}
+
 export async function requestProtocolV2DeviceInfo({
   commands,
   timeoutMs = PROTOCOL_V2_DEVICE_INFO_TIMEOUT_MS,

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

@@ -1,13 +1,18 @@
 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,
   getProtocolV2RuntimeMode,
   getProtocolV2SeState,
   getProtocolV2SeType,
+  parseProtocolV2BuildFingerprint,
+  requestProtocolV2ProtocolInfo,
+  supportsProtocolV2Message,
 } from './features';
 export type {
+  ProtocolV2BuildFingerprint,
   ProtocolV2DeviceInfo,
   ProtocolV2FirmwareImageInfo,
   ProtocolV2SEInfo,

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

@@ -2,14 +2,19 @@ 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>([
+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 => LOCK_FREE_DEVICE_SETTINGS.has(key as keyof DeviceSettings))
+  Object.keys(settings).every(key => lockFreeDeviceSettings.has(key as keyof DeviceSettings))
     ? 'none'
     : 'unlock-before-run';
 

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

@@ -1,7 +1,7 @@
 import { LoggerNames, getLogger } from '../../utils';
 import { isDeviceLockedError } from './lockedError';
 import { isProtocolV2UiEnabled, resolveProtocolV2UiInteraction } from './uiInteraction';
-import { restoreProtocolV2WalletSession } from './walletSession';
+import { refreshProtocolV2DeviceStatus, restoreProtocolV2WalletSession } from './walletSession';
 
 import type { BaseMethod } from '../../api/BaseMethod';
 import type { Device } from '../../device/Device';
@@ -46,8 +46,23 @@ export async function runMethodWithUnlockRetry(
   uiCoordinator?: UiInteractionCoordinator
 ) {
   const shouldEmitUi = isProtocolV2UiEnabled(method);
+  const isProtocolV2 = device.isProtocolV2();
+  const requiresFreshStatus =
+    isProtocolV2 &&
+    method.unlockPolicy === 'unlock-before-run' &&
+    !device.isBootloader?.() &&
+    !device.isRomloader?.();
+
+  if (requiresFreshStatus) {
+    await refreshProtocolV2DeviceStatus(device);
+  }
+
   const shouldUnlockBeforeRun =
-    device.isProtocolV2() && method.unlockPolicy !== 'none' && device.features?.unlocked === false;
+    isProtocolV2 &&
+    method.unlockPolicy !== 'none' &&
+    !device.isBootloader?.() &&
+    !device.isRomloader?.() &&
+    device.features?.unlocked === false;
 
   if (shouldUnlockBeforeRun) {
     if (shouldEmitUi) {
@@ -68,11 +83,7 @@ export async function runMethodWithUnlockRetry(
   try {
     return await method.run();
   } catch (error) {
-    if (
-      !device.isProtocolV2() ||
-      method.unlockPolicy !== 'retry-on-locked' ||
-      !isDeviceLockedError(error)
-    ) {
+    if (!isProtocolV2 || method.unlockPolicy !== 'retry-on-locked' || !isDeviceLockedError(error)) {
       throw error;
     }
 

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

@@ -3,11 +3,31 @@ import { DeviceSessionPinType } from '@onekeyfe/hd-transport';
 
 import { DEVICE } from '../../events';
 import { assertCompleteDeviceSession } from './deviceSession';
-import { isDeviceLockedError } from './lockedError';
 
-import type { DeviceSessionGet } from '@onekeyfe/hd-transport';
+import type { DeviceSessionAskPassphrase, DeviceSessionGet } from '@onekeyfe/hd-transport';
 import type { Device } from '../../device/Device';
 
+const HOST_PASSPHRASE_MAX_BYTES = 50;
+
+const isWalletSessionInvalidError = (error: unknown) =>
+  typeof error === 'object' &&
+  error !== null &&
+  'errorCode' in error &&
+  (error as { errorCode?: unknown }).errorCode === HardwareErrorCode.WalletSessionInvalid;
+
+const utf8ByteLength = (value: string): number | undefined => {
+  let length = 0;
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint >= 0xd800 && codePoint <= 0xdfff) return undefined;
+    if (codePoint <= 0x7f) length += 1;
+    else if (codePoint <= 0x7ff) length += 2;
+    else if (codePoint <= 0xffff) length += 3;
+    else length += 4;
+  }
+  return length;
+};
+
 export async function requestProtocolV2DeviceStatus(device: Device) {
   const { message } = await device.commands.typedCall('DeviceStatusGet', 'DeviceStatus', {});
   return message;
@@ -24,41 +44,20 @@ const negotiateEventlessWalletSession = async (device: Device) => {
   });
 };
 
-const getDeviceSession = async (device: Device, request: DeviceSessionGet) => {
-  try {
-    return await device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
-  } catch (error) {
-    if (!isDeviceLockedError(error)) {
-      throw error;
-    }
-    await device.unlockDevice(DeviceSessionPinType.Main);
-    return device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
-  }
-};
+const getDeviceSession = async (device: Device, request: DeviceSessionGet) =>
+  device.commands.typedCall('DeviceSessionGet', 'DeviceSession', request);
 
-const askDevicePassphrase = async (device: Device, passphrase?: string) => {
-  const request = () =>
-    device.commands.typedCall(
-      'DeviceSessionAskPassphrase',
-      'Success',
-      passphrase ? { passphrase, on_device: false } : { on_device: true }
-    );
-  try {
-    return await request();
-  } catch (error) {
-    if (!isDeviceLockedError(error)) {
-      throw error;
-    }
-    await device.unlockDevice(DeviceSessionPinType.Main);
-    return request();
-  }
+const askDevicePassphrase = async (device: Device, requestPayload: DeviceSessionAskPassphrase) => {
+  await device.commands.typedCall('DeviceSessionAskPassphrase', 'Success', requestPayload);
+  await refreshProtocolV2DeviceStatus(device);
 };
 
-const selectDeviceSession = async (device: Device) => {
+const selectDeviceSession = async (device: Device, expectedPassphraseState?: string) => {
   const existsAttachPinUser = device.features?.attachToPinEnabled === true;
   const metadata = {
     source: 'wallet-session-coordinator' as const,
-    reason: 'open-wallet' as const,
+    reason: expectedPassphraseState ? ('session-recovery' as const) : ('open-wallet' as const),
+    ...(expectedPassphraseState ? { expectedPassphraseState } : {}),
   };
   const response = await device.commands.promptPassphrase(
     {
@@ -68,8 +67,21 @@ const selectDeviceSession = async (device: Device) => {
     },
     { cancelDeviceOnReject: false }
   );
-  const hasHostPassphrase =
-    typeof response.passphrase === 'string' && response.passphrase.length > 0;
+  const hostPassphrase =
+    typeof response.passphrase === 'string' ? response.passphrase.normalize('NFKD') : undefined;
+  const hasHostPassphrase = typeof hostPassphrase === 'string' && hostPassphrase.length > 0;
+  const hostPassphraseByteLength = hasHostPassphrase ? utf8ByteLength(hostPassphrase) : undefined;
+  if (
+    hasHostPassphrase &&
+    (hostPassphrase.includes('\0') ||
+      hostPassphraseByteLength === undefined ||
+      hostPassphraseByteLength > HOST_PASSPHRASE_MAX_BYTES)
+  ) {
+    throw ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      `Host passphrase must contain 1 to ${HOST_PASSPHRASE_MAX_BYTES} valid UTF-8 bytes without NUL.`
+    );
+  }
   const selections = [
     hasHostPassphrase,
     response.passphraseOnDevice === true,
@@ -96,26 +108,38 @@ const selectDeviceSession = async (device: Device) => {
   }
 
   if (hasHostPassphrase) {
-    await askDevicePassphrase(device, response.passphrase);
+    await askDevicePassphrase(device, {
+      passphrase: hostPassphrase,
+      on_device: false,
+    });
     return getDeviceSession(device, {});
   }
 
   device.emit(DEVICE.PASSPHRASE_ON_DEVICE, device, metadata);
-  await askDevicePassphrase(device);
+  await askDevicePassphrase(device, { on_device: true });
   return getDeviceSession(device, {});
 };
 
 export async function getProtocolV2WalletSession(
   device: Device,
   options?: {
+    forceWalletSelection?: boolean;
+    /** @deprecated 兼容旧 getPassphraseState；新流程使用 forceWalletSelection。 */
     initSession?: boolean;
     expectedPassphraseState?: string;
     onlyMainPin?: boolean;
     resumeOnly?: boolean;
   }
 ) {
-  if (options?.initSession) {
-    device.clearInternalState();
+  const forceWalletSelection =
+    options?.forceWalletSelection === true || options?.initSession === true;
+
+  if (forceWalletSelection) {
+    if (options.onlyMainPin) {
+      device.clearStandardInternalState?.();
+    } else {
+      device.clearInternalState();
+    }
     device.passphraseState = undefined;
   }
 
@@ -124,35 +148,54 @@ export async function getProtocolV2WalletSession(
   if (options?.onlyMainPin) {
     device.passphraseState = undefined;
   }
-  const expectedPassphraseState = options?.onlyMainPin
+  let expectedPassphraseState = options?.onlyMainPin
     ? undefined
     : options?.expectedPassphraseState ?? device.passphraseState;
 
-  if (device.features?.unlocked === false) {
-    await device.unlockDevice(DeviceSessionPinType.Main);
-  }
-
-  if (options?.onlyMainPin || device.getCurrentPassphraseProtection() === false) {
-    return {
-      passphraseState: undefined,
-      newSession: undefined,
-      unlockedAttachPin: device.features?.unlockedAttachPin ?? false,
-      resumed: false,
-    };
-  }
-
+  const cachedStandardSession = options?.onlyMainPin
+    ? device.getStandardInternalState?.()
+    : undefined;
   const cachedSessionId =
-    typeof device.getInternalState === 'function' ? device.getInternalState() : undefined;
+    !options?.onlyMainPin && typeof device.getInternalState === 'function'
+      ? device.getInternalState()
+      : undefined;
   let response;
   let resumed = false;
 
-  if (cachedSessionId && expectedPassphraseState) {
+  if (options?.onlyMainPin) {
+    expectedPassphraseState = cachedStandardSession?.passphraseState;
+    if (cachedStandardSession) {
+      try {
+        if (device.features?.unlockedAttachPin === true) {
+          await device.unlockDevice(DeviceSessionPinType.Main);
+        }
+        response = await getDeviceSession(device, {
+          session_id: cachedStandardSession.sessionId,
+        });
+        resumed = true;
+      } catch (error) {
+        device.clearStandardInternalState?.();
+        if (!isWalletSessionInvalidError(error)) {
+          throw error;
+        }
+        resumed = false;
+      }
+    }
+
+    if (!response) {
+      await device.unlockDevice(DeviceSessionPinType.Main);
+      response = await getDeviceSession(device, {});
+    }
+  } else if (cachedSessionId && expectedPassphraseState) {
     try {
       response = await getDeviceSession(device, { session_id: cachedSessionId });
       resumed = true;
     } catch (error) {
       device.clearInternalState();
-      throw error;
+      if (options?.resumeOnly || !isWalletSessionInvalidError(error)) {
+        throw error;
+      }
+      resumed = false;
     }
   }
 
@@ -161,28 +204,67 @@ export async function getProtocolV2WalletSession(
       device.clearInternalState();
       throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
     }
-    response = await selectDeviceSession(device);
+    response = await selectDeviceSession(device, expectedPassphraseState);
   }
 
-  const { message } = response;
+  let { message } = response;
   try {
     assertCompleteDeviceSession(message);
   } catch (error) {
-    device.clearInternalState();
+    if (options?.onlyMainPin) {
+      device.clearStandardInternalState?.();
+    } else {
+      device.clearInternalState();
+    }
     throw error;
   }
   if (expectedPassphraseState && expectedPassphraseState !== message.btc_test_address) {
-    device.clearInternalState();
-    throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
+    resumed = false;
+    if (options?.resumeOnly) {
+      device.clearInternalState();
+      throw ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid);
+    }
+    if (options?.onlyMainPin) {
+      device.clearStandardInternalState?.();
+      await device.unlockDevice(DeviceSessionPinType.Main);
+      response = await getDeviceSession(device, {});
+    } else {
+      device.clearInternalState();
+      response = await selectDeviceSession(device, expectedPassphraseState);
+    }
+    message = response.message;
+    try {
+      assertCompleteDeviceSession(message);
+    } catch (error) {
+      if (options?.onlyMainPin) {
+        device.clearStandardInternalState?.();
+      } else {
+        device.clearInternalState();
+      }
+      throw error;
+    }
+    if (expectedPassphraseState !== message.btc_test_address) {
+      if (options?.onlyMainPin) {
+        device.clearStandardInternalState?.();
+      } else {
+        device.clearInternalState();
+      }
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
+    }
   }
 
-  device.updateInternalState(
+  const internalStateArgs = [
     true,
     message.btc_test_address,
     device.getCurrentDeviceId(),
     message.session_id,
-    options?.initSession ? null : cachedSessionId ?? null
-  );
+    forceWalletSelection ? null : cachedSessionId ?? null,
+  ] as const;
+  if (options?.onlyMainPin) {
+    device.updateInternalState(...internalStateArgs, 'standard');
+  } else {
+    device.updateInternalState(...internalStateArgs);
+  }
 
   return {
     passphraseState: message.btc_test_address,

package/src/types/api/protocolV2.ts

@@ -1,5 +1,5 @@
 import type { CommonParams, Response } from '../params';
-import type { DevOnboardingStatus, Success } from '@onekeyfe/hd-transport';
+import type { OnboardingStatus, Success } from '@onekeyfe/hd-transport';
 import type { DeviceRebootParams } from '../../api/protocol-v2/helpers';
 import type {
   DeviceUploadWallpaperParams,
@@ -45,7 +45,7 @@ export declare function deviceReboot(
 export declare function deviceGetOnboardingStatus(
   connectId: string,
   params?: CommonParams
-): Response<DevOnboardingStatus>;
+): Response<OnboardingStatus>;
 
 export declare function deviceUploadWallpaper(
   connectId: string,

package/src/types/device.ts

@@ -1,4 +1,4 @@
-import { EDeviceType, type EFirmwareType } from '@onekeyfe/hd-shared';
+import { EDeviceType, type EFirmwareType, type HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 
 import type { IVersionArray } from './settings';
 import type { PROTO } from '../constants';
@@ -7,6 +7,7 @@ import type {
   OneKeyDeviceCommType,
   ProtocolV2DeviceInfo,
   DeviceStatus as ProtocolV2DeviceStatus,
+  ProtocolInfo as ProtocolV2ProtocolInfo,
 } from '@onekeyfe/hd-transport';
 
 export type DeviceStatus = 'available' | 'occupied' | 'used';
@@ -28,6 +29,8 @@ export type UnavailableCapabilities = { [key: string]: UnavailableCapability };
 
 export type KnownDevice = {
   connectId: string | null;
+  /** Protocol family confirmed by the transport's active probe. */
+  connectProtocol?: HardwareConnectProtocol;
   /**
    * Stable physical-device identity. Current SDK responses always include this
    * value; it remains optional in the type during the uuid compatibility window.
@@ -46,7 +49,7 @@ export type KnownDevice = {
   /** Current SDK/transport usage state for connection indicators. */
   status?: DeviceStatus;
   mode: EOneKeyDeviceMode;
-  features?: Features;
+  features: Features;
   /** Unified SDK device-state snapshot; features remains a legacy projection. */
   state?: DeviceState;
   unavailableCapabilities: UnavailableCapabilities;
@@ -61,6 +64,8 @@ export type KnownDevice = {
 
 export type SearchDevice = {
   connectId: string | null;
+  /** Protocol family confirmed by the transport's active probe. */
+  connectProtocol?: HardwareConnectProtocol;
   /**
    * Available after device initialization. BLE discovery does not connect to the
    * device, so it returns null until a later initialized device response. Current
@@ -155,6 +160,7 @@ export type DeviceFeaturesVerify = {
 export type DeviceFeaturesRaw = {
   protocolV1Features?: PROTO.Features;
   protocolV1OneKeyFeatures?: OnekeyFeatures;
+  protocolV2ProtocolInfo?: ProtocolV2ProtocolInfo;
   protocolV2DeviceInfo?: ProtocolV2DeviceInfo;
   protocolV2DeviceStatus?: ProtocolV2DeviceStatus;
 };

package/src/types/params.ts

@@ -60,7 +60,8 @@ export interface CommonParams {
   usePreInitialize?: boolean;
 
   /**
-   * Expected transport protocol. If omitted, SDK probes Protocol V1 then Protocol V2.
+   * Strictly expected transport protocol. The SDK actively verifies this value and
+   * rejects a mismatch. If omitted, a cached protocol only influences probe order.
    */
   connectProtocol?: HardwareConnectProtocol;
 }