bsv-pay-cli 0.2.0

package/dist/commands/init.js

@@ -0,0 +1,188 @@
+import { Mnemonic, PrivateKey } from '@bsv/sdk';
+import chalk from 'chalk';
+import { CliError, EXIT, usageError } from '../errors.js';
+import { walletPath } from '../paths.js';
+import { ask, askHidden, confirm, isInteractive, readStdinLine } from '../prompt.js';
+import { connectBrc100 } from '../wallet/brc100.js';
+import { buildBrc100WalletFile, buildWalletFile, walletExists, writeWalletFile, } from '../wallet/wallet.js';
+import { Wallet } from '../wallet/wallet.js';
+function stderr(text) {
+    process.stderr.write(text + '\n');
+}
+async function obtainNewSeed() {
+    const mnemonic = Mnemonic.fromRandom();
+    const words = mnemonic.toString().split(' ');
+    stderr('');
+    stderr(chalk.bold('Your new wallet seed phrase — write it down on paper, in order:'));
+    stderr('');
+    words.forEach((w, i) => stderr(`  ${String(i + 1).padStart(2)}. ${w}`));
+    stderr('');
+    stderr(chalk.yellow('Anyone with these words can spend your funds. This is the ONLY time they are shown.'));
+    stderr('');
+    if (isInteractive()) {
+        const checkIndex = Math.floor(Math.random() * words.length);
+        for (let attempt = 1;; attempt++) {
+            const answer = await ask(`Confirm you wrote it down — type word #${checkIndex + 1}: `);
+            if (answer.toLowerCase() === words[checkIndex])
+                break;
+            if (attempt >= 3) {
+                throw usageError('seed_confirmation_failed', 'Seed confirmation failed 3 times. No wallet was created; run init again.');
+            }
+            stderr(chalk.red('That does not match. Check your written copy and try again.'));
+        }
+    }
+    else {
+        stderr(chalk.yellow('Non-interactive run: seed confirmation skipped. The phrase above was printed to stderr — store it now.'));
+    }
+    return { type: 'mnemonic', value: mnemonic.toString() };
+}
+async function obtainImportedSeed() {
+    const phrase = isInteractive()
+        ? await ask('Enter your BIP-39 seed phrase: ')
+        : await readStdinLine();
+    const normalized = phrase.trim().toLowerCase().split(/\s+/).join(' ');
+    if (!Mnemonic.isValid(normalized)) {
+        throw usageError('invalid_seed_phrase', 'That is not a valid BIP-39 seed phrase (checksum failed). Check the words and their order.');
+    }
+    return { type: 'mnemonic', value: normalized };
+}
+async function obtainImportedWif() {
+    stderr(chalk.yellow('WARNING: a raw WIF key gives a single-address wallet with no HD derivation.'));
+    stderr(chalk.yellow('Every payment reuses one address, which is bad for privacy. Prefer a seed phrase.'));
+    if (isInteractive() && !(await confirm('Continue with WIF import?'))) {
+        throw usageError('aborted', 'WIF import cancelled.');
+    }
+    const wif = isInteractive() ? await ask('Enter WIF private key: ') : await readStdinLine();
+    try {
+        PrivateKey.fromWif(wif.trim());
+    }
+    catch {
+        throw usageError('invalid_wif', 'That is not a valid WIF private key (checksum failed).');
+    }
+    return { type: 'wif', value: wif.trim() };
+}
+/** Resolve the encryption passphrase for a new wallet, or null for opt-in unencrypted mode. */
+async function obtainNewPassphrase(encrypt) {
+    if (!encrypt) {
+        stderr(chalk.yellow('WARNING: --no-encrypt stores the seed in PLAINTEXT on disk.'));
+        if (isInteractive() && !(await confirm('Store the wallet unencrypted?'))) {
+            throw usageError('aborted', 'Init cancelled. Re-run without --no-encrypt to use a passphrase.');
+        }
+        return null;
+    }
+    const env = process.env.BSV_PAY_PASSPHRASE;
+    if (env !== undefined) {
+        if (env === '')
+            throw usageError('empty_passphrase', 'BSV_PAY_PASSPHRASE is set but empty. Use a real passphrase or pass --no-encrypt explicitly.');
+        return env;
+    }
+    if (!isInteractive()) {
+        throw new CliError(EXIT.WALLET_LOCKED, 'passphrase_required', 'No terminal to prompt for a passphrase. Set BSV_PAY_PASSPHRASE, or pass --no-encrypt to opt out of encryption.');
+    }
+    for (;;) {
+        const first = await askHidden('Choose a wallet passphrase: ');
+        if (first === '') {
+            stderr(chalk.red('Passphrase cannot be empty (use --no-encrypt to explicitly opt out).'));
+            continue;
+        }
+        const second = await askHidden('Repeat passphrase: ');
+        if (first === second)
+            return first;
+        stderr(chalk.red('Passphrases do not match. Try again.'));
+    }
+}
+export async function cmdInit(ctx, opts, brc100Connect) {
+    if (opts.brc100) {
+        throw usageError('brc100_not_supported', 'BRC-100 custody is EXPERIMENTAL. Re-run with --experimental-brc100 to connect an ' +
+            'external wallet app (spending works; receiving still needs the wallet app itself — ' +
+            'see the README), or use a local wallet: "bsv-pay init".');
+    }
+    if (opts.experimentalBrc100 && (opts.importSeed || opts.importWif)) {
+        throw usageError('conflicting_flags', '--experimental-brc100 delegates custody to the external wallet; there is no seed or WIF to import.');
+    }
+    if (opts.importSeed && opts.importWif) {
+        throw usageError('conflicting_flags', 'Pass either --import-seed or --import-wif, not both.');
+    }
+    if (walletExists(ctx.network) && !opts.force) {
+        throw usageError('wallet_exists', `A ${ctx.network === 'test' ? 'testnet ' : ''}wallet already exists at ${walletPath(ctx.network)}. ` +
+            'Re-run with --force to overwrite it (this DESTROYS the old wallet unless you have its seed).');
+    }
+    if (opts.experimentalBrc100) {
+        await initBrc100(ctx, brc100Connect);
+        return;
+    }
+    const secret = opts.importSeed
+        ? await obtainImportedSeed()
+        : opts.importWif
+            ? await obtainImportedWif()
+            : await obtainNewSeed();
+    const passphrase = await obtainNewPassphrase(opts.encrypt !== false);
+    const file = buildWalletFile(ctx.network, secret, passphrase);
+    writeWalletFile(ctx.network, file);
+    // Derive and record the first receive address. Unlock reads the file we
+    // just wrote; passphrase comes from env or the in-memory value.
+    let firstAddress;
+    if (passphrase !== null && process.env.BSV_PAY_PASSPHRASE === undefined) {
+        process.env.BSV_PAY_PASSPHRASE = passphrase; // current process only
+        try {
+            const wallet = await Wallet.unlock(ctx.network);
+            firstAddress = wallet.issueAddress('receive').address;
+        }
+        finally {
+            delete process.env.BSV_PAY_PASSPHRASE;
+        }
+    }
+    else {
+        const wallet = await Wallet.unlock(ctx.network);
+        firstAddress = wallet.issueAddress('receive').address;
+    }
+    ctx.out.info('');
+    ctx.out.info(chalk.green('Wallet created.'));
+    ctx.out.info(`  Network:        ${ctx.network === 'test' ? 'testnet' : 'mainnet'}`);
+    ctx.out.info(`  Encrypted:      ${passphrase !== null ? 'yes (argon2id + AES-256-GCM)' : chalk.red('NO — plaintext seed')}`);
+    ctx.out.info(`  First address:  ${firstAddress}`);
+    ctx.out.info(`  State dir:      ${walletPath(ctx.network)}`);
+    ctx.out.info('');
+    ctx.out.info('Next: fund it, then try "bsv-pay balance" or "bsv-pay request 5000sats".');
+    ctx.out.result({
+        ok: true,
+        network: ctx.network,
+        encrypted: passphrase !== null,
+        type: secret.type,
+        address: firstAddress,
+    });
+}
+/**
+ * EXPERIMENTAL BRC-100 custody: connect the external wallet app, verify the
+ * network, and write a wallet file that records the delegation — no seed, no
+ * passphrase, nothing secret stored locally. Spending goes through the same
+ * policy gate as every wallet; receiving stays in the wallet app (documented
+ * limitation, see README).
+ */
+async function initBrc100(ctx, connectOpts) {
+    stderr(chalk.yellow('BRC-100 custody is EXPERIMENTAL. Keys stay in your wallet app;'));
+    stderr(chalk.yellow('bsv-pay will ask it to pay, and your policy.toml still governs every spend.'));
+    stderr('Connecting to the wallet app... (approve the connection if it prompts)');
+    const wallet = await connectBrc100(ctx.network, connectOpts);
+    await wallet.waitForAuthentication();
+    const identityKey = await wallet.identityKey();
+    const version = await wallet.version();
+    writeWalletFile(ctx.network, buildBrc100WalletFile(ctx.network, wallet.url));
+    ctx.out.info('');
+    ctx.out.info(chalk.green('Wallet connected (BRC-100, experimental).'));
+    ctx.out.info(`  Network:        ${ctx.network === 'test' ? 'testnet' : 'mainnet'}`);
+    ctx.out.info(`  Custody:        external wallet app (${version}) at ${wallet.url}`);
+    ctx.out.info(`  Identity key:   ${identityKey}`);
+    ctx.out.info(`  State dir:      ${walletPath(ctx.network)}`);
+    ctx.out.info('');
+    ctx.out.info('Spending (send/fetch/MCP pay) works now, governed by policy.toml.');
+    ctx.out.info('Receiving still happens in the wallet app itself — see the README.');
+    ctx.out.result({
+        ok: true,
+        network: ctx.network,
+        backend: 'brc100',
+        type: 'brc100',
+        identity_key: identityKey,
+        wallet_url: wallet.url,
+    });
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,13 @@
+import type { Ctx } from '../context.js';
+/**
+ * `bsv-pay mcp` — serve the MCP tools over stdio. stdout belongs to the
+ * MCP protocol from here on (the strictest case of invariant 5); every
+ * human-facing line goes to stderr.
+ *
+ * The wallet unlocks ONCE, at startup, before the transport opens: the
+ * passphrase comes from BSV_PAY_PASSPHRASE or an interactive TTY prompt,
+ * and there is deliberately no tool to unlock, lock, or re-key — the agent
+ * connected to this server never holds a secret. With neither env nor TTY
+ * the server refuses to start (exit 7) rather than serve a locked wallet.
+ */
+export declare function cmdMcp(ctx: Ctx): Promise<void>;

package/dist/commands/mcp.js

@@ -0,0 +1,32 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { openWallet } from '../core/wallet.js';
+import { buildMcpServer } from '../mcp/server.js';
+import { obtainPassphrase } from '../wallet/wallet.js';
+/**
+ * `bsv-pay mcp` — serve the MCP tools over stdio. stdout belongs to the
+ * MCP protocol from here on (the strictest case of invariant 5); every
+ * human-facing line goes to stderr.
+ *
+ * The wallet unlocks ONCE, at startup, before the transport opens: the
+ * passphrase comes from BSV_PAY_PASSPHRASE or an interactive TTY prompt,
+ * and there is deliberately no tool to unlock, lock, or re-key — the agent
+ * connected to this server never holds a secret. With neither env nor TTY
+ * the server refuses to start (exit 7) rather than serve a locked wallet.
+ */
+export async function cmdMcp(ctx) {
+    const wallet = await openWallet({
+        network: ctx.network,
+        config: ctx.config,
+        passphrase: () => obtainPassphrase(),
+        onWarning: (text) => process.stderr.write(text + '\n'),
+    });
+    const server = buildMcpServer({ network: ctx.network, wallet, config: ctx.config });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`bsv-pay MCP server ready on ${ctx.network === 'test' ? 'testnet' : 'mainnet'} (stdio). ` +
+        'Policy is enforced in core; edit policy.toml and restart to change limits.\n');
+    // Serve until the client closes the transport (stdin EOF).
+    await new Promise((resolve) => {
+        server.server.onclose = resolve;
+    });
+}

