@onekeyfe/hd-core 1.2.0-alpha.16 → 1.2.0-alpha.160

package/src/core/index.ts

@@ -1,7 +1,13 @@
 import semver from 'semver';
 import EventEmitter from 'events';
+import {
+  DeviceSessionPinType,
+  TRANSPORT_EVENT,
+  isProtocolV2LinkDisabledError,
+} from '@onekeyfe/hd-transport';
 import {
   ERRORS,
+  ERROR_CODES_REQUIRE_DISCONNECT,
   ERROR_CODES_REQUIRE_RELEASE,
   HardwareError,
   HardwareErrorCode,
@@ -14,14 +20,7 @@ import {
   createNewFirmwareUnReleaseHardwareError,
 } from '@onekeyfe/hd-shared';
 
-import {
-  LoggerNames,
-  enableLog,
-  getLogger,
-  isMethodVersionRangeUnsupported,
-  setLoggerPostMessage,
-  wait,
-} from '../utils';
+import { LoggerNames, enableLog, getLogger, setLoggerPostMessage, wait } from '../utils';
 import {
   findDefectiveBatchDevice,
   getDefectiveDeviceInfo,
@@ -32,10 +31,12 @@ import {
   createRequestContext,
   createSdkTracingContext,
   formatRequestContext,
+  generateInstanceId,
   getActiveRequestsByDeviceInstance,
   updateRequestContext,
 } from '../utils/tracing';
 import { Device } from '../device/Device';
+import { checkLiveDeviceId } from '../device/deviceIdentity';
 import { DeviceList } from '../device/DeviceList';
 import { DevicePool } from '../device/DevicePool';
 import { PollingStateManager } from './PollingStateManager';
@@ -51,24 +52,38 @@ import {
   createDeviceMessage,
   createResponseMessage,
   createUiMessage,
+  formatLogMethodLabel,
+  getLogBlockLabel,
+  getSafeLogPayload,
 } from '../events';
 import TransportManager from '../data-manager/TransportManager';
 import DeviceConnector from '../device/DeviceConnector';
 import RequestQueue from './RequestQueue';
+import { consumeUiPromise, findUiPromiseForResponse, rejectUiPromises } from './uiPromiseRegistry';
 import { registerHardwareUiEventListeners } from './deviceEventRegistration';
 import { getSynchronize } from '../utils/getSynchronize';
-import { runMethodWithUnlockRetry } from '../protocols/protocol-v2/unlockRetry';
+import { runMethodWithUnlockPolicy } from '../protocols/protocol-v2/unlockPolicyRunner';
+import {
+  ProtocolV2UiInteractionCoordinator,
+  isProtocolV2UiEnabled,
+} from '../protocols/protocol-v2/uiInteraction';
+import { createUiProgressMessageFilter } from '../utils/uiProgressThrottle';
 
 import type { ConnectSettings, Features, KnownDevice } from '../types';
 import type { CoreMessage, IFrameCallMessage, UiPromise, UiPromiseResponse } from '../events';
 import type { DeviceEvents, InitOptions, RunOptions } from '../device/Device';
 import type { SdkTracingContext } from '../utils/tracing';
 import type { Deferred } from '@onekeyfe/hd-shared';
-import type { LowlevelTransportSharedPlugin, OneKeyDeviceInfo } from '@onekeyfe/hd-transport';
+import type {
+  LowlevelTransportSharedPlugin,
+  OneKeyDeviceInfo,
+  TransportDeviceDisconnectEvent,
+} from '@onekeyfe/hd-transport';
 import type { BaseMethod } from '../api/BaseMethod';
 
 const Log = getLogger(LoggerNames.Core);
 const PRE_INITIALIZE_TTL_MS = 60 * 1000;
+const PRE_PENDING_CALL_TIMEOUT_MS = 15 * 1000;
 
 // Dedup/coalesce state for "pre-warm signal" methods (isPreWarmSignal),
 // keyed by getPreWarmKey(): coalesce in-flight, skip if warmed within TTL.
@@ -93,14 +108,15 @@ function hasDeriveCardano(method: BaseMethod): boolean {
 
 const parseInitOptions = (method?: BaseMethod): InitOptions => ({
   initSession: method?.payload.initSession,
-  passphraseState: method?.payload.passphraseState,
+  passphraseState: method?.payload.useEmptyPassphrase ? undefined : method?.payload.passphraseState,
   deviceId: method?.payload.deviceId,
   deriveCardano: method && hasDeriveCardano(method),
   connectProtocol: method?.payload.connectProtocol,
+  forceProtocolDetection: method?.payload.forceProtocolDetection,
   protocolV2DeviceInfoTimeoutMs: method?.payload.protocolV2DeviceInfoTimeoutMs,
 });
 
-let _core: Core;
+let _core: Core | undefined;
 let _deviceList: DeviceList | undefined;
 let _connector: DeviceConnector | undefined;
 let _uiPromises: UiPromise<UiPromiseResponse['type']>[] = []; // Waiting for ui response
@@ -125,6 +141,9 @@ const toError = (error: unknown): Error | undefined => {
   }
 };
 
+const isExpectedCompatibilityError = (error: unknown) =>
+  error instanceof HardwareError && error.errorCode === HardwareErrorCode.DeviceNotSupportMethod;
+
 const updateMethodRequestContext = (method: BaseMethod, updates: any) => {
   if (method.requestContext) {
     updateRequestContext(method.requestContext.responseID, updates);
@@ -144,11 +163,16 @@ export const callAPI = async (context: CoreContext, message: CoreMessage) => {
   }
 
   // find api method
-  let method: BaseMethod;
+  let method!: BaseMethod;
   try {
     method = findMethod(message as IFrameCallMessage);
     method.connector = _connector;
-    method.postMessage = postMessage;
+    const shouldPostMessage = createUiProgressMessageFilter();
+    method.postMessage = event => {
+      if (shouldPostMessage(event)) {
+        postMessage(event);
+      }
+    };
     method.setContext?.(context);
 
     method.requestContext = createRequestContext(method.responseID, method.name, {
@@ -160,11 +184,13 @@ export const callAPI = async (context: CoreContext, message: CoreMessage) => {
 
     method.init();
   } catch (error) {
-    return Promise.reject(error);
+    if (method) {
+      completeMethodRequestContext(method, error);
+      method.dispose();
+    }
+    return createResponseMessage(method?.responseID ?? message.id, false, { error });
   }
 
-  DevicePool.emitter.on(DEVICE.CONNECT, onDeviceConnectHandler);
-
   if (!method.useDevice) {
     updateMethodRequestContext(method, { status: 'running' });
     try {
@@ -271,26 +297,35 @@ const handlePreWarmSignal = async (
   }
 };
 
-const waitWithTimeout = async (promise: Promise<any>, timeout: number) => {
-  const timeoutPromise = new Promise((_, reject) => {
-    setTimeout(() => reject(new Error('Request timeout')), timeout);
-  });
-  return Promise.race([promise, timeoutPromise]);
-};
-
 const waitForPendingPromise = async (
-  getPrePendingCallPromise: () => Promise<void> | undefined,
-  removePrePendingCallPromise?: (promise: Promise<void> | undefined) => void
+  connectId: string,
+  getPrePendingCallPromise: (connectId: string) => Promise<void> | undefined,
+  removePrePendingCallPromise?: (connectId: string, promise: Promise<void>) => void
 ) => {
-  const pendingPromise = getPrePendingCallPromise();
+  const pendingPromise = getPrePendingCallPromise(connectId);
   if (pendingPromise) {
     Log.debug('pre pending call promise before call method, wait for it');
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
     try {
-      await waitWithTimeout(pendingPromise, 5 * 1000);
+      await Promise.race([
+        pendingPromise,
+        new Promise<void>(resolve => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            resolve();
+          }, PRE_PENDING_CALL_TIMEOUT_MS);
+        }),
+      ]);
     } catch (error) {
-      // ignore timeout error
+      // Cancellation is best-effort; the transport teardown owns recovery.
+    } finally {
+      if (timer) clearTimeout(timer);
+      removePrePendingCallPromise?.(connectId, pendingPromise);
+    }
+    if (timedOut) {
+      Log.warn('pre pending call promise timed out before call method', { connectId });
     }
-    removePrePendingCallPromise?.(pendingPromise);
     Log.debug('pre pending call promise before call method done');
   }
 };
@@ -302,7 +337,7 @@ const onCallDevice = async (
 ): Promise<any> => {
   let messageResponse: any;
 
-  const { requestQueue, getPrePendingCallPromise, setPrePendingCallPromise } = context;
+  const { requestQueue, getPrePendingCallPromise, removePrePendingCallPromise } = context;
 
   updateMethodRequestContext(method, { status: 'running' });
 
@@ -330,7 +365,11 @@ const onCallDevice = async (
     await context.waitForCallbackTasks(method.connectId);
   }
 
-  await waitForPendingPromise(getPrePendingCallPromise, setPrePendingCallPromise);
+  await waitForPendingPromise(
+    method.connectId ?? '',
+    getPrePendingCallPromise,
+    removePrePendingCallPromise
+  );
 
   const task = requestQueue.createTask(method);
 
@@ -359,7 +398,7 @@ const onCallDevice = async (
     );
   } catch (e) {
     preWarmCallbackTask?.resolve();
-    console.log('ensureConnected error: ', e);
+    Log.debug('ensureConnected error: ', e);
 
     completeMethodRequestContext(method, e);
 
@@ -398,17 +437,26 @@ const onCallDevice = async (
 
   registerHardwareUiEventListeners(device, {
     pin: onDevicePinHandler,
+    pinOnDevice: onEnterPinOnDeviceHandler,
+    pinOnDeviceComplete: onPinOnDeviceCompleteHandler,
     button: onDeviceButtonHandler,
     passphrase: message.payload.useEmptyPassphrase
       ? onEmptyPassphraseHandler
       : onDevicePassphraseHandler,
     passphraseOnDevice: onEnterPassphraseOnDeviceHandler,
+    attachPinOnDevice: onEnterAttachPinOnDeviceHandler,
   });
   device.on(DEVICE.FEATURES, onDeviceFeaturesHandler);
+  device.on(DEVICE.STATE, onDeviceStateHandler);
   device.on(
     DEVICE.SELECT_DEVICE_IN_BOOTLOADER_FOR_WEB_DEVICE,
     onSelectDeviceInBootloaderForWebDeviceHandler
   );
+
+  const protocolV2UiCoordinator = new ProtocolV2UiInteractionCoordinator(device, postMessage);
+  let protocolV2Operation = false;
+  let protocolV2CloseEmitted = false;
+  device.beginProtocolV2UiInteraction();
   device.on(
     DEVICE.SELECT_DEVICE_FOR_SWITCH_FIRMWARE_WEB_DEVICE,
     onSelectDeviceForSwitchFirmwareWebDeviceHandler
@@ -420,14 +468,17 @@ const onCallDevice = async (
       await context.waitForCallbackTasks(method.connectId, preWarmCallbackTask);
     }
 
-    await waitForPendingPromise(getPrePendingCallPromise, setPrePendingCallPromise);
+    await waitForPendingPromise(
+      method.connectId ?? '',
+      getPrePendingCallPromise,
+      removePrePendingCallPromise
+    );
 
     const inner = async (): Promise<void> => {
-      // Protocol V2 专属方法统一守卫：协议在 acquire/initialize 后已确定，
-      // 非 V2 设备直接抛出明确的 NotSupport 错误（见 BaseMethod.requireProtocolV2）。
-      if (method.requireProtocolV2 && !device.isProtocolV2()) {
-        throw createDeviceNotSupportMethodError(method.name, device.getCurrentFirmwareType());
-      }
+      // Protocol is established from an active device response during acquire/initialize.
+      // Reject unsupported methods before any method-specific device command is sent.
+      method.assertProtocolSupported(device.getProtocol(), device.getCurrentFirmwareType());
+      protocolV2Operation = device.isProtocolV2();
 
       // check firmware version
       const versionRange = device.getCurrentMethodVersionRange(
@@ -438,8 +489,8 @@ const onCallDevice = async (
       const deviceFirmwareType = device.getCurrentFirmwareType();
       let newVersionStatus: ReturnType<typeof DataManager.getFirmwareStatus> | undefined;
 
-      // 故障批次检测与远端强制升级门禁基于 V1 features/remote config，
-      // Pro2(V2) 暂不参与：profile 版的 firmwareStatus 需要 DataManager 支持后再接入。
+      // Defective-batch and forced-update gates depend on V1 features/remote config.
+      // Pro2 joins after DataManager supports its profile firmwareStatus.
       if (device.features && !device.isProtocolV2()) {
         await DataManager.checkAndReloadData();
 
@@ -487,10 +538,6 @@ const onCallDevice = async (
         }
       }
 
-      if (isMethodVersionRangeUnsupported(versionRange)) {
-        throw createDeviceNotSupportMethodError(method.name, deviceFirmwareType);
-      }
-
       if (versionRange) {
         if (semver.valid(versionRange.min) && semver.lt(currentFirmwareVersion, versionRange.min)) {
           if (newVersionStatus === 'none' || newVersionStatus === 'valid') {
@@ -541,89 +588,102 @@ const onCallDevice = async (
         );
       }
 
-      if (method.deviceId && method.checkDeviceId) {
-        const isSameDeviceID = device.checkDeviceId(method.deviceId);
-        if (!isSameDeviceID) {
-          return Promise.reject(ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError));
-        }
-      }
-
-      /**
-       * check firmware release info
-       */
-      method.checkFirmwareRelease();
+      try {
+        let deviceIdCheckedDuringUnlockPreflight = false;
+        const response = await runMethodWithUnlockPolicy<object>(method, device, {
+          uiCoordinator: protocolV2UiCoordinator,
+          afterStatusBeforeUnlock: () => {
+            if (method.deviceId && method.checkDeviceId) {
+              if (!device.checkDeviceId(method.deviceId)) {
+                throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
+              }
+              deviceIdCheckedDuringUnlockPreflight = true;
+            }
+          },
+          prepare: async () => {
+            if (method.deviceId && method.checkDeviceId && !deviceIdCheckedDuringUnlockPreflight) {
+              const isSameDeviceID = await checkLiveDeviceId(device, method.deviceId);
+              if (!isSameDeviceID) {
+                throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckDeviceIdError);
+              }
+            }
 
-      /**
-       * check additional supported feature
-       */
-      method.checkDeviceSupportFeature();
+            /**
+             * check firmware release info
+             */
+            method.checkFirmwareRelease();
 
-      // reconfigure messages
-      if (_deviceList && device.features && !device.isProtocolV2()) {
-        await TransportManager.reconfigure(device.features);
-      }
+            /**
+             * check additional supported feature
+             */
+            method.checkDeviceSupportFeature();
 
-      // Check to see if it is safe to use Passphrase
-      checkPassphraseEnableState(method, device.features);
+            // reconfigure messages
+            if (_deviceList && device.features && !device.isProtocolV2()) {
+              await TransportManager.reconfigure(device.features);
+            }
 
-      if (shouldCheckPassphraseState(method, device)) {
-        // check version
-        const support = device.supportNewPassphrase();
-        if (!support.support) {
-          return Promise.reject(
-            ERRORS.TypedError(
-              HardwareErrorCode.DeviceNotSupportPassphrase,
-              `Device not support passphrase, please update to ${support.require}`,
-              {
-                require: support.require,
+            // Check to see if it is safe to use Passphrase
+            checkPassphraseEnableState(method, device.features);
+
+            if (shouldCheckPassphraseState(method, device)) {
+              // check version
+              const support = device.supportNewPassphrase();
+              if (!support.support) {
+                throw ERRORS.TypedError(
+                  HardwareErrorCode.DeviceNotSupportPassphrase,
+                  `Device not support passphrase, please update to ${support.require}`,
+                  {
+                    require: support.require,
+                  }
+                );
               }
-            )
-          );
-        }
 
-        // Check Device passphrase State
-        const passphraseStateSafety = await device.checkPassphraseStateSafety(
-          method.payload?.passphraseState,
-          method.payload?.useEmptyPassphrase,
-          method.payload?.skipPassphraseCheck
-        );
-
-        // Double check, handles the special case of Touch/Pro
-        checkPassphraseEnableState(method, device.features);
+              // Check Device passphrase State after the Protocol V2 pre-unlock gate.
+              const passphraseStateSafety = await device.checkPassphraseStateSafety(
+                method.payload?.passphraseState,
+                method.payload?.useEmptyPassphrase,
+                method.payload?.skipPassphraseCheck,
+                hasDeriveCardano(method)
+              );
 
-        if (!passphraseStateSafety) {
-          DevicePool.clearDeviceCache(method.payload.connectId);
-          return Promise.reject(
-            ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError)
-          );
-        }
+              // Double check, handles the special case of Touch/Pro
+              checkPassphraseEnableState(method, device.features);
 
-        // close pin popup window
-        postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
-      }
+              if (!passphraseStateSafety) {
+                DevicePool.clearDeviceCache(method.payload.connectId);
+                throw ERRORS.TypedError(HardwareErrorCode.DeviceCheckPassphraseStateError);
+              }
 
-      // Automatic check safety_check level for Kovan, Ropsten, Rinkeby, Goerli test networks.
-      try {
-        await method.checkSafetyLevelOnTestNet();
-      } catch (e) {
-        const error =
-          e instanceof HardwareError
-            ? e
-            : ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'open safety check failed.');
-        // messageResponse = createResponseMessage(method.responseID, false, { error });
-        // requestQueue.resolveRequest(method.responseID, messageResponse);
-        // return;
-        throw error;
-      }
+              // Protocol V2 emits the PIN phase completion from DeviceSessionAskPin.
+              // Keep the legacy compatibility close for Protocol V1 only.
+              if (!device.isProtocolV2()) {
+                postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW));
+              }
+            }
 
-      method.device?.commands?.checkDisposed();
+            // Automatic check safety_check level for Kovan, Ropsten, Rinkeby, Goerli test networks.
+            try {
+              await method.checkSafetyLevelOnTestNet();
+            } catch (e) {
+              throw e instanceof HardwareError
+                ? e
+                : ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'open safety check failed.');
+            }
 
-      try {
-        const response: object = await runMethodWithUnlockRetry(method, device);
+            method.device?.commands?.checkDisposed();
+          },
+        });
         messageResponse = createResponseMessage(method.responseID, true, response);
         requestQueue.resolveRequest(method.responseID, messageResponse);
         completeMethodRequestContext(method);
       } catch (error) {
+        // Device.run may release the request before transport callbacks finish after a timeout.
+        // Ignore the stale callback because the caller already received the connection error.
+        if (!requestQueue.getTask(method.responseID)) {
+          Log.debug(`Call API - Ignore late inner method result`, error);
+          return;
+        }
         Log.debug(`Call API - Inner Method Run Error`, error);
         messageResponse = createResponseMessage(method.responseID, false, { error });
         requestQueue.resolveRequest(method.responseID, messageResponse);
@@ -636,6 +696,13 @@ const onCallDevice = async (
         ) {
           throw error;
         }
+      } finally {
+        if (isProtocolV2UiEnabled(method)) {
+          protocolV2CloseEmitted = protocolV2UiCoordinator.close({
+            ensureOperationClose: protocolV2Operation,
+            protocolV2Operation,
+          });
+        }
       }
     };
     Log.debug('Call API - Device Run: ', device.mainId);
@@ -651,7 +718,9 @@ const onCallDevice = async (
     try {
       return await task.callPromise.promise;
     } catch (e) {
-      Log.debug('Device Run Error: ', e);
+      if (!isExpectedCompatibilityError(e)) {
+        Log.debug('Device Run Error: ', e);
+      }
       completeMethodRequestContext(method, e);
       return createResponseMessage(method.responseID, false, { error: e });
     }
@@ -689,7 +758,17 @@ const onCallDevice = async (
 
     requestQueue.releaseTask(method.responseID);
 
-    closePopup();
+    if (isProtocolV2UiEnabled(method)) {
+      if (!protocolV2CloseEmitted && protocolV2Operation) {
+        protocolV2CloseEmitted = protocolV2UiCoordinator.close({
+          ensureOperationClose: true,
+          protocolV2Operation: true,
+        });
+      }
+      if (!protocolV2CloseEmitted) {
+        closePopup();
+      }
+    }
 
     cleanup();
 
@@ -835,24 +914,68 @@ function canSkipInitialize(method: BaseMethod, device: Device): boolean {
   return true;
 }
 
-function isRetryableBleProtocolV2ProbeError(method: BaseMethod, error: unknown) {
-  const message = error instanceof Error ? error.message : String(error ?? '');
+export function isRetryableBleProtocolV2ProbeError(method: BaseMethod, error: unknown) {
+  const typedError = error as { errorCode?: unknown; message?: unknown };
+  const message =
+    typeof typedError?.message === 'string' ? typedError.message : String(error ?? '');
   return (
     method.payload.connectProtocol === 'V2' &&
+    typedError?.errorCode === HardwareErrorCode.RuntimeError &&
     message.includes('Device protocol mismatch') &&
     message.includes('expected V2') &&
     message.includes('did not respond to expected protocol')
   );
 }
 
+export function isRetryableBleConnectionError(method: BaseMethod, error: unknown) {
+  if (method.device?.wasInterruptedByUser()) {
+    return false;
+  }
+  const typedError = error as { errorCode?: unknown };
+  return (
+    typedError?.errorCode === HardwareErrorCode.BleTimeoutError ||
+    typedError?.errorCode === HardwareErrorCode.BleConnectedError ||
+    isRetryableBleProtocolV2ProbeError(method, error) ||
+    isMissingDetectedProtocolV2Error(method, error)
+  );
+}
+
+export function isMissingDetectedProtocolV2Error(method: BaseMethod, error: unknown) {
+  const typedError = error as { errorCode?: unknown; message?: unknown };
+  return (
+    method.payload.connectProtocol === 'V2' &&
+    typedError?.errorCode === HardwareErrorCode.RuntimeError &&
+    typeof typedError.message === 'string' &&
+    typedError.message.includes('Device protocol has not been detected')
+  );
+}
+
 /**
  * If the Bluetooth connection times out, retry up to 6 times
  * @param retryCount - Current retry count (default 0)
  */
 async function connectDeviceForBle(method: BaseMethod, device: Device, retryCount = 0) {
   try {
-    await device.acquire(method.payload.connectProtocol);
+    if (device.wasInterruptedByUser()) {
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromUser);
+    }
+    if (method.payload.forceProtocolDetection && device.hasDeviceAcquire()) {
+      await device.release();
+    }
+    const shouldAcquire =
+      method.payload.forceProtocolDetection ||
+      !device.hasDeviceAcquire() ||
+      !device.commands ||
+      device.commands.disposed;
+    if (shouldAcquire) {
+      await device.acquire(method.payload.connectProtocol, {
+        forceProtocolDetection: method.payload.forceProtocolDetection,
+      });
+    }
     if (method.payload?.onlyConnectBleDevice) {
+      if (shouldAcquire) {
+        DevicePool.emitter.emit(DEVICE.CONNECT, device);
+      }
       return;
     }
     // Skip initialize if conditions are met
@@ -863,15 +986,29 @@ async function connectDeviceForBle(method: BaseMethod, device: Device, retryCoun
         passphraseState: initOptions.passphraseState,
       });
     }
+    if (shouldAcquire) {
+      DevicePool.emitter.emit(DEVICE.CONNECT, device);
+    }
   } catch (err) {
+    const requiresColdReconnect = isMissingDetectedProtocolV2Error(method, err);
+    // Device.run()'s REQUIRE_DISCONNECT handling never sees acquire/initialize
+    // failures, so with keep-alive a wedged link would be reused by every retry
+    // (field case: Initialize timing out at 25s per attempt, forever). Drop it
+    // here so the next retry cold-connects.
     if (
-      (err.errorCode === HardwareErrorCode.BleTimeoutError ||
-        err.errorCode === HardwareErrorCode.BleConnectedError ||
-        isRetryableBleProtocolV2ProbeError(method, err)) &&
-      retryCount < 6
+      (ERROR_CODES_REQUIRE_DISCONNECT.includes(err.errorCode) || requiresColdReconnect) &&
+      device.mainId &&
+      device.deviceConnector
     ) {
+      await device.deviceConnector.disconnect(device.mainId).catch(() => undefined);
+      // The connector only drops the link; `deviceAcquired` is reset by
+      // release()/markTransportDisconnected() alone. Leaving it set makes the
+      // next attempt skip acquire and initialize onto the link we just cut.
+      device.markTransportDisconnected();
+    }
+    if (isRetryableBleConnectionError(method, err) && retryCount < 6) {
       const nextRetry = retryCount + 1;
-      Log.debug(`Bluetooth connect timeout and will retry, retry count: ${nextRetry}`);
+      Log.debug(`Bluetooth connection will retry, retry count: ${nextRetry}`);
       await wait(3000);
       await connectDeviceForBle(method, device, nextRetry);
     } else {
@@ -978,6 +1115,11 @@ const ensureConnected = async (
             if (abort()) {
               return;
             }
+            // One generation per public ensureConnected() call, not per poll
+            // iteration. A later poll must not clear a user cancel.
+            if (tryCount === 1) {
+              device.beginConnectionAttempt();
+            }
             await connectDeviceForBle(method, device);
           }
           resolve(device);
@@ -985,6 +1127,19 @@ const ensureConnected = async (
         }
       } catch (error) {
         Log.debug('device error: ', error);
+        if (error.errorCode === HardwareErrorCode.BleUnavailableWhileUsbConnected) {
+          reject(error);
+          return;
+        }
+        if (isProtocolV2LinkDisabledError(error)) {
+          reject(
+            ERRORS.TypedError(HardwareErrorCode.BleUnavailableWhileUsbConnected, undefined, {
+              failureCode: error.failureCode,
+              firmwareMessage: error.firmwareMessage,
+            })
+          );
+          return;
+        }
         if ([HardwareErrorCode.BleCharacteristicNotifyChangeFailure].includes(error.errorCode)) {
           postMessage(createUiMessage(UI_REQUEST.BLUETOOTH_CHARACTERISTIC_NOTIFY_CHANGE_FAILURE));
         }
@@ -997,6 +1152,7 @@ const ensureConnected = async (
             HardwareErrorCode.BleLocationServicesDisabled,
             HardwareErrorCode.BleDeviceNotBonded,
             HardwareErrorCode.BleDeviceBondError,
+            HardwareErrorCode.BlePeerRemovedPairingInformation,
             HardwareErrorCode.BleDeviceBondedCanceled,
             HardwareErrorCode.BleCharacteristicNotifyError,
             HardwareErrorCode.BleTimeoutError,
@@ -1007,6 +1163,8 @@ const ensureConnected = async (
             HardwareErrorCode.DeviceDetectInBootloaderMode,
             HardwareErrorCode.BleCharacteristicNotifyChangeFailure,
             HardwareErrorCode.BridgeNeedsPermission,
+            HardwareErrorCode.DeviceInterruptedFromUser,
+            HardwareErrorCode.CallQueueActionCancelled,
           ].includes(error.errorCode)
         ) {
           reject(error);
@@ -1064,22 +1222,31 @@ export const cancel = (context: CoreContext, connectId?: string) => {
         )}`
       );
       const canceledDevices: Device[] = [];
+      const interruptDevice = (device: Device | undefined, deviceConnectId: string) => {
+        if (!device || canceledDevices.includes(device)) {
+          return;
+        }
+        setPrePendingCallPromise(deviceConnectId, device.interruptionFromUser());
+        canceledDevices.push(device);
+      };
       for (const requestId of requestIds) {
         const task = requestQueue.getTask(requestId);
         Log.debug('Cancel Api connect task: ', task);
-        if (task && task.method?.device) {
-          if (!canceledDevices.includes(task.method.device)) {
-            const { device } = task.method;
-            setPrePendingCallPromise(device?.interruptionFromUser());
-            canceledDevices.push(device);
-          }
+        if (task) {
+          // During ensureConnected the method has a connectId but device is
+          // assigned only after the poll succeeds. Interrupt the cached BLE
+          // Device so an in-flight acquire/initialize cannot finish.
+          interruptDevice(task.method?.device, task.method.connectId ?? connectId);
+          interruptDevice(deviceCacheMap.get(connectId), connectId);
           requestQueue.rejectRequest(
             requestId,
             ERRORS.TypedError(HardwareErrorCode.CallQueueActionCancelled)
           );
         }
       }
+      interruptDevice(deviceCacheMap.get(connectId), connectId);
       requestQueue.abortRequestsByConnectId(connectId);
+      pollingManager.stop(connectId);
     } catch (e) {
       Log.error('Cancel API Error: ', e);
     }
@@ -1088,22 +1255,31 @@ export const cancel = (context: CoreContext, connectId?: string) => {
     if (DataManager.isBleConnect(env)) {
       Log.debug('Cancel Api all _deviceList: ');
       const canceledDevices: Device[] = [];
+      const interruptDevice = (device?: Device) => {
+        if (!device || canceledDevices.includes(device)) {
+          return;
+        }
+        device.interruptionFromUser().catch(() => undefined);
+        canceledDevices.push(device);
+      };
       for (const requestId of requestQueue.getRequestTasksId()) {
         const task = requestQueue.getTask(requestId);
         Log.debug('Cancel Api connect task: ', task);
-        if (task && task.method?.device) {
-          if (!canceledDevices.includes(task.method.device)) {
-            const { device } = task.method;
-            device?.interruptionFromUser();
-            canceledDevices.push(device);
+        if (task) {
+          interruptDevice(task.method?.device);
+          if (task.method.connectId) {
+            interruptDevice(deviceCacheMap.get(task.method.connectId));
+            pollingManager.stop(task.method.connectId);
           }
-
           requestQueue.rejectRequest(
             requestId,
             ERRORS.TypedError(HardwareErrorCode.CallQueueActionCancelled)
           );
         }
       }
+      deviceCacheMap.forEach(interruptDevice);
+      requestQueue.abortAllRequests();
+      pollingManager.stopAll();
     } else {
       _deviceList?.allDevices().forEach(device => {
         Log.debug('device: ', device, ' device.hasDeviceAcquire: ', device.hasDeviceAcquire());
@@ -1157,14 +1333,16 @@ const shouldCheckPassphraseState = (method: BaseMethod, device: Device) => {
 };
 
 const cleanup = () => {
+  const pendingUiPromises = _uiPromises;
   _uiPromises = [];
-  Log.debug('Cleanup...');
+  rejectUiPromises(
+    pendingUiPromises,
+    ERRORS.TypedError(HardwareErrorCode.ActionCancelled, 'UI request was cancelled')
+  );
 };
 
 const removeDeviceListener = (device: Device) => {
   device.removeAllListeners();
-  DevicePool.emitter.removeAllListeners(DEVICE.CONNECT);
-  // DevicePool.emitter.removeListener(DEVICE.DISCONNECT, onDeviceDisconnectHandler);
 };
 
 /**
@@ -1175,19 +1353,33 @@ const closePopup = () => {
 };
 
 const onDeviceConnectHandler = (device: Device) => {
-  const env = DataManager.getSettings('env');
-  const deviceObject = DataManager.isBleConnect(env) ? device : device.toMessageObject();
-  postMessage(createDeviceMessage(DEVICE.CONNECT, { device: deviceObject as KnownDevice }));
+  const deviceObject = device.toMessageObject();
+  if (!deviceObject) return;
+  postMessage(createDeviceMessage(DEVICE.CONNECT, { device: deviceObject }));
 };
 
 const onDeviceDisconnectHandler = (device: Device) => {
   device.clearPreInitialized();
-  const env = DataManager.getSettings('env');
-  const deviceObject = DataManager.isBleConnect(env) ? device : device.toMessageObject();
-  postMessage(createDeviceMessage(DEVICE.DISCONNECT, { device: deviceObject as KnownDevice }));
+  const deviceObject = device.toMessageObject();
+  if (!deviceObject) return;
+  postMessage(createDeviceMessage(DEVICE.DISCONNECT, { device: deviceObject }));
+};
+
+const onTransportDeviceDisconnectHandler = (event: TransportDeviceDisconnectEvent) => {
+  const device =
+    deviceCacheMap.get(event.connectId) ??
+    DevicePool.devicesCache[event.connectId] ??
+    DevicePool.getDeviceByPath(event.connectId);
+  if (!device) {
+    Log.debug('Ignoring transport disconnect for an unknown device:', event.connectId);
+    return;
+  }
+
+  device.markTransportDisconnected();
+  DevicePool.emitter.emit(DEVICE.DISCONNECT, device);
 };
 
-const onDevicePinHandler = async (...[device, type, callback]: DeviceEvents['pin']) => {
+const onDevicePinHandler = (...[device, type, callback]: DeviceEvents['pin']) => {
   Log.log('request Input PIN');
   // create ui promise
   const uiPromise = createUiPromise(UI_RESPONSE.RECEIVE_PIN, device);
@@ -1196,12 +1388,14 @@ const onDevicePinHandler = async (...[device, type, callback]: DeviceEvents['pin
     createUiMessage(UI_REQUEST.REQUEST_PIN, {
       device: device.toMessageObject() as unknown as KnownDevice,
       type,
+      responseCorrelation: uiPromise.responseCorrelation,
     })
   );
-  // wait for pin
-  const uiResp = await uiPromise.promise;
-  // callback.apply(null, [null, pin]);
-  callback(null, uiResp.payload);
+  consumeUiPromise(
+    uiPromise.promise,
+    uiResp => callback(null, uiResp.payload),
+    error => callback(error, '')
+  );
 };
 
 export const onDeviceButtonHandler = (...[device, request]: [...DeviceEvents['button']]) => {
@@ -1225,7 +1419,11 @@ const onDeviceFeaturesHandler = (...[_, features]: [...DeviceEvents['features']]
   postMessage(createDeviceMessage(DEVICE.FEATURES, { ...features }));
 };
 
-const onDevicePassphraseHandler = async (
+const onDeviceStateHandler = (...[_, stateEvent]: [...DeviceEvents['state']]) => {
+  postMessage(createDeviceMessage(DEVICE.STATE, stateEvent));
+};
+
+const onDevicePassphraseHandler = (
   ...[device, requestPayload, callback]: DeviceEvents['passphrase']
 ) => {
   Log.debug('onDevicePassphraseHandler');
@@ -1235,18 +1433,27 @@ const onDevicePassphraseHandler = async (
       device: device.toMessageObject() as KnownDevice,
       passphraseState: device.passphraseState,
       existsAttachPinUser: requestPayload.existsAttachPinUser,
+      deviceOnly: requestPayload.deviceOnly,
+      source: requestPayload.source,
+      reason: requestPayload.reason,
+      expectedPassphraseState: requestPayload.expectedPassphraseState,
+      ...(requestPayload.interaction ? { interaction: requestPayload.interaction } : {}),
+      responseCorrelation: uiPromise.responseCorrelation,
     })
   );
-  // wait for passphrase
-  const uiResp = await uiPromise.promise;
-  const { value, passphraseOnDevice, save, attachPinOnDevice } = uiResp.payload;
-  // send as PassphrasePromptResponse
-  callback({
-    passphrase: value.normalize('NFKD'),
-    passphraseOnDevice,
-    attachPinOnDevice,
-    cache: save,
-  });
+  consumeUiPromise(
+    uiPromise.promise,
+    uiResp => {
+      const { value, passphraseOnDevice, save, attachPinOnDevice } = uiResp.payload;
+      callback({
+        passphrase: value.normalize('NFKD'),
+        passphraseOnDevice,
+        attachPinOnDevice,
+        cache: save,
+      });
+    },
+    error => callback({}, error)
+  );
 };
 
 const onEmptyPassphraseHandler = (...[_, , callback]: DeviceEvents['passphrase']) => {
@@ -1256,17 +1463,62 @@ const onEmptyPassphraseHandler = (...[_, , callback]: DeviceEvents['passphrase']
 };
 
 const onEnterPassphraseOnDeviceHandler = (
-  ...[device]: [...DeviceEvents['passphrase_on_device']]
+  ...[device, requestPayload]: [...DeviceEvents['passphrase_on_device']]
 ) => {
   postMessage(
     createUiMessage(UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE, {
       device: device.toMessageObject() as KnownDevice,
       passphraseState: device.passphraseState,
+      source: requestPayload?.source,
+      reason: requestPayload?.reason,
+      ...(requestPayload?.interaction ? { interaction: requestPayload.interaction } : {}),
+    })
+  );
+};
+
+const onEnterAttachPinOnDeviceHandler = (
+  ...[device, requestPayload]: [...DeviceEvents['attach_pin_on_device']]
+) => {
+  postMessage(
+    createUiMessage(UI_REQUEST.REQUEST_PIN, {
+      device: device.toMessageObject() as KnownDevice,
+      type: 'ButtonRequest_AttachPin',
+      source: requestPayload?.source,
+      reason: requestPayload?.reason,
+      ...(requestPayload?.interaction ? { interaction: requestPayload.interaction } : {}),
+    })
+  );
+};
+
+const onEnterPinOnDeviceHandler = (
+  ...[device, pinType, metadata]: [...DeviceEvents['pin_on_device']]
+) => {
+  postMessage(
+    createUiMessage(UI_REQUEST.REQUEST_PIN, {
+      device: device.toMessageObject() as KnownDevice,
+      type:
+        pinType === DeviceSessionPinType.AttachToPin
+          ? 'ButtonRequest_AttachPin'
+          : 'ButtonRequest_PinEntry',
+      source: metadata?.source,
+      reason: metadata?.reason,
+      deviceOnly: metadata?.deviceOnly ?? true,
+      completion: metadata?.completion,
+      method: metadata?.method,
+      page: metadata?.page,
+      operation: metadata?.operation,
+      ...(metadata?.interaction ? { interaction: metadata.interaction } : {}),
     })
   );
 };
 
-const onSelectDeviceInBootloaderForWebDeviceHandler = async (
+const onPinOnDeviceCompleteHandler = (
+  ...[_, metadata]: [...DeviceEvents['pin_on_device_complete']]
+) => {
+  postMessage(createUiMessage(UI_REQUEST.CLOSE_UI_PIN_WINDOW, metadata));
+};
+
+const onSelectDeviceInBootloaderForWebDeviceHandler = (
   ...[device, callback]: [...DeviceEvents['select_device_in_bootloader_for_web_device']]
 ) => {
   Log.debug('onSelectDeviceInBootloaderForWebDeviceHandler');
@@ -1276,11 +1528,14 @@ const onSelectDeviceInBootloaderForWebDeviceHandler = async (
       device: device.toMessageObject() as KnownDevice,
     })
   );
-  const uiResp = await uiPromise.promise;
-  callback(null, uiResp.payload.deviceId);
+  consumeUiPromise(
+    uiPromise.promise,
+    uiResp => callback(null, uiResp.payload.deviceId),
+    error => callback(error, '')
+  );
 };
 
-const onSelectDeviceForSwitchFirmwareWebDeviceHandler = async (
+const onSelectDeviceForSwitchFirmwareWebDeviceHandler = (
   ...[device, callback]: [...DeviceEvents['select_device_for_switch_firmware_web_device']]
 ) => {
   Log.debug('onSelectDeviceForSwitchFirmwareWebDeviceHandler');
@@ -1293,8 +1548,11 @@ const onSelectDeviceForSwitchFirmwareWebDeviceHandler = async (
       device: device.toMessageObject() as KnownDevice,
     })
   );
-  const uiResp = await uiPromise.promise;
-  callback(null, uiResp.payload.deviceId);
+  consumeUiPromise(
+    uiPromise.promise,
+    uiResp => callback(null, uiResp.payload.deviceId),
+    error => callback(error, '')
+  );
 };
 
 /**
@@ -1313,14 +1571,21 @@ const postMessage = (message: CoreMessage) => {
 
 const createUiPromise = <T extends UiPromiseResponse['type']>(promiseEvent: T, device?: Device) => {
   const uiPromise: UiPromise<T> = createDeferred(promiseEvent, device);
+  if (
+    device &&
+    (promiseEvent === UI_RESPONSE.RECEIVE_PIN || promiseEvent === UI_RESPONSE.RECEIVE_PASSPHRASE)
+  ) {
+    const publicDeviceId = device.toMessageObject()?.deviceId;
+    uiPromise.responseCorrelation = {
+      interactionId: generateInstanceId('UiResponse', device.sdkInstanceId),
+      deviceId: publicDeviceId || device.instanceId,
+    };
+  }
   _uiPromises.push(uiPromise as any);
 
   return uiPromise;
 };
 
-const findUiPromise = <T extends UiPromiseResponse['type']>(promiseEvent: T) =>
-  _uiPromises.find(p => p.id === promiseEvent);
-
 const removeUiPromise = (promise: Deferred<any>) => {
   _uiPromises = _uiPromises.filter(p => p !== promise);
 };
@@ -1332,8 +1597,10 @@ export default class Core extends EventEmitter {
 
   private requestQueue = new RequestQueue();
 
+  private disposePromise?: Promise<void>;
+
   // background task
-  private prePendingCallPromise: Promise<void> | undefined;
+  private prePendingCallPromises = new Map<string, Promise<void>>();
 
   private methodSynchronize = getSynchronize();
 
@@ -1344,19 +1611,24 @@ export default class Core extends EventEmitter {
     Log.debug(`[Core] Created SDK instance: ${this.sdkInstanceId}`);
   }
 
-  cancelOperation(operationId: string) {
-    this.requestQueue.abortOperation(operationId);
-  }
-
   private getCoreContext() {
     return {
       sdkInstanceId: this.sdkInstanceId,
       tracingContext: this.tracingContext,
       requestQueue: this.requestQueue,
       methodSynchronize: this.methodSynchronize,
-      getPrePendingCallPromise: () => this.prePendingCallPromise,
-      setPrePendingCallPromise: (promise: Promise<void> | undefined) => {
-        this.prePendingCallPromise = promise;
+      getPrePendingCallPromise: (connectId: string) => this.prePendingCallPromises.get(connectId),
+      setPrePendingCallPromise: (connectId: string, promise?: Promise<void>) => {
+        if (!promise) {
+          this.prePendingCallPromises.delete(connectId);
+          return;
+        }
+        this.prePendingCallPromises.set(connectId, promise);
+      },
+      removePrePendingCallPromise: (connectId: string, promise: Promise<void>) => {
+        if (this.prePendingCallPromises.get(connectId) === promise) {
+          this.prePendingCallPromises.delete(connectId);
+        }
       },
       // callback 任务管理
       registerCallbackTask: (connectId: string, callbackPromise: Deferred<any>) => {
@@ -1374,11 +1646,16 @@ export default class Core extends EventEmitter {
       case UI_RESPONSE.RECEIVE_PASSPHRASE:
       case UI_RESPONSE.SELECT_DEVICE_IN_BOOTLOADER_FOR_WEB_DEVICE:
       case UI_RESPONSE.SELECT_DEVICE_FOR_SWITCH_FIRMWARE_WEB_DEVICE: {
-        const uiPromise = findUiPromise(message.type);
+        const uiPromise = findUiPromiseForResponse(_uiPromises, message);
         if (uiPromise) {
           Log.log('receive UI Response: ', message.type);
           uiPromise.resolve(message);
           removeUiPromise(uiPromise);
+        } else if (
+          message.type === UI_RESPONSE.RECEIVE_PIN ||
+          message.type === UI_RESPONSE.RECEIVE_PASSPHRASE
+        ) {
+          Log.warn('Ignored unmatched or ambiguous sensitive UI response:', message.type);
         }
         break;
       }
@@ -1394,10 +1671,17 @@ export default class Core extends EventEmitter {
       }
 
       case IFRAME.CALL: {
-        Log.log(`[${Date.now()}][CALL_API]`, message);
+        const logBlockLabel = getLogBlockLabel(message);
+        Log.log(
+          formatLogMethodLabel(`[${Date.now()}][CALL_API]`, logBlockLabel),
+          getSafeLogPayload(message, logBlockLabel)
+        );
         const response = await callAPI(this.getCoreContext(), message);
         const { success, payload } = response;
-        Log.log(`[${Date.now()}][CALL_API_RESPONSE]`, response);
+        Log.log(
+          formatLogMethodLabel(`[${Date.now()}][CALL_API_RESPONSE]`, logBlockLabel),
+          getSafeLogPayload(response, logBlockLabel)
+        );
         if (success) {
           return response;
         }
@@ -1416,10 +1700,6 @@ export default class Core extends EventEmitter {
         cancel(this.getCoreContext(), message.payload.connectId);
         break;
       }
-      case IFRAME.CANCEL_OPERATION: {
-        this.cancelOperation(message.payload.operationId);
-        break;
-      }
       case IFRAME.CALLBACK: {
         Log.log('callback message: ', message);
         postMessage(message);
@@ -1431,25 +1711,65 @@ export default class Core extends EventEmitter {
     return Promise.resolve(message);
   }
 
-  dispose() {
+  dispose(): Promise<void> {
+    if (!this.disposePromise) {
+      this.disposePromise = this.disposeResources();
+    }
+    return this.disposePromise;
+  }
+
+  private async disposeResources(): Promise<void> {
+    Log.debug(`[Core] Disposing SDK instance: ${this.sdkInstanceId}`);
+    pollingManager.stopAll();
+    this.requestQueue.abortAllRequests();
+    cleanup();
+
+    _connector?.stop();
+    let transportCleanup: Promise<void>;
+    try {
+      transportCleanup = Promise.resolve(TransportManager.getTransport()?.stop?.()).catch(error => {
+        Log.warn('[Core] Transport cleanup failed:', error);
+      });
+    } catch (error) {
+      Log.warn('[Core] Transport cleanup failed:', error);
+      transportCleanup = Promise.resolve();
+    }
+
+    // Preserve synchronous dispose semantics for in-memory state and listeners.
     _deviceList = undefined;
     _connector = undefined;
+    DevicePool.dispose();
     deviceCacheMap.clear();
     preWarmInflight.clear();
     preWarmDoneAt.clear();
-    Log.debug(`[Core] Disposing SDK instance: ${this.sdkInstanceId}`);
+    preConnectCache = { passphraseState: undefined };
+    this.prePendingCallPromises.clear();
+    this.removeAllListeners();
     cleanupSdkInstance(this.sdkInstanceId);
+    if (_core === this) _core = undefined;
+
+    // Transports, especially Node USB, may release native handles asynchronously.
+    await transportCleanup;
   }
 }
 
 export const initCore = () => {
-  _core = new Core();
-  return _core;
+  const core = new Core();
+  _core = core;
+  return core;
 };
 
 export const initConnector = () => {
   _connector = new DeviceConnector();
+  DevicePool.emitter.removeListener(DEVICE.CONNECT, onDeviceConnectHandler);
+  DevicePool.emitter.removeListener(DEVICE.DISCONNECT, onDeviceDisconnectHandler);
+  DevicePool.emitter.removeListener(
+    TRANSPORT_EVENT.DEVICE_DISCONNECT,
+    onTransportDeviceDisconnectHandler
+  );
+  DevicePool.emitter.on(DEVICE.CONNECT, onDeviceConnectHandler);
   DevicePool.emitter.on(DEVICE.DISCONNECT, onDeviceDisconnectHandler);
+  DevicePool.emitter.on(TRANSPORT_EVENT.DEVICE_DISCONNECT, onTransportDeviceDisconnectHandler);
   return _connector;
 };
 
@@ -1463,12 +1783,8 @@ export const init = async (
   plugin?: LowlevelTransportSharedPlugin
 ) => {
   try {
-    try {
-      await DataManager.load(settings);
-      initTransport(Transport, plugin);
-    } catch {
-      Log.error('DataManager.load error');
-    }
+    await DataManager.load(settings);
+    initTransport(Transport, plugin);
     enableLog(DataManager.getSettings('debug'));
     if (DataManager.getSettings('env') !== 'react-native') {
       setLoggerPostMessage(postMessage);
@@ -1479,6 +1795,7 @@ export const init = async (
     return _core;
   } catch (error) {
     Log.error('core init', error);
+    throw error;
   }
 };