nansen-cli 1.13.1 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.15.0
+
+### Minor Changes
+
+- [#216](https://github.com/nansen-ai/nansen-cli/pull/216) [`5b88241`](https://github.com/nansen-ai/nansen-cli/commit/5b882411134efc5ece44d640adc105c8dd8c5771) Thanks [@TimNooren](https://github.com/TimNooren)! - Unified wallet abstraction: Privy server wallets are first-class citizens.
+
+  - `wallet create --provider privy` creates EVM + Solana wallets via Privy and stores a local reference
+  - All wallet commands (list, show, delete, default, send) work by name regardless of provider
+  - Trading (quote + execute) supports Privy wallets with sign-only + Trading API broadcast
+  - x402 auto-payment routes through Privy when credentials are configured
+
+### Patch Changes
+
+- [#232](https://github.com/nansen-ai/nansen-cli/pull/232) [`443aaad`](https://github.com/nansen-ai/nansen-cli/commit/443aaad15da051ac65e0999b4c4b09436050d0fe) Thanks [@kome12](https://github.com/kome12)! - Remove unsupported chains (zksync, unichain) from CLI
+
+## 1.14.0
+
+### Minor Changes
+
+- [#231](https://github.com/nansen-ai/nansen-cli/pull/231) [`c3968da`](https://github.com/nansen-ai/nansen-cli/commit/c3968dacb52521235ad6502321650148ac825d01) Thanks [@araa47](https://github.com/araa47)! - Agent-first secure wallet flow — OS keychain persistence, no interactive prompts
+
+  - **New `src/keychain.js`**: Password persistence via OS keychain (macOS Keychain / Linux secret-tool), with base64-encoded `.credentials` file fallback for containers/CI. Zero npm dependencies.
+  - **Non-interactive by default**: All readline prompts removed. Agents get structured JSON errors (`PASSWORD_REQUIRED`, `API_KEY_REQUIRED`) with actionable instructions. `--human` flag re-enables interactive mode.
+  - **Two-step wallet creation**: Agent asks user for password, runs `NANSEN_WALLET_PASSWORD=<pw> nansen wallet create`. Password auto-persists to keychain — all future operations are passwordless.
+  - **New commands**: `wallet secure` (migrate to keychain), `wallet forget-password` (clear from all stores).
+  - **Bug fixes**: Clear `passwordHash` on last wallet delete, verify password before keychain writes, exit non-zero when keychain migration fails, source-aware error messages.
+  - **New skill**: `nansen-wallet-migration` for migrating from old `~/.nansen/.env` storage to keychain.
+
 ## 1.13.1
 
 ### Patch Changes

package/README.md

@@ -55,7 +55,7 @@ Run `nansen schema --pretty` for the full subcommand and field reference.
 
 ## Supported Chains
 
-`ethereum` `solana` `base` `bnb` `arbitrum` `polygon` `optimism` `avalanche` `linea` `scroll` `zksync` `mantle` `ronin` `sei` `plasma` `sonic` `unichain` `monad` `hyperevm` `iotaevm`
+`ethereum` `solana` `base` `bnb` `arbitrum` `polygon` `optimism` `avalanche` `linea` `scroll` `mantle` `ronin` `sei` `plasma` `sonic` `monad` `hyperevm` `iotaevm`
 
 > Run `nansen schema` to get the current chain list (source of truth).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.13.1",
+  "version": "1.15.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -21,6 +21,7 @@
     "test:live": "NANSEN_LIVE_TEST=1 vitest run",
     "test:trade": "vitest run --config vitest.e2e.config.js src/__tests__/trade.e2e.test.js",
     "test:send": "vitest run --config vitest.e2e.config.js src/__tests__/send.e2e.test.js",
+    "test:privy": "vitest run --config vitest.e2e.config.js src/__tests__/privy.e2e.test.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "changeset": "changeset",

package/src/api.js

@@ -504,90 +504,133 @@ export class NansenAPI {
           const hasManualSignature = !!(this.defaultHeaders['Payment-Signature'] || options.headers?.['Payment-Signature']);
 
           if (!hasManualSignature) {
-            // 1. Try local wallet with fallback across payment networks
+            // Determine payment method from default wallet's provider
+            let defaultWalletProvider = 'local';
+            let defaultWalletName = 'unknown';
             try {
-              const { createPaymentSignatures } = await import('./x402.js');
-              for await (const { signature, network } of createPaymentSignatures(response, url)) {
-                const paidResponse = await fetch(url, {
-                  method: 'POST',
-                  headers: {
-                    'Content-Type': 'application/json',
-                    'X-Client-Type': 'nansen-cli',
-                    'X-Client-Version': packageVersion,
-                    'Payment-Signature': signature,
-                    ...this.defaultHeaders,
-                    ...options.headers,
-                  },
-                  body: JSON.stringify(NansenAPI.cleanBody(body)),
-                });
-                if (paidResponse.ok) {
-                  const chain = network.startsWith('solana:') ? 'Solana' : 'Base';
-                  console.error(`[x402] Paid via ${chain} USDC`);
-                  // Check remaining balance and warn if low
-                  try {
-                    const { checkX402Balance } = await import('./x402.js');
-                    const balance = await checkX402Balance(network);
-                    if (balance !== null && balance < 0.25) {
-                      console.error(`[x402] Warning: USDC balance low ($${balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
-                    }
-                  } catch { /* balance check is best-effort */ }
-                  return await paidResponse.json();
-                }
-                // This payment option was rejected, try next
+              const { getWalletConfig, showWallet } = await import('./wallet.js');
+              const walletConfig = getWalletConfig();
+              if (walletConfig.defaultWallet) {
+                defaultWalletName = walletConfig.defaultWallet;
+                const wallet = showWallet(walletConfig.defaultWallet);
+                defaultWalletProvider = wallet.provider || 'local';
               }
-            } catch { /* local wallet unavailable, try WalletConnect */ }
-
-            // 2. Fall back to WalletConnect (walletconnect-x402.js)
-            // (local wallet returns early on success above, so we always reach here if it failed)
-            {
-              let paymentRequirements;
-              const paymentHeader = response.headers.get('payment-required');
-              if (paymentHeader) {
-                try {
-                  paymentRequirements = JSON.parse(atob(paymentHeader));
-                } catch {
-                  data.paymentRequiredRaw = paymentHeader;
+            } catch (err) {
+              if (process.env.DEBUG) console.error(`[x402] Failed to detect wallet provider: ${err.message}`);
+            }
+
+            if (defaultWalletProvider === 'privy') {
+              // Default wallet is Privy: sign via Privy
+              try {
+                const { createPrivyPaymentSignatures } = await import('./privy.js');
+                for await (const { signature, network } of createPrivyPaymentSignatures(response, url)) {
+                  const paidResponse = await fetch(url, {
+                    method: 'POST',
+                    headers: {
+                      'Content-Type': 'application/json',
+                      'X-Client-Type': 'nansen-cli',
+                      'X-Client-Version': packageVersion,
+                      'Payment-Signature': signature,
+                      ...this.defaultHeaders,
+                      ...options.headers,
+                    },
+                    body: JSON.stringify(NansenAPI.cleanBody(body)),
+                  });
+                  if (paidResponse.ok) {
+                    console.error(`[x402] Paid via Privy wallet ${defaultWalletName} (${network})`);
+                    try {
+                      const { checkX402Balance } = await import('./x402.js');
+                      const balance = await checkX402Balance(network);
+                      if (balance !== null && balance < 0.25) {
+                        console.error(`[x402] Warning: USDC balance low ($${balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
+                      }
+                    } catch { /* balance check is best-effort */ }
+                    return await paidResponse.json();
+                  }
                 }
+              } catch (privyErr) {
+                message = `x402 Privy payment failed: ${privyErr.message}`;
               }
-              if (!paymentRequirements && data.paymentRequirements) {
-                paymentRequirements = data.paymentRequirements;
-              }
-
-              if (paymentRequirements) {
-                try {
-                  const { handleX402Payment } = await import('./walletconnect-x402.js');
-                  const paymentSignature = await handleX402Payment(paymentRequirements);
+            } else {
+              // Local wallet or no wallet: existing local wallet + WalletConnect flow
+              // 1. Try local wallet with fallback across payment networks
+              try {
+                const { createPaymentSignatures } = await import('./x402.js');
+                for await (const { signature, network } of createPaymentSignatures(response, url)) {
                   const paidResponse = await fetch(url, {
                     method: 'POST',
                     headers: {
                       'Content-Type': 'application/json',
                       'X-Client-Type': 'nansen-cli',
                       'X-Client-Version': packageVersion,
-                      'Payment-Signature': paymentSignature,
+                      'Payment-Signature': signature,
                       ...this.defaultHeaders,
                       ...options.headers,
                     },
                     body: JSON.stringify(NansenAPI.cleanBody(body)),
                   });
                   if (paidResponse.ok) {
+                    console.error(`[x402] Paid via local wallet ${defaultWalletName} (${network})`);
+                    // Check remaining balance and warn if low
+                    try {
+                      const { checkX402Balance } = await import('./x402.js');
+                      const balance = await checkX402Balance(network);
+                      if (balance !== null && balance < 0.25) {
+                        console.error(`[x402] Warning: USDC balance low ($${balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
+                      }
+                    } catch { /* balance check is best-effort */ }
                     return await paidResponse.json();
                   }
-                } catch (x402Err) {
-                  if (!this.apiKey) {
-                    // No API key and no payment wallet — guide the user to login rather than
-                    // showing a confusing x402 payment dump they can't act on.
-                    // TODO: full fix would skip x402 entirely when no apiKey is set — see PR #<this PR number>
-                    message = 'No API key configured. Two ways to authenticate:\n' +
-                      '  1. API key: nansen login --api-key <key> (get key at https://app.nansen.ai/api)\n' +
-                      '  2. x402 micropayment: nansen wallet create + fund with USDC (no API key needed)';
-                  } else {
-                    message = `x402 auto-payment failed: ${x402Err.message}`;
+                  // This payment option was rejected, try next
+                }
+              } catch { /* local wallet unavailable, try WalletConnect */ }
+
+              // 2. Fall back to WalletConnect (walletconnect-x402.js)
+              {
+                let paymentRequirements;
+                const paymentHeader = response.headers.get('payment-required');
+                if (paymentHeader) {
+                  try {
+                    paymentRequirements = JSON.parse(atob(paymentHeader));
+                  } catch {
+                    data.paymentRequiredRaw = paymentHeader;
                   }
                 }
-                // Only include raw payment requirements in the error details when the user
-                // has an API key — for unauthenticated users they add noise, not signal.
-                if (this.apiKey) {
-                  data.paymentRequirements = paymentRequirements;
+                if (!paymentRequirements && data.paymentRequirements) {
+                  paymentRequirements = data.paymentRequirements;
+                }
+
+                if (paymentRequirements) {
+                  try {
+                    const { handleX402Payment } = await import('./walletconnect-x402.js');
+                    const paymentSignature = await handleX402Payment(paymentRequirements);
+                    const paidResponse = await fetch(url, {
+                      method: 'POST',
+                      headers: {
+                        'Content-Type': 'application/json',
+                        'X-Client-Type': 'nansen-cli',
+                        'X-Client-Version': packageVersion,
+                        'Payment-Signature': paymentSignature,
+                        ...this.defaultHeaders,
+                        ...options.headers,
+                      },
+                      body: JSON.stringify(NansenAPI.cleanBody(body)),
+                    });
+                    if (paidResponse.ok) {
+                      return await paidResponse.json();
+                    }
+                  } catch (x402Err) {
+                    if (!this.apiKey) {
+                      message = 'No API key configured. Two ways to authenticate:\n' +
+                        '  1. API key: nansen login --api-key <key> (get key at https://app.nansen.ai/api)\n' +
+                        '  2. x402 micropayment: nansen wallet create + fund with USDC (no API key needed)';
+                    } else {
+                      message = `x402 auto-payment failed: ${x402Err.message}`;
+                    }
+                  }
+                  if (this.apiKey) {
+                    data.paymentRequirements = paymentRequirements;
+                  }
                 }
               }
             }

package/src/chain-ids.js

@@ -14,7 +14,6 @@ export const EVM_CHAIN_IDS = {
   bnb: 56,
   linea: 59144,
   scroll: 534352,
-  zksync: 324,
   mantle: 5000,
 };
 
@@ -25,6 +24,6 @@ export const EVM_CHAIN_IDS = {
  */
 export const EVM_CHAINS = [
   'ethereum', 'arbitrum', 'base', 'bnb', 'polygon', 'optimism',
-  'avalanche', 'linea', 'scroll', 'zksync', 'mantle', 'ronin',
-  'sei', 'plasma', 'sonic', 'unichain', 'monad', 'hyperevm', 'iotaevm',
+  'avalanche', 'linea', 'scroll', 'mantle', 'ronin',
+  'sei', 'plasma', 'sonic', 'monad', 'hyperevm', 'iotaevm',
 ];

package/src/cli.js

@@ -163,7 +163,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full') {
+      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human') {
         result.flags[key] = true;
       } else if (next && !next.startsWith('-')) {
         // Try to parse as JSON first (for objects/arrays/booleans),
@@ -669,8 +669,8 @@ USAGE: nansen <command> [subcommand] [options]
 COMMANDS:
   research    smart-money, profiler, token, search, perp, portfolio, points
   trade       quote, execute
-  wallet      create, list, show, export, default, delete
-  login       Save API key (--api-key <key> or interactive)
+  wallet      create, list, show, export, default, delete, forget-password
+  login       Save API key (--api-key <key> or NANSEN_API_KEY env var)
   logout      Remove saved API key
   schema      JSON schema for all commands (use "nansen schema <cmd>" for one)
   cache       clear
@@ -684,9 +684,9 @@ EXAMPLES:
   nansen research smart-money netflow --chain solana
   nansen research token screener --chain solana --timeframe 24h
   nansen research profiler balance --address 0x... --chain ethereum
-  nansen trade quote --chain base --from ETH --to USDC --amount 1
+  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
 
-Research chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, zksync, mantle, ronin, sei, plasma, sonic, unichain, monad, hyperevm, iotaevm
+Research chains: ethereum, solana, base, bnb, arbitrum, polygon, optimism, avalanche, linea, scroll, mantle, ronin, sei, plasma, sonic, monad, hyperevm, iotaevm
 Trade chains: solana, base
 Labels: Fund, Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader
 
@@ -761,43 +761,51 @@ export function buildCommands(deps = {}) {
       if (flags.help || flags.h) {
         log('nansen login - Save your Nansen API key\n');
         log('USAGE:');
-        log('  nansen login                    (interactive)');
-        log('  nansen login --api-key <key>    (non-interactive)\n');
+        log('  nansen login --api-key <key>');
+        log('  NANSEN_API_KEY=<key> nansen login');
+        log('  nansen login --human              (interactive prompt)\n');
         log('OPTIONS:');
         log('  --api-key <key>   Your Nansen API key');
+        log('  --human           Enable interactive prompt');
         log('  --help            Show this help\n');
         log('Get your API key at: https://app.nansen.ai/api');
         return;
       }
 
-      // Support non-interactive: nansen login --api-key <key>
       let apiKey = options['api-key'] || options.apiKey;
 
       if (!apiKey) {
-        if (!isTTY) {
-          // Non-interactive mode: check env var fallback
-          apiKey = process.env.NANSEN_API_KEY;
-          if (!apiKey) {
-            log('❌ No API key provided. Use: nansen login --api-key <key>\n   Or set NANSEN_API_KEY environment variable.\n   Get your API key at: https://app.nansen.ai/api');
-            exit(1);
-            return;
-          }
-        } else {
-          log('Nansen CLI Login\n');
-          log('Get your API key at: https://app.nansen.ai/api\n');
-          log('Tip: For non-interactive use: nansen login --api-key <key>\n');
+        apiKey = process.env.NANSEN_API_KEY;
+      }
 
-          apiKey = await promptFn('Enter your API key: ', true);
+      if (!apiKey && flags.human) {
+        if (!isTTY) {
+          log(JSON.stringify({
+            error: 'NOT_A_TTY',
+            message: '--human requires an interactive terminal. Use --api-key or NANSEN_API_KEY env var instead.',
+          }));
+          exit(1);
+          return;
         }
+        log('Nansen CLI Login\n');
+        log('Get your API key at: https://app.nansen.ai/api\n');
+        apiKey = await promptFn('Enter your API key: ', true);
       }
 
       if (!apiKey || apiKey.trim().length === 0) {
-        log('\n❌ No API key provided');
+        log(JSON.stringify({
+          error: 'API_KEY_REQUIRED',
+          message: 'No API key provided.',
+          resolution: [
+            'Run: nansen login --api-key <key>',
+            'Or set NANSEN_API_KEY environment variable',
+            'Get your API key at: https://app.nansen.ai/api',
+          ],
+        }));
         exit(1);
         return;
       }
 
-      // Save the config without validation
       saveConfigFn({
         apiKey: apiKey.trim(),
         baseUrl: 'https://api.nansen.ai'

package/src/keychain.js

@@ -0,0 +1,229 @@
+/**
+ * Nansen CLI - Password Persistence
+ * Stores/retrieves the wallet password, preferring the native OS credential
+ * store and falling back to a base64-encoded credentials file (not encrypted).
+ *
+ * Resolution order (read):
+ *   1. NANSEN_WALLET_PASSWORD env var
+ *   2. OS keychain (macOS Keychain / Linux secret-tool / Windows cmdkey)
+ *   3. ~/.nansen/wallets/.credentials file (insecure fallback)
+ *
+ * Storage order (write):
+ *   1. Try OS keychain first
+ *   2. Fall back to ~/.nansen/wallets/.credentials (chmod 600)
+ *
+ * Zero npm dependencies — uses native OS commands via child_process.
+ */
+
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const SERVICE = 'nansen-cli';
+const ACCOUNT = 'wallet-password';
+const TIMEOUT_MS = 5000;
+
+function getCredentialsPath() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  return path.join(home, '.nansen', 'wallets', '.credentials');
+}
+
+// ============= OS Keychain =============
+
+function keychainStore(password) {
+  try {
+    if (process.platform === 'darwin') {
+      // macOS `security` CLI requires -w <password> as argv — no stdin mode.
+      // Unlike secret-tool, omitting the value prompts from the TTY, not stdin.
+      // Exposure in process listings is brief (sub-second, execFileSync is synchronous).
+      execFileSync('/usr/bin/security', [
+        'add-generic-password',
+        '-s', SERVICE,
+        '-a', ACCOUNT,
+        '-w', password,
+        '-U',
+      ], { timeout: TIMEOUT_MS, stdio: 'pipe' });
+      return true;
+    }
+
+    if (process.platform === 'linux') {
+      execFileSync('secret-tool', [
+        'store',
+        '--label', SERVICE,
+        'service', SERVICE,
+        'account', ACCOUNT,
+      ], { input: password, timeout: TIMEOUT_MS, stdio: ['pipe', 'pipe', 'pipe'] });
+      return true;
+    }
+
+    // Windows: no reliable built-in CLI for credential read-back.
+    // cmdkey stores but can't retrieve passwords. Falls through to .credentials file.
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function keychainRetrieve() {
+  try {
+    if (process.platform === 'darwin') {
+      const result = execFileSync('/usr/bin/security', [
+        'find-generic-password',
+        '-s', SERVICE,
+        '-a', ACCOUNT,
+        '-w',
+      ], { timeout: TIMEOUT_MS, stdio: ['pipe', 'pipe', 'pipe'] });
+      const pw = result.toString().trim();
+      return pw || null;
+    }
+
+    if (process.platform === 'linux') {
+      const result = execFileSync('secret-tool', [
+        'lookup',
+        'service', SERVICE,
+        'account', ACCOUNT,
+      ], { timeout: TIMEOUT_MS, stdio: ['pipe', 'pipe', 'pipe'] });
+      const pw = result.toString().trim();
+      return pw || null;
+    }
+
+    // Windows: no reliable built-in CLI for credential read-back.
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function keychainDeleteEntry() {
+  try {
+    if (process.platform === 'darwin') {
+      execFileSync('/usr/bin/security', [
+        'delete-generic-password',
+        '-s', SERVICE,
+        '-a', ACCOUNT,
+      ], { timeout: TIMEOUT_MS, stdio: 'pipe' });
+      return true;
+    }
+
+    if (process.platform === 'linux') {
+      execFileSync('secret-tool', [
+        'clear',
+        'service', SERVICE,
+        'account', ACCOUNT,
+      ], { timeout: TIMEOUT_MS, stdio: 'pipe' });
+      return true;
+    }
+
+    // Windows: no keychain entries to delete (uses .credentials file).
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// ============= Credentials File Fallback =============
+
+function credentialsFileRead() {
+  try {
+    const filePath = getCredentialsPath();
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    // New format: base64-encoded (handles passwords with newlines/special chars)
+    const b64Match = content.match(/^NANSEN_WALLET_PASSWORD_B64=(.+)$/m);
+    if (b64Match) return Buffer.from(b64Match[1].trim(), 'base64').toString('utf8');
+    // Legacy format: plain text (backward compat)
+    const match = content.match(/^NANSEN_WALLET_PASSWORD=(.+)$/m);
+    return match ? match[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function credentialsFileWrite(password) {
+  try {
+    const filePath = getCredentialsPath();
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { mode: 0o700, recursive: true });
+    }
+    const encoded = Buffer.from(password, 'utf8').toString('base64');
+    fs.writeFileSync(filePath, `NANSEN_WALLET_PASSWORD_B64=${encoded}\n`, { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function credentialsFileDelete() {
+  try {
+    const filePath = getCredentialsPath();
+    if (!fs.existsSync(filePath)) return false;
+    fs.unlinkSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ============= Public API =============
+
+/**
+ * Store a password. Tries OS keychain first, falls back to .credentials file.
+ * @param {string} password
+ * @returns {{ stored: boolean, method: 'keychain'|'file'|'none' }}
+ */
+export function storePassword(password) {
+  if (keychainStore(password)) {
+    return { stored: true, method: 'keychain' };
+  }
+  if (credentialsFileWrite(password)) {
+    return { stored: true, method: 'file' };
+  }
+  return { stored: false, method: 'none' };
+}
+
+/**
+ * Retrieve the wallet password from OS keychain or .credentials file.
+ * @returns {{ password: string|null, source: 'env'|'keychain'|'file'|null }}
+ */
+export function retrievePassword() {
+  const envPw = process.env.NANSEN_WALLET_PASSWORD;
+  if (envPw) return { password: envPw, source: 'env' };
+
+  const keychainPw = keychainRetrieve();
+  if (keychainPw) return { password: keychainPw, source: 'keychain' };
+
+  const filePw = credentialsFileRead();
+  if (filePw) return { password: filePw, source: 'file' };
+
+  return { password: null, source: null };
+}
+
+/**
+ * Delete the wallet password from all stores.
+ * @returns {{ keychain: boolean, file: boolean }}
+ */
+export function deletePassword() {
+  return {
+    keychain: keychainDeleteEntry(),
+    file: credentialsFileDelete(),
+  };
+}
+
+/**
+ * Delete only the .credentials file (not the keychain entry).
+ * Used by `wallet secure` after migrating to keychain.
+ * @returns {boolean}
+ */
+export function deleteCredentialsFile() {
+  return credentialsFileDelete();
+}
+
+/**
+ * Resolve the wallet password from available sources.
+ * Order: env var → OS keychain → .credentials file → null
+ * @returns {string|null}
+ */
+export function resolvePassword() {
+  return retrievePassword().password;
+}