@onekeyfe/hd-core 1.2.0-alpha.7 → 1.2.0-alpha.70

package/src/core/index.ts

@@ -1,5 +1,6 @@
 import semver from 'semver';
 import EventEmitter from 'events';
+import { DeviceSessionPinType, TRANSPORT_EVENT } from '@onekeyfe/hd-transport';
 import {
   ERRORS,
   ERROR_CODES_REQUIRE_RELEASE,
@@ -14,14 +15,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 +26,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,18 +47,33 @@ 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 { 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);
@@ -91,14 +102,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
@@ -142,11 +154,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, {
@@ -158,11 +175,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 {
@@ -357,7 +376,7 @@ const onCallDevice = async (
     );
   } catch (e) {
     preWarmCallbackTask?.resolve();
-    console.log('ensureConnected error: ', e);
+    Log.debug('ensureConnected error: ', e);
 
     completeMethodRequestContext(method, e);
 
@@ -394,18 +413,28 @@ const onCallDevice = async (
     );
   }
 
-  device.on(DEVICE.PIN, onDevicePinHandler);
-  device.on(DEVICE.BUTTON, onDeviceButtonHandler);
-  device.on(
-    DEVICE.PASSPHRASE,
-    message.payload.useEmptyPassphrase ? onEmptyPassphraseHandler : onDevicePassphraseHandler
-  );
-  device.on(DEVICE.PASSPHRASE_ON_DEVICE, onEnterPassphraseOnDeviceHandler);
+  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,11 +449,10 @@ const onCallDevice = async (
     await waitForPendingPromise(getPrePendingCallPromise, setPrePendingCallPromise);
 
     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(
@@ -435,8 +463,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();
 
@@ -484,10 +512,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') {
@@ -538,89 +562,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 method.run();
+            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);
@@ -633,6 +670,13 @@ const onCallDevice = async (
         ) {
           throw error;
         }
+      } finally {
+        if (isProtocolV2UiEnabled(method)) {
+          protocolV2CloseEmitted = protocolV2UiCoordinator.close({
+            ensureOperationClose: protocolV2Operation,
+            protocolV2Operation,
+          });
+        }
       }
     };
     Log.debug('Call API - Device Run: ', device.mainId);
@@ -686,7 +730,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();
 
@@ -848,8 +902,23 @@ function isRetryableBleProtocolV2ProbeError(method: BaseMethod, error: unknown)
  */
 async function connectDeviceForBle(method: BaseMethod, device: Device, retryCount = 0) {
   try {
-    await device.acquire(method.payload.connectProtocol);
+    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
@@ -860,6 +929,9 @@ async function connectDeviceForBle(method: BaseMethod, device: Device, retryCoun
         passphraseState: initOptions.passphraseState,
       });
     }
+    if (shouldAcquire) {
+      DevicePool.emitter.emit(DEVICE.CONNECT, device);
+    }
   } catch (err) {
     if (
       (err.errorCode === HardwareErrorCode.BleTimeoutError ||
@@ -1154,14 +1226,17 @@ const shouldCheckPassphraseState = (method: BaseMethod, device: Device) => {
 };
 
 const cleanup = () => {
+  const pendingUiPromises = _uiPromises;
   _uiPromises = [];
+  rejectUiPromises(
+    pendingUiPromises,
+    ERRORS.TypedError(HardwareErrorCode.ActionCancelled, 'UI request was cancelled')
+  );
   Log.debug('Cleanup...');
 };
 
 const removeDeviceListener = (device: Device) => {
   device.removeAllListeners();
-  DevicePool.emitter.removeAllListeners(DEVICE.CONNECT);
-  // DevicePool.emitter.removeListener(DEVICE.DISCONNECT, onDeviceDisconnectHandler);
 };
 
 /**
@@ -1172,19 +1247,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 onDevicePinHandler = async (...[device, type, callback]: DeviceEvents['pin']) => {
+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 = (...[device, type, callback]: DeviceEvents['pin']) => {
   Log.log('request Input PIN');
   // create ui promise
   const uiPromise = createUiPromise(UI_RESPONSE.RECEIVE_PIN, device);
@@ -1193,12 +1282,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']]) => {
@@ -1222,7 +1313,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');
@@ -1232,18 +1327,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']) => {
@@ -1253,17 +1357,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 onSelectDeviceInBootloaderForWebDeviceHandler = async (
+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 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');
@@ -1273,11 +1422,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');
@@ -1290,8 +1442,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, '')
+  );
 };
 
 /**
@@ -1310,14 +1465,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);
 };
@@ -1329,6 +1491,8 @@ export default class Core extends EventEmitter {
 
   private requestQueue = new RequestQueue();
 
+  private disposePromise?: Promise<void>;
+
   // background task
   private prePendingCallPromise: Promise<void> | undefined;
 
@@ -1367,11 +1531,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;
       }
@@ -1387,10 +1556,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;
         }
@@ -1420,25 +1596,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.prePendingCallPromise = undefined;
+    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;
 };
 
@@ -1452,12 +1668,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);
@@ -1468,6 +1680,7 @@ export const init = async (
     return _core;
   } catch (error) {
     Log.error('core init', error);
+    throw error;
   }
 };