@onekeyfe/hwk-ledger-adapter 1.1.26-alpha.15 → 1.1.26-alpha.21

package/dist/index.mjs

@@ -16,6 +16,12 @@ import {
 
 // src/errors.ts
 import { HardwareErrorCode, enrichErrorMessage } from "@onekeyfe/hwk-adapter-core";
+var MULTIPLE_USB_LEDGER_DEVICES_ERROR_MESSAGE = "Multiple Ledger USB devices are connected. Please connect only one Ledger device and try again.";
+function createMultipleUsbLedgerDevicesError() {
+  return Object.assign(new Error(MULTIPLE_USB_LEDGER_DEVICES_ERROR_MESSAGE), {
+    code: HardwareErrorCode.DeviceOneDeviceOnly
+  });
+}
 function ledgerFailure(code, error, appName, tag, params) {
   const payload = { error, code };
   if (appName !== void 0) payload.appName = appName;
@@ -300,6 +306,15 @@ function isAppNotInstalledError(err) {
   if (hasStatusCode(err, APP_NOT_INSTALLED_CODES)) return true;
   return false;
 }
+function isOutOfMemoryError(err) {
+  if (!err || typeof err !== "object") return false;
+  const e = err;
+  if (e._tag === "OutOfMemoryDAError") return true;
+  if (typeof e.message === "string" && /out of memory|not enough.*space|insufficient.*memory/i.test(e.message)) {
+    return true;
+  }
+  return false;
+}
 function isDeviceDisconnectedError(err) {
   if (!err || typeof err !== "object") return false;
   const e = err;
@@ -362,6 +377,8 @@ function mapLedgerError(err, opts) {
     code = HardwareErrorCode.WrongApp;
   } else if (isAppNotInstalledError(err)) {
     code = HardwareErrorCode.AppNotInstalled;
+  } else if (isOutOfMemoryError(err)) {
+    code = HardwareErrorCode.DeviceOutOfMemory;
   } else if (isDeviceDisconnectedError(err)) {
     code = HardwareErrorCode.DeviceDisconnected;
   } else if (isTimeoutError(err)) {
@@ -447,7 +464,7 @@ function btcAccountIndexFromPath(path) {
   return Number.isFinite(accountIndex) ? accountIndex : null;
 }
 var _LedgerAdapter = class _LedgerAdapter {
-  constructor(connector, options) {
+  constructor(connector) {
     this.vendor = "ledger";
     this.emitter = new TypedEventEmitter();
     this._discoveredDevices = /* @__PURE__ */ new Map();
@@ -469,7 +486,7 @@ var _LedgerAdapter = class _LedgerAdapter {
      *
      * - 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 → 1 USB device: auto-connect, multiple USB devices: throw, 0: throw.
      */
     // Mutex for ensureConnected — prevents concurrent calls from establishing duplicate connections
     this._connectingPromise = null;
@@ -478,16 +495,45 @@ var _LedgerAdapter = class _LedgerAdapter {
     // ---------------------------------------------------------------------------
     this.deviceConnectHandler = (data) => {
       const deviceInfo = this.connectorDeviceToDeviceInfo(data.device);
+      const hadSession = this._sessions.get(deviceInfo.connectId);
       this._discoveredDevices.set(deviceInfo.connectId, deviceInfo);
       this._sessions.delete(deviceInfo.connectId);
+      debugLog(
+        "[SESS-DBG] deviceConnectHandler EVENT connectId=",
+        deviceInfo.connectId,
+        "deviceId=",
+        deviceInfo.deviceId,
+        "label=",
+        deviceInfo.label,
+        "serial=",
+        deviceInfo.serialNumber,
+        "staleSessionDeleted=",
+        hadSession ?? "(none)",
+        "sessionsAfter=",
+        this._snapshotSessions()
+      );
       this.emitter.emit(DEVICE.CONNECT, {
         type: DEVICE.CONNECT,
         payload: deviceInfo
       });
     };
     this.deviceDisconnectHandler = (data) => {
+      const lostSession = this._sessions.get(data.connectId);
+      const lostDeviceInfo = this._discoveredDevices.get(data.connectId);
       this._discoveredDevices.delete(data.connectId);
       this._sessions.delete(data.connectId);
+      debugLog(
+        "[SESS-DBG] deviceDisconnectHandler EVENT connectId=",
+        data.connectId,
+        "removedSessionId=",
+        lostSession ?? "(none)",
+        "removedDeviceId=",
+        lostDeviceInfo?.deviceId,
+        "removedSerial=",
+        lostDeviceInfo?.serialNumber,
+        "sessionsAfter=",
+        this._snapshotSessions()
+      );
       this.emitter.emit(DEVICE.DISCONNECT, {
         type: DEVICE.DISCONNECT,
         payload: { connectId: data.connectId }
@@ -500,7 +546,6 @@ var _LedgerAdapter = class _LedgerAdapter {
       this.emitter.emit("ui-event", event);
     };
     this.connector = connector;
-    this._handleSelectDevice = options?.handleSelectDevice ?? false;
     this._jobQueue = new DeviceJobQueue();
     this.registerEventListeners();
   }
@@ -549,12 +594,21 @@ var _LedgerAdapter = class _LedgerAdapter {
   // Device management
   // ---------------------------------------------------------------------------
   async searchDevices(options) {
+    debugLog(
+      "[SESS-DBG] searchDevices ENTER resetSession=",
+      options?.resetSession ?? false,
+      "sessionsBefore=",
+      this._snapshotSessions(),
+      "discoveredBefore=",
+      this._snapshotDiscovered()
+    );
     if (options?.resetSession) {
       this._doConnectAbortController?.abort();
       this._sessions.clear();
       this._connectingPromise = null;
       this._doConnectAbortController = null;
       this._btcHighIndexConfirmedThisSession = false;
+      debugLog("[SESS-DBG] searchDevices cleared _sessions (resetSession=true)");
     }
     await this._ensureDevicePermission();
     const devices = await this.connector.searchDevices();
@@ -568,32 +622,110 @@ var _LedgerAdapter = class _LedgerAdapter {
       await this._ensureDevicePermission();
     }
     debugLog(
-      `[LedgerAdapter] searchDevices() return count=${this._discoveredDevices.size} ids=[${[
-        ...this._discoveredDevices.keys()
-      ].join(",")}]`
+      "[SESS-DBG] searchDevices RETURN count=",
+      this._discoveredDevices.size,
+      "devices=",
+      devices.map((d) => ({
+        connectId: d.connectId,
+        deviceId: d.deviceId,
+        name: d.name,
+        serial: d.serialNumber
+      })),
+      "sessionsAfter=",
+      this._snapshotSessions()
     );
     return Array.from(this._discoveredDevices.values());
   }
+  _snapshotSessions() {
+    return [...this._sessions.entries()].map(([connectId, sessionId]) => ({
+      connectId,
+      sessionId
+    }));
+  }
+  _snapshotDiscovered() {
+    return [...this._discoveredDevices.entries()].map(([connectId, info]) => ({
+      connectId,
+      deviceId: info.deviceId,
+      label: info.label,
+      serial: info.serialNumber
+    }));
+  }
+  // Enforce USB single-session invariant — see connectDevice.
+  async _evictAllSessions(reason) {
+    if (this._sessions.size === 0) return;
+    const stale = [...this._sessions.entries()];
+    debugLog(
+      "[SESS-DBG] evictAllSessions reason=",
+      reason,
+      "evicting=",
+      stale.map(([cid, sid]) => ({ connectId: cid, sessionId: sid }))
+    );
+    this._sessions.clear();
+    for (const [, sid] of stale) {
+      try {
+        await this.connector.disconnect(sid);
+      } catch (err) {
+        debugLog(
+          "[SESS-DBG] evictAllSessions disconnect failed sessionId=",
+          sid,
+          "err=",
+          err?.message
+        );
+      }
+    }
+  }
   static _createDeviceBusyError(method) {
     return Object.assign(new Error(`Ledger device is busy while calling ${method}`), {
       code: HardwareErrorCode2.DeviceBusy
     });
   }
   async connectDevice(connectId) {
+    debugLog(
+      "[SESS-DBG] connectDevice ENTER connectId=",
+      connectId || "(empty)",
+      "sessionsBefore=",
+      this._snapshotSessions(),
+      "discoveredBefore=",
+      this._snapshotDiscovered()
+    );
     try {
       if (isLedgerBleConnectionType(this.connector.connectionType) && !connectId) {
         throw Object.assign(new Error("Ledger BLE connectId is required."), {
           code: HardwareErrorCode2.DeviceNotFound
         });
       }
+      if (!isLedgerBleConnectionType(this.connector.connectionType)) {
+        await this._evictAllSessions("connectDevice");
+      }
       await this._ensureDevicePermission(connectId);
       const session = await this.connector.connect(connectId);
+      const prev = this._sessions.get(connectId);
       this._sessions.set(connectId, session.sessionId);
+      debugLog(
+        "[SESS-DBG] connectDevice SET _sessions connectId=",
+        connectId,
+        "newSessionId=",
+        session.sessionId,
+        "replacedPrevSessionId=",
+        prev ?? "(none)",
+        "sessionInfoDeviceId=",
+        session.deviceInfo?.deviceId,
+        "sessionInfoSerial=",
+        session.deviceInfo?.serialNumber,
+        "sessionsAfter=",
+        this._snapshotSessions()
+      );
       if (session.deviceInfo) {
         this._discoveredDevices.set(connectId, session.deviceInfo);
       }
       return success(connectId);
     } catch (err) {
+      debugLog(
+        "[SESS-DBG] connectDevice ERROR connectId=",
+        connectId,
+        "err=",
+        err?.message
+      );
       return this.errorToFailure(err);
     }
   }
@@ -699,6 +831,62 @@ var _LedgerAdapter = class _LedgerAdapter {
   tronSignMessage(connectId, deviceId, params) {
     return this.callChain(connectId, deviceId, "tron", "tronSignMessage", params);
   }
+  // ---------------------------------------------------------------------------
+  // App management — OS-level Ledger app install / list. Bypass fingerprint
+  // (no chain identity to verify) and chain handler dispatch. Progress for
+  // installApp is forwarded to the adapter emitter as 'app-install-progress'
+  // events so consumers can render progress bars without subscribing to a
+  // separate channel.
+  // ---------------------------------------------------------------------------
+  async installApp(connectId, appName) {
+    try {
+      const params = {
+        appName,
+        onProgress: (progress) => {
+          this.emitter.emit("app-install-progress", {
+            type: "app-install-progress",
+            payload: { connectId, appName, ...progress }
+          });
+        }
+      };
+      await this.connectorCall(connectId, "installApp", params);
+      return success(void 0);
+    } catch (err) {
+      return this.errorToFailure(err);
+    }
+  }
+  async listInstalledApps(connectId) {
+    try {
+      const result = await this.connectorCall(connectId, "listInstalledApps", {});
+      return success(result);
+    } catch (err) {
+      return this.errorToFailure(err);
+    }
+  }
+  async listAvailableApps(connectId) {
+    try {
+      const result = await this.connectorCall(connectId, "listAvailableApps", {});
+      return success(result);
+    } catch (err) {
+      return this.errorToFailure(err);
+    }
+  }
+  async getLedgerFirmwareVersion(connectId) {
+    try {
+      const result = await this.connectorCall(connectId, "getFirmwareVersion", {});
+      return success(result);
+    } catch (err) {
+      return this.errorToFailure(err);
+    }
+  }
+  async getLedgerDeviceInfo(connectId) {
+    try {
+      const result = await this.connectorCall(connectId, "getDeviceInfo", {});
+      return success(result);
+    } catch (err) {
+      return this.errorToFailure(err);
+    }
+  }
   on(event, listener) {
     this.emitter.on(event, listener);
   }
@@ -912,10 +1100,50 @@ var _LedgerAdapter = class _LedgerAdapter {
         code: HardwareErrorCode2.DeviceNotFound
       });
     }
-    if (connectId && this._sessions.has(connectId)) return connectId;
-    if (this._sessions.size > 0) {
-      return this._sessions.keys().next().value;
+    debugLog(
+      "[SESS-DBG] ensureConnected ENTER inputConnectId=",
+      connectId || "(empty)",
+      "sessions=",
+      this._snapshotSessions(),
+      "discovered=",
+      this._snapshotDiscovered()
+    );
+    if (connectId && this._sessions.has(connectId)) {
+      debugLog(
+        "[SESS-DBG] ensureConnected RESOLVED path=fast-cache connectId=",
+        connectId,
+        "sessionId=",
+        this._sessions.get(connectId)
+      );
+      return connectId;
+    }
+    if (!connectId && this._sessions.size > 0) {
+      if (!isLedgerBleConnectionType(this.connector.connectionType) && this._sessions.size > 1) {
+        debugLog(
+          "[SESS-DBG] ensureConnected ABORT multiple USB sessions present sessions=",
+          this._snapshotSessions()
+        );
+        throw Object.assign(
+          new Error(
+            "Ledger USB session invariant violated: more than one session is active. Please reconnect the device."
+          ),
+          { code: HardwareErrorCode2.DeviceOneDeviceOnly }
+        );
+      }
+      const ambient = this._sessions.keys().next().value;
+      debugLog(
+        "[SESS-DBG] ensureConnected RESOLVED path=ambient-fallback chosenConnectId=",
+        ambient,
+        "sessionId=",
+        this._sessions.get(ambient)
+      );
+      return ambient;
     }
+    debugLog(
+      "[SESS-DBG] ensureConnected path=doConnect (no fast match)",
+      "connectId=",
+      connectId || "(empty)"
+    );
     if (!this._connectingPromise) {
       this._doConnectAbortController = new AbortController();
       const innerSignal = this._doConnectAbortController.signal;
@@ -997,28 +1225,44 @@ var _LedgerAdapter = class _LedgerAdapter {
     throw new Error("_doConnect aborted");
   }
   async _connectFirstOrSelect(devices, targetConnectId) {
+    if (!isLedgerBleConnectionType(this.connector.connectionType) && devices.length > 1) {
+      debugLog(
+        `[DMK] Multiple Ledger USB devices found (${devices.length}); refusing to auto-select by ephemeral connectId.`
+      );
+      throw createMultipleUsbLedgerDevicesError();
+    }
     if (targetConnectId) {
       const target = devices.find(
         (d) => d.connectId === targetConnectId || d.deviceId === targetConnectId
       );
-      if (!target) {
-        const err = Object.assign(new Error(`Target Ledger unavailable: ${targetConnectId}`), {
-          code: HardwareErrorCode2.DeviceNotFound
-        });
-        if (isLedgerBleConnectionType(this.connector.connectionType)) {
-          err._tag = ERROR_TAG.DeviceNotAdvertising;
-        }
-        throw err;
+      if (target) {
+        return this._connectDeviceOrThrow(target.connectId);
+      }
+      if (!isLedgerBleConnectionType(this.connector.connectionType) && devices.length === 1) {
+        debugLog(
+          `[LedgerAdapter] target ${targetConnectId} not in fresh enumeration; accepting sole USB device ${devices[0].connectId} (assumed ephemeral path change)`
+        );
+        return this._connectDeviceOrThrow(devices[0].connectId);
       }
-      return this._connectDeviceOrThrow(target.connectId);
+      const err = Object.assign(new Error(`Target Ledger unavailable: ${targetConnectId}`), {
+        code: HardwareErrorCode2.DeviceNotFound
+      });
+      if (isLedgerBleConnectionType(this.connector.connectionType)) {
+        err._tag = ERROR_TAG.DeviceNotAdvertising;
+      }
+      throw err;
     }
     if (isLedgerBleConnectionType(this.connector.connectionType)) {
       throw Object.assign(new Error("Ledger BLE connectId is required."), {
         code: HardwareErrorCode2.DeviceNotFound
       });
     }
-    const chosenConnectId = devices.length === 1 ? devices[0].connectId : await this._chooseDeviceFromList(devices);
-    return this._connectDeviceOrThrow(chosenConnectId);
+    if (devices.length !== 1) {
+      throw Object.assign(new Error("Ledger device not found."), {
+        code: HardwareErrorCode2.DeviceNotFound
+      });
+    }
+    return this._connectDeviceOrThrow(devices[0].connectId);
   }
   async _connectDeviceOrThrow(chosenConnectId) {
     const result = await this.connectDevice(chosenConnectId);
@@ -1034,46 +1278,6 @@ var _LedgerAdapter = class _LedgerAdapter {
     }
     return chosenConnectId;
   }
-  async _chooseDeviceFromList(devices) {
-    if (!this._handleSelectDevice) {
-      debugLog(
-        `[DMK] Multiple Ledger devices found (${devices.length}); handleSelectDevice=false, picking first (${devices[0].connectId}).`
-      );
-      return devices[0].connectId;
-    }
-    let response;
-    try {
-      const waitPromise = this._uiRegistry.wait(
-        UI_REQUEST.REQUEST_SELECT_DEVICE
-      );
-      this.emitter.emit(UI_REQUEST.REQUEST_SELECT_DEVICE, {
-        type: UI_REQUEST.REQUEST_SELECT_DEVICE,
-        payload: { devices }
-      });
-      response = await waitPromise;
-    } catch (err) {
-      if (err?._tag === UI_REQUEST_PREEMPTED_TAG) {
-        this.emitter.emit(UI_REQUEST.CLOSE_UI_WINDOW, {
-          type: UI_REQUEST.CLOSE_UI_WINDOW,
-          payload: {}
-        });
-        throw Object.assign(new Error("Device selection superseded"), {
-          _tag: ERROR_TAG.UserAborted,
-          code: HardwareErrorCode2.UserAborted,
-          cause: err
-        });
-      }
-      throw err;
-    }
-    const chosen = devices.find((d) => d.connectId === response?.sdkConnectId);
-    if (!chosen) {
-      throw Object.assign(
-        new Error(`Selected sdkConnectId '${response?.sdkConnectId}' not in discovered list`),
-        { _tag: ERROR_TAG.DeviceNotRecognized }
-      );
-    }
-    return chosen.connectId;
-  }
   /**
    * Call the connector with automatic session resolution and disconnect retry.
    *
@@ -1083,7 +1287,18 @@ var _LedgerAdapter = class _LedgerAdapter {
    * 4. On disconnect error: clears stale session, re-connects, retries once
    */
   async connectorCall(connectId, method, params, fingerprint, permissionDeviceId) {
-    debugLog("[LedgerAdapter] connectorCall:", method, "connectId:", connectId || "(empty)");
+    debugLog(
+      "[SESS-DBG] connectorCall ENTER method=",
+      method,
+      "callerConnectId=",
+      connectId || "(empty)",
+      "callerDeviceId=",
+      fingerprint?.deviceId ?? permissionDeviceId ?? "(none)",
+      "sessions=",
+      this._snapshotSessions(),
+      "discovered=",
+      this._snapshotDiscovered()
+    );
     const queueKey = connectId || "__ledger_default__";
     return this._jobQueue.enqueue(
       queueKey,
@@ -1238,8 +1453,7 @@ var _LedgerAdapter = class _LedgerAdapter {
               } catch {
               }
             }
-            const retryConnectId = isLedgerBleConnectionType(this.connector.connectionType) ? resolvedConnectId : void 0;
-            const reConnectId = await this.ensureConnected(retryConnectId, signal);
+            const reConnectId = await this.ensureConnected(resolvedConnectId, signal);
             const reSessionId = this._sessions.get(reConnectId);
             if (!reSessionId) throw lastErr;
             if (fingerprint && !fingerprint.skipFingerprint && fingerprint.deviceId) {
@@ -1307,8 +1521,7 @@ var _LedgerAdapter = class _LedgerAdapter {
    */
   async _retryAfterStuckApp(resolvedConnectId, method, params, signal, originalErr, fingerprint) {
     await this._sleepAbortable(_LedgerAdapter.STUCK_APP_RETRY_DELAY_MS, signal);
-    const retryTargetConnectId = isLedgerBleConnectionType(this.connector.connectionType) ? resolvedConnectId : void 0;
-    const retryConnectId = await this.ensureConnected(retryTargetConnectId, signal);
+    const retryConnectId = await this.ensureConnected(resolvedConnectId, signal);
     const retrySessionId = this._sessions.get(retryConnectId);
     if (!retrySessionId) throw originalErr;
     if (fingerprint && !fingerprint.skipFingerprint && fingerprint.deviceId) {
@@ -1486,7 +1699,7 @@ var _LedgerAdapter = class _LedgerAdapter {
     const tag = err && typeof err === "object" ? err._tag : void 0;
     if (err && typeof err === "object" && "code" in err && typeof err.code === "number") {
       const e = err;
-      const params = e.code === HardwareErrorCode2.DevicePermissionDenied && e.reason ? { permissionDeniedReason: e.reason } : void 0;
+      const params = e.code === HardwareErrorCode2.DevicePermissionDenied && e.reason ? { permissionDeniedReason: e.reason } : e.params;
       return ledgerFailure(e.code, e.message ?? "Unknown error", e.appName, tag, params);
     }
     const mapped = mapLedgerError(err);
@@ -1536,7 +1749,7 @@ _LedgerAdapter.MAX_DOCONNECT_CONFIRMS = 3;
 var LedgerAdapter = _LedgerAdapter;
 
 // src/connector/LedgerConnectorBase.ts
-import { HardwareErrorCode as HardwareErrorCode7 } from "@onekeyfe/hwk-adapter-core";
+import { HardwareErrorCode as HardwareErrorCode8 } from "@onekeyfe/hwk-adapter-core";
 
 // src/device/LedgerDeviceManager.ts
 var LedgerDeviceManager = class {
@@ -1814,7 +2027,7 @@ import { hexToBytes } from "@onekeyfe/hwk-adapter-core";
 // src/signer/deviceActionToPromise.ts
 import { DeviceActionStatus } from "@ledgerhq/device-management-kit";
 var IDLE_WATCHDOG_MS = 65e3;
-function deviceActionToPromise(action, onInteraction, timeoutMs = IDLE_WATCHDOG_MS, onRegisterCanceller) {
+function deviceActionToPromise(action, onInteraction, timeoutMs = IDLE_WATCHDOG_MS, onRegisterCanceller, onIntermediate) {
   return new Promise((resolve, reject) => {
     let settled = false;
     let lastStep;
@@ -1896,14 +2109,22 @@ function deviceActionToPromise(action, onInteraction, timeoutMs = IDLE_WATCHDOG_
           onInteraction?.("interaction-complete");
           sub?.unsubscribe();
           rejectWithStepContext(state.error, lastStep, observedSteps, reject);
-        } else if (state.status === DeviceActionStatus.Pending && onInteraction) {
-          const interaction = state.intermediateValue?.requiredUserInteraction;
-          if (interaction && interaction !== "none") {
-            if (interaction === "unlock-device" && timer) {
-              clearTimeout(timer);
-              timer = null;
+        } else if (state.status === DeviceActionStatus.Pending) {
+          if (onIntermediate) {
+            try {
+              onIntermediate(state.intermediateValue);
+            } catch {
+            }
+          }
+          if (onInteraction) {
+            const interaction = state.intermediateValue?.requiredUserInteraction;
+            if (interaction && interaction !== "none") {
+              if (interaction === "unlock-device" && timer) {
+                clearTimeout(timer);
+                timer = null;
+              }
+              onInteraction(String(interaction));
             }
-            onInteraction(String(interaction));
           }
         }
       },
@@ -2947,6 +3168,336 @@ async function _createTrx(ctx, sessionId) {
   return new Trx(new DmkTransport(dmk, sessionId));
 }
 
+// src/device-apps/DeviceApps.ts
+import { DeviceActionStatus as DeviceActionStatus2 } from "@ledgerhq/device-management-kit";
+import { HardwareErrorCode as HardwareErrorCode7 } from "@onekeyfe/hwk-adapter-core";
+import { Subject } from "rxjs";
+var INSTALL_TIMEOUT_MS = 5 * 6e4;
+var DeviceApps = class {
+  constructor(_dmk, _sessionId, _ledgerKit) {
+    this._dmk = _dmk;
+    this._sessionId = _sessionId;
+    this._ledgerKit = _ledgerKit;
+  }
+  async listInstalled(options) {
+    const action = this._dmk.executeDeviceAction({
+      sessionId: this._sessionId,
+      deviceAction: new this._ledgerKit.ListAppsWithMetadataDeviceAction({
+        input: { unlockTimeout: options?.unlockTimeout }
+      })
+    });
+    const result = await deviceActionToPromise(
+      action,
+      this.onInteraction,
+      void 0,
+      this.onRegisterCanceller
+    );
+    return result.filter((a) => a !== null).map(applicationToMetadata);
+  }
+  // Catalog lookup via custom device action — DMK has no typed wrapper for this.
+  async listAvailable() {
+    const customAction = new ListAvailableAppsDeviceAction({
+      GetOsVersionCommand: this._ledgerKit.GetOsVersionCommand,
+      isSuccessCommandResult: this._ledgerKit.isSuccessCommandResult
+    });
+    const action = this._dmk.executeDeviceAction({
+      sessionId: this._sessionId,
+      deviceAction: customAction
+    });
+    const result = await deviceActionToPromise(
+      action,
+      this.onInteraction,
+      void 0,
+      this.onRegisterCanceller
+    );
+    return result.map(applicationToMetadata);
+  }
+  async getFirmwareVersion() {
+    const v = await this._fetchOsVersion();
+    return {
+      seVersion: v.seVersion,
+      mcuSephVersion: v.mcuSephVersion,
+      mcuBootloaderVersion: v.mcuBootloaderVersion,
+      hwVersion: v.hwVersion
+    };
+  }
+  async getDeviceInfo() {
+    const v = await this._fetchOsVersion();
+    return {
+      isBootloader: v.isBootloader,
+      isOsu: v.isOsu,
+      targetId: v.targetId,
+      seTargetId: v.seTargetId,
+      mcuTargetId: v.mcuTargetId,
+      seVersion: v.seVersion,
+      seFlagsHex: bytesToHex2(v.seFlags),
+      mcuSephVersion: v.mcuSephVersion,
+      mcuBootloaderVersion: v.mcuBootloaderVersion,
+      hwVersion: v.hwVersion
+    };
+  }
+  /**
+   * Pre-flight space check. Mirrors DMK's PredictOutOfMemoryTask using the
+   * data we already expose (listInstalled / listAvailable / getOsVersion).
+   * Fails fast with HardwareErrorCode.DeviceOutOfMemory before issuing the
+   * actual install — saves the user the time-to-fail of DMK's state machine.
+   */
+  async _assertEnoughSpace(appName) {
+    let osVersion;
+    let installed;
+    let available;
+    try {
+      [osVersion, installed, available] = await Promise.all([
+        this._fetchOsVersion(),
+        this.listInstalled(),
+        this.listAvailable()
+      ]);
+    } catch (err) {
+      debugLog("[DeviceApps] precheck skipped:", err?.message);
+      return;
+    }
+    if (installed.some((a) => a.versionName === appName)) return;
+    const target = available.find((a) => a.versionName === appName);
+    if (!target) return;
+    const capacity = getDeviceCapacity(osVersion.targetId);
+    if (!capacity) return;
+    const blockSize = capacity.getBlockSize(osVersion.seVersion);
+    const totalBlocks = Math.floor(capacity.memorySize / blockSize);
+    const blocks = (b) => Math.ceil((b ?? 0) / blockSize);
+    const usedBlocks = installed.reduce((sum, a) => sum + blocks(a.bytes), 0);
+    const neededBlocks = blocks(target.bytes);
+    debugLog(
+      "[DeviceApps] space check",
+      "targetId=",
+      osVersion.targetId.toString(16),
+      "memorySize=",
+      capacity.memorySize,
+      "blockSize=",
+      blockSize,
+      "usedBlocks=",
+      usedBlocks,
+      "neededBlocks=",
+      neededBlocks,
+      "totalBlocks=",
+      totalBlocks
+    );
+    if (usedBlocks + neededBlocks > totalBlocks) {
+      const usedBytes = usedBlocks * blockSize;
+      const neededBytes = neededBlocks * blockSize;
+      const freeBytes = Math.max(0, capacity.memorySize - usedBytes);
+      throw Object.assign(
+        new Error(
+          `Not enough space to install "${appName}": needs ${neededBytes} bytes, ${freeBytes} bytes free of ${capacity.memorySize}.`
+        ),
+        {
+          code: HardwareErrorCode7.DeviceOutOfMemory,
+          _tag: "OutOfMemoryDAError",
+          appName,
+          params: {
+            requiredBytes: neededBytes,
+            availableBytes: freeBytes,
+            totalBytes: capacity.memorySize
+          }
+        }
+      );
+    }
+  }
+  // Sole sendCommand wrapper — surfaces unlock-device interaction through
+  // the same onInteraction pipeline as the device-action methods.
+  async _fetchOsVersion() {
+    const customAction = new GetOsVersionDeviceAction({
+      GetOsVersionCommand: this._ledgerKit.GetOsVersionCommand,
+      isSuccessCommandResult: this._ledgerKit.isSuccessCommandResult
+    });
+    const action = this._dmk.executeDeviceAction({
+      sessionId: this._sessionId,
+      deviceAction: customAction
+    });
+    return deviceActionToPromise(
+      action,
+      this.onInteraction,
+      void 0,
+      this.onRegisterCanceller
+    );
+  }
+  async install(appName, onProgress, options) {
+    if (!appName) throw new Error("DeviceApps.install: appName is required");
+    debugLog("[DeviceApps] install:", appName);
+    await this._assertEnoughSpace(appName);
+    const action = this._dmk.executeDeviceAction({
+      sessionId: this._sessionId,
+      deviceAction: new this._ledgerKit.InstallAppDeviceAction({
+        input: { appName, unlockTimeout: options?.unlockTimeout }
+      })
+    });
+    await deviceActionToPromise(
+      action,
+      this.onInteraction,
+      INSTALL_TIMEOUT_MS,
+      this.onRegisterCanceller,
+      onProgress ? (intermediateValue) => {
+        const iv = intermediateValue;
+        if (typeof iv?.progress === "number") {
+          onProgress({
+            progress: iv.progress,
+            requiredUserInteraction: iv.requiredUserInteraction
+          });
+        }
+      } : void 0
+    );
+  }
+};
+function bytesToHex2(bytes) {
+  if (!bytes) return "";
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function applicationToMetadata(app) {
+  return {
+    versionName: app.versionName,
+    versionId: app.versionId,
+    version: app.version,
+    versionDisplayName: app.versionDisplayName,
+    description: app.description,
+    icon: app.icon,
+    bytes: app.bytes,
+    currencyId: app.currencyId,
+    isDevTools: app.isDevTools
+  };
+}
+var DEVICE_CAPACITIES = [
+  // Nano S — block size 4K on fw<2.0, 2K on >=2.0. Default 4K (conservative).
+  {
+    mask: 823132160,
+    capacity: {
+      memorySize: 320 * 1024,
+      getBlockSize: (fw) => parseMajor(fw) >= 2 ? 2 * 1024 : 4 * 1024
+    }
+  },
+  // Nano S Plus
+  { mask: 856686592, capacity: { memorySize: 1533 * 1024, getBlockSize: () => 32 } },
+  // Nano X
+  { mask: 855638016, capacity: { memorySize: 2 * 1024 * 1024, getBlockSize: () => 4 * 1024 } },
+  // Stax
+  { mask: 857735168, capacity: { memorySize: 1533 * 1024, getBlockSize: () => 32 } },
+  // Flex
+  { mask: 858783744, capacity: { memorySize: 1533 * 1024, getBlockSize: () => 32 } },
+  // Apex / Nano Gen5
+  { mask: 859832320, capacity: { memorySize: 1533 * 1024, getBlockSize: () => 32 } }
+];
+function getDeviceCapacity(targetId) {
+  const masked = targetId & 4294901760;
+  return DEVICE_CAPACITIES.find((d) => d.mask === masked)?.capacity;
+}
+function parseMajor(version) {
+  const m = /^(\d+)/.exec(version);
+  return m ? Number(m[1]) : 0;
+}
+var GetOsVersionDeviceAction = class {
+  constructor(_deps) {
+    this._deps = _deps;
+    this.input = void 0;
+  }
+  _execute(internalApi) {
+    const subject = new Subject();
+    let cancelled = false;
+    (async () => {
+      try {
+        subject.next({
+          status: DeviceActionStatus2.Pending,
+          intermediateValue: { requiredUserInteraction: "none" }
+        });
+        const result = await internalApi.sendCommand(new this._deps.GetOsVersionCommand());
+        if (cancelled) return;
+        if (!this._deps.isSuccessCommandResult(result)) {
+          const errObj = result?.error;
+          throw new Error(errObj?.message ?? "GetOsVersionCommand failed");
+        }
+        subject.next({ status: DeviceActionStatus2.Completed, output: result.data });
+        subject.complete();
+      } catch (err) {
+        if (cancelled) return;
+        subject.next({ status: DeviceActionStatus2.Error, error: err });
+        subject.complete();
+      }
+    })();
+    return {
+      observable: subject.asObservable(),
+      cancel: () => {
+        cancelled = true;
+        subject.next({ status: DeviceActionStatus2.Stopped });
+        subject.complete();
+      }
+    };
+  }
+};
+var ListAvailableAppsDeviceAction = class {
+  constructor(deps) {
+    this.input = void 0;
+    this._GetOsVersionCommand = deps.GetOsVersionCommand;
+    this._isSuccessCommandResult = deps.isSuccessCommandResult;
+  }
+  _execute(internalApi) {
+    const subject = new Subject();
+    let cancelled = false;
+    (async () => {
+      try {
+        subject.next({
+          status: DeviceActionStatus2.Pending,
+          intermediateValue: { requiredUserInteraction: "none" }
+        });
+        const osVersionResult = await internalApi.sendCommand(new this._GetOsVersionCommand());
+        if (cancelled) return;
+        if (!this._isSuccessCommandResult(osVersionResult)) {
+          const errObj = osVersionResult?.error;
+          throw new Error(errObj?.message ?? "GetOsVersionCommand failed");
+        }
+        const managerApi = internalApi.getManagerApiService();
+        const either = await managerApi.getAppList(osVersionResult.data).run();
+        if (cancelled) return;
+        if (either.isLeft()) {
+          const httpErr = either.extract();
+          throw new Error(httpErr?.message ?? "Manager API getAppList failed");
+        }
+        const apps = either.extract();
+        subject.next({ status: DeviceActionStatus2.Completed, output: apps });
+        subject.complete();
+      } catch (err) {
+        if (cancelled) return;
+        subject.next({ status: DeviceActionStatus2.Error, error: err });
+        subject.complete();
+      }
+    })();
+    return {
+      observable: subject.asObservable(),
+      cancel: () => {
+        cancelled = true;
+        subject.next({ status: DeviceActionStatus2.Stopped });
+        subject.complete();
+      }
+    };
+  }
+};
+
+// src/device-apps/DeviceAppsManager.ts
+var DeviceAppsManager = class {
+  constructor(dmk, importLedgerKit) {
+    this._dmk = dmk;
+    this._importLedgerKit = importLedgerKit;
+  }
+  async getOrCreate(sessionId) {
+    const ledgerKit = await this._importLedgerKit(
+      "@ledgerhq/device-management-kit"
+    );
+    return new DeviceApps(this._dmk, sessionId, ledgerKit);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, class-methods-use-this
+  invalidate(_sessionId) {
+  }
+  // eslint-disable-next-line class-methods-use-this
+  clearAll() {
+  }
+};
+
 // src/connector/LedgerConnectorBase.ts
 var METHOD_PREFIX_TO_APP_NAME = {
   evm: "Ethereum",
@@ -2955,7 +3506,7 @@ var METHOD_PREFIX_TO_APP_NAME = {
   tron: "Tron"
 };
 var HARDWARE_ERROR_CODE_VALUES = new Set(
-  Object.values(HardwareErrorCode7).filter((value) => typeof value === "number")
+  Object.values(HardwareErrorCode8).filter((value) => typeof value === "number")
 );
 var BLE_CONNECT_SCAN_TIMEOUT_MS = 1500;
 async function defaultLedgerKitImporter(pkg) {
@@ -2974,10 +3525,25 @@ async function defaultLedgerKitImporter(pkg) {
       throw new Error(`Unknown Ledger kit package: ${pkg}`);
   }
 }
+async function _getDeviceApps(ctx, sessionId) {
+  const manager = await ctx.getDeviceAppsManager();
+  const apps = await manager.getOrCreate(sessionId);
+  apps.onInteraction = (interaction) => {
+    ctx.emit("ui-event", {
+      type: collapseSignerInteraction(interaction),
+      payload: { sessionId }
+    });
+  };
+  apps.onRegisterCanceller = (cancel) => {
+    ctx.registerCanceller(sessionId, cancel);
+  };
+  return apps;
+}
 var LedgerConnectorBase = class {
   constructor(createTransport, options) {
     this._deviceManager = null;
     this._signerManager = null;
+    this._deviceAppsManager = null;
     this._dmk = null;
     this._eventHandlers = /* @__PURE__ */ new Map();
     // ---------------------------------------------------------------------------
@@ -3016,6 +3582,7 @@ var LedgerConnectorBase = class {
       getOrCreateDmk: () => this._getOrCreateDmk(),
       getDeviceManager: () => this._getDeviceManager(),
       getSignerManager: () => this._getSignerManager(),
+      getDeviceAppsManager: () => this._getDeviceAppsManager(),
       clearAllSigners: () => this._signerManager?.clearAll(),
       replaceSession: (oldSid, newSid) => this._replaceSession(oldSid, newSid),
       registerCanceller: (sid, cancel) => this._cancellers.set(sid, cancel),
@@ -3050,12 +3617,22 @@ var LedgerConnectorBase = class {
     }
     return descriptors;
   }
+  _assertSingleUsbDescriptor(descriptors) {
+    if (isLedgerBleConnectionType(this.connectionType) || descriptors.length <= 1) {
+      return;
+    }
+    debugLog(
+      `[DMK] Multiple Ledger USB devices found (${descriptors.length}); refusing to choose by ephemeral path. paths=[${descriptors.map((d) => d.path).join(",")}]`
+    );
+    throw createMultipleUsbLedgerDevicesError();
+  }
   // ---------------------------------------------------------------------------
   // IConnector -- Device discovery
   // ---------------------------------------------------------------------------
   async searchDevices() {
     const dm = await this._getDeviceManager();
     const descriptors = await this._discoverDescriptors(dm);
+    this._assertSingleUsbDescriptor(descriptors);
     const resolvedDescriptors = descriptors.map((d) => ({
       descriptor: d,
       connectId: this._resolveConnectId(d)
@@ -3081,6 +3658,10 @@ var LedgerConnectorBase = class {
   async connect(deviceId) {
     const callerSuppliedConnectId = Boolean(deviceId);
     let targetPath = deviceId;
+    if (callerSuppliedConnectId && !isLedgerBleConnectionType(this.connectionType)) {
+      const dm = await this._getDeviceManager();
+      this._assertSingleUsbDescriptor(await this._discoverDescriptors(dm));
+    }
     if (!targetPath) {
       const discovered = await this.searchDevices();
       if (discovered.length === 0) {
@@ -3104,7 +3685,7 @@ var LedgerConnectorBase = class {
             `Ledger BLE connect did not return within ${HANG_CEILING_MS / 6e4}min \u2014 DMK hang fallback.`
           );
           err._tag = ERROR_TAG.BlePairingTimeout;
-          err.code = HardwareErrorCode7.BlePairingTimeout;
+          err.code = HardwareErrorCode8.BlePairingTimeout;
           reject(err);
         }, HANG_CEILING_MS);
       });
@@ -3137,7 +3718,7 @@ var LedgerConnectorBase = class {
         "Ledger device is not currently advertising. Wake up and unlock the device, keep it nearby, then try again."
       );
       err._tag = ERROR_TAG.DeviceNotAdvertising;
-      err.code = HardwareErrorCode7.DeviceNotFound;
+      err.code = HardwareErrorCode8.DeviceNotFound;
       throw err;
     };
     const doConnect = async (path) => {
@@ -3157,7 +3738,19 @@ var LedgerConnectorBase = class {
         }
         throw err;
       }
-      this._watchSessionState(sessionId, externalConnectId);
+      try {
+        this._watchSessionState(sessionId, externalConnectId);
+      } catch (subErr) {
+        debugLog(
+          "[DMK] state subscription failed during connect; disconnecting session:",
+          subErr
+        );
+        try {
+          await dm.disconnect(sessionId);
+        } catch {
+        }
+        throw subErr;
+      }
       const info = dm.getDiscoveredDeviceInfo(path);
       const session = {
         sessionId,
@@ -3174,6 +3767,18 @@ var LedgerConnectorBase = class {
         }
       };
       const name = dm.getDeviceName(path) ?? "Ledger";
+      debugLog(
+        "[SESS-DBG] connector.connect SUCCESS dmPath=",
+        path,
+        "externalConnectId=",
+        externalConnectId,
+        "newSessionId=",
+        sessionId,
+        "name=",
+        name,
+        "model=",
+        info?.model
+      );
       this._emit("device-connect", {
         device: { connectId: externalConnectId, deviceId: path, name }
       });
@@ -3192,7 +3797,7 @@ var LedgerConnectorBase = class {
           "Ledger Bluetooth pairing failed. Make sure the device is unlocked and nearby, then try again."
         );
         wrapped._tag = ERROR_TAG.BleGattBondingFailed;
-        wrapped.code = HardwareErrorCode7.BlePairingTimeout;
+        wrapped.code = HardwareErrorCode8.BlePairingTimeout;
         wrapped.originalError = err;
         throw wrapped;
       }
@@ -3236,24 +3841,48 @@ var LedgerConnectorBase = class {
       } catch {
       }
     }
-    try {
-      const sub = dmk.getDeviceSessionState({ sessionId }).subscribe({
-        next: (state) => {
-          if (state?.deviceStatus === "NOT CONNECTED") {
-            this._handleAutonomousDisconnect(sessionId, externalConnectId);
-          }
-        },
-        error: () => {
-          this._handleAutonomousDisconnect(sessionId, externalConnectId);
-        },
-        complete: () => {
+    debugLog(
+      "[SESS-DBG] _watchSessionState SUBSCRIBE sessionId=",
+      sessionId,
+      "connectId=",
+      externalConnectId
+    );
+    const sub = dmk.getDeviceSessionState({ sessionId }).subscribe({
+      next: (state) => {
+        debugLog(
+          "[SESS-DBG] _watchSessionState NEXT sessionId=",
+          sessionId,
+          "connectId=",
+          externalConnectId,
+          "deviceStatus=",
+          state?.deviceStatus
+        );
+        if (state?.deviceStatus === "NOT CONNECTED") {
           this._handleAutonomousDisconnect(sessionId, externalConnectId);
         }
-      });
-      this._sessionStateSubs.set(sessionId, sub);
-    } catch (err) {
-      debugLog("[DMK] _watchSessionState subscribe failed:", err);
-    }
+      },
+      error: (err) => {
+        debugLog(
+          "[SESS-DBG] _watchSessionState ERROR sessionId=",
+          sessionId,
+          "connectId=",
+          externalConnectId,
+          "err=",
+          err?.message
+        );
+        this._handleAutonomousDisconnect(sessionId, externalConnectId);
+      },
+      complete: () => {
+        debugLog(
+          "[SESS-DBG] _watchSessionState COMPLETE sessionId=",
+          sessionId,
+          "connectId=",
+          externalConnectId
+        );
+        this._handleAutonomousDisconnect(sessionId, externalConnectId);
+      }
+    });
+    this._sessionStateSubs.set(sessionId, sub);
   }
   _unwatchSessionState(sessionId) {
     const sub = this._sessionStateSubs.get(sessionId);
@@ -3265,7 +3894,21 @@ var LedgerConnectorBase = class {
     this._sessionStateSubs.delete(sessionId);
   }
   _handleAutonomousDisconnect(sessionId, externalConnectId) {
-    if (!this._sessionStateSubs.has(sessionId)) return;
+    if (!this._sessionStateSubs.has(sessionId)) {
+      debugLog(
+        "[SESS-DBG] _handleAutonomousDisconnect SKIP (already handled) sessionId=",
+        sessionId,
+        "connectId=",
+        externalConnectId
+      );
+      return;
+    }
+    debugLog(
+      "[SESS-DBG] _handleAutonomousDisconnect FIRE sessionId=",
+      sessionId,
+      "connectId=",
+      externalConnectId
+    );
     debugLog(
       "[DMK] autonomous disconnect detected \u2014 sessionId:",
       sessionId,
@@ -3275,7 +3918,7 @@ var LedgerConnectorBase = class {
     this._unwatchSessionState(sessionId);
     this._signerManager?.invalidate(sessionId);
     this._cancellers.get(sessionId)?.({
-      code: HardwareErrorCode7.DeviceDisconnected,
+      code: HardwareErrorCode8.DeviceDisconnected,
       tag: "DeviceDisconnected",
       message: "Device disconnected"
     });
@@ -3292,14 +3935,14 @@ var LedgerConnectorBase = class {
     } catch (err) {
       if (isAppStuckByApdu(err)) {
         throw Object.assign(new Error("Ledger app is unresponsive"), {
-          code: HardwareErrorCode7.DeviceAppStuck,
+          code: HardwareErrorCode8.DeviceAppStuck,
           _tag: ERROR_TAG.DeviceAppStuck,
           originalError: err
         });
       }
       if (isTransportStuck(err)) {
         throw Object.assign(new Error("Device communication interrupted, please retry"), {
-          code: HardwareErrorCode7.TransportError,
+          code: HardwareErrorCode8.TransportError,
           _tag: ERROR_TAG.DeviceTransportStuck,
           originalError: err
         });
@@ -3356,6 +3999,49 @@ var LedgerConnectorBase = class {
         };
         return tronSignMessage(ctx, sessionId, internalParams);
       }
+      // OS-level device management — symmetric to chain handlers.
+      // _getDeviceApps wires onInteraction/onRegisterCanceller like _getEthSigner.
+      case "installApp": {
+        const p = params;
+        const apps = await _getDeviceApps(ctx, sessionId);
+        try {
+          return await apps.install(p.appName, p.onProgress);
+        } finally {
+          ctx.clearCanceller(sessionId);
+        }
+      }
+      case "listInstalledApps": {
+        const apps = await _getDeviceApps(ctx, sessionId);
+        try {
+          return await apps.listInstalled(params);
+        } finally {
+          ctx.clearCanceller(sessionId);
+        }
+      }
+      case "listAvailableApps": {
+        const apps = await _getDeviceApps(ctx, sessionId);
+        try {
+          return await apps.listAvailable();
+        } finally {
+          ctx.clearCanceller(sessionId);
+        }
+      }
+      case "getFirmwareVersion": {
+        const apps = await _getDeviceApps(ctx, sessionId);
+        try {
+          return await apps.getFirmwareVersion();
+        } finally {
+          ctx.clearCanceller(sessionId);
+        }
+      }
+      case "getDeviceInfo": {
+        const apps = await _getDeviceApps(ctx, sessionId);
+        try {
+          return await apps.getDeviceInfo();
+        } finally {
+          ctx.clearCanceller(sessionId);
+        }
+      }
       default:
         throw new Error(`LedgerConnector: unknown method "${method}"`);
     }
@@ -3428,6 +4114,7 @@ var LedgerConnectorBase = class {
       const mod = await importKit("@ledgerhq/device-signer-kit-ethereum");
       return new mod.SignerEthBuilder(args);
     });
+    this._deviceAppsManager = new DeviceAppsManager(dmk, importKit);
   }
   async _getDeviceManager() {
     if (this._deviceManager) return this._deviceManager;
@@ -3442,6 +4129,13 @@ var LedgerConnectorBase = class {
     }
     return this._signerManager;
   }
+  async _getDeviceAppsManager() {
+    if (!this._deviceAppsManager) {
+      const dmk = await this._getOrCreateDmk();
+      this._initManagers(dmk);
+    }
+    return this._deviceAppsManager;
+  }
   _invalidateSession(sessionId) {
     this._signerManager?.invalidate(sessionId);
   }
@@ -3477,6 +4171,8 @@ var LedgerConnectorBase = class {
     debugLog("[DMK] _resetSignersAndSessions called");
     this._signerManager?.clearAll();
     this._signerManager = null;
+    this._deviceAppsManager?.clearAll();
+    this._deviceAppsManager = null;
     this._deviceManager?.disposeKeepingDmk();
     this._deviceManager = null;
   }
@@ -3497,9 +4193,11 @@ var LedgerConnectorBase = class {
     }
     this._sessionStateSubs.clear();
     this._signerManager?.clearAll();
+    this._deviceAppsManager?.clearAll();
     this._deviceManager?.dispose();
     this._deviceManager = null;
     this._signerManager = null;
+    this._deviceAppsManager = null;
     this._dmk = null;
   }
   // ---------------------------------------------------------------------------