@palmyr/cli 1.8.1 → 1.8.2

package/README.md

@@ -160,6 +160,23 @@ palmyr wallet import --mnemonic "twelve word seed phrase ..." --name imported
 palmyr wallet import --mnemonic "..." --name from-backup --tag restored --solana
 ```
 
+### Durable recovery — passphrase fallback
+
+By default a wallet is **session-only**: the mnemonic is encrypted with a random session secret stored in your OS credential store (DPAPI / Keychain / `secret-tool`). That secret does not survive a different OS user, a fresh install, or a headless box without an unlocked keyring. Two ways to add a durable scrypt-derived passphrase that decrypts on any machine:
+
+```bash
+# At create time — env var preferred (keeps the phrase out of shell history)
+PALMYR_WALLET_PASSPHRASE="your-passphrase" palmyr wallet create --name agent-prod
+
+# Migrate an existing wallet — run on the original machine while the OS session secret still works
+palmyr wallet rekey <WALLET_ID> --passphrase "your-passphrase"
+
+# Recover on a new machine — copy ~/.palmyr/wallet/wallets/<id>.json over, then:
+PALMYR_WALLET_PASSPHRASE="your-passphrase" palmyr wallet info <WALLET_ID>
+```
+
+When set, the wallet file gets a second AES-256-GCM blob (`owner_crypto`, scrypt KDF on the passphrase + random salt). Decryption tries the OS session secret first, then falls back to `PALMYR_WALLET_PASSPHRASE` / `--passphrase`. Minimum length 8 chars. Re-running `wallet rekey` rotates — old passphrase stops working.
+
 ### Exporting a seed
 
 ```bash
