nansen-wallet-keychain-migration

認証

Nansen アカウントの API 呼び出しでは、選択した nansen:api ブラウザーセッション、または同じ権限を持つ一般的な API キーを使用できます。NANSEN_API_KEY が優先されます。任意の primaryEnv を使うと、設定済みキーの注入を維持できます。オフラインで選択するには nansen auth status を実行します。キャッシュされたアクセス権の有効期限が切れただけであれば、認可されたタスクの実行中に自動更新できます。匿名の選択、無効な状態、更新のブロックまたは不確実な状態、実際の認証失敗があった場合は停止してください。認証情報を破棄したり、匿名の x402 支払いにフォールバックしたりしないでください。ブラウザーログインでは、ウォレットへの署名、特権サービス ID、永続的な 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 ファイルにあります。移行が必要です（Path B）
• "keychain" → すでに安全な状態です。移行は不要です
• null → パスワードはどこにも永続化されていません（Path C または D）
• "env" → NANSEN_WALLET_PASSWORD が設定されています。どこからエクスポートされているか確認してください（.env ファイルの場合は Path A）

パスワードの状態を調べるために nansen wallet export を使用しないでください。デフォルトでは値が伏せられ、パスワードも読み込まれないため、何も確認できません（また、--reveal は秘密鍵を表示します）。

移行パス

Path A：~/.nansen/.env にパスワードがある場合（古いスキルのパターン）

以前のウォレットスキルでは、エージェントにパスワードを ~/.nansen/.env に書き込むよう指示していました。

Step 1 — ユーザーにパスワードを確認します：

「現在、ウォレットのパスワードは安全でない ~/.nansen/.env に保存されています。 OS のキーチェーンに移行できます。ウォレット作成時に使用したパスワードを確認してください。 または、許可をいただければ ~/.nansen/.env から読み取ることもできます。」

Step 2 — 移行します：

source と nansen wallet secure は、環境変数を node プロセスから利用できるよう、同じシェルで実行する必要があります。

source ~/.nansen/.env 2>/dev/null && nansen wallet secure

Step 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 を実行し、正しいパスワードで再試行してください。

Step 4 — 安全でないファイルを削除します：

rm -f ~/.nansen/.env

Path B：.credentials ファイルにパスワードがある場合（自動保存されたフォールバック）

これは wallet create が OS キーチェーンにアクセスできなかった場合（コンテナー、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

Path 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 を再実行する必要があります。

エージェント向けの重要なルール

• パスワードを絶対に生成しないでください — 必ず人間に確認してください
• パスワードをファイル、メモリ、ログ、会話履歴に絶対に保存しないでください
• --human フラグを絶対に使用しないでください — 対話型プロンプトはエージェントの動作を妨げます
• 人間が ~/.nansen/.env の読み取りを許可した場合は、同じコマンド内で読み込んでください （source ~/.nansen/.env && nansen wallet secure） — 値を出力したり、ログに記録したりしないでください
• 移行後は必ず nansen wallet export default --reveal > /dev/null 2>&1 で検証してください（終了コードに応じて処理を分岐し、出力を絶対に表示させないでください） — wallet show ではパスワードが機能することを確認できません（パスワードを読み込まないため）