@profullstack/coinpay 0.29.0 → 0.30.0

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',
@@ -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']],
@@ -5548,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.29.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/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: '{}' } : {});
+}