package/dist/commands/policy.d.ts

@@ -0,0 +1,8 @@
+import type { Ctx } from '../context.js';
+export declare function cmdPolicyShow(ctx: Ctx): void;
+/**
+ * Dry-run a policy decision: exit 0 = would allow, 8 = would deny,
+ * 9 = would queue. Evaluates as an unattended spend (no soft-limit
+ * confirmation) and persists nothing — what-ifs are not decisions.
+ */
+export declare function cmdPolicyTest(ctx: Ctx, address: string, amountArg: string): void;

package/dist/commands/policy.js

@@ -0,0 +1,101 @@
+import chalk from 'chalk';
+import { validateAddress } from '../address.js';
+import { CliError, EXIT } from '../errors.js';
+import { policyPath } from '../paths.js';
+import { approvalSecretConfigured, listPendingApprovals } from '../policy/approvals.js';
+import { readUsage } from '../policy/budget.js';
+import { evaluateSpend } from '../policy/engine.js';
+import { loadPolicy } from '../policy/policy.js';
+import { formatSats, parseAmount } from '../units.js';
+export function cmdPolicyShow(ctx) {
+    const policy = loadPolicy(ctx.network, ctx.config);
+    const usage = readUsage(ctx.network);
+    const pending = listPendingApprovals(ctx.network);
+    const secretConfigured = approvalSecretConfigured();
+    const fromFile = policy.source === 'file';
+    ctx.out.info(chalk.bold(`Policy (${ctx.network === 'test' ? 'testnet' : 'mainnet'}) — ${fromFile ? policyPath() : 'defaults (no policy.toml)'}`));
+    if (policy.perTxLimitSats !== undefined) {
+        ctx.out.info(`  Per-tx limit:        ${formatSats(policy.perTxLimitSats)} (hard — no override)`);
+    }
+    else if (policy.softPerTxLimitSats !== undefined) {
+        ctx.out.info(`  Per-tx limit:        ${formatSats(policy.softPerTxLimitSats)} (soft — interactive confirm / --allow-large)`);
+    }
+    if (policy.dailyBudgetSats !== undefined) {
+        ctx.out.info(`  Daily budget:        ${formatSats(policy.dailyBudgetSats)} (spent ${formatSats(usage.dailySpentSats)} in 24h, ${formatSats(Math.max(0, policy.dailyBudgetSats - usage.dailySpentSats))} left)`);
+    }
+    if (policy.sessionBudgetSats !== undefined) {
+        ctx.out.info(`  Session budget:      ${formatSats(policy.sessionBudgetSats)} (this process has spent ${formatSats(usage.sessionSpentSats)})`);
+    }
+    if (policy.rateLimitPerMinute !== undefined || policy.rateLimitPerHour !== undefined) {
+        ctx.out.info(`  Rate limit:          ${policy.rateLimitPerMinute ?? '∞'}/min, ${policy.rateLimitPerHour ?? '∞'}/hour (sent ${usage.sendsLastMinute} last min, ${usage.sendsLastHour} last hour)`);
+    }
+    if (policy.approvalThresholdSats !== undefined) {
+        ctx.out.info(`  Approval threshold:  ${formatSats(policy.approvalThresholdSats)} (secret ${secretConfigured ? 'configured' : chalk.red('NOT SET — queued payments cannot be approved')})`);
+    }
+    if (policy.allowlist.length > 0)
+        ctx.out.info(`  Allowlist:           ${policy.allowlist.length} address(es)`);
+    if (policy.denylist.length > 0)
+        ctx.out.info(`  Denylist:            ${policy.denylist.length} address(es)`);
+    ctx.out.info(`  Pending approvals:   ${pending.length}`);
+    if (!fromFile) {
+        ctx.out.info('');
+        ctx.out.info(`No policy.toml — only the legacy spend limit applies. Create ${policyPath()} to govern agents.`);
+    }
+    if (policy.approvalThresholdSats !== undefined && !secretConfigured) {
+        process.stderr.write(chalk.yellow('WARNING: approval_threshold_sats is set but no approval secret exists. Run "bsv-pay approvals set-secret" or queued payments can never be approved.') + '\n');
+    }
+    ctx.out.result({
+        ok: true,
+        source: policy.source,
+        network: ctx.network,
+        rules: {
+            ...(policy.perTxLimitSats !== undefined && { per_tx_limit_sats: policy.perTxLimitSats }),
+            ...(policy.softPerTxLimitSats !== undefined && {
+                soft_spend_limit_sats: policy.softPerTxLimitSats,
+            }),
+            ...(policy.dailyBudgetSats !== undefined && { daily_budget_sats: policy.dailyBudgetSats }),
+            ...(policy.sessionBudgetSats !== undefined && {
+                session_budget_sats: policy.sessionBudgetSats,
+            }),
+            ...(policy.rateLimitPerMinute !== undefined && {
+                rate_limit_per_minute: policy.rateLimitPerMinute,
+            }),
+            ...(policy.rateLimitPerHour !== undefined && {
+                rate_limit_per_hour: policy.rateLimitPerHour,
+            }),
+            ...(policy.approvalThresholdSats !== undefined && {
+                approval_threshold_sats: policy.approvalThresholdSats,
+            }),
+            allowlist: policy.allowlist,
+            denylist: policy.denylist,
+        },
+        usage: {
+            daily_spent_sats: usage.dailySpentSats,
+            session_spent_sats: usage.sessionSpentSats,
+            sends_last_minute: usage.sendsLastMinute,
+            sends_last_hour: usage.sendsLastHour,
+        },
+        approval_secret_configured: secretConfigured,
+        pending_approvals: pending.length,
+    });
+}
+/**
+ * Dry-run a policy decision: exit 0 = would allow, 8 = would deny,
+ * 9 = would queue. Evaluates as an unattended spend (no soft-limit
+ * confirmation) and persists nothing — what-ifs are not decisions.
+ */
+export function cmdPolicyTest(ctx, address, amountArg) {
+    validateAddress(address, ctx.network);
+    const amountSats = parseAmount(amountArg);
+    const policy = loadPolicy(ctx.network, ctx.config);
+    const verdict = evaluateSpend(policy, readUsage(ctx.network), { to: address, amountSats });
+    if (verdict.decision === 'allow') {
+        ctx.out.info(chalk.green(`ALLOW (${verdict.rule}): ${verdict.reason}.`));
+        ctx.out.result({ ok: true, decision: 'allow', rule: verdict.rule, reason: verdict.reason });
+        return;
+    }
+    if (verdict.decision === 'deny') {
+        throw new CliError(EXIT.SPEND_LIMIT, verdict.errorCode, `Would be denied (${verdict.rule}): ${verdict.reason}.`, { decision: 'deny', rule: verdict.rule, ...verdict.data });
+    }
+    throw new CliError(EXIT.PENDING_APPROVAL, 'pending_approval', `Would be queued for approval (${verdict.rule}): ${verdict.reason}.`, { decision: 'queue', rule: verdict.rule, ...verdict.data });
+}

