@onekeyfe/hardware-cli 1.1.25-alpha.0 → 1.1.25

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "onekey-hardware",
   "description": "OneKey hardware wallet CLI skills for Claude Code — device management, multi-chain signing, firmware updates",
-  "version": "0.1.0",
+  "version": "1.1.25-alpha.1",
   "author": {
     "name": "OneKey",
     "email": "dev@onekey.so"

package/AGENTS.md

@@ -0,0 +1,40 @@
+# OneKey Hardware Wallet — CLI Agent Skills
+
+When working with the `onekey-hw` CLI, read the skill files before running commands.
+Do NOT guess parameters or explore via `--help` — the skills document exact
+command signatures, workflows, and security rules.
+
+## Skills
+
+| Skill | Path | Use When |
+|---|---|---|
+| **Device** | `skills/device/SKILL.md` | Search devices (with features), lock, verify, wipe |
+| **Signing** | `skills/signing/SKILL.md` | Get addresses, sign transactions/messages (27 chains) |
+| **Firmware** | `skills/firmware/SKILL.md` | Check firmware versions (updates via OneKey App only) |
+| **Security** | `skills/security/SKILL.md` | PIN, passphrase, device settings, factory reset |
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @onekeyfe/hardware-cli
+
+# Search for connected devices (auto-fetches device info)
+onekey-hw search
+
+# Get an Ethereum address
+onekey-hw get-address --chain evm --use-empty-passphrase
+
+# Sign a message
+onekey-hw sign-message --chain evm --message "hello" --use-empty-passphrase
+```
+
+## Important
+
+- All signing operations require **physical confirmation** on the hardware device
+- Commands block while waiting for device interaction (PIN, button press)
+- All output is structured JSON
+- Uses direct USB (libusb) — no external daemon needed
+
+Each skill file includes pre-flight checks, security rules, and parameter
+conventions. Read the relevant skill for your task.

package/CLAUDE.md

@@ -0,0 +1,40 @@
+# OneKey Hardware Wallet — CLI Agent Skills
+
+When working with the `onekey-hw` CLI, read the skill files before running commands.
+Do NOT guess parameters or explore via `--help` — the skills document exact
+command signatures, workflows, and security rules.
+
+## Skills
+
+| Skill | Path | Use When |
+|---|---|---|
+| **Device** | `skills/device/SKILL.md` | Search devices (with features), lock, verify, wipe |
+| **Signing** | `skills/signing/SKILL.md` | Get addresses, sign transactions/messages (27 chains) |
+| **Firmware** | `skills/firmware/SKILL.md` | Check firmware versions (updates via OneKey App only) |
+| **Security** | `skills/security/SKILL.md` | PIN, passphrase, device settings, factory reset |
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @onekeyfe/hardware-cli
+
+# Search for connected devices (auto-fetches device info)
+onekey-hw search
+
+# Get an Ethereum address
+onekey-hw get-address --chain evm --use-empty-passphrase
+
+# Sign a message
+onekey-hw sign-message --chain evm --message "hello" --use-empty-passphrase
+```
+
+## Important
+
+- All signing operations require **physical confirmation** on the hardware device
+- Commands block while waiting for device interaction (PIN, button press)
+- All output is structured JSON
+- Uses direct USB (libusb) — no external daemon needed
+
+Each skill file includes pre-flight checks, security rules, and parameter
+conventions. Read the relevant skill for your task.

package/README.md

@@ -0,0 +1,112 @@
+# @onekeyfe/hardware-cli
+
+OneKey hardware wallet CLI for AI agent integration. Enables Claude Code and other AI agents to interact with OneKey hardware wallets — search devices, get addresses, sign transactions, manage firmware and security.
+
+## Install
+
+### Claude Code
+
+```bash
+claude plugin marketplace add OneKeyHQ/hardware-js-sdk --sparse .claude-plugin packages/hd-cli
+claude plugin install onekey-hardware@onekey-hardware-plugins
+```
+
+The CLI is installed automatically on first use via the skill's pre-flight check.
+
+### Other AI Tools (Codex, Gemini, Cursor)
+
+```bash
+npm install -g @onekeyfe/hardware-cli
+```
+
+### Development / Testing
+
+```bash
+claude --plugin-dir /path/to/hardware-js-sdk/packages/hd-cli
+```
+
+## Commands
+
+### Device
+
+| Command | Description | Needs PIN? |
+|---------|-------------|:----------:|
+| `onekey-hw search` | Search devices + auto-fetch features | No |
+| `onekey-hw lock` | Lock the device | No |
+| `onekey-hw device-verify` | Verify device is genuine | Yes |
+| `onekey-hw device-settings` | Update label, language, etc. | Yes |
+| `onekey-hw device-wipe` | Factory reset (IRREVERSIBLE) | Yes |
+
+### Address & Signing
+
+| Command | Description | Needs PIN? |
+|---------|-------------|:----------:|
+| `onekey-hw get-address --chain <chain>` | Get address (27 chains) | Yes |
+| `onekey-hw get-public-key --chain <chain>` | Get public key | Yes |
+| `onekey-hw batch-get-address --bundle <json>` | Multi-chain batch | Yes |
+| `onekey-hw sign-transaction --chain <chain> --tx <json>` | Sign transaction | Yes |
+| `onekey-hw sign-message --chain <chain> --message <msg>` | Sign message | Yes |
+| `onekey-hw sign-typed-data --data <json>` | Sign EIP-712 (EVM) | Yes |
+| `onekey-hw sign-psbt --psbt <hex>` | Sign Bitcoin PSBT | Yes |
+| `onekey-hw verify-message --chain <chain> ...` | Verify signed message | Yes |
+
+### Chain-Specific
+
+| Command | Description |
+|---------|-------------|
+| `onekey-hw evm-sign-eip712` | EIP-712 by hash |
+| `onekey-hw sol-sign-offchain` | Solana off-chain message |
+| `onekey-hw nostr-encrypt` | Nostr NIP-04 encrypt |
+| `onekey-hw nostr-decrypt` | Nostr NIP-04 decrypt |
+| `onekey-hw nostr-sign-schnorr` | Nostr Schnorr signature |
+| `onekey-hw lnurl-auth` | Lightning LNURL auth |
+| `onekey-hw conflux-sign-cip23` | Conflux CIP-23 message |
+| `onekey-hw aptos-sign-in` | Aptos sign-in |
+| `onekey-hw ton-sign-proof` | TON Connect proof |
+
+### Firmware (Read-Only)
+
+| Command | Description |
+|---------|-------------|
+| `onekey-hw firmware-check` | Check firmware updates |
+| `onekey-hw firmware-check-all` | Check all components |
+| `onekey-hw bootloader-check` | Check bootloader |
+
+Firmware updates must be done via the [OneKey App](https://onekey.so/download) or [firmware.onekey.so](https://firmware.onekey.so/).
+
+### Security
+
+| Command | Description |
+|---------|-------------|
+| `onekey-hw change-pin` | Change/set PIN |
+| `onekey-hw passphrase-state` | Get passphrase state |
+| `onekey-hw toggle-passphrase --enable <bool>` | Enable/disable passphrase |
+
+## Supported Chains
+
+| Chain | `--chain` | Address | Sign TX | Sign Message |
+|-------|-----------|:-------:|:-------:|:------------:|
+| Ethereum / EVM | `evm` | ✅ | ✅ | ✅ |
+| Bitcoin | `btc` | ✅ | ✅ | ✅ |
+| Solana | `sol` | ✅ | ✅ | ✅ |
+| Cosmos | `cosmos` | ✅ | ✅ | — |
+| Cardano | `cardano` | ✅ | ✅ | ✅ |
+| Polkadot | `polkadot` | ✅ | ✅ | — |
+| Tron | `tron` | ✅ | ✅ | ✅ |
+| Aptos | `aptos` | ✅ | ✅ | ✅ |
+| Sui | `sui` | ✅ | ✅ | ✅ |
+| Near | `near` | ✅ | ✅ | — |
+| XRP | `xrp` | ✅ | ✅ | — |
+| Stellar | `stellar` | ✅ | ✅ | — |
+| TON | `ton` | ✅ | — | ✅ |
+| Nostr | `nostr` | ✅ | — | ✅ |
+| +13 more | | ✅ | ✅ | varies |
+
+## Transport
+
+Uses `libusb` for direct USB communication. No external daemon needed.
+Works on macOS, Linux, and Windows.
+
+## License
+
+Apache-2.0

package/dist/cli.js

@@ -9,11 +9,10 @@ const program = new commander_1.Command();
 program
     .name('onekey-hw')
     .description('OneKey hardware wallet CLI for AI agent integration')
-    .version('1.1.25-alpha.0');
+    .version('1.1.25-alpha.1');
 // ============================================================
 // Global Options
 // ============================================================
-program.option('--json', 'Output in JSON format (for agent consumption)');
 program.option('--connect-id <id>', 'Device connection ID (USB: serial, iOS: uuid, Android: MAC)');
 program.option('--device-id <id>', 'Persistent device ID from getFeatures (changes when seed changes)');
 program.option('--passphrase-state <state>', 'Passphrase state for hidden wallet access');
@@ -24,25 +23,30 @@ program.option('--use-empty-passphrase', 'Use standard wallet (skip passphrase p
 program
     .command('search')
     .description('Search for connected OneKey hardware wallet devices')
-    .option('--timeout <ms>', 'Search timeout in milliseconds', '10000')
-    .action(async (opts) => {
-    const sdk = await (0, sdk_1.createSDK)(program.opts());
-    try {
-        const result = await sdk.searchDevices();
-        outputResult(program.opts(), result);
-    }
-    finally {
-        sdk.dispose();
-    }
-});
-program
-    .command('status')
-    .description('Get device features and current status')
     .action(async () => {
     const globalOpts = program.opts();
     const sdk = await (0, sdk_1.createSDK)(globalOpts);
     try {
-        const result = await sdk.getFeatures(globalOpts.connectId);
+        const result = await sdk.searchDevices();
+        // Auto-fetch features for each discovered device (doesn't require PIN)
+        if (result?.success && Array.isArray(result.payload)) {
+            for (const device of result.payload) {
+                if (device.connectId) {
+                    try {
+                        const features = await sdk.getFeatures(device.connectId);
+                        if (features?.success && features.payload) {
+                            device.features = features.payload;
+                            device.name = features.payload.label || features.payload.ble_name || device.name;
+                            device.deviceType =
+                                features.payload.onekey_device_type?.toLowerCase() || device.deviceType;
+                        }
+                    }
+                    catch {
+                        // Features fetch failed — device may need PIN, continue with basic info
+                    }
+                }
+            }
+        }
         outputResult(globalOpts, result);
     }
     finally {
@@ -487,51 +491,27 @@ program
 });
 program
     .command('firmware-update')
-    .description('Update device firmware')
-    .option('--version <ver>', 'Target firmware version (e.g., "4.8.0")')
-    .option('--platform <platform>', 'Platform: native | desktop | ext | web', 'desktop')
-    .action(async (opts) => {
-    const globalOpts = program.opts();
-    const sdk = await (0, sdk_1.createSDK)(globalOpts);
-    try {
-        // firmwareUpdateV2 requires: connectId, deviceId, { updateType, platform, version? }
-        const params = {
-            updateType: 'firmware',
-            platform: opts.platform,
-        };
-        if (opts.version) {
-            params.version = parseVersion(opts.version);
-        }
-        // firmwareUpdateV2 signature: (connectId, params) — 2 args only
-        const result = await sdk.firmwareUpdateV2(globalOpts.connectId, params);
-        outputResult(globalOpts, result);
-    }
-    finally {
-        sdk.dispose();
-    }
+    .description('Firmware update is not supported via CLI')
+    .action(() => {
+    outputResult(program.opts(), {
+        success: false,
+        payload: {
+            error: 'Firmware update via CLI is not supported. Please use the OneKey App or https://firmware.onekey.so/ to update firmware.',
+            code: 'FIRMWARE_UPDATE_NOT_SUPPORTED',
+        },
+    });
 });
 program
     .command('firmware-update-ble')
-    .description('Update BLE (Bluetooth) firmware')
-    .option('--version <ver>', 'Target BLE firmware version')
-    .option('--platform <platform>', 'Platform: native | desktop | ext | web', 'desktop')
-    .action(async (opts) => {
-    const globalOpts = program.opts();
-    const sdk = await (0, sdk_1.createSDK)(globalOpts);
-    try {
-        const params = {
-            updateType: 'ble',
-            platform: opts.platform,
-        };
-        if (opts.version) {
-            params.version = parseVersion(opts.version);
-        }
-        const result = await sdk.firmwareUpdateV2(globalOpts.connectId, params);
-        outputResult(globalOpts, result);
-    }
-    finally {
-        sdk.dispose();
-    }
+    .description('BLE firmware update is not supported via CLI')
+    .action(() => {
+    outputResult(program.opts(), {
+        success: false,
+        payload: {
+            error: 'BLE firmware update via CLI is not supported. Please use the OneKey App or https://firmware.onekey.so/ to update firmware.',
+            code: 'FIRMWARE_UPDATE_NOT_SUPPORTED',
+        },
+    });
 });
 program
     .command('bootloader-check')
@@ -600,66 +580,6 @@ program
         sdk.dispose();
     }
 });
-program
-    .command('device-backup')
-    .description('Trigger recovery phrase backup on device')
-    .action(async () => {
-    const globalOpts = program.opts();
-    const sdk = await (0, sdk_1.createSDK)(globalOpts);
-    try {
-        const result = await sdk.deviceBackup(globalOpts.connectId);
-        outputResult(globalOpts, result);
-    }
-    finally {
-        sdk.dispose();
-    }
-});
-program
-    .command('device-recovery')
-    .description('Recover wallet from recovery phrase (entered on device)')
-    .option('--word-count <count>', 'Recovery phrase length: 12, 18, or 24', '24')
-    .option('--passphrase-protection <bool>', 'Enable passphrase after recovery', 'false')
-    .option('--pin-protection <bool>', 'Set PIN after recovery', 'true')
-    .option('--label <name>', 'Device label')
-    .action(async (opts) => {
-    const globalOpts = program.opts();
-    const sdk = await (0, sdk_1.createSDK)(globalOpts);
-    try {
-        const result = await sdk.deviceRecovery(globalOpts.connectId, {
-            wordCount: safeParseInt(opts.wordCount, '--word-count'),
-            passphraseProtection: opts.passphraseProtection === 'true',
-            pinProtection: opts.pinProtection === 'true',
-            label: opts.label,
-        });
-        outputResult(globalOpts, result);
-    }
-    finally {
-        sdk.dispose();
-    }
-});
-program
-    .command('device-reset')
-    .description('Initialize device with a new wallet seed (DESTROYS current wallet)')
-    .option('--word-count <count>', 'Seed phrase length: 12, 18, or 24', '24')
-    .option('--passphrase-protection <bool>', 'Enable passphrase', 'false')
-    .option('--pin-protection <bool>', 'Set PIN', 'true')
-    .option('--label <name>', 'Device label')
-    .action(async (opts) => {
-    const globalOpts = program.opts();
-    const sdk = await (0, sdk_1.createSDK)(globalOpts);
-    try {
-        const result = await sdk.deviceReset(globalOpts.connectId, {
-            strength: wordCountToStrength(safeParseInt(opts.wordCount, '--word-count')),
-            passphraseProtection: opts.passphraseProtection === 'true',
-            pinProtection: opts.pinProtection === 'true',
-            label: opts.label,
-        });
-        outputResult(globalOpts, result);
-    }
-    finally {
-        sdk.dispose();
-    }
-});
 program
     .command('device-wipe')
     .description('Factory reset — erase ALL data (IRREVERSIBLE)')
@@ -760,27 +680,15 @@ function getCommonParams(globalOpts) {
         useEmptyPassphrase: globalOpts.useEmptyPassphrase,
     };
 }
-function outputResult(globalOpts, result) {
+function outputResult(_globalOpts, result) {
     // #10 FIX: Always use JSON.stringify to avoid [Object] truncation
     console.log(JSON.stringify(result, null, 2));
-    // #11 FIX: Exit with code 1 on SDK failure
+    // Exit after output — SDK event listeners keep the process alive otherwise
     if (result && typeof result === 'object' && 'success' in result && !result.success) {
-        process.exitCode = 1;
+        process.exit(1);
     }
-}
-function wordCountToStrength(wordCount) {
-    // #8 FIX: Validate word count is one of the allowed values
-    if (![12, 18, 24].includes(wordCount)) {
-        throw new Error(`Invalid word count: ${wordCount}. Must be 12, 18, or 24.`);
-    }
-    switch (wordCount) {
-        case 12:
-            return 128;
-        case 18:
-            return 192;
-        case 24:
-        default:
-            return 256;
+    else {
+        process.exit(0);
     }
 }
 /**
@@ -811,14 +719,4 @@ function safeParseInt(input, label) {
     }
     return num;
 }
-/**
- * #15 FIX: Validate firmware version format
- */
-function parseVersion(input) {
-    const parts = input.split('.').map(Number);
-    if (parts.length < 2 || parts.length > 4 || parts.some(Number.isNaN)) {
-        throw new Error(`Invalid version format: "${input}". Expected format: "4.8.0"`);
-    }
-    return parts;
-}
 program.parse();

package/dist/index.d.ts

@@ -11,7 +11,6 @@ import { CoreApi } from '@onekeyfe/hd-core';
  * Reference: packages/core/src/core/index.ts (event registration pattern)
  */
 interface SDKOptions {
-    json?: boolean;
     connectId?: string;
     passphraseState?: string;
     useEmptyPassphrase?: boolean;

package/dist/index.js

@@ -12,7 +12,7 @@
  *   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.
+ * All output is structured JSON for AI agent consumption.
  *
  * IMPORTANT: All signing operations require physical confirmation on the
  * hardware device. The CLI handles PIN/Passphrase prompts via stdin for

package/dist/sdk.d.ts

@@ -8,7 +8,6 @@
  * Reference: packages/core/src/core/index.ts (event registration pattern)
  */
 export interface SDKOptions {
-    json?: boolean;
     connectId?: string;
     passphraseState?: string;
     useEmptyPassphrase?: boolean;

package/dist/sdk.js

@@ -159,15 +159,17 @@ function registerEventHandlers(sdk, opts) {
             process.stderr.write('[onekey-hw] Please confirm the action on your device...\n');
         }
     });
-    // Device connection events
+    // Device connection events — only show when device has a known name
     sdk.on(hd_core_1.DEVICE.CONNECT, (device) => {
-        if (!opts.json) {
-            process.stderr.write(`[onekey-hw] Device connected: ${device?.name || 'Unknown'}\n`);
+        const name = device?.label || device?.name;
+        if (name) {
+            process.stderr.write(`[onekey-hw] Device connected: ${name}\n`);
         }
     });
     sdk.on(hd_core_1.DEVICE.DISCONNECT, (device) => {
-        if (!opts.json) {
-            process.stderr.write(`[onekey-hw] Device disconnected: ${device?.name || 'Unknown'}\n`);
+        const name = device?.label || device?.name;
+        if (name) {
+            process.stderr.write(`[onekey-hw] Device disconnected: ${name}\n`);
         }
     });
 }