Nansen Wallet Keychain Migration

Migrate an existing nansen-cli wallet from insecure password storage (env files, .credentials) to the new secure keychain-backed flow.

Security Scan

The instructions match a legitimate local wallet migration flow, but the declared environment requirements are inconsistent (requests NANSEN_API_KEY even though the runtime steps use NANSEN_WALLET_PASSWORD and local files), so the skill's metadata and declared permissions do not align with what it actually does.

Purpose & Capability

The skill's stated purpose is migrating a local nansen-cli wallet password into the OS keychain. The runtime instructions only call the local 'nansen' CLI, read ~/.nansen files, and use NANSEN_WALLET_PASSWORD; they do not reference or need an API key. However the registry metadata declares NANSEN_API_KEY as a required/primary credential. That env var appears unrelated to the documented migration steps and is unnecessary for the described local operations.

Instruction Scope

SKILL.md provides concrete shell commands to detect password storage, run 'nansen wallet secure', unset env vars, and run 'nansen wallet export default' to verify decryption. These actions are coherent with migration. They do, however, require handling sensitive data: exporting the wallet will reveal private keys and the skill tells agents to read or source plaintext password files if authorized. The instructions explicitly warn not to store the password and to ask the human, which is good, but an agent executing these steps could still display or capture secrets if not carefully controlled.

Install Mechanism

Install is a node package (nansen-cli) that provides the 'nansen' binary. Pulling an official npm CLI is a reasonable install path for a CLI-based migration. This is moderate-risk compared to no install, but consistent with the need for a 'nansen' binary.

Credentials

Declared required env: NANSEN_API_KEY (primary). The instructions actually use NANSEN_WALLET_PASSWORD and local files (~/.nansen/.env, ~/.nansen/wallets/.credentials). NANSEN_API_KEY is never referenced in SKILL.md. Conversely, NANSEN_WALLET_PASSWORD (used at runtime) is not declared as a required env or primary credential. This mismatch is disproportionate and unexplained and increases risk: the skill requests access to an unrelated API credential while not declaring the sensitive local password variable it will handle.

Persistence & Privilege

The skill is not always-enabled and is user-invocable; it can be invoked autonomously (disable-model-invocation=false) which is the platform default. The skill does not attempt to persist itself or modify other skills' configs. Note: because it runs local shell commands that can reveal private keys/passwords, autonomous invocation combined with the environment mismatch (requests an API key) raises the possible blast radius if an agent is permitted to run it without human oversight.

What to consider before installing

Before installing, consider the following: - Ask the publisher why NANSEN_API_KEY is declared as a required/primary credential when the migration steps in SKILL.md never reference it. If the skill truly needs that API key, ask for a clear explanation and which commands use it. - The migration process will run commands that can reveal private keys (nansen wallet export default) and will read local files like ~/.nansen/.env or ~/.nansen/wallets/.credentials. Only run this skill on a trusted, local machine and avoid letting the agent send outputs (private keys or passwords) to external places or chat history. - The SKILL.md uses NANSEN_WALLET_PASSWORD at runtime but that env var is not declared in metadata; verify how you will provide the password. If you prefer, perform the migration manually following the documented commands instead of giving an agent permission to run them. - Verify the source of the nansen-cli npm package (official publisher) before allowing the skill to install it. Installing an npm CLI grants code execution privileges on your machine. - If you decide to proceed, run the commands interactively yourself or require explicit human confirmation before the agent executes any command that might print private keys or read password files.

Wallet Migration — Old Flow to Secure Keychain

Use this skill when a user already has a nansen-cli wallet set up with the old password storage method and wants to migrate to the new secure flow.

When to use

• User mentions they stored their password in ~/.nansen/.env, a .env file, or memory.md
• User gets the stderr warning: ⚠ Password loaded from insecure .credentials file
• User asks to "secure my wallet" or "migrate to keychain"
• User created a wallet before the keychain update was released

Detect current state

wallet show only displays addresses and does NOT load or check the password. To detect the actual password situation, check for stored password sources:

# 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

Interpret the export output:

• ⚠ Password loaded from ~/.nansen/wallets/.credentials on stderr → needs migration (Path B)
• Export succeeds silently → password is in keychain, no migration needed
• PASSWORD_REQUIRED JSON error → password not persisted anywhere (Path C or D)

Migration paths

Path A: Password in ~/.nansen/.env (old skill pattern)

The previous wallet skill told agents to write the password to ~/.nansen/.env.

Step 1 — Ask the human for their password:

"Your wallet password is currently stored in ~/.nansen/.env, which is insecure. I can migrate it to your OS keychain. Please confirm the password you used when creating the wallet, or I can read it from ~/.nansen/.env if you authorize it."

Step 2 — Migrate:

The source and nansen wallet secure MUST run in the same shell so the env var is available to the node process:

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

Step 3 — Verify the password actually decrypts the wallet:

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

If export succeeds (shows private keys), the migration worked. If it shows Incorrect password, the wrong password was migrated — run nansen wallet forget-password and retry with the correct password.

Step 4 — Clean up the insecure file:

rm -f ~/.nansen/.env

Path B: Password in .credentials file (auto-saved fallback)

This happens when wallet create couldn't access the OS keychain (containers, CI).

nansen wallet secure

If the keychain is still unavailable (e.g. containerized Linux without D-Bus), nansen wallet secure will explain the situation and suggest alternatives.

After migrating, verify decryption works:

nansen wallet export default 2>&1

Path C: Password only in NANSEN_WALLET_PASSWORD env var

# Persist the env var password to keychain
nansen wallet secure

Then verify without the env var:

unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1

Path D: Password lost entirely

The password cannot be recovered. The wallet's private keys are encrypted with AES-256-GCM and the password is not stored anywhere recoverable.

Tell the human:

"Your wallet password cannot be recovered. If you have funds in this wallet, they may be inaccessible. You can create a new wallet and transfer any remaining accessible funds."

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

Post-migration verification

After any migration, confirm the password was migrated correctly by proving the keychain password can actually decrypt the 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

If export shows Incorrect password, the wrong password was saved to the keychain. Fix with:

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

If stderr still shows the .credentials warning, the keychain migration did not succeed — check if the OS keychain service is running (secret-tool on Linux, security on macOS).

Forget password (all stores)

If the user wants to remove their persisted password entirely:

nansen wallet forget-password

This clears the password from both OS keychain and .credentials file. Future wallet operations will require NANSEN_WALLET_PASSWORD env var or re-running nansen wallet secure.

Critical rules for agents

• NEVER generate a password — always ask the human
• NEVER store the password in files, memory, logs, or conversation history
• NEVER use --human flag — interactive prompts break agents
• If the human authorizes reading ~/.nansen/.env, read it in the same command (source ~/.nansen/.env && nansen wallet secure) — do not echo or log the value
• ALWAYS verify after migration with nansen wallet export default — wallet show does NOT prove the password works (it never loads the password)