package/dist/commands/request.d.ts

@@ -0,0 +1,9 @@
+import type { ChainProvider } from '../chain/provider.js';
+import type { Ctx } from '../context.js';
+import { buildPaymentUri } from '../core/request.js';
+export { buildPaymentUri };
+export interface RequestOptions {
+    wait?: boolean;
+    timeout?: string;
+}
+export declare function cmdRequest(ctx: Ctx, amountArg: string, memo: string | undefined, opts: RequestOptions, provider?: ChainProvider): Promise<void>;

package/dist/commands/request.js

@@ -0,0 +1,85 @@
+import chalk from 'chalk';
+import qrcode from 'qrcode-terminal';
+import { awaitPayment, buildPaymentUri, createRequest } from '../core/request.js';
+import { openWallet } from '../core/wallet.js';
+import { CliError, EXIT, usageError } from '../errors.js';
+import { formatSats, parseAmount } from '../units.js';
+import { obtainPassphrase } from '../wallet/wallet.js';
+import { explorerTxUrl } from './send.js';
+export { buildPaymentUri };
+function renderQr(uri) {
+    return new Promise((resolve) => {
+        qrcode.generate(uri, { small: true }, (qr) => resolve(qr));
+    });
+}
+export async function cmdRequest(ctx, amountArg, memo, opts, provider) {
+    const amountSats = parseAmount(amountArg);
+    const timeoutSec = Number(opts.timeout ?? '600');
+    if (!Number.isInteger(timeoutSec) || timeoutSec <= 0) {
+        throw usageError('invalid_timeout', `--timeout must be a positive integer of seconds (got "${opts.timeout}").`);
+    }
+    const core = { network: ctx.network, config: ctx.config, provider };
+    const wallet = await openWallet({
+        ...core,
+        passphrase: () => obtainPassphrase(), // env var, then interactive prompt
+        onWarning: (text) => process.stderr.write(text + '\n'),
+    });
+    const { address, uri } = createRequest(wallet, { amountSats, memo });
+    ctx.out.info(chalk.bold('Payment request'));
+    ctx.out.info(`  Address:  ${address}`);
+    ctx.out.info(`  Amount:   ${formatSats(amountSats)}`);
+    if (memo)
+        ctx.out.info(`  Memo:     ${memo} (local only)`);
+    ctx.out.info(`  URI:      ${uri}`);
+    // QR only on a real terminal, never when piped or in --json mode
+    if (!ctx.json && process.stdout.isTTY) {
+        ctx.out.info('');
+        ctx.out.info(await renderQr(uri));
+    }
+    const requestObj = {
+        ok: true,
+        event: 'request_created',
+        address,
+        amount_sats: amountSats,
+        uri,
+        ...(memo ? { memo } : {}),
+        network: ctx.network,
+    };
+    if (!opts.wait) {
+        ctx.out.result(requestObj);
+        return;
+    }
+    // --wait emits NDJSON in --json mode: the request first, then the outcome
+    // (a script needs the address before anyone can pay it). See DECISIONS.md.
+    ctx.out.result(requestObj);
+    ctx.out.info('');
+    ctx.out.info(`Waiting for payment (0-conf), timeout ${timeoutSec}s — Ctrl-C to stop...`);
+    let paid;
+    try {
+        paid = await awaitPayment(core, { address, timeoutMs: timeoutSec * 1000, memo });
+    }
+    catch (e) {
+        // keep the CLI's original timeout message and data shape
+        if (e instanceof CliError && e.errorCode === 'request_timeout') {
+            throw new CliError(EXIT.NETWORK, 'request_timeout', `No payment seen on ${address} within ${timeoutSec}s. The request URI is still valid; re-run with --wait to keep watching.`, { address, amount_sats: amountSats });
+        }
+        throw e;
+    }
+    ctx.out.info(chalk.green('Payment received.'));
+    ctx.out.info(`  Amount:    ${formatSats(paid.receivedSats)}`);
+    ctx.out.info(`  Txid:      ${paid.txid}`);
+    ctx.out.info(`  Explorer:  ${explorerTxUrl(ctx.network, paid.txid)}`);
+    if (paid.receivedSats < amountSats) {
+        process.stderr.write(chalk.yellow(`Note: received ${formatSats(paid.receivedSats)} is less than the requested ${formatSats(amountSats)}.`) + '\n');
+    }
+    ctx.out.result({
+        ok: true,
+        event: 'payment_received',
+        address,
+        requested_sats: amountSats,
+        received_sats: paid.receivedSats,
+        txid: paid.txid,
+        status: paid.confirmed ? 'confirmed' : 'pending',
+        explorer_url: explorerTxUrl(ctx.network, paid.txid),
+    });
+}

