@onekeyfe/hardware-cli 1.1.26-alpha.106 → 1.1.26-alpha.4

package/dist/index.d.ts

@@ -1,95 +1,22 @@
-import * as _onekeyfe_hd_core from '@onekeyfe/hd-core';
-import { CoreApi } from '@onekeyfe/hd-core';
-
 /**
- * SDK Factory — creates and initializes the hardware SDK instance
- * for CLI usage with the appropriate transport.
+ * @onekeyfe/hardware-cli
  *
- * CRITICAL: Must register UI event handlers for PIN, Passphrase, and Button
- * confirmation. Without these, the SDK will hang waiting for responses.
+ * OneKey hardware wallet CLI for AI agent integration.
+ * Provides device management, multi-chain signing, firmware updates,
+ * and security management capabilities.
  *
- * Reference: packages/core/src/core/index.ts (event registration pattern)
- */
-interface SDKOptions {
-    connectId?: string;
-    passphraseState?: string;
-    useEmptyPassphrase?: boolean;
-}
-declare function createSDK(opts: SDKOptions): Promise<_onekeyfe_hd_core.CoreApi>;
-
-/**
- * Chain Resolver — maps chain identifiers to the correct SDK API calls.
- * Handles derivation path defaults and chain-specific parameter transformations.
+ * Usage:
+ *   npx @onekeyfe/hardware-cli search
+ *   npx @onekeyfe/hardware-cli get-address --chain evm
+ *   npx @onekeyfe/hardware-cli sign-transaction --chain evm --tx '{...}'
  *
- * Reference: developer-portal docs at
- *   content/en/hardware-sdk/chains/<chain>/<method>.mdx
- *   content/en/hardware-sdk/core-api-guide.mdx (HD path section)
+ * All output is structured JSON for AI agent consumption.
  *
- * Type definitions: packages/core/src/types/api/*.ts
- */
-
-/**
- * Common params passed to all SDK methods.
- * Reference: packages/core/src/types/api/export.ts (CommonParams)
+ * IMPORTANT: All signing operations require physical confirmation on the
+ * hardware device. The CLI handles PIN/Passphrase prompts via stdin for
+ * interactive use, or via SDK event system for programmatic use.
  */
-interface CommonCLIParams {
-    connectId?: string;
-    deviceId?: string;
-    passphraseState?: string;
-    useEmptyPassphrase?: boolean;
-}
-interface GetAddressParams extends CommonCLIParams {
-    chain: string;
-    path?: string;
-    showOnDevice?: boolean;
-}
-declare function resolveGetAddress(sdk: CoreApi, params: GetAddressParams): Promise<{
-    success: boolean;
-    error: string;
-    chain: string;
-    path: string;
-} | {
-    chain: string;
-    path: string;
-    success?: undefined;
-    error?: undefined;
-}>;
-interface GetPublicKeyParams extends CommonCLIParams {
-    chain: string;
-    path?: string;
-}
-declare function resolveGetPublicKey(sdk: CoreApi, params: GetPublicKeyParams): Promise<{
-    chain: string;
-    path: string;
-}>;
-interface SignTransactionParams extends CommonCLIParams {
-    chain: string;
-    path?: string;
-    transaction: Record<string, unknown>;
-}
-declare function resolveSignTransaction(sdk: CoreApi, params: SignTransactionParams): Promise<{
-    chain: string;
-    path: string;
-}>;
-interface SignMessageParams extends CommonCLIParams {
-    chain: string;
-    path?: string;
-    message: string;
-}
-declare function resolveSignMessage(sdk: CoreApi, params: SignMessageParams): Promise<{
-    chain: string;
-    path: string;
-}>;
-interface BatchGetAddressParams extends CommonCLIParams {
-    bundle: Array<{
-        chain: string;
-        path?: string;
-        showOnDevice?: boolean;
-    }>;
-}
-declare function resolveBatchGetAddress(sdk: CoreApi, params: BatchGetAddressParams): Promise<{
-    success: boolean;
-    addresses: Record<string, unknown>[];
-}>;
-
-export { BatchGetAddressParams, CommonCLIParams, GetAddressParams, GetPublicKeyParams, SDKOptions, SignMessageParams, SignTransactionParams, createSDK, resolveBatchGetAddress, resolveGetAddress, resolveGetPublicKey, resolveSignMessage, resolveSignTransaction };
+export { createSDK } from './sdk';
+export type { SDKOptions } from './sdk';
+export { resolveGetAddress, resolveGetPublicKey, resolveSignTransaction, resolveSignMessage, resolveBatchGetAddress, } from './chains';
+export type { CommonCLIParams, GetAddressParams, GetPublicKeyParams, SignTransactionParams, SignMessageParams, BatchGetAddressParams, } from './chains';

