@bytezhang/ledger-adapter 0.0.10 → 0.0.11

package/dist/entries/node.d.mts

@@ -0,0 +1,5 @@
+declare function registerNodeTransport(options?: {
+    logger?: unknown;
+}): void;
+
+export { registerNodeTransport };

package/dist/entries/node.d.ts

@@ -0,0 +1,5 @@
+declare function registerNodeTransport(options?: {
+    logger?: unknown;
+}): void;
+
+export { registerNodeTransport };

package/dist/entries/react-native.d.mts

@@ -0,0 +1,5 @@
+declare function registerRnBleTransport(options?: {
+    logger?: unknown;
+}): void;
+
+export { registerRnBleTransport };

package/dist/entries/react-native.d.ts

@@ -0,0 +1,5 @@
+declare function registerRnBleTransport(options?: {
+    logger?: unknown;
+}): void;
+
+export { registerRnBleTransport };

package/dist/entries/web.d.mts

@@ -0,0 +1,5 @@
+declare function registerWebTransports(options?: {
+    logger?: unknown;
+}): void;
+
+export { registerWebTransports };

package/dist/entries/web.d.ts

@@ -0,0 +1,5 @@
+declare function registerWebTransports(options?: {
+    logger?: unknown;
+}): void;
+
+export { registerWebTransports };

package/dist/index.d.mts

@@ -0,0 +1,539 @@
+import { IHardwareWallet, IConnector, TransportType, IUiHandler, DeviceInfo, Response, ChainCapability, HardwareEventMap, DeviceEventListener, ChainForFingerprint, 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, ConnectionType, DeviceDescriptor, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, 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;
+    getChainFingerprint(connectId: string, deviceId: string, chain: ChainForFingerprint): Promise<Response<string>>;
+    /**
+     * Verify that the connected device matches the expected fingerprint.
+     *
+     * - If deviceId is empty, verification is skipped (returns true).
+     * - deviceId is used here as the stored fingerprint to compare against.
+     */
+    private _verifyDeviceFingerprint;
+    /**
+     * Derive an address at the fixed testnet path for fingerprint generation.
+     */
+    private _deriveAddressForFingerprint;
+    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): 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 static readonly MAX_DEVICE_RETRY;
+    private _deviceConnectResolve;
+    private _connectingPromise;
+    private static readonly DEVICE_CONNECT_TIMEOUT_MS;
+    /**
+     * Wait for user to connect and unlock device.
+     * Emits 'ui-request' event via the adapter's own emitter.
+     * The consumer (monorepo adapter wrapper) listens for this and shows UI.
+     * When user confirms, they call adapter.deviceConnectResponse() which resolves this promise.
+     * Times out after 60 seconds if no response is received.
+     */
+    private _waitForDeviceConnect;
+    /**
+     * Called by consumer to respond to ui-request-device-connect.
+     * type='confirm' → retry search, type='cancel' → abort.
+     */
+    deviceConnectResponse(type: 'confirm' | 'cancel'): void;
+    private ensureConnected;
+    private _doConnect;
+    private _connectFirstOrSelect;
+    /**
+     * 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;
+}
+
+/**
+ * A function that lazily loads and returns the transport factory
+ * for the Ledger DMK builder (e.g. webHidTransportFactory, rnBleTransportFactory).
+ */
+type TransportFactory = () => Promise<unknown>;
+interface LedgerConnectorBaseOptions {
+    /**
+     * Pre-built DMK instance. If not provided, a DMK will be created
+     * lazily on first use via the transport factory.
+     */
+    dmk?: IDmk;
+}
+/**
+ * Shared base class for Ledger IConnector implementations.
+ *
+ * Encapsulates all shared logic: device discovery, connection management,
+ * method dispatch (EVM / BTC / SOL), signer lifecycle, event emission,
+ * and error handling.
+ *
+ * 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).
+ */
+declare class LedgerConnectorBase implements IConnector {
+    private _deviceManager;
+    private _signerManager;
+    private _dmk;
+    private readonly _eventHandlers;
+    private readonly _providedDmk;
+    private readonly _createTransport;
+    private readonly _connectionType;
+    constructor(createTransport: TransportFactory, options?: {
+        connectionType?: ConnectionType;
+        dmk?: IDmk;
+    });
+    /**
+     * 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).
+     */
+    protected _resolveConnectId(descriptor: DeviceDescriptor): string;
+    searchDevices(): Promise<ConnectorDevice[]>;
+    connect(deviceId?: string): Promise<ConnectorSession>;
+    disconnect(sessionId: string): Promise<void>;
+    call(sessionId: string, method: string, params: unknown): Promise<unknown>;
+    cancel(_sessionId: string): Promise<void>;
+    uiResponse(_response: {
+        type: string;
+        payload: unknown;
+    }): void;
+    on<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
+    off<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
+    reset(): void;
+    private _evmGetAddress;
+    private _evmSignTransaction;
+    private _evmSignMessage;
+    private _evmSignTypedData;
+    private _btcGetAddress;
+    private _btcGetPublicKey;
+    private _btcSignTransaction;
+    private _btcSignMessage;
+    private _btcGetMasterFingerprint;
+    private _solGetAddress;
+    private _solSignTransaction;
+    private _solSignMessage;
+    /**
+     * Lazily create or return the DMK instance.
+     * If a DMK was provided via constructor, it is used directly.
+     * Otherwise, one is created via the transport factory.
+     */
+    protected _getOrCreateDmk(): Promise<IDmk>;
+    private _initManagers;
+    private _getDeviceManager;
+    private _getEthSigner;
+    private _createBtcSigner;
+    private _createSolSigner;
+    private _invalidateSession;
+    private _resetManagers;
+    private _emit;
+    private _wrapError;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * SDK SOL signer interface — duck-typed to avoid hard dependency on
+ * @ledgerhq/device-signer-kit-solana.
+ */
+interface ISdkSignerSol {
+    getAddress(derivationPath: string, options?: {
+        checkOnDevice?: boolean;
+    }): unknown;
+    signTransaction(derivationPath: string, transaction: Uint8Array, options?: unknown): unknown;
+    signMessage(derivationPath: string, message: string | Uint8Array, options?: unknown): unknown;
+}
+/**
+ * Wraps Ledger's Solana SDK signer (Observable-based DeviceActions) into
+ * a simple async interface returning plain serializable data.
+ *
+ * The Solana signer's `getAddress` returns a base58-encoded Ed25519 public key,
+ * which is also the Solana address.
+ */
+declare class SignerSol {
+    private readonly _sdk;
+    onInteraction?: (interaction: string) => void;
+    constructor(_sdk: ISdkSignerSol);
+    /**
+     * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
+     */
+    getAddress(derivationPath: string, options?: {
+        checkOnDevice?: boolean;
+    }): Promise<string>;
+    /**
+     * Sign a Solana transaction.
+     */
+    signTransaction(derivationPath: string, transaction: Uint8Array, options?: unknown): Promise<Uint8Array>;
+    /**
+     * Sign a message with the Solana app.
+     */
+    signMessage(derivationPath: string, message: string | Uint8Array, options?: unknown): 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, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, type TransportProvider, type TransportProviderInstance, type TransportProviderOptions, clearRegistry, deviceActionToPromise, getTransportProvider, isDeviceLockedError, listRegisteredTransports, mapLedgerError, registerTransport, unregisterTransport };