nansen-wallet-keychain-migration

身份验证

Nansen 账户 API 调用可使用选定的 nansen:api 浏览器会话，或使用权限相同的常规 API 密钥。NANSEN_API_KEY 优先；可选的 primaryEnv 会保留已配置密钥的注入方式。运行 nansen auth status 可离线选择。仅缓存的访问权限过期时，可在已授权任务期间自动续期。若选择匿名状态、状态无效、续期受阻或无法确定，或身份验证实际失败，请停止；切勿丢弃凭据，也不要回退到匿名 x402 付款。浏览器登录不会授予钱包签名权限、特权服务身份或持久的 MCP 集成密钥。请保留下方所有确认、签名、制裁和地理位置检查。CLI 2.0.0 中提供浏览器登录，但仅限于 macOS arm64 预览范围。

钱包迁移——从旧流程迁移到安全密钥链

当用户已设置 nansen-cli 钱包，使用的是旧版密码存储方式，并希望迁移到新的安全流程时，请使用此技能。

使用时机

• 用户提到密码存储在 ~/.nansen/.env、某个 .env 文件或 memory.md 中
• 用户看到标准错误警告：⚠ Password loaded from insecure .credentials file
• 用户要求“保护我的钱包”或“迁移到密钥链”
• 用户在密钥链更新发布前创建了钱包

检测当前状态

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

# 1. Where is the password stored? Offline, decrypts nothing, prints no secrets
nansen auth status --pretty     # → x402.password.source: "env" | "keychain" | "file" | null

# 2. Full setup check — flags the insecure .credentials file with a fix
nansen doctor --offline

# 3. Legacy pattern doctor does not cover: password written to ~/.nansen/.env
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 中（旧版技能模式）

之前的钱包技能曾要求 Agent 将密码写入 ~/.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 env var to prove keychain works, then run a decrypting export with
# all output discarded — the exit code alone is the signal, so no key
# material can land in a transcript or log
unset NANSEN_WALLET_PASSWORD
if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

如果导出命令以状态码 0 退出（decryption OK），说明迁移成功。如果失败， 说明迁移的是错误密码——请运行 nansen wallet forget-password，然后使用正确的密码重试。

步骤 4 — 清理不安全的文件：

rm -f ~/.nansen/.env

路径 B：密码位于 .credentials 文件中（自动保存的回退方式）

当 wallet create 无法访问操作系统密钥链时，就会出现这种情况（例如容器、CI）。

nansen wallet secure

如果密钥链仍不可用（例如，没有 D-Bus 的容器化 Linux）， nansen wallet secure 会说明情况并提供替代方案。

迁移后，请验证解密是否正常（有意丢弃输出—— 根据退出码分支处理）：

if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

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

# Persist the env var password to keychain
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 加密，密码不会存储在任何可恢复的位置。

告知用户：

“您的钱包密码无法恢复。如果此钱包中有资金， 这些资金可能无法访问。您可以创建一个新钱包，并转移任何仍可访问的 资金。”

# Create a fresh wallet (human must provide a new password)
NANSEN_WALLET_PASSWORD="<new_password_from_user>" nansen wallet create --name new-wallet

迁移后验证

任何迁移完成后，都要确认密码已正确迁移，方法是验证密钥链密码确实可以解密钱包：

# Unset env var to prove keychain works
unset NANSEN_WALLET_PASSWORD

# This MUST exit 0 — it proves the keychain password decrypts the wallet.
# Output is discarded on purpose: the exit code alone is the signal.
if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

如果导出失败，则保存到密钥链中的密码不正确。请通过以下方式修复：

nansen wallet forget-password
NANSEN_WALLET_PASSWORD="<correct_password>" nansen wallet secure

如果 stderr 仍显示 .credentials 警告，则表示密钥链迁移未成功——请检查 OS 密钥链服务是否正在运行（Linux 上的 secret-tool，macOS 上的 security）。

忘记密码（所有存储位置）

如果用户想要彻底删除已持久化的密码：

nansen wallet forget-password

这会同时清除 OS 密钥链和 .credentials 文件中的密码。今后进行钱包操作时，需要设置 NANSEN_WALLET_PASSWORD 环境变量，或重新运行 nansen wallet secure。

Agent 的关键规则

• 绝不生成密码——始终询问用户
• 绝不将密码存储在文件、内存、日志或对话历史中
• 绝不使用 --human 标志——交互式提示会导致 Agent 无法正常工作
• 如果用户授权读取 ~/.nansen/.env，请在同一条命令中读取 （source ~/.nansen/.env && nansen wallet secure）——不要回显或记录该值
• 迁移后始终进行验证，使用 nansen wallet export default --reveal > /dev/null 2>&1（根据退出代码进行分支判断；绝不让输出显示）——wallet show 无法证明密码有效（它从不加载密码）