package/dist/index.js

@@ -1,5 +1,4 @@
-'use strict';
-
+"use strict";
 /**
  * @onekeyfe/hardware-cli
  *

package/dist/sdk.d.ts

@@ -2,14 +2,24 @@
  * SDK Factory — creates and initializes the hardware SDK instance
  * for CLI usage with the appropriate transport.
  *
- * CRITICAL: Must register UI event handlers for PIN, Passphrase, and Button
- * confirmation. Without these, the SDK will hang waiting for responses.
- *
- * Reference: packages/core/src/core/index.ts (event registration pattern)
+ * Passphrase flow aligns with app-monorepo CLI:
+ *   - Standard wallet: --use-empty-passphrase, auto-respond
+ *   - Hidden wallet: interactive 1/2/3 selection (standard / pinentry / on-device)
+ *   - Session caching: passphraseState + sessionId stored in OS keychain,
+ *     preloaded via preloadSessionCache on next invocation
  */
+import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 export interface SDKOptions {
     connectId?: string;
     passphraseState?: string;
     useEmptyPassphrase?: boolean;
 }
-export declare function createSDK(opts: SDKOptions): Promise<import("@onekeyfe/hd-core").CoreApi>;
+export declare function createSDK(opts: SDKOptions): Promise<typeof HardwareSDK>;
+/**
+ * Release the SDK and clear the singleton. Must be called before the CLI
+ * process exits — the USB transport holds open handles (event listeners,
+ * polling timers) that otherwise keep Node.js alive for ~26s.
+ *
+ * Safe to call multiple times (no-op after the first successful call).
+ */
+export declare function disposeSDK(): Promise<void>;

package/dist/sdk.js

@@ -1,189 +1,295 @@
-'use strict';
-
+"use strict";
 /**
  * SDK Factory — creates and initializes the hardware SDK instance
  * for CLI usage with the appropriate transport.
  *
- * CRITICAL: Must register UI event handlers for PIN, Passphrase, and Button
- * confirmation. Without these, the SDK will hang waiting for responses.
- *
- * Reference: packages/core/src/core/index.ts (event registration pattern)
+ * Passphrase flow aligns with app-monorepo CLI:
+ *   - Standard wallet: --use-empty-passphrase, auto-respond
+ *   - Hidden wallet: interactive 1/2/3 selection (standard / pinentry / on-device)
+ *   - Session caching: passphraseState + sessionId stored in OS keychain,
+ *     preloaded via preloadSessionCache on next invocation
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSDK = void 0;
-const tslib_1 = require("tslib");
-// @ts-ignore - hd-common-connect-sdk may not have type declarations
-const hd_common_connect_sdk_1 = tslib_1.__importDefault(require("@onekeyfe/hd-common-connect-sdk"));
+exports.disposeSDK = exports.createSDK = void 0;
+const node_child_process_1 = require("node:child_process");
+const readline = __importStar(require("node:readline"));
+const hd_common_connect_sdk_1 = __importDefault(require("@onekeyfe/hd-common-connect-sdk"));
 const hd_core_1 = require("@onekeyfe/hd-core");
-const hd_transport_usb_1 = require("@onekeyfe/hd-transport-usb");
-const readline = tslib_1.__importStar(require("readline"));
 /**
- * Prompt user for input in the terminal (hidden for PIN).
- * Falls back to empty string in non-TTY (piped) mode.
+ * Current per-invocation CLI options. Event handlers read from this object
+ * so that invoking createSDK() with different opts never results in stale
+ * closure captures — the SDK is a singleton, but opts can change per call.
+ */
+let currentOpts = {};
+/**
+ * Promise-singleton that resolves to the initialised SDK. Set on first call,
+ * reused by all subsequent (and concurrent) callers.
+ *
+ * Using a Promise instead of a boolean flag eliminates the race where two
+ * concurrent createSDK() calls could both pass the "initialised?" check
+ * before the flag was set, then both run init() — each call replaces the
+ * internal Core/Connector at the hd-core layer and leaks USB handles.
+ *
+ * Mirrors app-monorepo's apps/cli/src/commands/device/hardware-sdk.ts
+ * (sdkReadyPromise). Cleared by disposeSDK() so REPL/test harnesses can
+ * re-init cleanly after an explicit tear-down.
  */
