@bytezhang/ledger-adapter 0.0.3 → 0.0.4

package/dist/index.d.ts

@@ -0,0 +1,389 @@
+import { IHardwareWallet, IConnector, TransportType, IUiHandler, DeviceInfo, Response, ChainCapability, HardwareEventMap, DeviceEventListener, EvmGetAddressParams, EvmAddress, ProgressCallback, EvmGetPublicKeyParams, EvmPublicKey, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolGetPublicKeyParams, SolPublicKey, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, DeviceDescriptor, DeviceChangeEvent, HardwareErrorCode } from '@bytezhang/hardware-wallet-core';
+
+/**
+ * Ledger hardware wallet adapter that delegates to an IConnector.
+ *
+ * This is a thin translation layer that:
+ * - Accepts a pre-configured IConnector (transport decisions are made at connector creation time)
+ * - Translates IHardwareWallet method calls to connector.call() invocations
+ * - Maps connector results/errors to our Response<T> format with enriched error messages
+ * - Translates connector events to HardwareEventMap events
+ * - Integrates with IUiHandler for permission flows
+ */
+declare class LedgerAdapter implements IHardwareWallet {
+    readonly vendor: "ledger";
+    private readonly connector;
+    private readonly emitter;
+    private _uiHandler;
+    private _discoveredDevices;
+    private _sessions;
+    constructor(connector: IConnector);
+    get activeTransport(): TransportType | null;
+    getAvailableTransports(): TransportType[];
+    switchTransport(_type: TransportType): Promise<void>;
+    setUiHandler(handler: Partial<IUiHandler>): void;
+    init(_config?: unknown): Promise<void>;
+    dispose(): Promise<void>;
+    searchDevices(): Promise<DeviceInfo[]>;
+    connectDevice(connectId: string): Promise<Response<string>>;
+    disconnectDevice(connectId: string): Promise<void>;
+    getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
+    getSupportedChains(): ChainCapability[];
+    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;
+    off(event: string, listener: DeviceEventListener): void;
+    cancel(connectId: string): void;
+    evmGetAddress(connectId: string, _deviceId: string, params: EvmGetAddressParams): Promise<Response<EvmAddress>>;
+    evmGetAddresses(connectId: string, deviceId: string, params: EvmGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<EvmAddress[]>>;
+    evmGetPublicKey(connectId: string, _deviceId: string, params: EvmGetPublicKeyParams): Promise<Response<EvmPublicKey>>;
+    evmSignTransaction(connectId: string, _deviceId: string, params: EvmSignTxParams): Promise<Response<EvmSignedTx>>;
+    evmSignMessage(connectId: string, _deviceId: string, params: EvmSignMsgParams): Promise<Response<EvmSignature>>;
+    evmSignTypedData(connectId: string, _deviceId: string, params: EvmSignTypedDataParams): Promise<Response<EvmSignature>>;
+    btcGetAddress(connectId: string, _deviceId: string, params: BtcGetAddressParams): Promise<Response<BtcAddress>>;
+    btcGetAddresses(connectId: string, deviceId: string, params: BtcGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<BtcAddress[]>>;
+    btcGetPublicKey(connectId: string, _deviceId: string, params: BtcGetPublicKeyParams): Promise<Response<BtcPublicKey>>;
+    btcSignTransaction(connectId: string, _deviceId: string, params: BtcSignTxParams): Promise<Response<BtcSignedTx>>;
+    btcSignMessage(_connectId: string, _deviceId: string, _params: BtcSignMsgParams): Promise<Response<BtcSignature>>;
+    btcGetMasterFingerprint(connectId: string, _deviceId: string, params?: {
+        skipOpenApp?: boolean;
+    }): Promise<Response<{
+        masterFingerprint: string;
+    }>>;
+    solGetAddress(_connectId: string, _deviceId: string, _params: SolGetAddressParams): Promise<Response<SolAddress>>;
+    solGetAddresses(_connectId: string, _deviceId: string, _params: SolGetAddressParams[], _onProgress?: ProgressCallback): Promise<Response<SolAddress[]>>;
+    solGetPublicKey(_connectId: string, _deviceId: string, _params: SolGetPublicKeyParams): Promise<Response<SolPublicKey>>;
+    solSignTransaction(_connectId: string, _deviceId: string, _params: SolSignTxParams): Promise<Response<SolSignedTx>>;
+    solSignMessage(_connectId: string, _deviceId: string, _params: SolSignMsgParams): Promise<Response<SolSignature>>;
+    /**
+     * Ensure at least one device is connected and return a valid connectId.
+     *
+     * - 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.
+     */
+    private ensureConnected;
+    /**
+     * Call the connector with automatic session resolution and disconnect retry.
+     *
+     * 1. Resolves a valid connectId via ensureConnected()
+     * 2. Looks up sessionId from _sessions
+     * 3. Calls connector.call()
+     * 4. On disconnect error: clears stale session, re-connects, retries once
+     */
+    private connectorCall;
+    /**
+     * Ensure device permission before proceeding.
+     * - No connectId (searchDevices): check environment-level permission
+     * - With connectId (business methods): check device-level permission
+     * If not granted, calls onDevicePermission so the consumer can request access.
+     */
+    private _ensureDevicePermission;
+    /**
+     * Convert a thrown error to a Response failure.
+     * Uses mapLedgerError to parse Ledger DMK error codes into HardwareErrorCode values.
+     */
+    private errorToFailure;
+    /**
+     * Generic batch call with progress reporting.
+     * If any single call fails, returns the failure immediately.
+     */
+    private batchCall;
+    private deviceConnectHandler;
+    private deviceDisconnectHandler;
+    private uiRequestHandler;
+    private uiEventHandler;
+    private registerEventListeners;
+    private unregisterEventListeners;
+    private handleUiEvent;
+    private connectorDeviceToDeviceInfo;
+    private extractDeviceInfoFromPayload;
+    private unknownDevice;
+}
+
+interface DmkDiscoveredDevice {
+    id: string;
+    deviceModel: {
+        id: string;
+        productName: string;
+        model: string;
+        name: string;
+    };
+    transport: string;
+    [key: string]: unknown;
+}
+interface IDmk {
+    startDiscovering(args?: {
+        transport?: string;
+    }): {
+        subscribe(observer: {
+            next: (device: DmkDiscoveredDevice) => void;
+            error?: (err: unknown) => void;
+        }): {
+            unsubscribe: () => void;
+        };
+    };
+    stopDiscovering(): void;
+    listenToAvailableDevices(args?: {
+        transport?: string;
+    }): {
+        subscribe(observer: {
+            next: (devices: DmkDiscoveredDevice[]) => void;
+            error?: (err: unknown) => void;
+        }): {
+            unsubscribe: () => void;
+        };
+    };
+    connect(params: {
+        device: DmkDiscoveredDevice;
+    }): Promise<string>;
+    disconnect(params: {
+        sessionId: string;
+    }): Promise<void>;
+    sendCommand(params: {
+        sessionId: string;
+        command: unknown;
+    }): Promise<unknown>;
+    close?(): void;
+}
+interface DeviceActionState$1<T> {
+    status: 'pending' | 'completed' | 'error';
+    output?: T;
+    error?: unknown;
+    intermediateValue?: {
+        requiredUserInteraction?: string;
+        [key: string]: unknown;
+    };
+}
+interface SignerEvmAddress {
+    address: string;
+    publicKey: string;
+}
+interface SignerEvmSignature {
+    r: string;
+    s: string;
+    v: number;
+}
+interface SignerBtcAddress {
+    address: string;
+}
+interface TransportProviderOptions {
+    logger?: unknown;
+}
+interface TransportProviderInstance {
+    dmk: IDmk;
+    dispose?: () => Promise<void>;
+}
+interface TransportProvider {
+    create(options?: TransportProviderOptions): TransportProviderInstance;
+}
+
+/**
+ * Manages device discovery, connection, and session tracking.
+ * Wraps DMK's Observable APIs into simpler imperative calls.
+ */
+declare class LedgerDeviceManager {
+    private readonly _dmk;
+    private readonly _discovered;
+    private readonly _sessions;
+    private readonly _sessionToDevice;
+    private _listenSub;
+    constructor(dmk: IDmk);
+    /**
+     * One-shot enumeration: subscribe to listenToAvailableDevices,
+     * take the first emission, unsubscribe, return DeviceDescriptors.
+     */
+    enumerate(): Promise<DeviceDescriptor[]>;
+    /**
+     * Continuous listening: tracks device connect/disconnect via diffing.
+     */
+    listen(onChange: (event: DeviceChangeEvent) => void): void;
+    stopListening(): void;
+    /**
+     * Trigger browser device selection (WebHID requestDevice).
+     * Starts discovery for a short period, then stops.
+     */
+    requestDevice(timeoutMs?: number): Promise<void>;
+    /** Connect to a previously discovered device. Returns sessionId. */
+    connect(deviceId: string): Promise<string>;
+    /** Disconnect a session. */
+    disconnect(sessionId: string): Promise<void>;
+    getSessionId(deviceId: string): string | undefined;
+    getDeviceId(sessionId: string): string | undefined;
+    /** Get the underlying DMK instance (needed by SignerManager). */
+    getDmk(): IDmk;
+    dispose(): void;
+}
+
+/**
+ * SDK signer interface — duck-typed to avoid hard dependency on
+ * @ledgerhq/device-signer-kit-ethereum.
+ */
+interface ISdkSignerEth {
+    getAddress(derivationPath: string, options?: {
+        checkOnDevice?: boolean;
+    }): unknown;
+    signTransaction(derivationPath: string, transaction: Uint8Array, options?: unknown): unknown;
+    signMessage(derivationPath: string, message: string): unknown;
+    signTypedData(derivationPath: string, data: unknown): unknown;
+}
+/**
+ * Wraps Ledger's SDK signer (Observable-based DeviceActions) into
+ * a simple async interface returning plain serializable data.
+ */
+declare class SignerEth {
+    private readonly _sdk;
+    onInteraction?: (interaction: string) => void;
+    constructor(_sdk: ISdkSignerEth);
+    getAddress(derivationPath: string, options?: {
+        checkOnDevice?: boolean;
+    }): Promise<SignerEvmAddress>;
+    signTransaction(derivationPath: string, serializedTxHex: string): Promise<SignerEvmSignature>;
+    signMessage(derivationPath: string, message: string): Promise<SignerEvmSignature>;
+    signTypedData(derivationPath: string, data: unknown): Promise<SignerEvmSignature>;
+}
+
+type SignerEthBuilderFn = (args: {
+    dmk: IDmk;
+    sessionId: string;
+}) => {
+    build(): unknown;
+} | Promise<{
+    build(): unknown;
+}>;
+/**
+ * Manages per-sessionId SignerEth instances.
+ * Creates on demand, caches for reuse, invalidates on session change.
+ */
+declare class SignerManager {
+    private readonly _cache;
+    private readonly _dmk;
+    private readonly _builderFn;
+    constructor(dmk: IDmk, builderFn?: SignerEthBuilderFn);
+    getOrCreate(sessionId: string): Promise<SignerEth>;
+    invalidate(sessionId: string): void;
+    clearAll(): void;
+    private static _defaultBuilder;
+}
+
+/**
+ * SDK BTC signer interface — duck-typed to avoid hard dependency on
+ * @ledgerhq/device-signer-kit-bitcoin.
+ */
+interface ISdkSignerBtc {
+    getExtendedPublicKey(derivationPath: string, options?: {
+        checkOnDevice?: boolean;
+    }): unknown;
+    getWalletAddress(wallet: unknown, addressIndex: number, options?: {
+        checkOnDevice?: boolean;
+        change?: boolean;
+    }): unknown;
+    getMasterFingerprint(options?: {
+        skipOpenApp?: boolean;
+    }): unknown;
+}
+/**
+ * Wraps Ledger's BTC SDK signer (Observable-based DeviceActions) into
+ * a simple async interface returning plain serializable data.
+ */
+declare class SignerBtc {
+    private readonly _sdk;
+    onInteraction?: (interaction: string) => void;
+    constructor(_sdk: ISdkSignerBtc);
+    getWalletAddress(wallet: unknown, addressIndex: number, options?: {
+        checkOnDevice?: boolean;
+        change?: boolean;
+    }): Promise<SignerBtcAddress>;
+    getExtendedPublicKey(derivationPath: string, options?: {
+        checkOnDevice?: boolean;
+    }): Promise<string>;
+    getMasterFingerprint(options?: {
+        skipOpenApp?: boolean;
+    }): Promise<Uint8Array>;
+}
+
+/** DeviceAction state emitted by DMK signer operations. */
+interface DeviceActionState<T> {
+    status: 'pending' | 'completed' | 'error';
+    output?: T;
+    error?: unknown;
+    intermediateValue?: {
+        requiredUserInteraction?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Convert a DMK DeviceAction (Observable-based) into a Promise.
+ * Handles pending → completed/error state transitions and interaction callbacks.
+ */
+declare function deviceActionToPromise<T>(action: {
+    observable: {
+        subscribe(observer: {
+            next: (value: DeviceActionState<T>) => void;
+            error?: (err: unknown) => void;
+            complete?: () => void;
+        }): {
+            unsubscribe: () => void;
+        };
+    };
+}, onInteraction?: (interaction: string) => void): Promise<T>;
+
+declare function registerTransport(type: string, provider: TransportProvider): void;
+declare function unregisterTransport(type: string): void;
+declare function getTransportProvider(type: string): TransportProvider | null;
+declare function listRegisteredTransports(): string[];
+declare function clearRegistry(): void;
+
+interface AppManagerOptions {
+    waitMs?: number;
+    maxRetries?: number;
+}
+/**
+ * Orchestrates opening / closing Ledger on-device apps so that the
+ * correct signer application is running before any signing call.
+ */
+declare class AppManager {
+    private readonly _dmk;
+    private readonly _waitMs;
+    private readonly _maxRetries;
+    constructor(dmk: IDmk, options?: AppManagerOptions);
+    /**
+     * Return the Ledger app name for a given chain ticker,
+     * or undefined if the chain is not supported.
+     */
+    static getAppName(chain: string): string | undefined;
+    /**
+     * Ensure the target app is open on the device identified by `sessionId`.
+     *
+     * Flow:
+     * 1. Check the currently running app.
+     * 2. If it is already the target, return immediately.
+     * 3. If a different app is running (not dashboard), close it first.
+     * 4. Open the target app.
+     * 5. Poll until the device confirms the target app is running.
+     */
+    ensureAppOpen(sessionId: string, targetAppName: string): Promise<void>;
+    private _getCurrentApp;
+    private _openApp;
+    private _closeCurrentApp;
+    /**
+     * Poll the device until the expected app is reported as running,
+     * or throw after `_maxRetries` attempts.
+     */
+    private _waitForApp;
+    private _isDashboard;
+    private _wait;
+}
+
+/** Check if an error (or any error in its chain) represents a locked Ledger device. */
+declare function isDeviceLockedError(err: unknown): boolean;
+/**
+ * Map a Ledger DMK error to a HardwareErrorCode and human-readable message
+ * with actionable recovery information for the caller.
+ */
+declare function mapLedgerError(err: unknown): {
+    code: HardwareErrorCode;
+    message: string;
+};
+
+export { AppManager, type DeviceActionState$1 as DeviceActionState, type DmkDiscoveredDevice, type IDmk, LedgerAdapter, LedgerDeviceManager, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, type TransportProvider, type TransportProviderInstance, type TransportProviderOptions, clearRegistry, deviceActionToPromise, getTransportProvider, isDeviceLockedError, listRegisteredTransports, mapLedgerError, registerTransport, unregisterTransport };

package/dist/index.js

@@ -494,12 +494,88 @@ var LedgerAdapter = class {
   // Private helpers
   // ---------------------------------------------------------------------------
   /**
-   * Call the connector with session resolution.
-   * Looks up sessionId from connectId, falls back to connectId itself.
+   * Ensure at least one device is connected and return a valid connectId.
+   *
+   * - 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.
+   */
+  async ensureConnected(connectId) {
+    if (connectId && this._sessions.has(connectId)) {
+      return connectId;
+    }
+    if (this._sessions.size > 0) {
+      return this._sessions.keys().next().value;
+    }
+    const devices = await this.searchDevices();
+    if (devices.length === 0) {
+      throw Object.assign(
+        new Error("No Ledger device found. Make sure the device is connected via USB and ready."),
+        { _tag: "DeviceNotRecognizedError" }
+      );
+    }
+    if (devices.length === 1) {
+      const result2 = await this.connectDevice(devices[0].connectId);
+      if (!result2.success) {
+        throw Object.assign(
+          new Error(result2.payload.error),
+          { _tag: "DeviceNotRecognizedError" }
+        );
+      }
+      return devices[0].connectId;
+    }
+    if (this._uiHandler?.onSelectDevice) {
+      const selectedConnectId = await this._uiHandler.onSelectDevice(devices);
+      const result2 = await this.connectDevice(selectedConnectId);
+      if (!result2.success) {
+        throw Object.assign(
+          new Error(result2.payload.error),
+          { _tag: "DeviceNotRecognizedError" }
+        );
+      }
+      return selectedConnectId;
+    }
+    const result = await this.connectDevice(devices[0].connectId);
+    if (!result.success) {
+      throw Object.assign(
+        new Error(result.payload.error),
+        { _tag: "DeviceNotRecognizedError" }
+      );
+    }
+    return devices[0].connectId;
+  }
+  /**
+   * Call the connector with automatic session resolution and disconnect retry.
+   *
+   * 1. Resolves a valid connectId via ensureConnected()
+   * 2. Looks up sessionId from _sessions
+   * 3. Calls connector.call()
+   * 4. On disconnect error: clears stale session, re-connects, retries once
    */
   async connectorCall(connectId, method, params) {
-    const sessionId = this._sessions.get(connectId) ?? connectId;
-    return this.connector.call(sessionId, method, params);
+    const resolvedConnectId = await this.ensureConnected(connectId);
+    const sessionId = this._sessions.get(resolvedConnectId);
+    if (!sessionId) {
+      throw Object.assign(
+        new Error("Auto-connect succeeded but no session found"),
+        { _tag: "DeviceSessionNotFound" }
+      );
+    }
+    try {
+      return await this.connector.call(sessionId, method, params);
+    } catch (err) {
+      if (isDeviceDisconnectedError(err)) {
+        this._sessions.delete(resolvedConnectId);
+        this._discoveredDevices.clear();
+        const retryConnectId = await this.ensureConnected();
+        const retrySessionId = this._sessions.get(retryConnectId);
+        if (!retrySessionId) {
+          throw err;
+        }
+        return this.connector.call(retrySessionId, method, params);
+      }
+      throw err;
+    }
   }
   /**
    * Ensure device permission before proceeding.
@@ -597,7 +673,8 @@ var LedgerAdapter = class {
       deviceId: device.deviceId,
       connectId: device.connectId,
       label: device.name,
-      connectionType: "usb"
+      connectionType: "usb",
+      capabilities: device.capabilities
     };
   }
   extractDeviceInfoFromPayload(payload) {
@@ -640,13 +717,21 @@ var LedgerDeviceManager = class {
    */
   enumerate() {
     return new Promise((resolve) => {
-      const sub = this._dmk.listenToAvailableDevices().subscribe({
+      let resolved = false;
+      let sub = null;
+      sub = this._dmk.listenToAvailableDevices().subscribe({
         next: (devices) => {
+          if (resolved) return;
+          resolved = true;
           this._discovered.clear();
           for (const d of devices) {
             this._discovered.set(d.id, d);
           }
-          sub.unsubscribe();
+          if (sub) {
+            sub.unsubscribe();
+          } else {
+            Promise.resolve().then(() => sub?.unsubscribe());
+          }
           console.log("[LedgerDeviceManager] enumerate devices:", JSON.stringify(devices.map((d) => ({
             id: d.id,
             deviceModel: d.deviceModel,
@@ -655,7 +740,9 @@ var LedgerDeviceManager = class {
           resolve(devices.map((d) => ({ path: d.id, type: d.deviceModel.name })));
         },
         error: () => {
-          sub.unsubscribe();
+          if (resolved) return;
+          resolved = true;
+          sub?.unsubscribe();
           resolve([]);
         }
       });