package/dist/commands/send.d.ts

@@ -0,0 +1,11 @@
+import type { ChainProvider } from '../chain/provider.js';
+import type { Ctx } from '../context.js';
+import { explorerTxUrl } from '../core/send.js';
+export { explorerTxUrl };
+export interface SendOptions {
+    yes?: boolean;
+    allowLarge?: boolean;
+    dryRun?: boolean;
+    confirmedOnly?: boolean;
+}
+export declare function cmdSend(ctx: Ctx, address: string, amountArg: string, memo: string | undefined, opts: SendOptions, provider?: ChainProvider): Promise<void>;

package/dist/commands/send.js

@@ -0,0 +1,125 @@
+import chalk from 'chalk';
+import { validateAddress } from '../address.js';
+import { executeSend, explorerTxUrl, planSend } from '../core/send.js';
+import { openWallet } from '../core/wallet.js';
+import { CliError, EXIT, usageError } from '../errors.js';
+import { ask, confirm, isInteractive } from '../prompt.js';
+import { formatSats, parseAmount } from '../units.js';
+import { obtainPassphrase } from '../wallet/wallet.js';
+export { explorerTxUrl };
+/**
+ * Spend-limit policy (invariant 4): at/above the limit, an explicit
+ * interactive confirmation is required; scripts need --yes --allow-large.
+ */
+async function enforceSpendLimit(ctx, amountSats, opts) {
+    const limit = ctx.config.spendLimitSats;
+    if (amountSats < limit)
+        return;
+    if (opts.yes) {
+        if (opts.allowLarge)
+            return;
+        throw new CliError(EXIT.SPEND_LIMIT, 'spend_limit_exceeded', `Amount ${formatSats(amountSats)} is at/above your ${formatSats(limit)} per-transaction limit. ` +
+            'Add --allow-large alongside --yes, or raise spend_limit_sats in config.toml.', { limit_sats: limit, amount_sats: amountSats });
+    }
+    if (!isInteractive()) {
+        throw new CliError(EXIT.SPEND_LIMIT, 'spend_limit_exceeded', `Amount ${formatSats(amountSats)} is at/above your ${formatSats(limit)} limit and there is no terminal to confirm. Use --yes --allow-large in scripts.`, { limit_sats: limit, amount_sats: amountSats });
+    }
+    process.stderr.write(chalk.yellow(`This send is at/above your spend limit of ${formatSats(limit)}.`) + '\n');
+    const typed = await ask(`Type the amount in sats (${amountSats}) to proceed: `);
+    if (typed.trim() !== String(amountSats)) {
+        throw new CliError(EXIT.SPEND_LIMIT, 'spend_limit_exceeded', 'Confirmation did not match; nothing was sent.');
+    }
+}
+export async function cmdSend(ctx, address, amountArg, memo, opts, provider) {
+    // 1. Validate everything local BEFORE unlocking or touching the network
+    //    (invariant 4): address, amount, then the spend limit — a script that
+    //    is over the limit fails fast with exit 8, not after network calls.
+    validateAddress(address, ctx.network);
+    const amountSats = parseAmount(amountArg);
+    await enforceSpendLimit(ctx, amountSats, opts);
+    const core = { network: ctx.network, config: ctx.config, provider };
+    const wallet = await openWallet({
+        ...core,
+        passphrase: () => obtainPassphrase(), // env var, then interactive prompt
+        onWarning: (text) => process.stderr.write(text + '\n'),
+    });
+    // 2. Gather funds and plan the transaction. The CLI enforced its limit
+    //    above (interactively when needed), so the core guard is satisfied.
+    const plan = await planSend(wallet, core, {
+        to: address,
+        amountSats,
+        memo,
+        confirmedOnly: opts.confirmedOnly,
+        allowAboveLimit: true,
+        dryRun: opts.dryRun,
+    });
+    // 3. Per-send confirmation (always shows recipient, amount, fee, and
+    //    resulting balance before broadcast).
+    if (opts.dryRun) {
+        process.stderr.write(chalk.bold('Dry run — nothing will be broadcast.') + '\n');
+    }
+    const summaryLines = [
+        `  Recipient:        ${address}`,
+        `  Amount:           ${formatSats(amountSats)}`,
+        plan.external
+            ? `  Fee:              ~${plan.feeSats} sats estimated (the external wallet sets the real fee)`
+            : `  Fee:              ${plan.feeSats} sats (${ctx.config.feeRateSatsPerKb} sats/KB, ${plan.inputCount} input${plan.inputCount === 1 ? '' : 's'})`,
+        `  Balance after:    ${plan.external ? '~' : ''}${formatSats(plan.balanceAfterSats)}`,
+    ];
+    if (plan.external) {
+        summaryLines.push('  Custody:          external BRC-100 wallet app (it may ask you to approve)');
+    }
+    if (memo)
+        summaryLines.push(`  Memo (local):     ${memo}`);
+    for (const line of summaryLines)
+        process.stderr.write(line + '\n');
+    if (!opts.yes && !opts.dryRun) {
+        if (!isInteractive()) {
+            throw usageError('confirmation_required', 'send needs a confirmation prompt but no terminal is available. Pass --yes in scripts.');
+        }
+        if (!(await confirm('Send it?'))) {
+            throw usageError('aborted', 'Send cancelled; nothing was broadcast.');
+        }
+    }
+    // 4. Sign, broadcast, and record via core (ledger writes live there).
+    const result = await executeSend(wallet, core, plan, { dryRun: opts.dryRun });
+    if (result.dryRun) {
+        ctx.out.info(chalk.bold('Dry run complete (not broadcast).'));
+        if (result.external) {
+            ctx.out.info('  Txid (if sent):   decided by the external wallet');
+        }
+        else {
+            ctx.out.info(`  Txid (if sent):   ${result.txid}`);
+            ctx.out.info(`  Size:             ${result.sizeBytes} bytes`);
+        }
+        ctx.out.result({
+            ok: true,
+            dry_run: true,
+            txid: result.txid,
+            recipient: address,
+            amount_sats: result.amountSats,
+            fee_sats: result.feeSats,
+            change_sats: result.changeSats,
+            balance_after_sats: result.balanceAfterSats,
+            ...(result.feeEstimated ? { fee_estimated: true } : {}),
+            ...(result.external ? { backend: 'brc100' } : {}),
+        });
+        return;
+    }
+    ctx.out.info(chalk.green('Sent.'));
+    ctx.out.info(`  Txid:           ${result.txid}`);
+    ctx.out.info(`  Explorer:       ${result.explorerUrl}`);
+    ctx.out.info(`  New balance:    ~${formatSats(result.balanceAfterSats)} (pending confirmation)`);
+    ctx.out.result({
+        ok: true,
+        txid: result.txid,
+        recipient: address,
+        amount_sats: result.amountSats,
+        fee_sats: result.feeSats,
+        change_sats: result.changeSats,
+        balance_after_sats: result.balanceAfterSats,
+        explorer_url: result.explorerUrl,
+        ...(result.feeEstimated ? { fee_estimated: true } : {}),
+        ...(result.external ? { backend: 'brc100' } : {}),
+    });
+}