-function promptUser(question, hidden = false) {
+let sdkReadyPromise = null;
+// ---------------------------------------------------------------------------
+// Pinentry — secure passphrase input via native OS dialog
+// ---------------------------------------------------------------------------
+const PINENTRY_PROGRAMS = ['pinentry-mac', 'pinentry', 'pinentry-gnome3', 'pinentry-qt'];
+function findPinentry() {
+    for (const prog of PINENTRY_PROGRAMS) {
+        try {
+            const result = (0, node_child_process_1.execFileSync)('which', [prog], {
+                encoding: 'utf-8',
+                timeout: 2000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            if (result.trim())
+                return prog;
+        }
+        catch {
+            // not found
+        }
+    }
+    return null;
+}
+function promptPassphraseViaPinentry() {
+    return new Promise((resolve, reject) => {
+        const pinentryBin = findPinentry();
+        if (!pinentryBin) {
+            process.stderr.write('[onekey-hw] No pinentry found, falling back to on-device entry.\n');
+            resolve({ value: '', passphraseOnDevice: true });
+            return;
+        }
+        const commands = [
+            'SETDESC OneKey Hardware Wallet',
+            'SETPROMPT Enter passphrase',
+            'GETPIN',
+            'BYE',
+        ].join('\n');
+        const child = (0, node_child_process_1.execFile)(pinentryBin, [], { timeout: 120000, encoding: 'utf-8' }, (error, stdout) => {
+            if (error) {
+                if (error.killed || (stdout && stdout.includes('ERR 83886179'))) {
+                    process.stderr.write('[onekey-hw] Passphrase entry cancelled, falling back to on-device.\n');
+                    resolve({ value: '', passphraseOnDevice: true });
+                    return;
+                }
+                reject(error);
+                return;
+            }
+            const dataLine = stdout.split('\n').find(l => l.startsWith('D '));
+            if (dataLine) {
+                resolve({ value: dataLine.slice(2), passphraseOnDevice: false });
+                return;
+            }
+            if (stdout.includes('ERR 83886179') || stdout.includes('Operation cancelled')) {
+                process.stderr.write('[onekey-hw] Passphrase entry cancelled, falling back to on-device.\n');
+                resolve({ value: '', passphraseOnDevice: true });
+                return;
+            }
+            // Empty passphrase — on-device
+            resolve({ value: '', passphraseOnDevice: true });
+        });
+        child.stdin?.write(commands);
+        child.stdin?.end();
+    });
+}
+// ---------------------------------------------------------------------------
+// Interactive prompts
+// ---------------------------------------------------------------------------
+/**
+ * Prompt user to select wallet type (aligns with app-monorepo flow):
+ *   1. Standard wallet (no passphrase)
+ *   2. Hidden wallet — enter passphrase via pinentry (secure OS dialog)
+ *   3. Hidden wallet — enter passphrase on device screen
+ */
+function resolvePassphraseByChoice(choice) {
+    if (choice === '1')
+        return Promise.resolve({ value: '', passphraseOnDevice: false });
+    if (choice === '2')
+        return promptPassphraseViaPinentry();
+    return Promise.resolve({ value: '', passphraseOnDevice: true });
+}
+function promptPassphraseMode() {
     if (!process.stdin.isTTY) {
-        // Non-interactive mode: return empty (agent should handle via uiResponse)
-        return Promise.resolve('');
+        return Promise.resolve({ value: '', passphraseOnDevice: true });
     }
     return new Promise(resolve => {
         const rl = readline.createInterface({
             input: process.stdin,
-            output: process.stderr, // Use stderr so JSON stdout stays clean
+            output: process.stderr,
+            terminal: true,
         });
-        if (hidden) {
-            // Mute output for PIN entry
-            process.stderr.write(question);
-            const { stdin } = process;
-            const wasRaw = stdin.isRaw;
-            if (stdin.setRawMode)
-                stdin.setRawMode(true);
-            let input = '';
-            const onData = (char) => {
-                const c = char.toString('utf8');
-                if (c === '\n' || c === '\r' || c === '\u0004') {
-                    if (stdin.setRawMode)
-                        stdin.setRawMode(wasRaw ?? false);
-                    stdin.removeListener('data', onData);
-                    process.stderr.write('\n');
+        const prompt = () => {
+            process.stderr.write([
+                '[onekey-hw] Select wallet type:',
+                '  1. Standard wallet (no passphrase)',
+                '  2. Hidden wallet — enter passphrase on this computer (pinentry)',
+                '  3. Hidden wallet — enter passphrase on device screen',
+                '',
+            ].join('\n'));
+            rl.question('Enter selection [1/2/3]: ', answer => {
+                const n = answer.trim();
+                if (n === '1' || n === '2' || n === '3') {
                     rl.close();
-                    resolve(input);
+                    resolvePassphraseByChoice(n).then(resolve);
+                    return;
                 }
-                else if (c === '\u0003') {
-                    // Ctrl+C
-                    process.exit(1);
-                }
-                else if (c === '\u007F' || c === '\b') {
-                    // Backspace
-                    input = input.slice(0, -1);
-                }
-                else {
-                    input += c;
-                    process.stderr.write('*');
-                }
-            };
-            stdin.on('data', onData);
-        }
-        else {
-            rl.question(question, answer => {
-                rl.close();
-                resolve(answer);
+                process.stderr.write('Invalid selection. Enter 1, 2, or 3.\n');
+                prompt();
             });
-        }
+        };
+        prompt();
     });
 }
-/**
- * Register UI event handlers for interactive device operations.
- *
- * The SDK emits events when the device needs user interaction:
- * - PIN entry (entered on device screen for Touch/Pro, or via matrix for Classic)
- * - Passphrase input (for hidden wallets)
- * - Button confirmation (user must physically press on device)
- *
- * Reference: packages/core/src/core/index.ts lines 315-330, 1021-1098
- */
-function registerEventHandlers(sdk, opts) {
+// ---------------------------------------------------------------------------
+// Event handlers
+// ---------------------------------------------------------------------------
+function registerEventHandlers(sdk) {
     sdk.on(hd_core_1.UI_EVENT, (message) => {
-        // PIN Request
-        // For Touch/Pro devices, PIN is entered on-device (device screen shows numpad).
-        // For Classic devices, PIN uses a matrix mapping.
-        // In CLI context, we auto-acknowledge since PIN entry happens on-device.
+        // PIN Request — always on-device for CLI security (no terminal echo).
+        // The sentinel '@@ONEKEY_INPUT_PIN_IN_DEVICE' makes DeviceCommands send
+        // `BixinPinInputOnDevice` so the device switches to on-device PIN entry.
+        // Sending an empty string would be treated as a wrong (empty) PIN and
+        // would consume a PIN retry on Classic/1S/Mini/Pure.
+        // Touch/Pro never emit PinMatrixRequest — they handle PIN on touchscreen
+        // before this code path runs, so the sentinel is harmless there.
         if (message.type === hd_core_1.UI_REQUEST.REQUEST_PIN) {
-            const pinType = message.payload?.type;
-            if (pinType === 'ButtonRequest_PinEntry' || pinType === 'ButtonRequest_AttachPin') {
-                // PIN is entered directly on device screen (Touch/Pro)
-                process.stderr.write('[onekey-hw] Please enter PIN on your device screen...\n');
-                // No uiResponse needed — device handles PIN input internally
-            }
-            else {
-                // Classic devices: PIN entry via matrix
-                // In CLI mode, prompt user or let agent handle
-                process.stderr.write('[onekey-hw] PIN required. Please enter PIN on your device.\n');
-                promptUser('PIN (on-device numpad mapping): ', true).then(pin => {
-                    sdk.uiResponse({
-                        type: hd_core_1.UI_RESPONSE.RECEIVE_PIN,
-                        payload: pin,
-                    });
-                });
-            }
+            process.stderr.write('[onekey-hw] Please enter PIN on your device screen...\n');
+            sdk.uiResponse({
+                type: hd_core_1.UI_RESPONSE.RECEIVE_PIN,
+                payload: '@@ONEKEY_INPUT_PIN_IN_DEVICE',
+            });
         }
         // Passphrase Request
-        // User must provide passphrase for hidden wallet access.
-        // Passphrase can be entered on-device (Touch/Pro) or via host.
         if (message.type === hd_core_1.UI_REQUEST.REQUEST_PASSPHRASE) {
-            if (opts.useEmptyPassphrase) {
-                // Standard wallet (no passphrase)
+            // 1. Explicit --use-empty-passphrase: auto-respond
+            if (currentOpts.useEmptyPassphrase) {
+                sdk.uiResponse({
+                    type: hd_core_1.UI_RESPONSE.RECEIVE_PASSPHRASE,
+                    payload: { value: '', passphraseOnDevice: false, save: false },
+                });
+                return;
+            }
+            // 2. Interactive: 1/2/3 selection
+            promptPassphraseMode()
+                .then(result => {
                 sdk.uiResponse({
                     type: hd_core_1.UI_RESPONSE.RECEIVE_PASSPHRASE,
                     payload: {
-                        value: '',
-                        passphraseOnDevice: false,
+                        value: result.value,
+                        passphraseOnDevice: result.passphraseOnDevice,
                         save: false,
                     },
                 });
-            }
-            else {
-                process.stderr.write('[onekey-hw] Passphrase required for hidden wallet.\n');
-                promptUser('Enter passphrase (or press Enter for on-device entry): ').then(passphrase => {
-                    if (passphrase === '') {
-                        // Enter on device
-                        sdk.uiResponse({
-                            type: hd_core_1.UI_RESPONSE.RECEIVE_PASSPHRASE,
-                            payload: {
-                                value: '',
-                                passphraseOnDevice: true,
-                                save: false,
-                            },
-                        });
-                    }
-                    else {
-                        sdk.uiResponse({
-                            type: hd_core_1.UI_RESPONSE.RECEIVE_PASSPHRASE,
-                            payload: {
-                                value: passphrase,
-                                passphraseOnDevice: false,
-                                save: false,
-                            },
-                        });
-                    }
+            })
+                .catch(() => {
+                process.stderr.write('[onekey-hw] Passphrase prompt failed, falling back to on-device.\n');
+                sdk.uiResponse({
+                    type: hd_core_1.UI_RESPONSE.RECEIVE_PASSPHRASE,
+                    payload: { value: '', passphraseOnDevice: true, save: false },
                 });
-            }
+            });
         }
         // Passphrase On Device
         if (message.type === hd_core_1.UI_REQUEST.REQUEST_PASSPHRASE_ON_DEVICE) {
             process.stderr.write('[onekey-hw] Please enter passphrase on your device screen...\n');
         }
         // Button Confirmation
-        // User must physically press confirm/reject on the device.
         if (message.type === hd_core_1.UI_REQUEST.REQUEST_BUTTON) {
             process.stderr.write('[onekey-hw] Please confirm the action on your device...\n');
         }
     });
-    // Device connection events — only show when device has a known name
     sdk.on(hd_core_1.DEVICE.CONNECT, (device) => {
         const name = device?.label || device?.name;
-        if (name) {
+        if (name)
             process.stderr.write(`[onekey-hw] Device connected: ${name}\n`);
-        }
     });
     sdk.on(hd_core_1.DEVICE.DISCONNECT, (device) => {
         const name = device?.label || device?.name;
-        if (name) {
+        if (name)
             process.stderr.write(`[onekey-hw] Device disconnected: ${name}\n`);
-        }
     });
 }
-async function createSDK(opts) {
+// ---------------------------------------------------------------------------
+// SDK Factory
+// ---------------------------------------------------------------------------
+async function initSDK() {
     const settings = {
         debug: false,
         fetchConfig: true,
+        env: 'node-usb',
     };
-    // Direct USB via libusb — works on macOS, Linux, Windows
-    settings.env = 'lowlevel';
-    const plugin = hd_transport_usb_1.UsbPlugin;
-    await hd_common_connect_sdk_1.default.init(settings, undefined, plugin);
-    // Register event handlers AFTER init
-    registerEventHandlers(hd_common_connect_sdk_1.default, opts);
+    await hd_common_connect_sdk_1.default.init(settings);
+    // Defensive: strip any stale listeners (e.g. left over from a previous
+    // dispose/init cycle in a long-running process) before wiring ours.
+    // Mirrors app-monorepo's cleanupHardwareSDKInstance() which removes
+    // listeners for ALL events at once.
+    // @ts-expect-error CoreApi types require an event name; passing none
+    // removes listeners for ALL events (Node.js EventEmitter semantics).
+    hd_common_connect_sdk_1.default.removeAllListeners();
+    registerEventHandlers(hd_common_connect_sdk_1.default);
     return hd_common_connect_sdk_1.default;
 }
+async function createSDK(opts) {
+    // Always refresh opts — event handlers read from the module-level ref,
+    // so subsequent createSDK() calls pick up new opts without re-registering.
+    currentOpts = opts;
+    if (!sdkReadyPromise) {
+        sdkReadyPromise = initSDK();
+    }
+    return sdkReadyPromise;
+}
 exports.createSDK = createSDK;
+/**
+ * Release the SDK and clear the singleton. Must be called before the CLI
+ * process exits — the USB transport holds open handles (event listeners,
+ * polling timers) that otherwise keep Node.js alive for ~26s.
+ *
+ * Safe to call multiple times (no-op after the first successful call).
+ */
+async function disposeSDK() {
+    if (!sdkReadyPromise)
+        return;
+    try {
+        const sdk = await sdkReadyPromise;
+        sdk.dispose();
+    }
+    catch {
+        // ignore errors during cleanup
+    }
+    finally {
+        sdkReadyPromise = null;
+        currentOpts = {};
+    }
+}
+exports.disposeSDK = disposeSDK;

package/dist/session.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Passphrase session management for hd-cli.
+ *
+ * Aligns with app-monorepo's CLI pattern:
+ *   Login:   getPassphraseState → passphraseState + sessionId → keychain
+ *   Command: keychain → preloadSessionCache → SDK call (no passphrase prompt)
+ *   Stale:   error 112 → clear keychain → re-prompt → retry
+ *   Logout:  keychain delete
+ */
+/**
+ * Load passphraseState + sessionId from keychain and call preloadSessionCache.
+ * Non-fatal: returns the loaded passphraseState or undefined.
+ */
+export declare function preloadSessionFromKeychain(deviceId: string): Promise<string | undefined>;
+/**
+ * Save passphraseState + sessionId to keychain for next CLI invocation.
+ */
+export declare function saveSessionToKeychain(deviceId: string, passphraseState: string, sessionId: string): Promise<void>;
+/**
+ * Clear cached session from keychain.
+ */
+export declare function clearSessionFromKeychain(deviceId?: string): Promise<void>;