bsv-pay-cli 0.2.0

package/dist/policy/approvals.js

@@ -0,0 +1,89 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { argon2id } from '@noble/hashes/argon2';
+import { CliError, EXIT, usageError } from '../errors.js';
+import { appendLedger, readLedger } from '../ledger.js';
+import { approvalSecretPath } from '../paths.js';
+import { DEFAULT_KDF } from '../wallet/crypto.js';
+function hashSecret(secret, saltHex, params) {
+    const pass = new TextEncoder().encode(secret.normalize('NFKD'));
+    const salt = Buffer.from(saltHex, 'hex');
+    return Buffer.from(argon2id(pass, salt, { ...params, dkLen: 32 }));
+}
+export function approvalSecretConfigured() {
+    return fs.existsSync(approvalSecretPath());
+}
+/** Store the argon2id hash of a new approval secret (never the secret). */
+export function storeApprovalSecret(secret) {
+    const file = {
+        algo: 'argon2id',
+        salt: crypto.randomBytes(16).toString('hex'),
+        ...DEFAULT_KDF,
+        hash: '',
+    };
+    file.hash = hashSecret(secret, file.salt, file).toString('hex');
+    fs.mkdirSync(path.dirname(approvalSecretPath()), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(approvalSecretPath(), JSON.stringify(file, null, 2) + '\n', { mode: 0o600 });
+}
+export function verifyApprovalSecret(secret) {
+    if (!approvalSecretConfigured())
+        return false;
+    let file;
+    try {
+        file = JSON.parse(fs.readFileSync(approvalSecretPath(), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    const expected = Buffer.from(file.hash, 'hex');
+    const actual = hashSecret(secret, file.salt, file);
+    return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
+}
+/**
+ * Pending approvals are a fold over the append-only ledger: queue decisions
+ * minus resolutions. No second mutable state file to tamper with.
+ */
+export function listPendingApprovals(network) {
+    const resolved = new Set();
+    const queued = [];
+    for (const entry of readLedger(network)) {
+        if (entry.type === 'approval_resolved')
+            resolved.add(entry.approval_id);
+        if (entry.type === 'policy_decision' && entry.decision === 'queue' && entry.approval_id) {
+            queued.push({
+                approvalId: entry.approval_id,
+                address: entry.address,
+                amountSats: entry.amount_sats,
+                memo: entry.memo,
+                confirmedOnly: entry.confirmed_only,
+                queuedAt: entry.timestamp,
+            });
+        }
+    }
+    return queued.filter((q) => !resolved.has(q.approvalId));
+}
+/** Find a pending approval by full id or unambiguous prefix. */
+export function findPendingApproval(network, id) {
+    const pending = listPendingApprovals(network);
+    const matches = pending.filter((p) => p.approvalId === id || p.approvalId.startsWith(id));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw usageError('ambiguous_approval', `Approval id "${id}" matches ${matches.length} pending approvals. Use more characters.`);
+    }
+    throw usageError('unknown_approval', `No pending approval matches "${id}". Run "bsv-pay approvals list".`);
+}
+export function resolveApproval(network, approvalId, resolution, txid) {
+    appendLedger(network, {
+        type: 'approval_resolved',
+        approval_id: approvalId,
+        resolution,
+        timestamp: new Date().toISOString(),
+        txid,
+    });
+}
+/** Thrown when the typed approval secret is wrong. Exit 7 (auth failure). */
+export function badApprovalSecret() {
+    return new CliError(EXIT.WALLET_LOCKED, 'bad_approval_secret', 'Wrong approval secret. The wallet passphrase is NOT accepted here; the approval secret is the one set via "bsv-pay approvals set-secret".');
+}

package/dist/policy/budget.d.ts

@@ -0,0 +1,16 @@
+import type { Network } from '../paths.js';
+export declare function addSessionSpent(network: Network, amountSats: number): void;
+export declare function resetSessionSpentForTests(): void;
+export interface SpendUsage {
+    /** Sum of send amounts (pending, confirmed, AND unknown) in the last 24h. */
+    dailySpentSats: number;
+    sessionSpentSats: number;
+    sendsLastMinute: number;
+    sendsLastHour: number;
+}
+/**
+ * Read current spend usage from the ledger. Amounts are amount_sats only
+ * (fees excluded); `unknown` broadcasts count as spent — conservative, the
+ * funds may have moved.
+ */
+export declare function readUsage(network: Network, now?: number): SpendUsage;

package/dist/policy/budget.js

@@ -0,0 +1,47 @@
+import { readLedger } from '../ledger.js';
+const MINUTE_MS = 60_000;
+const HOUR_MS = 3_600_000;
+const DAY_MS = 24 * HOUR_MS;
+/**
+ * Session spend is the ONLY in-memory accounting: by definition it covers
+ * this process's lifetime (an MCP server session; each CLI invocation is its
+ * own session). Everything else below is recomputed from the append-only
+ * ledger at every decision, so restarting a process never resets a budget.
+ */
+const sessionSpentByNetwork = new Map();
+export function addSessionSpent(network, amountSats) {
+    sessionSpentByNetwork.set(network, (sessionSpentByNetwork.get(network) ?? 0) + amountSats);
+}
+export function resetSessionSpentForTests() {
+    sessionSpentByNetwork.clear();
+}
+/**
+ * Read current spend usage from the ledger. Amounts are amount_sats only
+ * (fees excluded); `unknown` broadcasts count as spent — conservative, the
+ * funds may have moved.
+ */
+export function readUsage(network, now = Date.now()) {
+    let dailySpentSats = 0;
+    let sendsLastMinute = 0;
+    let sendsLastHour = 0;
+    for (const entry of readLedger(network)) {
+        if (entry.type !== 'send')
+            continue;
+        const t = Date.parse(entry.timestamp);
+        if (!Number.isFinite(t))
+            continue;
+        // Future-dated entries (clock skew) count as "just now" — conservative.
+        if (now - t < DAY_MS)
+            dailySpentSats += entry.amount_sats;
+        if (now - t < HOUR_MS)
+            sendsLastHour += 1;
+        if (now - t < MINUTE_MS)
+            sendsLastMinute += 1;
+    }
+    return {
+        dailySpentSats,
+        sessionSpentSats: sessionSpentByNetwork.get(network) ?? 0,
+        sendsLastMinute,
+        sendsLastHour,
+    };
+}

package/dist/policy/engine.d.ts

@@ -0,0 +1,76 @@
+import type { Config } from '../config.js';
+import type { Network } from '../paths.js';
+import { type SpendUsage } from './budget.js';
+import { type Policy } from './policy.js';
+/**
+ * THE policy gate (invariant 2). Every spend path — CLI send/donate, the
+ * core library, the MCP server, the 402 client — reaches the network only
+ * via core executeSend, and executeSend only accepts plans this module has
+ * authorized. No flag, parameter, or tool argument can disable a policy.toml
+ * rule; `softLimitConfirmed` satisfies only the legacy confirmable limit
+ * that exists when no policy.toml hard limit is set (pre-Phase-2 behavior).
+ */
+export interface PolicyEnv {
+    network: Network;
+    config: Config;
+}
+export interface SpendRequest {
+    to: string;
+    amountSats: number;
+    memo?: string;
+    /** The human confirmed the legacy soft limit (interactive / --allow-large). */
+    softLimitConfirmed?: boolean;
+    confirmedOnly?: boolean;
+}
+export type Verdict = {
+    decision: 'allow';
+    rule: string;
+    reason: string;
+} | {
+    decision: 'deny';
+    rule: string;
+    reason: string;
+    errorCode: string;
+    data: Record<string, unknown>;
+} | {
+    decision: 'queue';
+    rule: string;
+    reason: string;
+    data: Record<string, unknown>;
+};
+/** Pure rule evaluation: deny wins, then queue, then allow. No I/O. */
+export declare function evaluateSpend(policy: Policy, usage: SpendUsage, req: SpendRequest): Verdict;
+/** Proof an allow decision was made for exactly this recipient and amount. */
+export interface SpendAuthorization {
+    decisionId: string;
+    to: string;
+    amountSats: number;
+    /** True when authorized in evaluate-only mode (dry runs): never executable for real. */
+    evaluateOnly: boolean;
+}
+export interface AuthorizeOptions {
+    /**
+     * enforce: the decision is real — append it to the ledger (invariant 6),
+     * queue approvals. evaluate: dry runs and `policy test` — same verdicts and
+     * thrown errors, but nothing persisted and nothing queued.
+     */
+    mode: 'enforce' | 'evaluate';
+}
+/**
+ * Decide a spend. Returns an authorization on allow; throws exit 8 on deny
+ * and exit 9 on queue (after recording the decision — and, for queues, the
+ * approval — in the ledger when mode is enforce).
+ */
+export declare function authorizeSpend(env: PolicyEnv, req: SpendRequest, opts: AuthorizeOptions): SpendAuthorization;
+/**
+ * Decide a previously queued spend in approval context: every rule except
+ * the approval threshold still applies at approval time. Called ONLY by the
+ * approvals command after the human passed the TTY + approval-secret gate;
+ * not exported from the core public surface.
+ */
+export declare function authorizeApprovedSpend(env: PolicyEnv, req: SpendRequest, approvalId: string): SpendAuthorization;
+export declare function registerAuthorizedPlan(plan: object, auth: SpendAuthorization): void;
+export declare function takeAuthorizedPlan(plan: object, expected: {
+    to: string;
+    amountSats: number;
+}, forBroadcast: boolean): SpendAuthorization;

package/dist/policy/engine.js

@@ -0,0 +1,199 @@
+import crypto from 'node:crypto';
+import { CliError, EXIT } from '../errors.js';
+import { appendLedger } from '../ledger.js';
+import { formatSats } from '../units.js';
+import { readUsage } from './budget.js';
+import { loadPolicy } from './policy.js';
+/** Pure rule evaluation: deny wins, then queue, then allow. No I/O. */
+export function evaluateSpend(policy, usage, req) {
+    const { to, amountSats } = req;
+    if (policy.denylist.includes(to)) {
+        return {
+            decision: 'deny',
+            rule: 'denylist',
+            reason: `recipient ${to} is denylisted`,
+            errorCode: 'recipient_denied',
+            data: { address: to },
+        };
+    }
+    if (policy.allowlist.length > 0 && !policy.allowlist.includes(to)) {
+        return {
+            decision: 'deny',
+            rule: 'allowlist',
+            reason: `recipient ${to} is not on the allowlist`,
+            errorCode: 'recipient_not_allowed',
+            data: { address: to },
+        };
+    }
+    if (policy.perTxLimitSats !== undefined && amountSats > policy.perTxLimitSats) {
+        return {
+            decision: 'deny',
+            rule: 'per_tx_limit_sats',
+            reason: `amount ${formatSats(amountSats)} exceeds the hard per-transaction limit of ${formatSats(policy.perTxLimitSats)}`,
+            errorCode: 'per_tx_limit_exceeded',
+            data: { limit_sats: policy.perTxLimitSats, amount_sats: amountSats },
+        };
+    }
+    if (policy.softPerTxLimitSats !== undefined &&
+        amountSats >= policy.softPerTxLimitSats &&
+        !req.softLimitConfirmed) {
+        // Legacy confirmable limit — byte-compatible with pre-policy behavior.
+        return {
+            decision: 'deny',
+            rule: 'spend_limit',
+            reason: `amount ${formatSats(amountSats)} is at/above the ${formatSats(policy.softPerTxLimitSats)} per-transaction limit`,
+            errorCode: 'spend_limit_exceeded',
+            data: { limit_sats: policy.softPerTxLimitSats, amount_sats: amountSats },
+        };
+    }
+    if (policy.sessionBudgetSats !== undefined) {
+        const remaining = policy.sessionBudgetSats - usage.sessionSpentSats;
+        if (amountSats > remaining) {
+            return {
+                decision: 'deny',
+                rule: 'session_budget_sats',
+                reason: `amount ${formatSats(amountSats)} exceeds the remaining session budget of ${formatSats(Math.max(0, remaining))}`,
+                errorCode: 'session_budget_exceeded',
+                data: {
+                    budget_sats: policy.sessionBudgetSats,
+                    spent_sats: usage.sessionSpentSats,
+                    remaining_sats: Math.max(0, remaining),
+                    amount_sats: amountSats,
+                },
+            };
+        }
+    }
+    if (policy.dailyBudgetSats !== undefined) {
+        const remaining = policy.dailyBudgetSats - usage.dailySpentSats;
+        if (amountSats > remaining) {
+            return {
+                decision: 'deny',
+                rule: 'daily_budget_sats',
+                reason: `amount ${formatSats(amountSats)} exceeds the remaining 24h budget of ${formatSats(Math.max(0, remaining))}`,
+                errorCode: 'daily_budget_exceeded',
+                data: {
+                    budget_sats: policy.dailyBudgetSats,
+                    spent_sats: usage.dailySpentSats,
+                    remaining_sats: Math.max(0, remaining),
+                    amount_sats: amountSats,
+                },
+            };
+        }
+    }
+    if (policy.rateLimitPerMinute !== undefined &&
+        usage.sendsLastMinute >= policy.rateLimitPerMinute) {
+        return {
+            decision: 'deny',
+            rule: 'rate_limit_per_minute',
+            reason: `rate limit reached: ${usage.sendsLastMinute} payment(s) in the last minute (max ${policy.rateLimitPerMinute})`,
+            errorCode: 'rate_limit_exceeded',
+            data: { limit: policy.rateLimitPerMinute, window: 'minute', sent: usage.sendsLastMinute },
+        };
+    }
+    if (policy.rateLimitPerHour !== undefined && usage.sendsLastHour >= policy.rateLimitPerHour) {
+        return {
+            decision: 'deny',
+            rule: 'rate_limit_per_hour',
+            reason: `rate limit reached: ${usage.sendsLastHour} payment(s) in the last hour (max ${policy.rateLimitPerHour})`,
+            errorCode: 'rate_limit_exceeded',
+            data: { limit: policy.rateLimitPerHour, window: 'hour', sent: usage.sendsLastHour },
+        };
+    }
+    if (policy.approvalThresholdSats !== undefined && amountSats >= policy.approvalThresholdSats) {
+        return {
+            decision: 'queue',
+            rule: 'approval_threshold_sats',
+            reason: `amount ${formatSats(amountSats)} is at/above the ${formatSats(policy.approvalThresholdSats)} approval threshold`,
+            data: { threshold_sats: policy.approvalThresholdSats, amount_sats: amountSats },
+        };
+    }
+    return { decision: 'allow', rule: 'default', reason: 'within policy' };
+}
+function throwVerdict(verdict, extra) {
+    if (verdict.decision === 'deny') {
+        throw new CliError(EXIT.SPEND_LIMIT, verdict.errorCode, `Denied by policy (${verdict.rule}): ${verdict.reason}.`, { rule: verdict.rule, ...verdict.data, ...extra });
+    }
+    throw new CliError(EXIT.PENDING_APPROVAL, 'pending_approval', `Queued for human approval (${verdict.rule}): ${verdict.reason}. Run "bsv-pay approvals list" to review.`, { rule: verdict.rule, ...verdict.data, ...extra });
+}
+/**
+ * Decide a spend. Returns an authorization on allow; throws exit 8 on deny
+ * and exit 9 on queue (after recording the decision — and, for queues, the
+ * approval — in the ledger when mode is enforce).
+ */
+export function authorizeSpend(env, req, opts) {
+    const policy = loadPolicy(env.network, env.config);
+    const verdict = evaluateSpend(policy, readUsage(env.network), req);
+    return settle(env, req, verdict, opts.mode);
+}
+/**
+ * Decide a previously queued spend in approval context: every rule except
+ * the approval threshold still applies at approval time. Called ONLY by the
+ * approvals command after the human passed the TTY + approval-secret gate;
+ * not exported from the core public surface.
+ */
+export function authorizeApprovedSpend(env, req, approvalId) {
+    const policy = loadPolicy(env.network, env.config);
+    const withoutThreshold = { ...policy, approvalThresholdSats: undefined };
+    const verdict = evaluateSpend(withoutThreshold, readUsage(env.network), req);
+    if (verdict.decision === 'allow') {
+        return settle(env, req, { decision: 'allow', rule: 'approval', reason: `human-approved ${approvalId}` }, 'enforce');
+    }
+    return settle(env, req, verdict, 'enforce', approvalId);
+}
+function settle(env, req, verdict, mode, approvalId) {
+    const decisionId = crypto.randomUUID();
+    if (mode === 'evaluate') {
+        if (verdict.decision !== 'allow')
+            throwVerdict(verdict);
+        return { decisionId, to: req.to, amountSats: req.amountSats, evaluateOnly: true };
+    }
+    const base = {
+        type: 'policy_decision',
+        rule: verdict.rule,
+        reason: verdict.reason,
+        address: req.to,
+        amount_sats: req.amountSats,
+        memo: req.memo,
+        timestamp: new Date().toISOString(),
+        decision_id: decisionId,
+    };
+    if (verdict.decision === 'allow') {
+        appendLedger(env.network, { ...base, decision: 'allow' });
+        return { decisionId, to: req.to, amountSats: req.amountSats, evaluateOnly: false };
+    }
+    if (verdict.decision === 'deny') {
+        appendLedger(env.network, { ...base, decision: 'deny' });
+        throwVerdict(verdict);
+    }
+    const newApprovalId = approvalId ?? crypto.randomUUID();
+    appendLedger(env.network, {
+        ...base,
+        decision: 'queue',
+        approval_id: newApprovalId,
+        confirmed_only: req.confirmedOnly,
+    });
+    throwVerdict(verdict, { approval_id: newApprovalId });
+}
+/**
+ * Unforgeable plan registry: planSend records each authorized plan here;
+ * executeSend refuses anything missing, mismatched, evaluate-only, or
+ * already executed (one authorization = one broadcast). Module-private and
+ * NOT exported from bsv-pay/core — a hand-built plan can never pass.
+ */
+const authorizedPlans = new WeakMap();
+export function registerAuthorizedPlan(plan, auth) {
+    authorizedPlans.set(plan, auth);
+}
+export function takeAuthorizedPlan(plan, expected, forBroadcast) {
+    const auth = authorizedPlans.get(plan);
+    if (!auth || auth.to !== expected.to || auth.amountSats !== expected.amountSats) {
+        throw new CliError(EXIT.SPEND_LIMIT, 'unauthorized_spend', 'This spend was not authorized by the policy gate. Plans must come from planSend(); they cannot be constructed or altered by hand.');
+    }
+    if (forBroadcast) {
+        if (auth.evaluateOnly) {
+            throw new CliError(EXIT.SPEND_LIMIT, 'unauthorized_spend', 'This plan was authorized for a dry run only. Re-plan without dryRun to broadcast.');
+        }
+        authorizedPlans.delete(plan); // consumed: one authorization, one broadcast
+    }
+    return auth;
+}

package/dist/policy/policy.d.ts

@@ -0,0 +1,30 @@
+import type { Config } from '../config.js';
+import { type Network } from '../paths.js';
+/**
+ * The active spend policy. With no policy.toml, `source` is "defaults" and
+ * the ONLY rule is the legacy soft per-tx limit from config.spendLimitSats
+ * (confirmable interactively / --allow-large) — current behavior exactly.
+ * When policy.toml exists, per_tx_limit_sats (if set) is a HARD limit no
+ * flag can cross; the soft limit applies only when the file omits it.
+ */
+export interface Policy {
+    source: 'defaults' | 'file';
+    /** Hard per-transaction cap (policy.toml). No override exists. */
+    perTxLimitSats?: number;
+    /** Legacy confirmable limit from config.toml (pre-policy behavior). */
+    softPerTxLimitSats?: number;
+    /** Rolling 24h spend cap, computed from the ledger at decision time. */
+    dailyBudgetSats?: number;
+    /** Per-process spend cap (meaningful for long-running consumers). */
+    sessionBudgetSats?: number;
+    rateLimitPerMinute?: number;
+    rateLimitPerHour?: number;
+    /** At/above this, spends queue for human approval instead of sending. */
+    approvalThresholdSats?: number;
+    /** When non-empty, only these recipients are allowed. */
+    allowlist: string[];
+    /** Always wins over everything else. */
+    denylist: string[];
+}
+export declare function resetPolicyCacheForTests(): void;
+export declare function loadPolicy(network: Network, config: Config): Policy;

package/dist/policy/policy.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import { Utils } from '@bsv/sdk';
+import { parse as parseToml } from 'smol-toml';
+import { usageError } from '../errors.js';
+import { baseDir, policyPath } from '../paths.js';
+const RULE_KEYS = [
+    'per_tx_limit_sats',
+    'daily_budget_sats',
+    'session_budget_sats',
+    'rate_limit_per_minute',
+    'rate_limit_per_hour',
+    'approval_threshold_sats',
+    'allowlist',
+    'denylist',
+];
+function invalidPolicy(message) {
+    throw usageError('invalid_policy', `${message} Fix ${policyPath()}.`);
+}
+function asSats(value, key) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        invalidPolicy(`Policy key "${key}" must be a non-negative integer of satoshis.`);
+    }
+    return value;
+}
+function asAddressList(value, key) {
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+        invalidPolicy(`Policy key "${key}" must be an array of address strings.`);
+    }
+    const list = value;
+    for (const address of list) {
+        try {
+            Utils.fromBase58Check(address);
+        }
+        catch {
+            // A typo'd denylist entry would silently never match — fail loudly instead.
+            invalidPolicy(`Policy ${key} entry "${address}" is not a valid address (checksum failed).`);
+        }
+    }
+    return list;
+}
+function rejectUnknownKeys(doc, allowed) {
+    for (const key of Object.keys(doc)) {
+        if (!allowed.includes(key)) {
+            // An ignored typo like "daily_budget_stas" would mean NO budget — unsafe.
+            invalidPolicy(`Unknown policy key "${key}".`);
+        }
+    }
+}
+function applyRules(policy, doc) {
+    if ('per_tx_limit_sats' in doc)
+        policy.perTxLimitSats = asSats(doc.per_tx_limit_sats, 'per_tx_limit_sats');
+    if ('daily_budget_sats' in doc)
+        policy.dailyBudgetSats = asSats(doc.daily_budget_sats, 'daily_budget_sats');
+    if ('session_budget_sats' in doc)
+        policy.sessionBudgetSats = asSats(doc.session_budget_sats, 'session_budget_sats');
+    if ('rate_limit_per_minute' in doc)
+        policy.rateLimitPerMinute = asSats(doc.rate_limit_per_minute, 'rate_limit_per_minute');
+    if ('rate_limit_per_hour' in doc)
+        policy.rateLimitPerHour = asSats(doc.rate_limit_per_hour, 'rate_limit_per_hour');
+    if ('approval_threshold_sats' in doc)
+        policy.approvalThresholdSats = asSats(doc.approval_threshold_sats, 'approval_threshold_sats');
+    if ('allowlist' in doc)
+        policy.allowlist = asAddressList(doc.allowlist, 'allowlist');
+    if ('denylist' in doc)
+        policy.denylist = asAddressList(doc.denylist, 'denylist');
+}
+/**
+ * Cached per process (key: state dir + network): limits change only when a
+ * human edits policy.toml AND the process restarts (invariant 2) — a
+ * long-running MCP server does not pick up live edits.
+ */
+const cache = new Map();
+export function resetPolicyCacheForTests() {
+    cache.clear();
+}
+export function loadPolicy(network, config) {
+    // spendLimitSats participates: the synthesized default policy depends on it.
+    const cacheKey = `${baseDir()}::${network}::${config.spendLimitSats}`;
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const file = policyPath();
+    let policy;
+    if (!fs.existsSync(file)) {
+        policy = {
+            source: 'defaults',
+            softPerTxLimitSats: config.spendLimitSats,
+            allowlist: [],
+            denylist: [],
+        };
+    }
+    else {
+        let doc;
+        try {
+            doc = parseToml(fs.readFileSync(file, 'utf8'));
+        }
+        catch (e) {
+            invalidPolicy(`Cannot parse policy.toml: ${e instanceof Error ? e.message : String(e)}.`);
+        }
+        rejectUnknownKeys(doc, [...RULE_KEYS, 'network']);
+        policy = { source: 'file', allowlist: [], denylist: [] };
+        applyRules(policy, doc);
+        // Optional [network.main] / [network.test] override tables.
+        if ('network' in doc) {
+            const networks = doc.network;
+            if (typeof networks !== 'object' || networks === null || Array.isArray(networks)) {
+                invalidPolicy('Policy [network] must be a table of per-network overrides.');
+            }
+            rejectUnknownKeys(networks, ['main', 'test']);
+            const override = networks[network];
+            if (override !== undefined) {
+                if (typeof override !== 'object' || override === null || Array.isArray(override)) {
+                    invalidPolicy(`Policy [network.${network}] must be a table.`);
+                }
+                rejectUnknownKeys(override, RULE_KEYS);
+                applyRules(policy, override);
+            }
+        }
+        // Keep the legacy config limit working when the file doesn't set a hard one.
+        if (policy.perTxLimitSats === undefined) {
+            policy.softPerTxLimitSats = config.spendLimitSats;
+        }
+    }
+    cache.set(cacheKey, policy);
+    return policy;
+}

