bsv-pay-cli 0.2.0

package/dist/errors.js

@@ -0,0 +1,39 @@
+/** Stable exit codes, documented in README. */
+export const EXIT = {
+    OK: 0,
+    UNEXPECTED: 1,
+    USAGE: 2,
+    INSUFFICIENT_FUNDS: 3,
+    NETWORK: 4,
+    BROADCAST_REJECTED: 5,
+    BROADCAST_UNKNOWN: 6,
+    WALLET_LOCKED: 7,
+    SPEND_LIMIT: 8,
+    /** Phase 2: the spend was queued for human approval instead of sent. */
+    PENDING_APPROVAL: 9,
+    /** Phase 2: a 402 payment broadcast but the server refused the content. */
+    PAYMENT_NOT_REDEEMED: 10,
+};
+/**
+ * Error carrying a stable exit code and a snake_case machine-readable code
+ * for --json output. `data` is merged into the JSON error object (never
+ * include key material).
+ */
+export class CliError extends Error {
+    exitCode;
+    errorCode;
+    data;
+    constructor(exitCode, errorCode, message, data) {
+        super(message);
+        this.exitCode = exitCode;
+        this.errorCode = errorCode;
+        this.data = data;
+        this.name = 'CliError';
+    }
+}
+export function usageError(errorCode, message) {
+    return new CliError(EXIT.USAGE, errorCode, message);
+}
+export function networkError(message, data) {
+    return new CliError(EXIT.NETWORK, 'network_error', message, data);
+}

package/dist/http402/client.d.ts

@@ -0,0 +1,32 @@
+import type { CoreOptions } from '../core/context.js';
+import type { CoreWallet } from '../core/wallet.js';
+export interface PaidFetchParams {
+    url: string;
+    /** Hard cap for THIS fetch, checked before any spend. Exit 8 when exceeded. */
+    maxPriceSats?: number;
+}
+export interface PaidFetchPayment {
+    txid: string;
+    amountSats: number;
+    feeSats: number;
+    address: string;
+    derivationPrefix: string;
+}
+export interface PaidFetchResult {
+    /** HTTP status of the final response (after payment, if one was made). */
+    status: number;
+    body: string;
+    contentType?: string;
+    /** False when the resource came back without requiring payment. */
+    paid: boolean;
+    payment?: PaidFetchPayment;
+}
+/**
+ * GET a URL, automatically paying a BRC-105 402 challenge within policy.
+ * Free resources return with `paid: false` and no spend. Throws exit 8 on
+ * `max_price_exceeded` (before the gate) or any policy denial (from the
+ * gate, ledgered), exit 9 when the payment queued for human approval, and
+ * exit 10 `payment_not_redeemed` when the payment broadcast but the server
+ * still refused the content (the txid is in the error data — money moved).
+ */
+export declare function paidFetch(wallet: CoreWallet, opts: CoreOptions, params: PaidFetchParams): Promise<PaidFetchResult>;

package/dist/http402/client.js