@@ -409,8 +426,9 @@ All wallet operations except `addresses`, `api-key`, `config`, and `request-appr
 
 | Command | Network | Notes |
 |---|---|---|
-| `palmyr wallet create [--name N] [--managed] [--solana\|--base] [--tag T] [--count N] [--name-prefix P]` | local *(server only if `--managed`)* | New wallet. Stores session secret in OS credential store. `--count > 1` bulk-creates N unmanaged wallets under a required `--tag` (max 500/call, batched DPAPI seal on Windows). `--solana` / `--base` materializes only one chain. |
-| `palmyr wallet import --mnemonic "..." [--name N] [--managed] [--solana\|--base] [--tag T]` | local | Restore from BIP-39. Same chain / tag flags as `create`. |
+| `palmyr wallet create [--name N] [--managed] [--solana\|--base] [--tag T] [--count N] [--name-prefix P] [--passphrase P]` | local *(server only if `--managed`)* | New wallet. Stores session secret in OS credential store. `--count > 1` bulk-creates N unmanaged wallets under a required `--tag` (max 500/call, batched DPAPI seal on Windows). `--solana` / `--base` materializes only one chain. `--passphrase` (or `PALMYR_WALLET_PASSPHRASE` env) also seals the mnemonic with scrypt so the wallet survives OS-keychain loss. |
+| `palmyr wallet import --mnemonic "..." [--name N] [--managed] [--solana\|--base] [--tag T] [--passphrase P]` | local | Restore from BIP-39. Same chain / tag / passphrase flags as `create`. |
+| `palmyr wallet rekey <ID> --passphrase P` | local | Add (or rotate) the scrypt passphrase fallback on an existing wallet. Wallet must be decryptable right now (session secret still works, or `--current-passphrase` provided). Run on the original machine, then `PALMYR_WALLET_PASSPHRASE` decrypts the wallet anywhere. |
 | `palmyr wallet list [--tag T]` | local | Lists wallets in the local vault. `--tag` filters to one folder. |
 | `palmyr wallet info <ID>` | local | Show one wallet (id, name, addresses, mode, tag). |
 | `palmyr wallet tags` | local | List all tags with wallet count, chains, and date range. |
@@ -779,7 +797,7 @@ Config is stored in `~/.palmyr/config.json`. Environment variables override file
 | `PALMYR_PAY_WALLET` | Force a specific wallet ID for x402 payment. |
 | `PALMYR_WALLET_PATH` | Override vault directory (default `~/.palmyr/wallet`). |
 | `PALMYR_KEYFILE` | Solana keyfile path (legacy single-key flow). |
-| `PALMYR_WALLET_PASSPHRASE` | Optional BIP-39 passphrase for legacy import/export. |
+| `PALMYR_WALLET_PASSPHRASE` | Vault decryption passphrase. Used when the wallet was created with `--passphrase` (or env) or migrated via `wallet rekey`. Falls back to the OS-keychain session secret when unset. |
 
 ### Chain selection during payment
 
@@ -838,6 +856,7 @@ The CLI uses distinct exit codes so scripts and agents can branch on failure mod
 - **Keys never leave the machine.** `wallet create` and `wallet import` never transmit seed material to the server. Even managed wallets register only the wallet ID and the derived public addresses with the server.
 - **Encryption at rest.** The wallet file is AES-256-GCM with the session secret as the key. The session secret is generated on wallet creation and never stored on disk in plaintext.
 - **OS credential store.** Session secrets live in DPAPI (Windows), Keychain (macOS), or `secret-tool` (libsecret on Linux). If none is available the CLI errors rather than falling back to plaintext.
+- **Optional passphrase fallback.** Create with `--passphrase` (or `PALMYR_WALLET_PASSPHRASE` env), or migrate with `wallet rekey`, to add a second AES-256-GCM blob keyed by scrypt(passphrase, random salt). Lets the wallet decrypt on a different machine / user / headless box where the OS keychain isn't reachable. Decryption tries the OS session secret first, then falls back to the env/flag passphrase.
 - **Bidirectional vault integrity.** On every load, the CLI checks that every account stored in the wallet file is still derivable from the seed, **and** that every account derivable from the seed is still in the file. Either direction failing returns exit code `7`.
 - **Pre-flight validation.** Endpoints that are easy to fail (bad pubkey for an inbox, malformed E.164 for SMS, unsupported destination country) are validated **before** the x402 paywall, so you don't pay for requests that were never going to succeed.
 - **No `--no-verify`.** Hooks, signatures, and webhooks are always verified.

package/dist/cli.js

@@ -219,6 +219,7 @@ const WALLET_HELP = {
         { flag: '--tag <name>', desc: 'Folder-like grouping tag', hint: 'e.g. palmyr-demo — required with --count' },
         { flag: '--count <N>', desc: 'Bulk-create N wallets in one call (1-500)', hint: 'unmanaged only; requires --tag' },
         { flag: '--name-prefix <p>', desc: 'Bulk name prefix; suffixed `-001..-N`', hint: 'default: same as --tag' },
+        { flag: '--passphrase <p>', desc: 'Also seal the mnemonic with this passphrase (≥8 chars) for durable recovery', hint: 'or PALMYR_WALLET_PASSPHRASE env (env preferred — keeps phrase out of shell history)' },
     ],
     import: [
         { flag: '--mnemonic <words>', desc: 'BIP-39 mnemonic phrase (required)' },
@@ -227,6 +228,13 @@ const WALLET_HELP = {
         { flag: '--solana', desc: 'Materialize the Solana account only' },
         { flag: '--base', desc: 'Materialize the Base/EVM account only' },
         { flag: '--tag <name>', desc: 'Assign a tag at import time' },
+        { flag: '--passphrase <p>', desc: 'Also seal the mnemonic with this passphrase (≥8 chars) for durable recovery', hint: 'or PALMYR_WALLET_PASSPHRASE env (env preferred)' },
+    ],
+    rekey: [
+        { flag: '<WALLET_ID>', desc: 'Wallet ID or name (positional or --id)' },
+        { flag: '--passphrase <p>', desc: 'New passphrase to seal the mnemonic with (≥8 chars)', hint: 'or PALMYR_WALLET_PASSPHRASE env; interactive prompt if neither set' },
+        { flag: '--current-passphrase <p>', desc: 'Existing passphrase, if the wallet was already rekeyed and the OS session secret is gone', hint: 'or PALMYR_WALLET_PASSPHRASE_CURRENT env' },
+        { flag: '(note)', desc: 'Run on the original machine while the OS session secret is still resolvable. Becomes the durable recovery path on any other host.' },
     ],
     tags: [
         { flag: '(no args)', desc: 'List all tags with wallet count, chains, and date range' },
@@ -2153,6 +2161,7 @@ async function main() {
                             { name: 'tag-delete', description: 'Cascade-delete every wallet under a tag', hint: 'TAG --confirm' },
                             { name: 'sign-message', description: 'Sign a message', hint: 'WALLET_ID --chain evm --msg "hello"' },
                             { name: 'export', description: 'Export mnemonic for backup', hint: 'WALLET_ID --confirm' },
+                            { name: 'rekey', description: 'Add or rotate the passphrase fallback (durable across OS-keychain loss)', hint: 'WALLET_ID --passphrase <p>' },
                             { name: 'api-key', description: 'Create agent API key', hint: 'WALLET_ID --name my-agent' },
                             { name: 'config', description: 'Get agent config', hint: 'WALLET_ID' },
                             { name: 'use', description: 'Set default pay wallet', hint: 'WALLET_ID' },
@@ -2201,6 +2210,10 @@ async function main() {
                         const chains = (wantSol && !wantBase) ? ['solana']
                             : (wantBase && !wantSol) ? ['base']
                                 : ['solana', 'base'];
+                        // Optional passphrase fallback — seals the mnemonic with scrypt so
+                        // PALMYR_WALLET_PASSPHRASE can decrypt on a different machine / user /
+                        // headless box where the OS credential-store secret isn't reachable.
+                        const passphrase = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
                         // ─── Bulk path ───
                         if (count > 1) {
                             if (isManaged)
@@ -2214,12 +2227,12 @@ async function main() {
                             const { storeSecretsBatch } = await import('./credential-store.js');
                             // Progress to stderr so JSON on stdout stays clean
                             if (!AGENT_MODE)
-                                process.stderr.write(`creating ${count} wallets under tag "${tagRaw}"...\n`);
-                            const results = createLocalWalletsBatch(prefix, count, 'unmanaged', { tag: tagRaw, chains });
+                                process.stderr.write(`creating ${count} wallets under tag "${tagRaw}"${passphrase ? ' (+ passphrase fallback)' : ''}...\n`);
+                            const results = createLocalWalletsBatch(prefix, count, 'unmanaged', { tag: tagRaw, chains, passphrase });
                             if (!AGENT_MODE)
                                 process.stderr.write(`sealing ${count} session secrets in OS credential store...\n`);
                             storeSecretsBatch(results.map(r => ({ account: r.id, secret: r.sessionSecret })));
-                            log(`wallet create: ${count} wallets under tag "${tagRaw}" (chains=${chains.join(',')})`);
+                            log(`wallet create: ${count} wallets under tag "${tagRaw}" (chains=${chains.join(',')}${passphrase ? ', passphrase=set' : ''})`);
                             if (AGENT_MODE) {
                                 print({
                                     count: results.length,
@@ -2251,7 +2264,7 @@ async function main() {
                         const mode = isManaged ? 'managed' : 'unmanaged';
                         // Create locally — no server needed for the key material
                         const { createLocalWallet } = await import('./vault.js');
-                        const w = createLocalWallet(name, mode, { tag: tagRaw, chains });
+                        const w = createLocalWallet(name, mode, { tag: tagRaw, chains, passphrase });
                         // Store session secret in OS credential store
                         const { storeSecret } = await import('./credential-store.js');
                         storeSecret(w.id, w.sessionSecret);
@@ -2315,12 +2328,13 @@ async function main() {
                         const chains = (wantSol && !wantBase) ? ['solana']
                             : (wantBase && !wantSol) ? ['base']
                                 : ['solana', 'base'];
+                        const passphrase = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
                         const { importLocalWallet } = await import('./vault.js');
-                        const w = importLocalWallet(name, mnemonic, mode, { tag: tagRaw, chains });
+                        const w = importLocalWallet(name, mnemonic, mode, { tag: tagRaw, chains, passphrase });
                         // Store session secret
                         const { storeSecret } = await import('./credential-store.js');
                         storeSecret(w.id, w.sessionSecret);
-                        log(`wallet import: ${w.id}`);
+                        log(`wallet import: ${w.id}${passphrase ? ' (+ passphrase fallback)' : ''}`);
                         if (!AGENT_MODE) {
                             render(React.createElement(WalletCreateScreen, {
                                 version: VERSION,
@@ -2629,6 +2643,43 @@ async function main() {
                         }
                         break;
                     }
+                    case 'rekey': {
+                        const walletId = positional[0] || flags.id;
+                        if (!walletId)
+                            err('Wallet ID required: palmyr wallet rekey <WALLET_ID> --passphrase <p>', EXIT.BAD_INPUT);
+                        // New passphrase: flag → env → interactive prompt (TTY only).
+                        let newPass = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE || undefined;
+                        if (!newPass) {
+                            if (!process.stdin.isTTY)
+                                err('--passphrase or PALMYR_WALLET_PASSPHRASE required (no TTY for interactive prompt)', EXIT.BAD_INPUT);
+                            const { promptNewPassphrase } = await import('./passphrase-prompt.js');
+                            newPass = await promptNewPassphrase();
+                        }
+                        // Current passphrase is only needed if the wallet was already
+                        // passphrase-sealed and the OS session secret is gone (rare —
+                        // typically the rekey runs on the original machine where the
+                        // session secret still resolves).
+                        const currentPass = flags['current-passphrase'] || process.env.PALMYR_WALLET_PASSPHRASE_CURRENT || undefined;
+                        const { rekeyWallet } = await import('./vault.js');
+                        let result;
+                        try {
+                            result = rekeyWallet(walletId, newPass, currentPass);
+                        }
+                        catch (e) {
+                            const code = e.message?.includes('SECURITY') ? EXIT.SECURITY : EXIT.GENERAL;
+                            err(e.message, code);
+                        }
+                        log(`wallet rekey: ${result.id} (${result.rotated ? 'rotated' : 'added'})`);
+                        if (!AGENT_MODE) {
+                            const verb = result.rotated ? 'Rotated' : 'Added';
+                            console.log(`\n  ${t.success}✔${t.reset} ${verb} passphrase fallback on ${t.accent}${result.name}${t.reset}`);
+                            console.log(`  ${t.muted}Wallet now decrypts with PALMYR_WALLET_PASSPHRASE on any machine (in addition to the OS keychain on this one).${t.reset}\n`);
+                        }
+                        else {
+                            print({ success: true, ...result });
+                        }
+                        break;
+                    }
                     case 'buy': {
                         const chain = (positional[0] || 'solana').toLowerCase();
                         if (chain !== 'solana' && chain !== 'base')