HD Wallet

目标

• npx agent-hd-wallet：提供标准 CLI 能力（无交互，便于 agent 调用）
• npx agent-hd-wallet human：OpenTUI 交互界面（面向用户）
• 支持 eth/arb/base/bsc/sol 分层确定性钱包（HD）
• 支持多钱包管理（每个钱包独立权限与密钥材料）

本地运行

• 安装依赖：cd agent-hd-wallet && npm install
• 查看帮助：npx agent-hd-wallet --help 或 node ./bin/agent-hd-wallet.js --help
• 运行测试：cd agent-hd-wallet && npm test

发布后调用（npm）

• 包名：agent-hd-wallet
• 直接调用：
  • npx agent-hd-wallet --help
  • npx agent-hd-wallet human

功能定义

• wallet create：仅 TUI 执行，生成助记词 + 地址（EVM: eth/arb/base/bsc + SOL），自动生成该钱包 agent_password
• wallet import：仅 TUI 执行，从助记词导入并自动生成该钱包 agent_password
• wallet list：列出当前 agent-pass 可访问的钱包（需输入 agent-pass）
• wallet sign --wallet-id <id> --chain <chain>：交易/消息签名（需输入 agent-pass，严格离线）
• wallet export --wallet-id <id>：仅 TUI + 主密码二次验证可导出助记词
• tui password reset：仅 TUI 内可执行，支持重置 TUI 启动密码

预期安全策略（已确认）

• 本地密文文件存储（例如 ~/.agent-hd-wallet/keystore.json）
• Argon2id + AES-256-GCM 加密
• Agent 密码：按钱包自动生成，直接写入 .agent-hd-wallet/agent/，仅用于签名与钱包访问鉴权，禁止导出助记词
• TUI 主密码：首次启动 TUI 必须设置；后续每次启动 TUI 都必须先验证
• TUI 主密码策略：最少 8 位，不限制复杂度；连续输错 3 次锁定 1 小时
• TUI 主密码存储：不保存明文，使用 Argon2id 派生摘要后再加密落盘（本地仅存密文/摘要）
• 助记词导出：仅在 TUI 内完成，且必须通过当前 TUI 主密码二次验证
• 所有密码相关数据（TUI 主密码校验材料、agent-pass 元数据）必须加密存储

多钱包与 Agent 密码模型

• 每个钱包有唯一 wallet_id（推荐 UUIDv4），钱包级操作必须带 --wallet-id
• agent_password 与钱包一一绑定，创建/导入时自动生成
• agent_password 文件位置：.agent-hd-wallet/agent/<wallet_id>.pass
• agent-pass 文件权限要求：仅 owner 可读写（0600），目录权限 0700
• agent-pass 默认过期时间 30 天（可在 TUI 内重新生成并设置新的过期时间）
• wallet list / wallet sign 都强制二次认证：必须输入 agent-pass

TUI 操作流程（完整版）

1. 首次启动

• 执行 npx agent-hd-wallet human，进入初始化向导。
• 设置 TUI 主密码（两次输入一致、满足强度要求）。
• 创建本地目录：.agent-hd-wallet/、.agent-hd-wallet/agent/，并设置权限。

2. 登录解锁

• 非首次启动时先输入 TUI 主密码。
• 验证成功后加载钱包索引与加密材料；验证失败则拒绝进入主界面。
• 连续失败触发退避延迟（例如 1s/2s/4s）。

3. 主菜单

• Create Wallet：生成助记词，展示一次确认页，用户确认后落库并生成 agent-pass。
• Import Wallet：输入助记词并校验，导入成功后生成 agent-pass。
• Wallet List：展示 wallet_id、地址、创建时间。
• Export Mnemonic：选择钱包后，要求再次输入主密码，成功后才显示助记词。
• Security -> Reset Password：重置主密码。
• Security -> Regenerate Agent-pass：为指定钱包重新生成 agent-pass，并设置过期时间（默认 30 天）。

4. 退出与锁定

• 用户主动 Lock/Exit 后清空内存敏感数据（助记词、私钥、解密密钥）。
• 下次进入 TUI 必须重新输入主密码。

TUI 启动密码流程

• 首次执行 npx agent-hd-wallet human：进入 TUI 初始化页面，在 TUI 内设置主密码
• 非首次执行 npx agent-hd-wallet human：进入 TUI 登录页面，在 TUI 内完成验密后才进入钱包界面
• 连续输错密码应触发延迟/限流，避免暴力尝试
• 达到 3 次失败后锁定 1 小时
• 密码校验失败时禁止执行 create/import/export

TUI 重置密码流程

• 入口仅在 TUI 内（例如 Security -> Reset Password）
• 必须先输入当前 TUI 主密码，再输入新密码与确认密码
• 重置成功后，使用新密码重新加密本地密钥材料与密码校验数据
• 重置不影响已创建钱包和 agent-pass 文件
• 忘记当前密码时不提供任何恢复流程（无法解锁当前本地数据）

联网边界

• wallet sign 全流程离线执行，不允许任何网络请求。
• wallet list 本地执行，不允许网络请求。
• agent-hd-wallet CLI 不提供任何联网功能，余额查询迁移到 agent skill（通过 RPC + curl）。

CLI 交互约定

• npx agent-hd-wallet human（仅此入口允许 create/import/export）
• npx agent-hd-wallet wallet list --agent-pass-stdin --json
• npx agent-hd-wallet wallet sign --wallet-id <id> --chain <eth|arb|base|bsc|sol> --sign-type <message|transaction|typed_data> --payload-file <path> --agent-pass-stdin --json

Agent-pass 输入规范

• 禁止命令行明文参数（例如 --agent-pass xxx）
• 统一使用标准输入：--agent-pass-stdin
• 示例：npx agent-hd-wallet wallet sign --wallet-id <id> --chain eth --agent-pass-stdin --json < .agent-hd-wallet/agent/<id>.pass

Agent 侧余额查询 RPC 配置

• ETH_RPC_URL、ARB_RPC_URL、BASE_RPC_URL、BSC_RPC_URL、SOL_RPC_URL
• 由 agent/skill 读取这些环境变量，并通过 RPC 直接查询地址余额。

默认派生路径

• eth/arb/base/bsc：m/44'/60'/0'/0/0
• sol：m/44'/501'/0'/0'

按链签名 Payload Schema

• EVM 链（eth|arb|base|bsc）

• sign_type=message：{ "message": "0x..." | "text" }

• sign_type=transaction：{ "to": "0x..", "value": "hex", "data": "0x..", "nonce": number, "gas": "hex", "chainId": number }

• sign_type=typed_data：EIP-712 标准结构（domain/types/message/primaryType）

• SOL 链（sol）

• sign_type=message：{ "message_base64": "..." }

• sign_type=transaction：{ "transaction_base64": "..." }

目录规划

• agent-hd-wallet/cli：Node/TS CLI（npx 入口）
• agent-hd-wallet/tui：OpenTUI 交互入口
• agent-hd-wallet/core：钱包核心库（助记词、派生、签名）