package/dist/prompt.d.ts

@@ -0,0 +1,11 @@
+/**
+ * All prompts write to stderr so --json stdout stays machine-clean
+ * (invariant 2).
+ */
+export declare function isInteractive(): boolean;
+export declare function ask(question: string): Promise<string>;
+/** Prompt without echoing the typed characters (passphrases). */
+export declare function askHidden(question: string): Promise<string>;
+export declare function confirm(question: string, def?: boolean): Promise<boolean>;
+/** Read all of stdin (for piped seed phrases / passphrases in scripts). */
+export declare function readStdinLine(): Promise<string>;

package/dist/prompt.js

@@ -0,0 +1,57 @@
+import readline from 'node:readline';
+/**
+ * All prompts write to stderr so --json stdout stays machine-clean
+ * (invariant 2).
+ */
+export function isInteractive() {
+    return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}
+export function ask(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/** Prompt without echoing the typed characters (passphrases). */
+export function askHidden(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+    });
+    let muted = false;
+    // readline has no public mute API; overriding _writeToOutput is the
+    // long-standing supported workaround.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rl._writeToOutput = (s) => {
+        if (!muted)
+            process.stderr.write(s);
+    };
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            muted = false;
+            rl.close();
+            process.stderr.write('\n');
+            resolve(answer);
+        });
+        muted = true;
+    });
+}
+export async function confirm(question, def = false) {
+    const suffix = def ? ' (Y/n) ' : ' (y/N) ';
+    const answer = (await ask(question + suffix)).toLowerCase();
+    if (answer === '')
+        return def;
+    return answer === 'y' || answer === 'yes';
+}
+/** Read all of stdin (for piped seed phrases / passphrases in scripts). */
+export async function readStdinLine() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const text = Buffer.concat(chunks).toString('utf8');
+    return (text.split('\n')[0] ?? '').trim();
+}