@@ -0,0 +1,85 @@
+import { CliError, EXIT, networkError } from '../errors.js';
+import { send } from '../core/send.js';
+import { encodePaymentEnvelope, parsePaymentTerms, HEADER } from './protocol.js';
+/**
+ * The paying side of the 402 flow (BRC-105 simplified profile — see
+ * src/http402/protocol.ts and DECISIONS.md M11). The payment itself goes
+ * through core send(): the policy gate decides and ledgers it, the
+ * single-flight lock serializes it, and `maxPriceSats` additionally caps
+ * this one fetch regardless of policy headroom. This module is the ONLY
+ * core file allowed to call fetch() besides the chain provider — it can
+ * talk HTTP, but it cannot sign or broadcast anything itself.
+ */
+const REQUEST_TIMEOUT_MS = 30_000;
+const MEMO_MAX_CHARS = 120;
+async function httpGet(url, headers) {
+    try {
+        return await fetch(url, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    }
+    catch (e) {
+        throw networkError(`Cannot reach ${url}: ${e instanceof Error ? e.message : String(e)}.`, {
+            url,
+        });
+    }
+}
+/**
+ * GET a URL, automatically paying a BRC-105 402 challenge within policy.
+ * Free resources return with `paid: false` and no spend. Throws exit 8 on
+ * `max_price_exceeded` (before the gate) or any policy denial (from the
+ * gate, ledgered), exit 9 when the payment queued for human approval, and
+ * exit 10 `payment_not_redeemed` when the payment broadcast but the server
+ * still refused the content (the txid is in the error data — money moved).
+ */
+export async function paidFetch(wallet, opts, params) {
+    if (!/^https?:\/\//i.test(params.url)) {
+        throw new CliError(EXIT.USAGE, 'invalid_url', `fetch needs an http(s) URL (got "${params.url}").`);
+    }
+    const first = await httpGet(params.url);
+    if (first.status !== 402) {
+        return {
+            status: first.status,
+            body: await first.text(),
+            contentType: first.headers.get('content-type') ?? undefined,
+            paid: false,
+        };
+    }
+    const terms = parsePaymentTerms(first.headers, opts.network);
+    if (params.maxPriceSats !== undefined && terms.satoshisRequired > params.maxPriceSats) {
+        throw new CliError(EXIT.SPEND_LIMIT, 'max_price_exceeded', `Server asks ${terms.satoshisRequired} sats but --max-price caps this fetch at ${params.maxPriceSats} sats. Nothing was paid.`, { url: params.url, price_sats: terms.satoshisRequired, max_price_sats: params.maxPriceSats });
+    }
+    // The actual spend: policy gate, single-flight lock, ledger — all in core.
+    const payment = await send(wallet, opts, {
+        to: terms.address,
+        amountSats: terms.satoshisRequired,
+        memo: `402 ${params.url}`.slice(0, MEMO_MAX_CHARS),
+    });
+    const retry = await httpGet(params.url, {
+        [HEADER.payment]: encodePaymentEnvelope({
+            derivationPrefix: terms.derivationPrefix,
+            txid: payment.txid,
+            transaction: payment.rawTxHex,
+        }),
+    });
+    if (!retry.ok) {
+        throw new CliError(EXIT.PAYMENT_NOT_REDEEMED, 'payment_not_redeemed', `Paid ${terms.satoshisRequired} sats (txid ${payment.txid}) but the server still responded ${retry.status}. The payment is on-chain and in your ledger; take it up with the seller.`, {
+            url: params.url,
+            status: retry.status,
+            txid: payment.txid,
+            amount_sats: terms.satoshisRequired,
+            address: terms.address,
+        });
+    }
+    return {
+        status: retry.status,
+        body: await retry.text(),
+        contentType: retry.headers.get('content-type') ?? undefined,
+        paid: true,
+        payment: {
+            txid: payment.txid,
+            amountSats: payment.amountSats,
+            feeSats: payment.feeSats,
+            address: terms.address,
+            derivationPrefix: terms.derivationPrefix,
+        },
+    };
+}

package/dist/http402/middleware.d.ts

@@ -0,0 +1,37 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { CoreOptions } from '../core/context.js';
+import type { CoreWallet } from '../core/wallet.js';
+/**
+ * The selling side of the 402 flow (BRC-105 simplified profile — see
+ * src/http402/protocol.ts). Express-compatible `(req, res, next)` handler
+ * with zero framework dependencies: it types req/res structurally against
+ * node's http primitives, so it drops into Express, plain node:http
+ * (`bsv-pay serve`), or anything shaped like them.
+ *
+ * Money flow: every quote issues a fresh wallet address (the bsv-pay
+ * `request` model — unambiguous matching, funds land tracked and
+ * spendable). The buyer broadcasts; this side only READS its chain view
+ * to confirm (awaitPayment, which also ledgers the receive, invariant 6).
+ * No signing, no broadcasting, no fetch — the choke points are untouched.
+ */
+export interface RequirePaymentOptions extends CoreOptions {
+    wallet: CoreWallet;
+    /** Price per paid request, in satoshis. */
+    priceSats: number;
+    /** How long a quoted prefix stays payable (default 10 minutes). */
+    quoteTtlMs?: number;
+    /** How long to wait for the presented payment on-chain (default 20 s). */
+    confirmTimeoutMs?: number;
+}
+export interface PaymentReceipt {
+    txid: string;
+    amountSats: number;
+    address: string;
+    derivationPrefix: string;
+}
+/** A request that passed the paywall carries its receipt. */
+export type PaidRequest = IncomingMessage & {
+    bsvPayment?: PaymentReceipt;
+};
+export type PaidRequestHandler = (req: PaidRequest, res: ServerResponse, next?: () => void) => Promise<void>;
+export declare function requirePayment(opts: RequirePaymentOptions): PaidRequestHandler;

package/dist/http402/middleware.js

@@ -0,0 +1,96 @@
+import crypto from 'node:crypto';
+import { awaitPayment, createRequest } from '../core/request.js';
+import { brc100ReceiveNotSupported } from '../wallet/brc100.js';
+import { buildTermsHeaders, parsePaymentEnvelope, transactionPays, HEADER } from './protocol.js';
+export function requirePayment(opts) {
+    // Selling means issuing receive addresses, which BRC-100 custody cannot do
+    // (the wallet app would never see the funds). Fail at construction, not on
+    // the first customer.
+    if (opts.wallet.backend === 'brc100')
+        throw brc100ReceiveNotSupported();
+    const quoteTtlMs = opts.quoteTtlMs ?? 600_000;
+    const confirmTimeoutMs = opts.confirmTimeoutMs ?? 20_000;
+    const core = {
+        network: opts.network,
+        config: opts.config,
+        provider: opts.provider,
+    };
+    /** prefix → quote. In-memory and single-use: a restart simply re-quotes. */
+    const quotes = new Map();
+    function respond402(res, error) {
+        const now = Date.now();
+        for (const [prefix, quote] of quotes) {
+            if (quote.used || quote.expiresAt < now)
+                quotes.delete(prefix);
+        }
+        const derivationPrefix = crypto.randomBytes(16).toString('base64');
+        const request = createRequest(opts.wallet, {
+            amountSats: opts.priceSats,
+            memo: '402 quote',
+        });
+        quotes.set(derivationPrefix, {
+            address: request.address,
+            satoshisRequired: opts.priceSats,
+            expiresAt: now + quoteTtlMs,
+            used: false,
+        });
+        res.writeHead(402, {
+            'content-type': 'application/json',
+            ...buildTermsHeaders({
+                satoshisRequired: opts.priceSats,
+                derivationPrefix,
+                address: request.address,
+            }),
+            ...(error ? { [HEADER.error]: error } : {}),
+        });
+        res.end(JSON.stringify({
+            ok: false,
+            error: error ?? 'payment_required',
+            satoshis_required: opts.priceSats,
+        }));
+    }
+    return async (req, res, next) => {
+        const envelope = parsePaymentEnvelope(req.headers[HEADER.payment]);
+        if (!envelope) {
+            respond402(res);
+            return;
+        }
+        const quote = quotes.get(envelope.derivationPrefix);
+        if (!quote || quote.used || quote.expiresAt < Date.now()) {
+            respond402(res, 'unknown_or_expired_prefix');
+            return;
+        }
+        // Structural pre-check on the presented hex (public data) before
+        // touching the chain: does it even pay this quote?
+        if (!transactionPays(envelope.transaction, quote.address, quote.satoshisRequired, opts.network)) {
+            respond402(res, 'payment_insufficient');
+            return;
+        }
+        // Claim the quote BEFORE confirming so two concurrent retries with the
+        // same prefix can never both redeem (released again if not found).
+        quote.used = true;
+        let payment;
+        try {
+            payment = await awaitPayment(core, {
+                address: quote.address,
+                timeoutMs: confirmTimeoutMs,
+                memo: `402 sale ${req.url ?? ''}`.trim(),
+            });
+        }
+        catch {
+            quote.used = false; // still payable until the TTL
+            respond402(res, 'payment_not_found');
+            return;
+        }
+        const receipt = {
+            txid: payment.txid,
+            amountSats: payment.receivedSats,
+            address: quote.address,
+            derivationPrefix: envelope.derivationPrefix,
+        };
+        req.bsvPayment = receipt;
+        res.setHeader(HEADER.satoshisPaid, String(payment.receivedSats));
+        if (next)
+            next();
+    };
+}

package/dist/http402/protocol.d.ts

@@ -0,0 +1,50 @@
+import type { Network } from '../paths.js';
+/**
+ * The BRC-105 header exchange, simplified profile (see DECISIONS.md M11):
+ * same header names, flow, and version as the spec, with two documented
+ * divergences until M12 brings BRC-100 custody — the payment destination
+ * is a fresh server-wallet address advertised via `x-bsv-payment-address`
+ * (instead of BRC-29 key derivation), and `transaction` in the retry
+ * envelope is raw tx hex (instead of AtomicBEEF).
+ */
+export declare const PAYMENT_VERSION = "1.0";
+export declare const HEADER: {
+    readonly version: "x-bsv-payment-version";
+    readonly satoshisRequired: "x-bsv-payment-satoshis-required";
+    readonly derivationPrefix: "x-bsv-payment-derivation-prefix";
+    readonly address: "x-bsv-payment-address";
+    readonly payment: "x-bsv-payment";
+    readonly satoshisPaid: "x-bsv-payment-satoshis-paid";
+    readonly error: "x-bsv-payment-error";
+};
+/** What a 402 response demands. */
+export interface PaymentTerms {
+    satoshisRequired: number;
+    derivationPrefix: string;
+    address: string;
+}
+/** What the client presents on retry (the `x-bsv-payment` header, JSON). */
+export interface PaymentEnvelope {
+    derivationPrefix: string;
+    txid: string;
+    /** Signed raw transaction hex — public data, already broadcast by the payer. */
+    transaction: string;
+}
+/**
+ * Parse and validate the payment terms on a 402 response. Throws exit 4
+ * without spending anything when the terms are unusable; per BRC-105, a
+ * version we do not support means we MUST NOT pay.
+ */
+export declare function parsePaymentTerms(headers: {
+    get(name: string): string | null;
+}, network: Network): PaymentTerms;
+export declare function buildTermsHeaders(terms: PaymentTerms): Record<string, string>;
+export declare function encodePaymentEnvelope(envelope: PaymentEnvelope): string;
+/** Parse the retry envelope; null means "treat as an unpaid request". */
+export declare function parsePaymentEnvelope(raw: string | undefined | null): PaymentEnvelope | null;
+/**
+ * Structural check of a presented payment: does this transaction pay at
+ * least `satoshisRequired` to `address`? Read-only over public data — the
+ * authoritative confirmation is the seller's own chain view.
+ */
+export declare function transactionPays(rawTxHex: string, address: string, satoshisRequired: number, network: Network): boolean;

package/dist/http402/protocol.js

@@ -0,0 +1,114 @@
+import { Transaction, Utils } from '@bsv/sdk';
+import { validateAddress } from '../address.js';
+import { CliError, EXIT } from '../errors.js';
+/**
+ * The BRC-105 header exchange, simplified profile (see DECISIONS.md M11):
+ * same header names, flow, and version as the spec, with two documented
+ * divergences until M12 brings BRC-100 custody — the payment destination
+ * is a fresh server-wallet address advertised via `x-bsv-payment-address`
+ * (instead of BRC-29 key derivation), and `transaction` in the retry
+ * envelope is raw tx hex (instead of AtomicBEEF).
+ */
+export const PAYMENT_VERSION = '1.0';
+export const HEADER = {
+    version: 'x-bsv-payment-version',
+    satoshisRequired: 'x-bsv-payment-satoshis-required',
+    derivationPrefix: 'x-bsv-payment-derivation-prefix',
+    address: 'x-bsv-payment-address',
+    payment: 'x-bsv-payment',
+    satoshisPaid: 'x-bsv-payment-satoshis-paid',
+    error: 'x-bsv-payment-error',
+};
+function badTerms(message) {
+    // The server sent a 402 we must not pay: a remote-protocol failure
+    // (exit 4), and crucially BEFORE any spend was attempted.
+    throw new CliError(EXIT.NETWORK, 'invalid_payment_terms', message);
+}
+/**
+ * Parse and validate the payment terms on a 402 response. Throws exit 4
+ * without spending anything when the terms are unusable; per BRC-105, a
+ * version we do not support means we MUST NOT pay.
+ */
+export function parsePaymentTerms(headers, network) {
+    const version = headers.get(HEADER.version);
+    if (version !== PAYMENT_VERSION) {
+        badTerms(`Server requested payment version "${version ?? '(missing)'}" but this client supports ${PAYMENT_VERSION}. Not paying.`);
+    }
+    const satoshisRequired = Number(headers.get(HEADER.satoshisRequired));
+    if (!Number.isSafeInteger(satoshisRequired) || satoshisRequired <= 0) {
+        badTerms('Missing or invalid x-bsv-payment-satoshis-required header. Not paying.');
+    }
+    const derivationPrefix = headers.get(HEADER.derivationPrefix);
+    if (typeof derivationPrefix !== 'string' || derivationPrefix.length < 1) {
+        badTerms('Missing x-bsv-payment-derivation-prefix header. Not paying.');
+    }
+    const address = headers.get(HEADER.address);
+    if (typeof address !== 'string' || address.length < 1) {
+        badTerms('Missing x-bsv-payment-address header. Not paying.');
+    }
+    try {
+        validateAddress(address, network); // wrong-network terms are never payable
+    }
+    catch {
+        badTerms(`Payment address "${address}" is not valid for this network. Not paying.`);
+    }
+    return { satoshisRequired, derivationPrefix, address };
+}
+export function buildTermsHeaders(terms) {
+    return {
+        [HEADER.version]: PAYMENT_VERSION,
+        [HEADER.satoshisRequired]: String(terms.satoshisRequired),
+        [HEADER.derivationPrefix]: terms.derivationPrefix,
+        [HEADER.address]: terms.address,
+    };
+}
+export function encodePaymentEnvelope(envelope) {
+    return JSON.stringify(envelope);
+}
+/** Parse the retry envelope; null means "treat as an unpaid request". */
+export function parsePaymentEnvelope(raw) {
+    if (!raw)
+        return null;
+    try {
+        const doc = JSON.parse(raw);
+        if (typeof doc.derivationPrefix === 'string' &&
+            typeof doc.txid === 'string' &&
+            typeof doc.transaction === 'string') {
+            return {
+                derivationPrefix: doc.derivationPrefix,
+                txid: doc.txid,
+                transaction: doc.transaction,
+            };
+        }
+    }
+    catch {
+        // malformed JSON falls through to null
+    }
+    return null;
+}
+const P2PKH_PREFIX = { main: 0x00, test: 0x6f };
+/**
+ * Structural check of a presented payment: does this transaction pay at
+ * least `satoshisRequired` to `address`? Read-only over public data — the
+ * authoritative confirmation is the seller's own chain view.
+ */
+export function transactionPays(rawTxHex, address, satoshisRequired, network) {
+    let tx;
+    try {
+        tx = Transaction.fromHex(rawTxHex);
+    }
+    catch {
+        return false;
+    }
+    let paid = 0;
+    for (const out of tx.outputs) {
+        const m = /^76a914([0-9a-f]{40})88ac$/.exec(out.lockingScript.toHex());
+        if (!m)
+            continue;
+        const bytes = m[1].match(/../g).map((b) => parseInt(b, 16));
+        if (Utils.toBase58Check(bytes, [P2PKH_PREFIX[network]]) === address) {
+            paid += out.satoshis ?? 0;
+        }
+    }
+    return paid >= satoshisRequired;
+}

package/dist/ledger.d.ts

@@ -0,0 +1,51 @@
+import { type Network } from './paths.js';
+/**
+ * Append-only local ledger (~/.bsv-pay/ledger.jsonl). Records sends,
+ * receives, issued addresses, and (Phase 2) every policy decision and
+ * approval resolution. Memos are local-only — never on-chain.
+ * Never contains key material. Entry types are additive-only.
+ */
+export type LedgerEntry = {
+    type: 'send' | 'receive';
+    txid: string;
+    amount_sats: number;
+    address: string;
+    memo?: string;
+    timestamp: string;
+    status: 'pending' | 'confirmed' | 'unknown';
+    fee_sats?: number;
+    /** Links a send to the policy decision that authorized it (Phase 2). */
+    decision_id?: string;
+} | {
+    type: 'address_issued';
+    address: string;
+    derivation_index: number;
+    purpose: 'receive' | 'change' | 'request';
+    memo?: string;
+    timestamp: string;
+} | {
+    type: 'policy_decision';
+    decision: 'allow' | 'deny' | 'queue';
+    /** Which policy rule decided, e.g. "daily_budget_sats" or "default". */
+    rule: string;
+    reason: string;
+    address: string;
+    amount_sats: number;
+    memo?: string;
+    timestamp: string;
+    decision_id: string;
+    /** Present when decision === "queue". */
+    approval_id?: string;
+    confirmed_only?: boolean;
+} | {
+    type: 'approval_resolved';
+    approval_id: string;
+    resolution: 'approved' | 'rejected';
+    timestamp: string;
+    /** Present when resolution === "approved" and the send broadcast. */
+    txid?: string;
+};
+export declare function appendLedger(network: Network, entry: LedgerEntry): void;
+/** Unique addresses this wallet has issued, oldest first (no unlock needed). */
+export declare function trackedAddressesFromLedger(network: Network): string[];
+export declare function readLedger(network: Network): LedgerEntry[];

package/dist/ledger.js

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ledgerPath } from './paths.js';
+export function appendLedger(network, entry) {
+    const file = ledgerPath(network);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(entry) + '\n', { mode: 0o600 });
+}
+/** Unique addresses this wallet has issued, oldest first (no unlock needed). */
+export function trackedAddressesFromLedger(network) {
+    const seen = new Set();
+    for (const entry of readLedger(network)) {
+        if (entry.type === 'address_issued')
+            seen.add(entry.address);
+    }
+    return [...seen];
+}
+export function readLedger(network) {
+    const file = ledgerPath(network);
+    if (!fs.existsSync(file))
+        return [];
+    return fs
+        .readFileSync(file, 'utf8')
+        .split('\n')
+        .filter((line) => line.trim() !== '')
+        .map((line) => JSON.parse(line));
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,32 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ChainProvider } from '../chain/provider.js';
+import type { Config } from '../config.js';
+import type { Network } from '../paths.js';
+import type { CoreWallet } from '../core/wallet.js';
+import type { Brc100Interface } from '../wallet/brc100.js';
+/**
+ * The bsv-pay MCP server: tools over the core library, nothing else. The
+ * wallet is unlocked BEFORE this server is built (env passphrase or TTY
+ * prompt at startup) and no tool can unlock, lock, or export anything —
+ * the agent on the other end of the transport never holds a secret. All
+ * spending goes through core, where the policy gate and the single-flight
+ * spend lock live; this module cannot reach the network or a key directly.
+ *
+ * Results contract (stable, additive-only once shipped): every tool returns
+ * structuredContent with `ok: true | false`. Expected failures — policy
+ * denials, queued approvals, insufficient funds — are RESULTS with stable
+ * snake_case `error` codes and the engine's data fields (remaining_sats,
+ * approval_id, ...), never protocol errors, so an agent can read them and
+ * adapt. Only unexpected exceptions surface as isError tool results.
+ */
+export interface McpServerOptions {
+    network: Network;
+    wallet: CoreWallet;
+    config?: Partial<Config>;
+    /** Tests inject a mock; production uses the default (WhatsOnChain). */
+    provider?: ChainProvider;
+    /** Tests inject a mock BRC-100 wallet app (used only under brc100 custody). */
+    brc100?: Brc100Interface;
+}
+export declare const MCP_SERVER_VERSION = "0.2.0";
+export declare function buildMcpServer(opts: McpServerOptions): McpServer;