nansen-wallet-migration

ウォレットの移行 — 旧フローからセキュアなキーチェーンへ

ユーザーがすでに旧式のパスワード保存方法で nansen-cli ウォレットを設定しており、新しいセキュアなフローへの移行を希望している場合に、このスキルを使用します。

使用するタイミング

• ~/.nansen/.env、.env ファイル、または memory.md にパスワードを保存したとユーザーが言っている
• ユーザーに stderr 警告 ⚠ Password loaded from insecure .credentials file が表示される
• ユーザーが「ウォレットを安全にしたい」または「キーチェーンに移行したい」と尋ねている
• キーチェーンのアップデートがリリースされる前にユーザーがウォレットを作成した

現在の状態を検出する

wallet show はアドレスのみを表示し、パスワードの読み込みや確認は行いません。 実際のパスワードの状態を検出するには、保存されているパスワードの保存先を確認します。

# 1. Check if a wallet exists at all
nansen wallet list 2>&1

# 2. Check for insecure password stores
ls -la ~/.nansen/.env 2>/dev/null && echo "FOUND: ~/.nansen/.env (insecure)"
ls -la ~/.nansen/wallets/.credentials 2>/dev/null && echo "FOUND: .credentials file (insecure)"

# 3. Try an operation that requires the password (without setting env var)
nansen wallet export default 2>&1

export の出力を解釈します。

• stderr に ⚠ Password loaded from ~/.nansen/wallets/.credentials → 移行が必要です（パス B）
• export が何も表示せずに成功する → パスワードはキーチェーンに保存されています。移行は不要です
• PASSWORD_REQUIRED JSON エラー → パスワードはどこにも保存されていません（パス C または D）

移行パス

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

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

ステップ 1 — ユーザーにパスワードを尋ねます。

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

ステップ 2 — 移行します。

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

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

ステップ 3 — パスワードでウォレットを実際に復号できることを確認します。

# Unset env var to prove keychain works, then export to verify decryption
unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1

export が成功する（秘密鍵が表示される）場合、移行は成功です。Incorrect password と表示される場合、誤ったパスワードが移行されています。nansen wallet forget-password を実行してから、正しいパスワードで再試行してください。

ステップ 4 — 安全でないファイルを削除します。

rm -f ~/.nansen/.env

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

wallet create が OS のキーチェーンにアクセスできなかった場合（コンテナー、CI）に発生します。

nansen wallet secure

キーチェーンを引き続き利用できない場合（例：D-Bus のないコンテナー化された Linux）、nansen wallet secure が状況を説明し、代替案を提示します。

移行後、復号が機能することを確認します。

nansen wallet export default 2>&1

パス C：NANSEN_WALLET_PASSWORD 環境変数にのみパスワードがある場合

# Persist the env var password to keychain
nansen wallet secure

その後、環境変数なしで確認します。

unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1

パス 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 succeed — it proves the keychain password decrypts the wallet
nansen wallet export default 2>&1

export に Incorrect password と表示される場合、誤ったパスワードがキーチェーンに保存されています。次の手順で修正します。

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 で検証してください — wallet show ではパスワードが機能することを証明できません（パスワードを読み込まないためです）