@onekeyfe/hwk-ledger-adapter 1.1.27-alpha.34 → 1.1.27-alpha.4

package/dist/index.d.mts

@@ -1,30 +1,106 @@
-import { IHardwareWallet, IConnector, TransportType, UiResponseEvent, DeviceInfo, Response, ChainCapability, EvmGetAddressParams, EvmAddress, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, ChainForFingerprint, DeviceDescriptor, DeviceChangeEvent, ConnectionType, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
+import { IHardwareWallet, IConnector, TransportType, UiResponseEvent, SearchDevicesOptions, DeviceInfo, Response, ChainCapability, EvmGetAddressParams, EvmAddress, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, ChainForFingerprint, DeviceDescriptor, DeviceChangeEvent, ConnectionType, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
 import { DeviceActionState as DeviceActionState$1, DiscoveredDevice, ExecuteDeviceActionReturnType, DeviceManagementKit } from '@ledgerhq/device-management-kit';
 import { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
+import { ContextModule } from '@ledgerhq/context-module';
 import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
 import { SignerSolana } from '@ledgerhq/device-signer-kit-solana';
 import Transport from '@ledgerhq/hw-transport';
 
-interface LedgerAdapterOptions {
-    /**
-     * `true` — emit `REQUEST_SELECT_DEVICE` on multi-device discovery and await
-     * `uiResponse({ type: RECEIVE_SELECT_DEVICE, payload: { sdkConnectId } })`.
-     * `false` (default) — silently pick the first device.
-     */
-    handleSelectDevice?: boolean;
+/**
+ * Re-export DMK types under local aliases for backward compatibility.
+ * These replace the previous duck-typed interfaces with the real SDK types.
+ */
+type DmkDiscoveredDevice = DiscoveredDevice;
+/**
+ * DMK DeviceAction — the Observable-based return type of all DMK signer methods.
+ *
+ * This is a permissive alias for `ExecuteDeviceActionReturnType` that accepts
+ * any Error and IntermediateValue generics. Signer wrapper code only cares about
+ * the Output type and the observable/cancel shape.
+ */
+type DeviceAction<T> = ExecuteDeviceActionReturnType<T, any, any>;
+/**
+ * DMK DeviceActionState — re-exported with permissive Error/IntermediateValue.
+ * The real type is a discriminated union on `status`.
+ */
+type DeviceActionState<T> = DeviceActionState$1<T, any, any>;
+/** ETH address result — re-exported from DMK for backward compatibility. */
+type SignerEvmAddress = Address;
+/** ETH signature result — re-exported from DMK for backward compatibility. */
+type SignerEvmSignature = Signature;
+/** BTC address result (WalletAddress not exported from DMK top-level). */
+interface SignerBtcAddress {
+    address: string;
+}
+
+/** Optional context attached to the rejection when a canceller fires. */
+interface CancelReason {
+    code?: number;
+    tag?: string;
+    message?: string;
 }
+/**
+ * Convert a DMK DeviceAction (Observable-based) into a Promise.
+ * Handles pending -> completed/error state transitions and interaction callbacks.
+ *
+ * Tracks the last DMK step observed (e.g. `signer.eth.steps.blindSignTransactionFallback`)
+ * and attaches it to the rejected error as a non-enumerable `_lastStep` property,
+ * so upstream error classifiers can distinguish failure contexts (e.g. Blind signing
+ * disabled vs. generic Invalid data).
+ *
+ * @param timeoutMs  Idle watchdog ms. Re-armed on each emission, paused
+ *                   during interactive pending. 0 disables. Default 65s
+ *                   (covers DMK's 60s + margin; we're a backstop only).
+ * @param onRegisterCanceller  Optional callback that receives a function which, when
+ *                             called, unsubscribes and cancels the underlying DeviceAction
+ *                             (releases DMK's IntentQueue slot). Caller is responsible
+ *                             for invoking the canceller on timeout/abort scenarios.
+ */
+declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void, onIntermediate?: (intermediateValue: unknown) => void): Promise<T>;
+
+interface AppMetadata {
+    versionName: string;
+    versionId: number;
+    version: string;
+    versionDisplayName: string | null;
+    description: string | null;
+    icon: string | null;
+    bytes: number | null;
+    currencyId: string | null;
+    isDevTools: boolean;
+}
+interface FirmwareVersion {
+    /** BOLOS version on the secure element — the user-facing firmware version. */
+    seVersion: string;
+    /** MCU SEPH (SE–MCU link protocol) version. */
+    mcuSephVersion: string;
+    /** MCU bootloader version. */
+    mcuBootloaderVersion: string;
+    /** Hardware revision (e.g. "00" / "01" on Nano X). */
+    hwVersion: string;
+}
+/** Full GetOsVersionResponse projected to a plain serializable shape. */
+interface LedgerDeviceInfo extends FirmwareVersion {
+    isBootloader: boolean;
+    isOsu: boolean;
+    targetId: number;
+    seTargetId?: number;
+    mcuTargetId?: number;
+    /** Secure element flags as hex string (raw bytes turned readable). */
+    seFlagsHex: string;
+}
+
 declare class LedgerAdapter implements IHardwareWallet {
     readonly vendor: "ledger";
     private readonly connector;
     private readonly emitter;
-    private readonly _handleSelectDevice;
     private _discoveredDevices;
     private _sessions;
     private readonly _uiRegistry;
     private _btcHighIndexConfirmedThisSession;
     private readonly _jobQueue;
     private _doConnectAbortController;
-    constructor(connector: IConnector, options?: LedgerAdapterOptions);
+    constructor(connector: IConnector);
     get activeTransport(): TransportType | null;
     getAvailableTransports(): TransportType[];
     switchTransport(_type: TransportType): Promise<void>;
@@ -37,8 +113,10 @@ declare class LedgerAdapter implements IHardwareWallet {
     resetState(): void;
     dispose(): Promise<void>;
     uiResponse(response: UiResponseEvent): void;
-    searchDevices(): Promise<DeviceInfo[]>;
+    searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
+    private _evictAllSessions;
     private static readonly MAX_BUSINESS_RETRY_BUDGET;
+    private static readonly STUCK_APP_RETRY_DELAY_MS;
     private static readonly MAX_DOCONNECT_CONFIRMS;
     private _lastCancelReason;
     private static _createDeviceBusyError;
@@ -65,6 +143,11 @@ declare class LedgerAdapter implements IHardwareWallet {
     tronGetAddress(connectId: string, deviceId: string, params: TronGetAddressParams): Promise<Response<TronAddress>>;
     tronSignTransaction(connectId: string, deviceId: string, params: TronSignTxParams): Promise<Response<TronSignedTx>>;
     tronSignMessage(connectId: string, deviceId: string, params: TronSignMsgParams): Promise<Response<TronSignature>>;
+    installApp(connectId: string, appName: string): Promise<Response<void>>;
+    listInstalledApps(connectId: string): Promise<Response<AppMetadata[]>>;
+    listAvailableApps(connectId: string): Promise<Response<AppMetadata[]>>;
+    getLedgerFirmwareVersion(connectId: string): Promise<Response<FirmwareVersion>>;
+    getLedgerDeviceInfo(connectId: string): Promise<Response<LedgerDeviceInfo>>;
     on<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
     on(event: string, listener: DeviceEventListener): void;
     off<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
@@ -96,7 +179,7 @@ declare class LedgerAdapter implements IHardwareWallet {
      *
      * - If a session already exists for the given connectId, reuse it.
      * - If ANY session exists (Ledger IDs are ephemeral), reuse it.
-     * - Otherwise: search → 1 device: auto-connect, multiple: ask user, 0: throw.
+     * - Otherwise: search → exactly 1 USB device auto-connects; multiple or none throws.
      */
     private _connectingPromise;
     private _waitForDeviceConnect;
@@ -113,7 +196,6 @@ declare class LedgerAdapter implements IHardwareWallet {
     private _doConnect;
     private _connectFirstOrSelect;
     private _connectDeviceOrThrow;
-    private _chooseDeviceFromList;
     /**
      * Call the connector with automatic session resolution and disconnect retry.
      *
@@ -132,6 +214,16 @@ declare class LedgerAdapter implements IHardwareWallet {
     private static _throwIfAborted;
     /** Actual work done under the job queue — connection, fingerprint, call, and recovery. */
     private _runConnectorCall;
+    /**
+     * Stuck-app recovery: pause for the device's UI transition, then retry once.
+     *
+     * Caller has already cleared the session + reset connector. We wait so Stax
+     * finishes its post-CloseApp animation, then go through ensureConnected +
+     * fingerprint check + call exactly once. Caller decides what to do on a
+     * second stuck-app hit.
+     */
+    private _retryAfterStuckApp;
+    private _sleepAbortable;
     /**
      * Clear stale session, reconnect, and retry the call.
      *
@@ -161,38 +253,12 @@ declare class LedgerAdapter implements IHardwareWallet {
     private deviceConnectHandler;
     private deviceDisconnectHandler;
     private uiEventForwarder;
+    private appInstallProgressForwarder;
     private registerEventListeners;
     private unregisterEventListeners;
     private connectorDeviceToDeviceInfo;
 }
 
-/**
- * Re-export DMK types under local aliases for backward compatibility.
- * These replace the previous duck-typed interfaces with the real SDK types.
- */
-type DmkDiscoveredDevice = DiscoveredDevice;
-/**
- * DMK DeviceAction — the Observable-based return type of all DMK signer methods.
- *
- * This is a permissive alias for `ExecuteDeviceActionReturnType` that accepts
- * any Error and IntermediateValue generics. Signer wrapper code only cares about
- * the Output type and the observable/cancel shape.
- */
-type DeviceAction<T> = ExecuteDeviceActionReturnType<T, any, any>;
-/**
- * DMK DeviceActionState — re-exported with permissive Error/IntermediateValue.
- * The real type is a discriminated union on `status`.
- */
-type DeviceActionState<T> = DeviceActionState$1<T, any, any>;
-/** ETH address result — re-exported from DMK for backward compatibility. */
-type SignerEvmAddress = Address;
-/** ETH signature result — re-exported from DMK for backward compatibility. */
-type SignerEvmSignature = Signature;
-/** BTC address result (WalletAddress not exported from DMK top-level). */
-interface SignerBtcAddress {
-    address: string;
-}
-
 /**
  * Manages device discovery, connection, and session tracking.
  * Wraps DMK's Observable APIs into simpler imperative calls.
@@ -244,6 +310,14 @@ declare class LedgerDeviceManager {
     requestDevice(): Promise<void>;
     /** Lookup a previously-discovered device's display name. */
     getDeviceName(deviceId: string): string | undefined;
+    /** Lookup minimal model/signal info from a previously-discovered device. */
+    getDiscoveredDeviceInfo(deviceId: string): {
+        model?: string;
+        modelName?: string;
+        name?: string;
+        rssi?: number | null;
+    } | undefined;
+    hasDiscoveredDevice(deviceId: string): boolean;
     /** Connect to a previously discovered device. Returns sessionId. */
     connect(deviceId: string): Promise<string>;
     /** Disconnect a session. */
@@ -288,22 +362,24 @@ interface LedgerConnectorBaseOptions {
  * Subclasses only need to:
  * 1. Supply a transport factory via the constructor.
  * 2. Optionally override `_resolveConnectId()` for transport-specific
- *    device identity resolution (e.g. BLE hex ID extraction).
+ *    device identity resolution.
+ *
+ * Invariant: one instance = one transport. `connectionType` is fixed at
+ * construction. To switch transport (e.g. desktop BLE ↔ WebHID), the host
+ * must build a new connector instance and replace the old one — don't add
+ * multiple transports to a single instance. Lifting this constraint would
+ * require routing `connectionType` from `descriptor.transport` per-device
+ * and updating every `this.connectionType` branch in this file.
  */
 declare class LedgerConnectorBase implements IConnector {
     private _deviceManager;
     private _signerManager;
+    private _deviceAppsManager;
     private _dmk;
     private readonly _eventHandlers;
     private readonly _providedDmk;
     private readonly _createTransport;
     readonly connectionType: ConnectionType;
-    private _connectIdToPath;
-    private _pathToConnectId;
-    /** Get DMK path from external connectId. Falls back to connectId itself. */
-    private _getPathForConnectId;
-    /** Get external connectId from DMK path. Falls back to path itself. */
-    private _getConnectIdForPath;
     private readonly _cancellers;
     private readonly _sessionStateSubs;
     /**
@@ -314,6 +390,10 @@ declare class LedgerConnectorBase implements IConnector {
     protected _importLedgerKit: (pkg: string) => Promise<any>;
     /** Context object passed to per-chain handler functions. */
     private readonly _ctx;
+    /** When true, BLE direct-connect throws NotAdvertising if the pre-flight
+     *  scan can't see the device — guard for GATT stacks that wedge on
+     *  non-advertising peripherals (iOS). */
+    private readonly _requirePreFlightScan;
     constructor(createTransport: TransportFactory, options?: {
         connectionType?: ConnectionType;
         dmk?: DeviceManagementKit;
@@ -323,11 +403,13 @@ declare class LedgerConnectorBase implements IConnector {
          * For Metro (React Native): pass a resolver that uses CJS paths.
          */
         importLedgerKit?: (pkg: string) => Promise<any>;
+        /** Default false. RN-iOS subclass should pass `true`. */
+        requirePreFlightScan?: boolean;
     });
     /**
      * Resolve the connectId for a discovered device descriptor.
      * Default: use the DMK path (ephemeral UUID).
-     * Override in subclasses to extract stable identifiers (e.g. BLE hex ID).
+     * Override in subclasses only when the public connectId differs from the transport path.
      */
     protected _resolveConnectId(descriptor: DeviceDescriptor): string;
     /**
@@ -346,8 +428,7 @@ declare class LedgerConnectorBase implements IConnector {
      * `LedgerAdapter._sessions` map would hold a dead session entry until
      * the next call hit `DeviceSessionNotFound`.
      *
-     * Best-effort: any error subscribing is swallowed so a flaky DMK
-     * doesn't break the connect path.
+     * Subscribe failure is fatal — see the inline note at the subscribe call.
      */
     private _watchSessionState;
     private _unwatchSessionState;
@@ -368,15 +449,15 @@ declare class LedgerConnectorBase implements IConnector {
     private _initManagers;
     private _getDeviceManager;
     private _getSignerManager;
+    private _getDeviceAppsManager;
     private _invalidateSession;
     /**
      * Replace an old session with a new one after app switch.
-     * Updates the connectId→path mapping so subsequent calls() use the new session,
-     * and emits device-connect so the adapter updates its _sessions Map.
+     * Emits device-connect so the adapter updates its _sessions Map.
      */
     private _replaceSession;
     /**
-     * Light reset: clear signer/session state but keep DMK and ID mapping alive.
+     * Light reset: clear signer/session state but keep DMK alive.
      * Used by connect() retry — we want to re-discover with the same transport.
      *
      * Note: drops the device manager but tears down its RxJS subs first via
@@ -395,31 +476,6 @@ declare class LedgerConnectorBase implements IConnector {
     private _wrapError;
 }
 
-/** Optional context attached to the rejection when a canceller fires. */
-interface CancelReason {
-    code?: number;
-    tag?: string;
-    message?: string;
-}
-/**
- * Convert a DMK DeviceAction (Observable-based) into a Promise.
- * Handles pending -> completed/error state transitions and interaction callbacks.
- *
- * Tracks the last DMK step observed (e.g. `signer.eth.steps.blindSignTransactionFallback`)
- * and attaches it to the rejected error as a non-enumerable `_lastStep` property,
- * so upstream error classifiers can distinguish failure contexts (e.g. Blind signing
- * disabled vs. generic Invalid data).
- *
- * @param timeoutMs  Idle watchdog ms. Re-armed on each emission, paused
- *                   during interactive pending. 0 disables. Default 65s
- *                   (covers DMK's 60s + margin; we're a backstop only).
- * @param onRegisterCanceller  Optional callback that receives a function which, when
- *                             called, unsubscribes and cancels the underlying DeviceAction
- *                             (releases DMK's IntentQueue slot). Caller is responsible
- *                             for invoking the canceller on timeout/abort scenarios.
- */
-declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void): Promise<T>;
-
 /**
  * Wraps Ledger's SDK signer (Observable-based DeviceActions) into
  * a simple async interface returning plain serializable data.
@@ -446,8 +502,14 @@ type SignerEthBuilderFn = (args: {
     dmk: DeviceManagementKit;
     sessionId: string;
 }) => {
+    withContextModule?(contextModule: ContextModule): {
+        build(): SignerEth$1;
+    };
     build(): SignerEth$1;
 } | Promise<{
+    withContextModule?(contextModule: ContextModule): {
+        build(): SignerEth$1;
+    };
     build(): SignerEth$1;
 }>;
 /**
@@ -463,6 +525,8 @@ declare class SignerManager {
     invalidate(_sessionId: string): void;
     clearAll(): void;
     private static _defaultBuilder;
+    private static _createContextModule;
+    static wrapBlindSigningReportNonBlocking<T extends ContextModule>(contextModule: T): T;
 }
 
 type BtcWallet = Parameters<SignerBtc$1['getWalletAddress']>[0];
@@ -655,12 +719,7 @@ type SdkEventListener = (event: SdkEvent) => void;
 declare function onSdkEvent(listener: SdkEventListener): () => void;
 declare function offSdkEvent(listener: SdkEventListener): void;
 
-/**
- * Extract the stable 4-digit HEX identifier from a Ledger BLE device name.
- * e.g., "Nano X 123A" -> "123A", "Ledger Nano X AB12" -> "AB12"
- * Returns undefined if no valid HEX suffix found.
- */
-declare function extractBleHexId(name?: string): string | undefined;
+declare function debugLog(...args: unknown[]): void;
 
 /**
  * Ledger DMK transport identifiers that represent BLE devices.
@@ -675,6 +734,5 @@ declare function extractBleHexId(name?: string): string | undefined;
 declare function isLedgerDmkBleTransport(transport?: string): boolean;
 declare function isLedgerBleConnectionType(connectionType?: ConnectionType): boolean;
 declare function isLedgerBleDescriptor(connectionType: ConnectionType, descriptor: DeviceDescriptor): boolean;
-declare function isValidLedgerBleConnectId(connectId?: string): boolean;
 
-export { AppManager, type DeviceActionState, type DmkDiscoveredDevice, DmkTransport, LedgerAdapter, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, type LedgerFailure, type SdkEvent, type SdkEventListener, type SdkLogEvent, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, extractBleHexId, isDeviceLockedError, isLedgerBleConnectionType, isLedgerBleDescriptor, isLedgerDmkBleTransport, isValidLedgerBleConnectId, ledgerFailure, mapLedgerError, offSdkEvent, onSdkEvent };
+export { AppManager, type DeviceActionState, type DmkDiscoveredDevice, DmkTransport, LedgerAdapter, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, type LedgerFailure, type SdkEvent, type SdkEventListener, type SdkLogEvent, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, debugLog, deviceActionToPromise, isDeviceLockedError, isLedgerBleConnectionType, isLedgerBleDescriptor, isLedgerDmkBleTransport, ledgerFailure, mapLedgerError, offSdkEvent, onSdkEvent };