@onekeyfe/hd-core 1.2.0-alpha.47 → 1.2.0-alpha.49

package/src/device/Device.ts

@@ -95,6 +95,7 @@ export type InitOptions = {
   passphraseState?: string;
   deriveCardano?: boolean;
   connectProtocol?: HardwareConnectProtocol;
+  forceProtocolDetection?: boolean;
   protocolV2DeviceInfoTimeoutMs?: number;
   /** Refresh Protocol V2 runtime state before returning discovery results. */
   refreshRuntimeState?: boolean;
@@ -377,7 +378,10 @@ export class Device extends EventEmitter {
    * Device connect
    * @returns {Promise<boolean>}
    */
-  connect(connectProtocol?: HardwareConnectProtocol) {
+  connect(
+    connectProtocol?: HardwareConnectProtocol,
+    options?: { forceProtocolDetection?: boolean }
+  ) {
     const env = DataManager.getSettings('env');
     // eslint-disable-next-line no-async-promise-executor
     return new Promise<boolean>(async (resolve, reject) => {
@@ -387,7 +391,7 @@ export class Device extends EventEmitter {
           return;
         }
         try {
-          await this.acquire(connectProtocol);
+          await this.acquire(connectProtocol, options);
           resolve(true);
         } catch (error) {
           reject(error);
@@ -397,7 +401,7 @@ export class Device extends EventEmitter {
       // 不存在 Session ID 或存在 Session ID 但设备在别处使用，都需要 acquire 获取最新 sessionID
       if (!this.mainId || (!this.isUsedHere() && this.originalDescriptor)) {
         try {
-          await this.acquire(connectProtocol);
+          await this.acquire(connectProtocol, options);
           resolve(true);
         } catch (error) {
           reject(error);
@@ -414,11 +418,16 @@ export class Device extends EventEmitter {
 
   async acquire(
     expectedProtocol?: HardwareConnectProtocol,
-    options?: { throwOnRunPromiseError?: boolean }
+    options?: { throwOnRunPromiseError?: boolean; forceProtocolDetection?: boolean }
   ) {
     const env = DataManager.getSettings('env');
     const mainIdKey = DataManager.isBleConnect(env) ? 'id' : 'session';
-    const protocolHint = expectedProtocol ? undefined : this.originalDescriptor.protocolType;
+    const previousProtocol = this.originalDescriptor.protocolType;
+    // A protocol stored after a successful probe is authoritative. Only the explicit
+    // first-connection/recovery path may bypass it and probe both protocols again.
+    const strictProtocol = options?.forceProtocolDetection
+      ? undefined
+      : expectedProtocol ?? this.originalDescriptor.protocolType;
     try {
       let acquireResult: unknown;
       if (DataManager.isBleConnect(env)) {
@@ -430,8 +439,8 @@ export class Device extends EventEmitter {
           this.originalDescriptor.id,
           undefined,
           true,
-          expectedProtocol,
-          protocolHint
+          strictProtocol,
+          undefined
         );
         this.mainId = (acquireResult as any)?.uuid ?? '';
         Log.debug('Expected uuid:', this.mainId);
@@ -440,24 +449,31 @@ export class Device extends EventEmitter {
           this.originalDescriptor.path,
           this.originalDescriptor.session,
           undefined,
-          expectedProtocol,
-          protocolHint
+          strictProtocol,
+          undefined
         );
         this.mainId = acquireResult as string | undefined;
         Log.debug('Expected session id:', this.mainId);
       }
-      this.deviceAcquired = true;
-      this.updateDescriptor({ [mainIdKey]: this.mainId } as unknown as DeviceDescriptor);
-
       // Propagate protocol version detected during acquire.
       const detectedProtocol =
         (acquireResult as { protocolType?: HardwareConnectProtocol } | undefined)?.protocolType ??
         TransportManager.transport?.getProtocolType?.(
           DataManager.isBleConnect(env) ? this.originalDescriptor.id : this.originalDescriptor.path
         );
+      if (options?.forceProtocolDetection && !detectedProtocol) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.RuntimeError,
+          `Active protocol detection returned no protocol for ${
+            this.originalDescriptor.path || this.originalDescriptor.id
+          }`
+        );
+      }
       if (detectedProtocol) {
         this.originalDescriptor.protocolType = detectedProtocol;
       }
+      this.deviceAcquired = true;
+      this.updateDescriptor({ [mainIdKey]: this.mainId } as unknown as DeviceDescriptor);
 
       if (this.commands) {
         await this.commands.dispose(false);
@@ -465,6 +481,22 @@ export class Device extends EventEmitter {
 
       this.commands = new DeviceCommands(this, this.mainId ?? '');
     } catch (error) {
+      if (options?.forceProtocolDetection) {
+        this.originalDescriptor.protocolType = previousProtocol;
+        const failedSession = this.mainId;
+        this.deviceAcquired = false;
+        if (failedSession) {
+          try {
+            await this.deviceConnector?.release?.(failedSession, false);
+          } catch (releaseError) {
+            Log.debug('Failed to release an unsuccessful protocol probe', releaseError);
+          }
+        }
+        if (!DataManager.isBleConnect(env)) {
+          this.mainId = null;
+          this.updateDescriptor({ session: null } as DeviceDescriptor);
+        }
+      }
       if (options?.throwOnRunPromiseError) {
         throw error;
       }
@@ -1349,11 +1381,17 @@ export class Device extends EventEmitter {
       }
     };
 
-    if (!this.isUsedHere() || this.commands.disposed) {
-      const env = DataManager.getSettings('env');
+    const env = DataManager.getSettings('env');
+    if (options.forceProtocolDetection && env !== 'react-native' && this.isUsedHere()) {
+      await this.release();
+    }
+
+    if (options.forceProtocolDetection || !this.isUsedHere() || this.commands.disposed) {
       if (env !== 'react-native') {
         try {
-          await this.acquire(options.connectProtocol);
+          await this.acquire(options.connectProtocol, {
+            forceProtocolDetection: options.forceProtocolDetection,
+          });
         } catch (error) {
           clearRunPromise();
           runPromise.reject(error);

package/src/device/DevicePool.ts

@@ -156,7 +156,9 @@ export class DevicePool extends EventEmitter {
     if (!device) {
       device = Device.fromDescriptor(descriptor);
       device.deviceConnector = this.connector;
-      await device.connect(initOptions?.connectProtocol);
+      await device.connect(initOptions?.connectProtocol, {
+        forceProtocolDetection: initOptions?.forceProtocolDetection,
+      });
       try {
         await device.initialize(initOptions);
         if (initOptions?.refreshRuntimeState && device.isProtocolV2()) {
@@ -181,7 +183,10 @@ export class DevicePool extends EventEmitter {
           refreshError = error;
         }
       },
-      { connectProtocol: initOptions.connectProtocol }
+      {
+        connectProtocol: initOptions.connectProtocol,
+        forceProtocolDetection: initOptions.forceProtocolDetection,
+      }
     );
     if (refreshError instanceof Error) throw refreshError;
     if (refreshError) throw new Error(String(refreshError));

package/src/inject.ts

@@ -1,3 +1,4 @@
+import type { HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 import type { Unsuccessful } from './types';
 import type { EventEmitter } from 'events';
 import type { CallMethod } from './events';
@@ -39,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,
@@ -49,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);
@@ -66,7 +112,9 @@ export const inject = ({
 
     init,
 
-    call,
+    call: protocolAwareCall.call,
+
+    setDeviceConnectProtocol: protocolAwareCall.setDeviceConnectProtocol,
 
     dispose,
 
@@ -78,7 +126,7 @@ export const inject = ({
 
     switchTransport,
 
-    ...createCoreApi(call),
+    ...createCoreApi(protocolAwareCall.call),
   };
   return api;
 };
@@ -93,6 +141,7 @@ export const createCoreApi = (
   | 'removeAllListeners'
   | 'init'
   | 'call'
+  | 'setDeviceConnectProtocol'
   | 'dispose'
   | 'uiResponse'
   | 'cancel'
@@ -105,6 +154,12 @@ export const createCoreApi = (
    * 搜索设备
    */
   searchDevices: params => call({ ...params, method: 'searchDevices' }),
+  detectDeviceConnectProtocol: connectId =>
+    call({
+      connectId,
+      method: 'detectDeviceConnectProtocol',
+      forceProtocolDetection: true,
+    }),
 
   /**
    * 获取设备信息

package/src/lowLevelInject.ts

@@ -1,4 +1,4 @@
-import { createCoreApi } from './inject';
+import { createCoreApi, createProtocolAwareCall } from './inject';
 
 import type { EventEmitter } from 'events';
 import type { CallMethod, CoreMessage } from './events';
@@ -33,6 +33,7 @@ export const lowLevelInject = ({
   switchTransport,
   addHardwareGlobalEventListener,
 }: LowLevelInjectApi): LowLevelCoreApi => {
+  const protocolAwareCall = createProtocolAwareCall(call);
   const api: LowLevelCoreApi = {
     addHardwareGlobalEventListener,
     removeAllListeners: type => {
@@ -41,7 +42,9 @@ export const lowLevelInject = ({
 
     init,
 
-    call,
+    call: protocolAwareCall.call,
+
+    setDeviceConnectProtocol: protocolAwareCall.setDeviceConnectProtocol,
 
     dispose,
 
@@ -55,7 +58,7 @@ export const lowLevelInject = ({
 
     emit: () => {},
 
-    ...createCoreApi(call),
+    ...createCoreApi(protocolAwareCall.call),
   };
   return api;
 };

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

@@ -1,4 +1,5 @@
 import { sha256 } from '@noble/hashes/sha256';
+import { PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE } from '@onekeyfe/hd-transport';
 
 import type {
   IProtocolV2BootResources,
@@ -7,7 +8,6 @@ import type {
   IProtocolV2Resources,
 } from '../../types';
 import type { DeviceCommands } from '../../device/DeviceCommands';
-import type { ResourceInventory } from '@onekeyfe/hd-transport';
 
 export const PROTOCOL_V2_RESOURCE_TYPES = [
   'images',
@@ -31,23 +31,16 @@ export const PROTOCOL_V2_RESOURCE_DEVICE_PATHS: Readonly<Record<IProtocolV2Resou
 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;
 
-const RESOURCE_TYPE_BY_DEVICE_VALUE: Readonly<Record<string, IProtocolV2ResourceType>> = {
-  '0': 'images',
-  IMAGES: 'images',
-  '1': 'animation',
-  ANIMATION: 'animation',
-  '2': 'wallpaper',
-  WALLPAPER: 'wallpaper',
-  '3': 'translations',
-  TRANSLATIONS: 'translations',
-  '4': 'roobert',
-  ROOBERT: 'roobert',
-  '5': 'noto',
-  NOTO: 'noto',
-};
-
 export type ProtocolV2ResourceInventoryItem = {
   type: IProtocolV2ResourceType;
   size: number;
@@ -61,57 +54,153 @@ export type ProtocolV2ResourceUpdatePlan = {
   resources: IProtocolV2Resource[];
 };
 
-/** Normalize the success-only device response into the SDK resource identity shape. */
-export function parseProtocolV2ResourceInventory(
-  value: ResourceInventory | unknown
-): ProtocolV2ResourceInventoryItem[] {
-  const items = (value as { items?: unknown })?.items;
-  if (!Array.isArray(items)) {
-    throw new Error('Invalid Pro2 resource inventory: items must be an array');
+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;
   }
-
-  const inventory = items.map((item, index) => {
-    if (!item || typeof item !== 'object') {
-      throw new Error(`Invalid Pro2 resource inventory item at ${index}`);
+  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;
     }
-    const raw = item as { type?: unknown; size?: unknown; header_hash?: unknown };
-    const type = RESOURCE_TYPE_BY_DEVICE_VALUE[String(raw.type).toUpperCase()];
-    if (!type) {
-      throw new Error(`Invalid Pro2 resource inventory type at ${index}`);
+  }
+  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);
     }
-    if (!Number.isSafeInteger(raw.size) || Number(raw.size) <= 0) {
-      throw new Error(`Invalid Pro2 resource inventory size at ${index}`);
+    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 {
-      type,
-      size: Number(raw.size),
-      headerHash: normalizeHex(raw.header_hash, SHA3_512_HEX_LENGTH, 'inventory headerHash'),
-    };
-  });
+    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(
+    ''
+  );
+}
 
-  if (new Set(inventory.map(item => item.type)).size !== inventory.length) {
-    throw new Error('Invalid Pro2 resource inventory: duplicate resource type');
+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 PROTOCOL_V2_RESOURCE_TYPES.flatMap(type => {
-    const item = inventory.find(candidate => candidate.type === type);
-    return item ? [item] : [];
-  });
+  return bytesToHex(
+    bytes.slice(
+      PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET,
+      PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE
+    )
+  );
 }
 
-export async function requestProtocolV2ResourceInventory({
+async function readProtocolV2ResourceIdentity({
   commands,
+  resource,
+  chunkSize,
   timeoutMs = PROTOCOL_V2_RESOURCE_INVENTORY_TIMEOUT_MS,
 }: {
-  commands: DeviceCommands;
+  commands: Pick<DeviceCommands, 'typedCall'>;
+  resource: IProtocolV2Resource;
+  chunkSize: number;
   timeoutMs?: number;
-}): Promise<ProtocolV2ResourceInventoryItem[]> {
-  const { message } = await commands.typedCall(
-    'ResourceInventoryGet',
-    'ResourceInventory',
-    {},
+}): Promise<ProtocolV2ResourceInventoryItem | undefined> {
+  const path = PROTOCOL_V2_RESOURCE_DEVICE_PATHS[resource.type];
+  const pathInfo = await commands.typedCall(
+    'FilesystemPathInfoQuery',
+    'FilesystemPathInfo',
+    { path },
     { timeoutMs }
   );
-  return parseProtocolV2ResourceInventory(message);
+  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 {
@@ -213,7 +302,7 @@ export function parseProtocolV2Resources(value: unknown): IProtocolV2Resources |
   };
 }
 
-/** Compare the application inventory or select the full set for bootloader recovery. */
+/** 比较文件系统资源清单；恢复模式无法取得清单时回退到全量更新。 */
 export function buildProtocolV2ResourceUpdatePlan({
   resources,
   inventory,
@@ -225,14 +314,19 @@ export function buildProtocolV2ResourceUpdatePlan({
   mode: ProtocolV2ResourceUpdateMode;
   forced?: boolean;
 }): ProtocolV2ResourceUpdatePlan {
-  if (mode === 'bootloader-recovery' || forced) {
+  if (forced) {
     return {
       status: resources.length > 0 ? 'outdated' : 'valid',
       resources: [...resources],
     };
   }
   if (!inventory) {
-    return { status: 'unknown', resources: [] };
+    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]));

package/src/topLevelInject.ts

@@ -1,6 +1,6 @@
 import EventEmitter from 'events';
 
-import { createCoreApi } from './inject';
+import { createCoreApi, createProtocolAwareCall } from './inject';
 
 import type { ConnectSettings } from './types/settings';
 import type { CoreApi } from './types/api';
@@ -19,6 +19,7 @@ export const topLevelInject = () => {
     if (!lowLevelApi) return Promise.resolve(undefined);
     return lowLevelApi.call(params);
   };
+  const protocolAwareCall = createProtocolAwareCall(call);
   const api: CoreApi = {
     on: <T extends string, P extends (...args: any[]) => any>(type: T, fn: P) => {
       eventEmitter.on(type, fn);
@@ -37,9 +38,11 @@ export const topLevelInject = () => {
       return lowLevelApi?.init(settings) ?? Promise.resolve(false);
     },
 
-    call,
+    call: protocolAwareCall.call,
 
-    ...createCoreApi(call),
+    setDeviceConnectProtocol: protocolAwareCall.setDeviceConnectProtocol,
+
+    ...createCoreApi(protocolAwareCall.call),
 
     removeAllListeners: type => {
       eventEmitter.removeAllListeners(type);

package/src/types/api/detectDeviceConnectProtocol.ts

@@ -0,0 +1,7 @@
+import type { HardwareConnectProtocol } from '@onekeyfe/hd-shared';
+
+import type { Response } from '../params';
+
+export declare function detectDeviceConnectProtocol(
+  connectId: string
+): Response<HardwareConnectProtocol>;

package/src/types/api/index.ts

@@ -19,6 +19,7 @@ import type { checkBootloaderRelease } from './checkBootloaderRelease';
 import type { checkAllFirmwareRelease } from './checkAllFirmwareRelease';
 import type { checkFirmwareTypeAvailable } from './checkFirmwareTypeAvailable';
 import type { searchDevices } from './searchDevices';
+import type { detectDeviceConnectProtocol } from './detectDeviceConnectProtocol';
 import type { getFeatures } from './getFeatures';
 import type { getDeviceState } from './getDeviceState';
 import type { getOnekeyFeatures } from './getOnekeyFeatures';
@@ -145,6 +146,7 @@ import type { benfenSignMessage } from './benfenSignMessage';
 import type { neoGetAddress } from './neoGetAddress';
 import type { neoSignTransaction } from './neoSignTransaction';
 import type { ConnectSettings } from '../settings';
+import type { HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 
 export * from './export';
 export type { DeviceStateScope, GetDeviceStateParams } from './getDeviceState';
@@ -169,6 +171,14 @@ export type CoreApi = {
   removeAllListeners: typeof removeAllListeners;
   dispose: () => void | Promise<void>;
   call: (params: any) => Promise<any>;
+  /**
+   * Bind a protocol that has already been verified for one transport endpoint.
+   * Every later SDK call for the same connectId uses it as a strict expectation.
+   */
+  setDeviceConnectProtocol: (
+    connectId: string,
+    connectProtocol: HardwareConnectProtocol | undefined
+  ) => void;
   uiResponse: typeof uiResponse;
   cancel: (connectId?: string) => void;
   updateSettings: typeof updateSettings;
@@ -196,6 +206,7 @@ export type CoreApi = {
    * Device function
    */
   searchDevices: typeof searchDevices;
+  detectDeviceConnectProtocol: typeof detectDeviceConnectProtocol;
   promptWebDeviceAccess: typeof promptWebDeviceAccess;
   getFeatures: typeof getFeatures;
   getDeviceState: typeof getDeviceState;

package/src/types/params.ts

@@ -61,9 +61,15 @@ export interface CommonParams {
 
   /**
    * Strictly expected transport protocol. The SDK actively verifies this value and
-   * rejects a mismatch. If omitted, a cached protocol only influences probe order.
+   * rejects a mismatch. After a successful probe, the cached protocol is also strict.
    */
   connectProtocol?: HardwareConnectProtocol;
+
+  /**
+   * Ignore a previously bound protocol for this call and actively detect the
+   * protocol again. Intended for the first verified connection or explicit recovery.
+   */
+  forceProtocolDetection?: boolean;
 }
 
 export type Params<T> = CommonParams & T & { bundle?: undefined };