@onekeyfe/hardware-cli 1.1.25-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+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.
+ *
+ * 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)
+ */
+interface SDKOptions {
+    json?: boolean;
+    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.
+ *
+ * Reference: developer-portal docs at
+ *   content/en/hardware-sdk/chains/<chain>/<method>.mdx
+ *   content/en/hardware-sdk/core-api-guide.mdx (HD path section)
+ *
+ * Type definitions: packages/core/src/types/api/*.ts
+ */
+
+/**
+ * Common params passed to all SDK methods.
+ * Reference: packages/core/src/types/api/export.ts (CommonParams)
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * @onekeyfe/hardware-cli
+ *
+ * OneKey hardware wallet CLI for AI agent integration.
+ * Provides device management, multi-chain signing, firmware updates,
+ * and security management capabilities.
+ *
+ * Usage:
+ *   npx @onekeyfe/hardware-cli search
+ *   npx @onekeyfe/hardware-cli get-address --chain evm
+ *   npx @onekeyfe/hardware-cli sign-transaction --chain evm --tx '{...}'
+ *
+ * For AI agent integration, use --json flag for structured output.
+ *
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBatchGetAddress = exports.resolveSignMessage = exports.resolveSignTransaction = exports.resolveGetPublicKey = exports.resolveGetAddress = exports.createSDK = void 0;
+var sdk_1 = require("./sdk");
+Object.defineProperty(exports, "createSDK", { enumerable: true, get: function () { return sdk_1.createSDK; } });
+var chains_1 = require("./chains");
+Object.defineProperty(exports, "resolveGetAddress", { enumerable: true, get: function () { return chains_1.resolveGetAddress; } });
+Object.defineProperty(exports, "resolveGetPublicKey", { enumerable: true, get: function () { return chains_1.resolveGetPublicKey; } });
+Object.defineProperty(exports, "resolveSignTransaction", { enumerable: true, get: function () { return chains_1.resolveSignTransaction; } });
+Object.defineProperty(exports, "resolveSignMessage", { enumerable: true, get: function () { return chains_1.resolveSignMessage; } });
+Object.defineProperty(exports, "resolveBatchGetAddress", { enumerable: true, get: function () { return chains_1.resolveBatchGetAddress; } });

package/dist/sdk.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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)
+ */
+export interface SDKOptions {
+    json?: boolean;
+    connectId?: string;
+    passphraseState?: string;
+    useEmptyPassphrase?: boolean;
+}
+export declare function createSDK(opts: SDKOptions): Promise<import("@onekeyfe/hd-core").CoreApi>;

package/dist/sdk.js

@@ -0,0 +1,187 @@
+'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)
+ */
+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"));
+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.
+ */
+function promptUser(question, hidden = false) {
+    if (!process.stdin.isTTY) {
+        // Non-interactive mode: return empty (agent should handle via uiResponse)
+        return Promise.resolve('');
+    }
+    return new Promise(resolve => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stderr, // Use stderr so JSON stdout stays clean
+        });
+        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');
+                    rl.close();
+                    resolve(input);
+                }
+                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);
+            });
+        }
+    });
+}
+/**
+ * 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) {
+    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.
+        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,
+                    });
+                });
+            }
+        }
+        // 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)
+                sdk.uiResponse({
+                    type: hd_core_1.UI_RESPONSE.RECEIVE_PASSPHRASE,
+                    payload: {
+                        value: '',
+                        passphraseOnDevice: false,
+                        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,
+                            },
+                        });
+                    }
+                });
+            }
+        }
+        // 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
+    sdk.on(hd_core_1.DEVICE.CONNECT, (device) => {
+        if (!opts.json) {
+            process.stderr.write(`[onekey-hw] Device connected: ${device?.name || 'Unknown'}\n`);
+        }
+    });
+    sdk.on(hd_core_1.DEVICE.DISCONNECT, (device) => {
+        if (!opts.json) {
+            process.stderr.write(`[onekey-hw] Device disconnected: ${device?.name || 'Unknown'}\n`);
+        }
+    });
+}
+async function createSDK(opts) {
+    const settings = {
+        debug: false,
+        fetchConfig: true,
+    };
+    // 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);
+    return hd_common_connect_sdk_1.default;
+}
+exports.createSDK = createSDK;