package/dist/commands/serve.d.ts

@@ -0,0 +1,16 @@
+import type { ChainProvider } from '../chain/provider.js';
+import type { Ctx } from '../context.js';
+export interface ServeOptions {
+    price: string;
+    port?: string;
+    host?: string;
+    body?: string;
+}
+/**
+ * `bsv-pay serve` — a demo BRC-105 paywall: every request must pay
+ * `--price` into this wallet before it gets the content. Exists for
+ * testing, tutorials, and the two-agent demo (M13); the real product is
+ * the importable requirePayment() middleware this wraps. Human logging
+ * goes to stderr; the HTTP responses are the machine surface.
+ */
+export declare function cmdServe(ctx: Ctx, opts: ServeOptions, provider?: ChainProvider): Promise<void>;

package/dist/commands/serve.js

@@ -0,0 +1,59 @@
+import http from 'node:http';
+import chalk from 'chalk';
+import { openWallet } from '../core/wallet.js';
+import { usageError } from '../errors.js';
+import { requirePayment } from '../http402/middleware.js';
+import { formatSats, parseAmount } from '../units.js';
+import { obtainPassphrase } from '../wallet/wallet.js';
+/**
+ * `bsv-pay serve` — a demo BRC-105 paywall: every request must pay
+ * `--price` into this wallet before it gets the content. Exists for
+ * testing, tutorials, and the two-agent demo (M13); the real product is
+ * the importable requirePayment() middleware this wraps. Human logging
+ * goes to stderr; the HTTP responses are the machine surface.
+ */
+export async function cmdServe(ctx, opts, provider) {
+    const priceSats = parseAmount(opts.price);
+    const port = Number(opts.port ?? '8402');
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw usageError('invalid_port', `--port must be 1-65535 (got "${opts.port}").`);
+    }
+    const core = { network: ctx.network, config: ctx.config, provider };
+    const wallet = await openWallet({
+        ...core,
+        passphrase: () => obtainPassphrase(),
+        onWarning: (text) => process.stderr.write(text + '\n'),
+    });
+    const gate = requirePayment({ ...core, wallet, priceSats });
+    const server = http.createServer((req, res) => {
+        gate(req, res, () => {
+            const receipt = req.bsvPayment;
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({
+                ok: true,
+                message: opts.body ?? 'Paid content served by bsv-pay.',
+                amount_sats: receipt.amountSats,
+                txid: receipt.txid,
+            }));
+            process.stderr.write(chalk.green(`sold: ${formatSats(receipt.amountSats)} for ${req.url ?? '/'} (txid ${receipt.txid.slice(0, 12)}…)`) + '\n');
+        }).catch((err) => {
+            process.stderr.write(chalk.red(`serve error: ${err instanceof Error ? err.message : String(err)}`) + '\n');
+            if (!res.headersSent) {
+                res.writeHead(500, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: false, error: 'internal_error' }));
+            }
+        });
+    });
+    const host = opts.host ?? '127.0.0.1'; // localhost-only unless explicitly exposed
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => resolve());
+    });
+    process.stderr.write(`bsv-pay paywall on http://${host}:${port} — ${formatSats(priceSats)} per request, ` +
+        `paid into this ${ctx.network === 'test' ? 'testnet' : 'mainnet'} wallet. Ctrl+C stops.\n`);
+    // Serve until interrupted.
+    await new Promise((resolve) => {
+        process.once('SIGINT', () => server.close(() => resolve()));
+        process.once('SIGTERM', () => server.close(() => resolve()));
+    });
+}