@profullstack/coinpay 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to `@profullstack/coinpay` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.29.0] - 2026-10-29
+
+### Added
+- `coinpay login` uses OAuth 2.1 either way: authorization code + PKCE on a loopback redirect when a
+  browser is on this machine, the device flow (RFC 8628) otherwise. Over SSH or with no display it
+  picks the device flow by itself; `--device` / `--browser` force one. The device flow now gets real
+  OAuth tokens (rotating refresh token) from `/api/oauth/device_authorization` and the token
+  endpoint instead of the old `/api/cli-auth` session.
+- `coinpay logout` revokes the session at CoinPay (RFC 7009, `/api/oauth/revoke`) before forgetting it.
+- `deviceLogin`, `revokeToken` and `hasLocalBrowser` exported from `src/oauth-login.js`.
+
 ## [0.28.0] - 2026-10-29
 
 ### Added

package/bin/coinpay.js

@@ -85,6 +85,7 @@ import {
   moveDocument,
 } from '../src/documents.js';
 import { publishDirectory } from '../src/documents-publish.js';
+import { getVault, initVault, unlockVault, lockVault, payoutWallet } from '../src/secrets-vault.js';
 import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
@@ -227,6 +228,9 @@ function createUnauthenticatedClient() {
 }
 
 const BOOLEAN_FLAGS = new Set([
+  // vault, payout wallet
+  'no-recovery',
+  'create',
   // projects, time, client portal
   'non-billable',
   'unbilled',
@@ -500,8 +504,8 @@ ${colors.cyan}Commands:${colors.reset}
     set-url <base-url>    Set custom API URL
     show                  Show current configuration
 
-  ${colors.bright}login${colors.reset}                 Sign in (OAuth 2.1 in your browser; --device on a machine without one)
-  ${colors.bright}logout${colors.reset}                Forget the saved session
+  ${colors.bright}login${colors.reset}                 Sign in (OAuth 2.1: browser + PKCE, or the device flow over SSH / --device)
+  ${colors.bright}logout${colors.reset}                Sign out and revoke the session at CoinPay
 
   ${colors.bright}auth${colors.reset}
     register              Register new merchant account
@@ -618,6 +622,18 @@ ${colors.cyan}Commands:${colors.reset}
     get <id>              Get business details
     list                  List businesses
     update <id>           Update business
+    payout-wallet <id>    Show the business payout (hot) wallet; --create makes it
+                          (needs the secrets vault set up + unlocked, and an API key)
+
+  ${colors.bright}vault${colors.reset}             Your secrets vault (sealed to a passphrase only you know;
+                    payouts, bank links and payout wallets need it). Needs an API key
+                    (COINPAY_API_KEY / config set-key): apps signed in with CoinPay cannot.
+                    Passphrase: COINPAY_VAULT_PASSPHRASE or a hidden prompt.
+    status                Exists? Unlocked until when?
+    init                  Create it and unlock it; prints a recovery key ONCE
+                          [--no-recovery] [--ttl 8]
+    unlock                [--ttl 8 (hours, max 168)] [--recovery-key KEY]
+    lock                  Forget the unlock on the server now
 
   ${colors.bright}rates${colors.reset}
     get <crypto>          Get exchange rate
@@ -2451,6 +2467,63 @@ async function handleTokens(subcommand, args, flags) {
 /**
  * Business commands
  */
+async function readVaultPassphrase(confirm = false) {
+  if (process.env.COINPAY_VAULT_PASSPHRASE) return process.env.COINPAY_VAULT_PASSPHRASE;
+  const pass = await promptPassword('Vault passphrase: ');
+  if (confirm) {
+    const again = await promptPassword('Repeat passphrase: ');
+    if (again !== pass) {
+      print.error('Passphrases do not match');
+      process.exit(1);
+    }
+  }
+  return pass;
+}
+
+function vaultTtl(flags) {
+  if (flags.ttl === undefined) return 8;
+  const ttl = Number(flags.ttl);
+  if (!Number.isFinite(ttl) || ttl <= 0 || ttl > 168) usageExit('--ttl is hours, 1 to 168');
+  return ttl;
+}
+
+async function handleVault(subcommand, args, flags) {
+  const client = createClient();
+  switch (subcommand || 'status') {
+    case 'status': {
+      const v = await getVault(client);
+      if (flags.json) return print.json({ exists: v.exists, unlocked: !!v.unlocked, expiresAt: v.expiresAt ?? null });
+      if (!v.exists) return print.info('No secrets vault yet: coinpay vault init');
+      return v.unlocked
+        ? print.success('Vault unlocked until ' + v.expiresAt)
+        : print.info('Vault exists and is locked: coinpay vault unlock');
+    }
+    case 'init': {
+      const passphrase = await readVaultPassphrase(!process.env.COINPAY_VAULT_PASSPHRASE);
+      const out = await initVault(client, { passphrase, withRecoveryKey: !flags['no-recovery'], ttlHours: vaultTtl(flags) });
+      if (flags.json) return print.json(out);
+      print.success('Secrets vault created and unlocked until ' + out.expiresAt);
+      if (out.recoveryKey) {
+        print.warn('Recovery key (shown once; store it somewhere safe, it opens the vault without the passphrase):');
+        console.log(out.recoveryKey);
+      }
+      return;
+    }
+    case 'unlock': {
+      const recoveryKey = flags['recovery-key'];
+      const passphrase = recoveryKey ? undefined : await readVaultPassphrase();
+      const out = await unlockVault(client, { passphrase, recoveryKey, ttlHours: vaultTtl(flags) });
+      return flags.json ? print.json(out) : print.success('Vault unlocked until ' + out.expiresAt);
+    }
+    case 'lock': {
+      await lockVault(client);
+      return print.success('Vault locked');
+    }
+    default:
+      usageExit('coinpay vault <status|init|unlock|lock>');
+  }
+}
+
 async function handleBusiness(subcommand, args, flags) {
   const client = createClient();
   
@@ -2486,6 +2559,13 @@ async function handleBusiness(subcommand, args, flags) {
       break;
     }
 
+    case 'payout-wallet': {
+      if (!args[0]) usageExit('coinpay business payout-wallet <business-id> [--create]');
+      const out = await payoutWallet(client, args[0], { create: !!flags.create });
+      print.json(out.payout_wallet ?? out);
+      break;
+    }
+
     case 'categories': {
       // Fetched rather than hardcoded: the taxonomy is server-side and a stale
       // copy in the CLI is how "Select a valid business category" happens twice.
@@ -4509,7 +4589,8 @@ const SUBCOMMANDS = {
   payment: [['create', 'Create a new payment'], ['get', 'Get payment details <id>'], ['list', 'List payments'], ['qr', 'Get payment QR code <id>']],
   invoice: [['create', 'Create a draft invoice'], ['list', 'List invoices'], ['get', 'Get invoice details <id>'], ['update', 'Update a draft invoice <id>'], ['publish', 'Publish an invoice <id>'], ['send', 'Send an invoice <id>'], ['delete', 'Delete a draft invoice <id>']],
   tokens: [['list', 'List checkout tokens']],
-  business: [['create', 'Create a new business'], ['get', 'Get business details <id>'], ['list', 'List businesses'], ['update', 'Update business <id>']],
+  business: [['create', 'Create a new business'], ['get', 'Get business details <id>'], ['list', 'List businesses'], ['update', 'Update business <id>'], ['payout-wallet', 'Payout wallet <id> [--create]']],
+  vault: [['status', 'Secrets vault status'], ['init', 'Create + unlock the vault'], ['unlock', 'Unlock [--ttl hours]'], ['lock', 'Lock now']],
   rates: [['get', 'Get exchange rate <crypto>'], ['list', 'Get all exchange rates']],
   wallet: [['create', 'Create a new wallet'], ['import', 'Import wallet <mnemonic>'], ['unlock', 'Decrypt wallet and show info'], ['info', 'Show wallet info'], ['addresses', 'List all addresses'], ['derive', 'Derive new address <chain>'], ['derive-missing', 'Derive missing chains'], ['balance', 'Get balance(s) [chain]'], ['send', 'Send a transaction'], ['history', 'Transaction history'], ['backup', 'Export encrypted backup'], ['delete', 'Delete local wallet file']],
   swap: [['coins', 'List supported coins'], ['quote', 'Get swap quote'], ['create', 'Create swap transaction'], ['status', 'Check swap status <swap-id>'], ['history', 'Swap history']],
@@ -4746,22 +4827,28 @@ async function runInteractiveMenu() {
   }
 }
 
-// Headless login: ask the server for a device code, show a URL to approve on any
-// device, and poll until a merchant session token is minted and stored. No
-// password on this machine — works over SSH / on a server.
+// `coinpay login`: OAuth 2.1 as the public client `coinpay-cli`. With a local
+// browser it uses authorization code + PKCE on a loopback redirect; over SSH
+// or with no display (or --device) it uses the device flow (RFC 8628): it
+// prints a code to type at coinpayportal.com/oauth/device on any device.
+// Either way it stores a rotating refresh token in ~/.coinpay.json.
 async function handleLogin(flags = {}) {
-  // OAuth 2.1 (authorization code + PKCE, loopback redirect, rotating refresh)
-  // unless asked for the device flow, which is what works over SSH.
-  if (!flags.device) {
-    const cfg = loadConfig();
-    const { loopbackLogin, toStoredSession } = await import('../src/oauth-login.js');
+  const cfg = loadConfig();
+  const { loopbackLogin, deviceLogin, hasLocalBrowser, toStoredSession } = await import('../src/oauth-login.js');
+  const useDevice = Boolean(flags.device) || (!flags.browser && !hasLocalBrowser());
+
+  const save = async (tokens, how) => {
+    cfg.oauth = toStoredSession(tokens);
+    cfg.jwtToken = cfg.oauth.accessToken;
+    saveConfig(cfg);
+    const me = await fetchMe();
+    print.success(me ? `Logged in as ${meLabel(me)} (${how})` : 'Logged in! Session saved to ' + CONFIG_FILE);
+  };
+
+  if (!useDevice) {
     try {
       const tokens = await loopbackLogin({ apiBase: cfg.baseUrl, log: (line) => console.log(line) });
-      cfg.oauth = toStoredSession(tokens);
-      cfg.jwtToken = cfg.oauth.accessToken;
-      saveConfig(cfg);
-      const me = await fetchMe();
-      print.success(me ? `Logged in as ${meLabel(me)} (OAuth 2.1)` : 'Logged in! Session saved to ' + CONFIG_FILE);
+      await save(tokens, 'OAuth 2.1');
       return;
     } catch (err) {
       print.error(`Browser sign-in failed: ${err.message}`);
@@ -4769,75 +4856,54 @@ async function handleLogin(flags = {}) {
       process.exit(1);
     }
   }
-  const cfg = loadConfig();
-  const base = (cfg.baseUrl || 'https://coinpayportal.com/api').replace(/\/$/, '');
 
-  let start;
   try {
-    const res = await fetch(`${base}/cli-auth/start`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ client_name: hostname() }),
+    const tokens = await deviceLogin({
+      apiBase: cfg.baseUrl,
+      prompt: ({ userCode, verificationUri }) => {
+        // No pre-filled link (verification_uri_complete): typing the code is
+        // what ties the approval to this terminal.
+        console.log('');
+        console.log('  To sign in, open this page on any device where you are signed in to CoinPay:');
+        console.log('');
+        console.log('    ' + colors.cyan + verificationUri + colors.reset);
+        console.log('');
+        console.log('  and enter this code: ' + colors.bright + userCode + colors.reset);
+        console.log('');
+        console.log(colors.yellow + '  Only enter a code your own terminal printed.' + colors.reset);
+        console.log('');
+        print.info('Waiting for approval… (Ctrl-C to cancel)');
+      },
     });
-    if (!res.ok) throw new Error(`server returned ${res.status}`);
-    start = await res.json();
+    await save(tokens, 'OAuth 2.1 device flow');
   } catch (err) {
-    print.error(`Couldn't start login: ${err.message}`);
+    if (err.code === 'access_denied') print.error('Request denied.');
+    else if (err.code === 'expired_token') print.error('The code expired. Run `coinpay login --device` again.');
+    else print.error(`Couldn't sign in: ${err.message}`);
     process.exit(1);
   }
-
-  // G-1.2-10: there is no pre-filled approval link any more. A link that filled
-  // in the code turned a phishing message into one-click account takeover —
-  // anyone could start a device authorization and send the resulting link to a
-  // signed-in merchant. Entering the code by hand is what ties the approval to
-  // a terminal the person is actually sitting at.
-  print.info('');
-  console.log('  To log in, open this URL on any device (e.g. your desktop):');
-  console.log('');
-  console.log('    ' + colors.cyan + start.verification_uri + colors.reset);
-  console.log('');
-  console.log('  and enter this code: ' + colors.bright + start.user_code + colors.reset);
-  console.log('');
-  console.log(colors.yellow + '  Only enter a code your own terminal printed.' + colors.reset);
-  console.log('');
-  print.info('Waiting for approval… (Ctrl-C to cancel)');
-
-  const deadline = Date.now() + (start.expires_in || 600) * 1000;
-  const intervalMs = Math.max(1, start.interval || 5) * 1000;
-  while (Date.now() < deadline) {
-    await new Promise((r) => setTimeout(r, intervalMs));
-    let data = {};
-    try {
-      const res = await fetch(`${base}/cli-auth/poll`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ device_code: start.device_code }),
-      });
-      if (res.status === 202) continue; // authorization_pending
-      data = await res.json().catch(() => ({}));
-    } catch {
-      continue; // transient network error — keep polling
-    }
-    if (data.status === 'complete' && data.token) {
-      cfg.jwtToken = data.token;
-      saveConfig(cfg);
-      const me = await fetchMe();
-      print.success(me ? `Logged in as ${meLabel(me)}` : 'Logged in! Session saved to ' + CONFIG_FILE);
-      return;
-    }
-    if (data.status === 'denied') { print.error('Request denied.'); process.exit(1); }
-    if (data.status === 'expired') { print.error('Login request expired — run `coinpay login` again.'); process.exit(1); }
-  }
-  print.error('Timed out waiting for approval.');
-  process.exit(1);
 }
 
-function handleLogout() {
+// `coinpay logout`: revoke the grant at CoinPay (RFC 7009; revoking the
+// refresh token revokes its access tokens too), then forget it locally.
+async function handleLogout() {
   const cfg = loadConfig();
+  if (cfg.oauth) {
+    const { revokeToken, CLI_CLIENT_ID } = await import('../src/oauth-login.js');
+    const clientId = cfg.oauth.clientId || CLI_CLIENT_ID;
+    let ok = false;
+    if (cfg.oauth.refreshToken) {
+      ok = await revokeToken({ apiBase: cfg.baseUrl, token: cfg.oauth.refreshToken, tokenTypeHint: 'refresh_token', clientId });
+    }
+    if (cfg.oauth.accessToken) {
+      ok = (await revokeToken({ apiBase: cfg.baseUrl, token: cfg.oauth.accessToken, tokenTypeHint: 'access_token', clientId })) || ok;
+    }
+    if (!ok) print.warn('Could not reach CoinPay to revoke the session; it is removed locally and expires on its own.');
+  }
   delete cfg.jwtToken;
   delete cfg.oauth;
   saveConfig(cfg);
-  print.success('Logged out — session removed from ' + CONFIG_FILE);
+  print.success('Logged out — session revoked and removed from ' + CONFIG_FILE);
 }
 
 // Fetch the signed-in merchant (via the stored session token), or null if not
@@ -5505,7 +5571,7 @@ async function handleLightning(subcommand, args, flags) {
         break;
 
       case 'logout':
-        handleLogout();
+        await handleLogout();
         break;
 
       case 'whoami':
@@ -5563,6 +5629,10 @@ async function handleLightning(subcommand, args, flags) {
       case 'business':
         await handleBusiness(subcommand, args, flags);
         break;
+
+      case 'vault':
+        await handleVault(subcommand, args, flags);
+        break;
         
       case 'rates':
         await handleRates(subcommand, args, flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "CoinPay SDK & CLI — Accept cryptocurrency and card payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet, swap and a live finances dashboard",
   "type": "module",
   "main": "./src/index.js",
@@ -33,6 +33,10 @@
       "import": "./src/wallet.js",
       "types": "./src/wallet.d.ts"
     },
+    "./agents": {
+      "import": "./src/agents.js",
+      "types": "./src/agents.d.ts"
+    },
     "./swap": {
       "import": "./src/swap.js",
       "types": "./src/swap.d.ts"

package/src/agents.d.ts

@@ -0,0 +1,19 @@
+import type { CoinPayClient } from './client.js';
+import type { AgentWalletLimits } from './client.js';
+
+export interface AgentWalletInput extends AgentWalletLimits {
+  name: string;
+  address: string;
+  network?: string;
+  status?: 'active' | 'paused' | 'revoked';
+}
+
+export declare class AgentWalletClient {
+  constructor(client: CoinPayClient);
+  list(): Promise<Record<string, unknown>>;
+  create(input: AgentWalletInput): Promise<Record<string, unknown>>;
+  update(id: string, patch: Partial<AgentWalletInput>): Promise<Record<string, unknown>>;
+  pause(id: string): Promise<Record<string, unknown>>;
+  resume(id: string): Promise<Record<string, unknown>>;
+  revoke(id: string): Promise<Record<string, unknown>>;
+}

package/src/agents.js

@@ -0,0 +1,11 @@
+/** Mercury-style capped agent wallets. */
+export class AgentWalletClient {
+  #client;
+  constructor(client) { this.#client = client; }
+  list() { return this.#client.request('/v1/agents'); }
+  create(input) { return this.#client.request('/v1/agents', { method: 'POST', body: JSON.stringify(input) }); }
+  update(id, patch) { return this.#client.request(`/v1/agents/${encodeURIComponent(id)}`, { method: 'PATCH', body: JSON.stringify(patch) }); }
+  pause(id) { return this.update(id, { status: 'paused' }); }
+  resume(id) { return this.update(id, { status: 'active' }); }
+  revoke(id) { return this.#client.request(`/v1/agents/${encodeURIComponent(id)}`, { method: 'DELETE' }); }
+}

package/src/client.d.ts

@@ -13,6 +13,17 @@ export interface CoinPayClientOptions {
   timeout?: number;
 }
 
+export interface AgentWalletLimits {
+  perPaymentUsd?: number | null;
+  hourlyLimitUsd?: number | null;
+  dailyLimitUsd?: number | null;
+  weeklyLimitUsd?: number | null;
+  monthlyLimitUsd?: number | null;
+  quarterlyLimitUsd?: number | null;
+  yearlyLimitUsd?: number | null;
+  totalLimitUsd?: number | null;
+}
+
 /** Parameters for creating a payment */
 export interface PaymentParams {
   /** Business ID from your CoinPay dashboard */

package/src/client.js

@@ -4,6 +4,7 @@
  */
 
 import { LightningClient } from './lightning.js';
+import { AgentWalletClient } from './agents.js';
 
 const DEFAULT_BASE_URL = 'https://coinpayportal.com/api';
 
@@ -29,6 +30,8 @@ export class CoinPayClient {
 
     /** @type {LightningClient} Lightning/BOLT12 operations */
     this.lightning = new LightningClient(this);
+    /** Capped wallets for bots and agent fleets. */
+    this.agents = new AgentWalletClient(this);
   }
 
   /** The API base this client talks to (read-only). */

package/src/index.d.ts

@@ -7,6 +7,8 @@
 
 // Client exports
 export { CoinPayClient } from './client.js';
+export { AgentWalletClient } from './agents.js';
+export type { AgentWalletInput } from './agents.js';
 export type { 
   CoinPayClientOptions, 
   PaymentParams, 

package/src/index.js

@@ -37,6 +37,7 @@
  */
 
 import { CoinPayClient } from './client.js';
+import { AgentWalletClient } from './agents.js';
 import {
   createPayment,
   getPayment,
@@ -262,6 +263,7 @@ import {
 } from './finances.js';
 
 export {
+  AgentWalletClient,
   // Client
   CoinPayClient,
   

package/src/oauth-login.js

@@ -147,6 +147,99 @@ export async function loopbackLogin({ apiBase, open = openInBrowser, log = () =>
   }
 }
 
+export const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+
+/**
+ * Is there a browser this process can open? Not over SSH, not on a Linux box
+ * with no display. Used to pick loopback PKCE vs the device flow.
+ */
+export function hasLocalBrowser(env = process.env, platform = process.platform) {
+  if (env.SSH_CONNECTION || env.SSH_TTY || env.SSH_CLIENT) return false;
+  if (env.COINPAY_NO_BROWSER) return false;
+  if (platform === 'darwin' || platform === 'win32') return true;
+  return Boolean(env.DISPLAY || env.WAYLAND_DISPLAY || env.BROWSER);
+}
+
+/**
+ * OAuth 2.0 Device Authorization Grant (RFC 8628). Starts at
+ * /api/oauth/device_authorization, shows the user_code via `prompt`, and polls
+ * /api/oauth/token honouring interval and slow_down. Resolves with the token
+ * response; rejects with err.code access_denied / expired_token.
+ */
+export async function deviceLogin({
+  apiBase,
+  clientId = CLI_CLIENT_ID,
+  scope = CLI_SCOPE,
+  prompt = () => {},
+  fetchImpl = fetch,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+} = {}) {
+  const origin = siteOrigin(apiBase);
+  const res = await fetchImpl(new URL('/api/oauth/device_authorization', origin), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams({ client_id: clientId, scope }).toString(),
+  });
+  const start = await res.json().catch(() => ({}));
+  if (!res.ok || !start.device_code) {
+    const err = new Error(start.error_description || start.error || `device authorization answered ${res.status}`);
+    err.code = start.error || 'device_error';
+    throw err;
+  }
+  prompt({ userCode: start.user_code, verificationUri: start.verification_uri, expiresIn: start.expires_in });
+
+  let interval = Math.max(1, Number(start.interval) || 5);
+  const deadline = now() + (Number(start.expires_in) || 600) * 1000;
+  while (now() < deadline) {
+    await sleep(interval * 1000);
+    let data = {};
+    let status = 0;
+    try {
+      const r = await fetchImpl(new URL('/api/oauth/token', origin), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body: new URLSearchParams({ grant_type: DEVICE_GRANT, device_code: start.device_code, client_id: clientId }).toString(),
+      });
+      status = r.status;
+      data = await r.json().catch(() => ({}));
+    } catch {
+      continue; // network blip: keep polling
+    }
+    if (status === 200 && data.access_token) return data;
+    if (data.error === 'authorization_pending') continue;
+    if (data.error === 'slow_down') {
+      interval += 5;
+      continue;
+    }
+    const err = new Error(
+      data.error === 'access_denied' ? 'access denied' : data.error === 'expired_token' ? 'the code expired' : data.error_description || data.error || `token endpoint answered ${status}`
+    );
+    err.code = data.error || 'token_error';
+    throw err;
+  }
+  const err = new Error('the code expired');
+  err.code = 'expired_token';
+  throw err;
+}
+
+/** RFC 7009: revoke a token at CoinPay. Best effort; resolves true on 200. */
+export async function revokeToken({ apiBase, token, tokenTypeHint, clientId = CLI_CLIENT_ID, fetchImpl = fetch }) {
+  if (!token) return false;
+  try {
+    const params = { token, client_id: clientId };
+    if (tokenTypeHint) params.token_type_hint = tokenTypeHint;
+    const res = await fetchImpl(new URL('/api/oauth/revoke', siteOrigin(apiBase)), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams(params).toString(),
+    });
+    return res.status === 200;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Before any command: if the stored OAuth access token is within a minute of
  * expiring, rotate it. Mutates and saves `cfg`. Returns false when the

package/src/secrets-vault.js

@@ -0,0 +1,234 @@
+/**
+ * Merchant secrets vault, from the CLI.
+ *
+ * The same scheme as the dashboard's /dashboard/vault (src/lib/vault/sealed-vault.ts,
+ * WebCrypto only, so this is a line-for-line port): the passphrase stays on this
+ * machine. Create builds the vault record here and sends only the record; unlock
+ * derives the data key (DEK) here and sends only the DEK, which the server checks
+ * against key_check and keeps in memory for a TTL (default 8 h, max 168 h).
+ *
+ *   passphrase --PBKDF2-SHA256 600k--> ikm --HKDF--> KEK
+ *   KEK wraps a random 32-byte DEK                 -> wrapped_dek
+ *   recovery key --HKDF--> RKEK wraps the same DEK -> recovery_wrapped_dek
+ *   DEK seals a fixed string                       -> key_check
+ *   DEK seals a P-256 private key (pkcs8)          -> private_key_sealed
+ *
+ * The API refuses apps signed in with CoinPay (OAuth), so these calls need a
+ * business API key (COINPAY_API_KEY or `coinpay config set-key`); the vault they
+ * reach is the key owner's.
+ */
+
+export const PBKDF2_ITERATIONS = 600_000;
+export const MIN_PASSPHRASE_LENGTH = 10;
+const KEY_CHECK_TEXT = 'coinpay-vault-key-check-v1';
+const IV_BYTES = 12;
+const B32 = 'ABCDEFGHJKMNPQRSTVWXYZ0123456789';
+
+const enc = new TextEncoder();
+
+function subtle() {
+  const c = globalThis.crypto;
+  if (!c?.subtle) throw new Error('WebCrypto (crypto.subtle) is not available: use Node 20 or newer');
+  return c.subtle;
+}
+
+const b64 = (bytes) => Buffer.from(bytes).toString('base64');
+const unb64 = (s) => new Uint8Array(Buffer.from(s, 'base64'));
+
+function randomBytes(n) {
+  const out = new Uint8Array(n);
+  globalThis.crypto.getRandomValues(out);
+  return out;
+}
+
+function vaultAad(subjectType, subjectId, field) {
+  if (!subjectId) throw new Error('subjectId required');
+  return enc.encode(`coinpay:vault:${subjectType}:${subjectId}:${field}`);
+}
+
+async function gcmEncrypt(key, plaintext, ad) {
+  const iv = randomBytes(IV_BYTES);
+  const ct = new Uint8Array(await subtle().encrypt({ name: 'AES-GCM', iv, additionalData: ad }, key, plaintext));
+  return { ct: b64(ct), iv: b64(iv) };
+}
+
+async function gcmDecrypt(key, blob, ad) {
+  return new Uint8Array(
+    await subtle().decrypt({ name: 'AES-GCM', iv: unb64(blob.iv), additionalData: ad }, key, unb64(blob.ct)),
+  );
+}
+
+async function aesKey(raw) {
+  return subtle().importKey('raw', raw, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+
+async function hkdfAesKey(ikm, salt, info) {
+  const base = await subtle().importKey('raw', ikm, 'HKDF', false, ['deriveKey']);
+  return subtle().deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt, info: enc.encode(info) },
+    base,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+async function deriveKek(passphrase, kdf) {
+  if (kdf.alg !== 'PBKDF2-SHA256') throw new Error(`unsupported kdf ${kdf.alg}`);
+  const salt = unb64(kdf.salt);
+  const pw = await subtle().importKey('raw', enc.encode(passphrase.normalize('NFKC')), 'PBKDF2', false, ['deriveBits']);
+  const bits = new Uint8Array(
+    await subtle().deriveBits({ name: 'PBKDF2', hash: 'SHA-256', salt, iterations: kdf.iterations }, pw, 256),
+  );
+  try {
+    return await hkdfAesKey(bits, salt, 'coinpay/vault/kek/v1');
+  } finally {
+    bits.fill(0);
+  }
+}
+
+export function encodeRecoveryKey(raw) {
+  let bits = 0;
+  let value = 0;
+  let out = '';
+  for (const b of raw) {
+    value = ((value << 8) | b) & 0xffff;
+    bits += 8;
+    while (bits >= 5) {
+      out += B32[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += B32[(value << (5 - bits)) & 31];
+  return out.match(/.{1,4}/g).join('-');
+}
+
+export function decodeRecoveryKey(text) {
+  const clean = text.toUpperCase().replace(/[^A-Z0-9]/g, '');
+  let bits = 0;
+  let value = 0;
+  const out = [];
+  for (const ch of clean) {
+    const idx = B32.indexOf(ch);
+    if (idx < 0) throw new Error('invalid recovery key');
+    value = ((value << 5) | idx) & 0xffff;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  if (out.length !== 32) throw new Error('invalid recovery key');
+  return new Uint8Array(out);
+}
+
+async function deriveRecoveryKek(recoveryKey) {
+  const raw = decodeRecoveryKey(recoveryKey);
+  try {
+    return await hkdfAesKey(raw, enc.encode('coinpay/vault/recovery'), 'coinpay/vault/recovery-kek/v1');
+  } finally {
+    raw.fill(0);
+  }
+}
+
+/** Build a vault record. Returns { record, dek, recoveryKey }; only `record` goes to the server. */
+export async function createVaultRecord(passphrase, subjectId, { subjectType = 'merchant', withRecoveryKey = true } = {}) {
+  if (typeof passphrase !== 'string' || passphrase.length < MIN_PASSPHRASE_LENGTH) {
+    throw new Error(`passphrase must be at least ${MIN_PASSPHRASE_LENGTH} characters`);
+  }
+  const kdf = { alg: 'PBKDF2-SHA256', iterations: PBKDF2_ITERATIONS, salt: b64(randomBytes(16)) };
+  const kek = await deriveKek(passphrase, kdf);
+  const dek = randomBytes(32);
+  const dekKey = await aesKey(dek);
+  const pair = await subtle().generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+  const publicRaw = new Uint8Array(await subtle().exportKey('raw', pair.publicKey));
+  const pkcs8 = new Uint8Array(await subtle().exportKey('pkcs8', pair.privateKey));
+
+  let recoveryKey = null;
+  let recoveryWrapped = null;
+  if (withRecoveryKey) {
+    const raw = randomBytes(32);
+    recoveryKey = encodeRecoveryKey(raw);
+    raw.fill(0);
+    recoveryWrapped = await gcmEncrypt(await deriveRecoveryKek(recoveryKey), dek, vaultAad(subjectType, subjectId, 'recovery_dek'));
+  }
+  const record = {
+    v: 1,
+    kdf,
+    wrapped_dek: await gcmEncrypt(kek, dek, vaultAad(subjectType, subjectId, 'dek')),
+    recovery_wrapped_dek: recoveryWrapped,
+    key_check: await gcmEncrypt(dekKey, enc.encode(KEY_CHECK_TEXT), vaultAad(subjectType, subjectId, 'key_check')),
+    public_key: b64(publicRaw),
+    private_key_sealed: await gcmEncrypt(dekKey, pkcs8, vaultAad(subjectType, subjectId, 'private_key')),
+  };
+  pkcs8.fill(0);
+  return { record, dek, recoveryKey };
+}
+
+/** Passphrase (or recovery key) -> DEK, checked against key_check before anything is sent. */
+export async function unwrapDek(record, subjectId, { passphrase, recoveryKey, subjectType = 'merchant' } = {}) {
+  let dek;
+  if (recoveryKey) {
+    if (!record.recovery_wrapped_dek) throw new Error('This vault has no recovery key');
+    try {
+      dek = await gcmDecrypt(await deriveRecoveryKek(recoveryKey), record.recovery_wrapped_dek, vaultAad(subjectType, subjectId, 'recovery_dek'));
+    } catch {
+      throw new Error('Wrong recovery key');
+    }
+  } else {
+    try {
+      dek = await gcmDecrypt(await deriveKek(passphrase ?? '', record.kdf), record.wrapped_dek, vaultAad(subjectType, subjectId, 'dek'));
+    } catch {
+      throw new Error('Wrong passphrase');
+    }
+  }
+  const check = await gcmDecrypt(await aesKey(dek), record.key_check, vaultAad(subjectType, subjectId, 'key_check'));
+  if (new TextDecoder().decode(check) !== KEY_CHECK_TEXT) throw new Error('Vault key check failed');
+  return dek;
+}
+
+/** GET /vault: { subject_id, exists, record, unlocked, expiresAt }. */
+export function getVault(client) {
+  return client.request('/vault', { headers: { 'Cache-Control': 'no-store' } });
+}
+
+/** Create the vault and unlock it right away. Returns { recoveryKey, migrated, expiresAt }. */
+export async function initVault(client, { passphrase, withRecoveryKey = true, ttlHours = 8 } = {}) {
+  const status = await getVault(client);
+  if (status.exists) throw new Error('This account already has a secrets vault: use `coinpay vault unlock`');
+  const { record, dek, recoveryKey } = await createVaultRecord(passphrase, status.subject_id, { withRecoveryKey });
+  const created = await client.request('/vault', { method: 'POST', body: JSON.stringify({ record }) });
+  try {
+    const unlocked = await client.request('/vault/unlock', {
+      method: 'POST',
+      body: JSON.stringify({ data_key: b64(dek), ttl_hours: ttlHours }),
+    });
+    return { recoveryKey, migrated: created.migrated ?? null, expiresAt: unlocked.expiresAt };
+  } finally {
+    dek.fill(0);
+  }
+}
+
+/** Unlock with the passphrase or recovery key for ttlHours (1..168). */
+export async function unlockVault(client, { passphrase, recoveryKey, ttlHours = 8 } = {}) {
+  const status = await getVault(client);
+  if (!status.exists) throw new Error('No secrets vault yet: run `coinpay vault init`');
+  const dek = await unwrapDek(status.record, status.subject_id, { passphrase, recoveryKey });
+  try {
+    return await client.request('/vault/unlock', {
+      method: 'POST',
+      body: JSON.stringify({ data_key: b64(dek), ttl_hours: ttlHours }),
+    });
+  } finally {
+    dek.fill(0);
+  }
+}
+
+export function lockVault(client) {
+  return client.request('/vault/lock', { method: 'POST', body: '{}' });
+}
+
+/** GET (create=false) or POST (create=true) /businesses/:id/payout-wallet. */
+export function payoutWallet(client, businessId, { create = false } = {}) {
+  return client.request(`/businesses/${encodeURIComponent(businessId)}/payout-wallet`, create ? { method: 'POST', body: '{}' } : {});
+}