SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场nansen-wallet-keychain-migration

nansen-wallet-keychain-migration

安全与审计

查看项目

更新于 10-15 14:13

技能介绍

用途

本技能用于将已有的 nansen-cli 钱包从旧的不安全密码存储方式迁移到新的、由操作系统钥匙串（keychain）支持的安全流程。当用户此前把钱包密码保存在 ~/.nansen/.env、.env 文件或 memory.md 中，或收到 stderr 警告“⚠ Password loaded from insecure .credentials file”，或提出“保护我的钱包”“迁移到 keychain”，或钱包创建于 keychain 更新发布之前时，适用本技能。

检测当前状态

wallet show 只显示地址，不会加载或检查密码。要检测实际密码情况，需直接检查密码存储来源：

  • nansen auth status --pretty：离线运行，不解密任何内容，不打印任何密钥，输出 x402.password.source，取值为 "env"、"keychain"、"file" 或 null。
  • nansen doctor --offline：完整设置检查，会标记不安全的 .credentials 文件并给出修复建议。
  • 检查旧模式：ls -la ~/.nansen/.env 2>/dev/null && echo "FOUND: ~/.nansen/.env (insecure)"。

对 x402.password.source 的解释："file" 表示密码在 .credentials 文件中，需要迁移（路径 B）；"keychain" 表示已安全，无需迁移；null 表示密码未持久化到任何位置（路径 C 或 D）；"env" 表示设置了 NANSEN_WALLET_PASSWORD，需检查其导出位置（来自 .env 文件则为路径 A）。

不要用 nansen wallet export 探测密码状态——默认会脱敏且从不加载密码，因此无法证明任何事（而 --reveal 会打印私钥）。

迁移路径

路径 A：密码在 ~/.nansen/.env（旧技能模式）

  1. 向用户询问密码，说明当前存储在 ~/.nansen/.env 不安全，可迁移到操作系统钥匙串，请用户确认创建钱包时使用的密码，或在授权后从 ~/.nansen/.env 读取。
  2. 迁移：source 与 nansen wallet secure 必须在同一 shell 中运行，以便环境变量对 node 进程可用：source ~/.nansen/.env 2>/dev/null && nansen wallet secure
  3. 验证密码确实能解密钱包：取消环境变量以证明钥匙串可用，然后运行解密导出并将所有输出丢弃——仅以退出码为信号，避免密钥材料进入记录或日志：unset NANSEN_WALLET_PASSWORD; if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi。若退出码为 0，迁移成功；若失败，说明迁移了错误密码，运行 nansen wallet forget-password 后用正确密码重试。
  4. 清理不安全文件：rm -f ~/.nansen/.env

路径 B：密码在 .credentials 文件（自动保存的回退）

当 wallet create 无法访问操作系统钥匙串（容器、CI）时会出现此情况。运行 nansen wallet secure。若钥匙串仍不可用（例如无 D-Bus 的容器化 Linux），该命令会说明情况并建议替代方案。迁移后验证解密（故意丢弃输出，依据退出码分支）：if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

路径 C：密码仅在 NANSEN_WALLET_PASSWORD 环境变量中

运行 nansen wallet secure 将环境变量中的密码持久化到钥匙串。然后在无环境变量的情况下验证（退出码为信号，输出被丢弃以免泄露密钥）：unset NANSEN_WALLET_PASSWORD; if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

路径 D：密码彻底丢失

密码无法恢复。钱包私钥使用 AES-256-GCM 加密，密码未存储在任何可恢复位置。应告知用户：钱包密码无法恢复，若钱包中有资金可能无法访问，可创建新钱包并转移仍可访问的资金。创建新钱包：NANSEN_WALLET_PASSWORD="<new_password_from_user>" nansen wallet create --name new-wallet

迁移后验证

任何迁移后，都要证明钥匙串中的密码确实能解密钱包：unset NANSEN_WALLET_PASSWORD; if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi。该命令必须以 0 退出。若导出失败，说明保存到钥匙串的是错误密码，用以下方式修复：nansen wallet forget-password; NANSEN_WALLET_PASSWORD="<correct_password>" nansen wallet secure。若 stderr 仍显示 .credentials 警告，说明钥匙串迁移未成功——检查操作系统钥匙串服务是否运行（Linux 上为 secret-tool，macOS 上为 security）。

忘记密码（清除所有存储）

若用户想彻底移除已持久化的密码：nansen wallet forget-password。这会从操作系统钥匙串和 .credentials 文件中清除密码。之后的钱包操作将需要 NANSEN_WALLET_PASSWORD 环境变量或重新运行 nansen wallet secure。

代理的关键规则

  • 绝不生成密码——始终询问用户。
  • 绝不将密码存储在文件、内存、日志或对话历史中。
  • 绝不使用 --human 标志——交互式提示会破坏代理。
  • 若用户授权读取 ~/.nansen/.env，需在同一命令中读取（source ~/.nansen/.env && nansen wallet secure）——不要回显或记录该值。
  • 迁移后始终用 nansen wallet export default --reveal > /dev/null 2>&1 验证（依据退出码分支；绝不让输出打印）——wallet show 不能证明密码可用（它从不加载密码）。

认证相关说明

Nansen 账户 API 调用接受选定的 nansen:api 浏览器会话或具有相同权限的传统 API 密钥。NANSEN_API_KEY 优先；可选的 primaryEnv 保留已配置密钥的注入。运行 nansen auth status 进行离线选择。仅缓存的访问过期允许在授权任务期间自动续期。遇到匿名选择、无效状态、被阻止或不确定的续期或实际认证失败时应停止；绝不丢弃凭据或回退到匿名 x402 支付。浏览器登录不授予钱包签名、特权服务身份或持久 MCP 集成密钥。保留所有确认、签名、制裁和地理检查。浏览器登录在 CLI 2.0.0 的 macOS arm64 预览范围内可用。