@forum-labs/payfetch 1.0.0

package/dist/src/guards/types.d.ts

@@ -0,0 +1,59 @@
+import type { PayfetchDeps, PaymentQuote } from "../payer/types.js";
+export type GuardId = "trust" | "safety";
+export interface PrePayGuard {
+    id: GuardId;
+    applies(req: GuardInput): boolean;
+    check(req: GuardInput, deps: PayfetchDeps): Promise<GuardResult>;
+}
+export type GuardInput = {
+    url: string;
+    host: string;
+    quote: PaymentQuote;
+    context: {
+        tokenAddress?: string;
+        chain?: "solana" | "base" | "ethereum";
+    };
+    dryRun?: boolean;
+    config?: TrustGuardConfig | SafetyGuardConfig;
+};
+export type GuardResult = {
+    id: string;
+    verdict: "pass" | "warn" | "block" | "unavailable";
+    detail: Record<string, unknown>;
+    latencyMs: number;
+    costUsd: number;
+};
+export type TrustGuardConfig = {
+    enabled: boolean;
+    mode: "advisory" | "enforce";
+    minScore: number | null;
+    blockVerdicts: string[];
+    blockUnrated: boolean;
+    onUnavailable: "proceed" | "block";
+    dailyBudgetUsd: number;
+};
+export type SafetyGuardConfig = {
+    enabled: boolean;
+    mode: "advisory" | "enforce";
+    depth: "basic" | "deep";
+    blockVerdicts: string[];
+    blockDeployerVerdicts: string[];
+    onUnavailable: "proceed" | "block";
+    onDegraded: "block" | "warn" | "proceed";
+    dailyBudgetUsd: number;
+};
+export declare const DEFAULT_TRUST_GUARD_CONFIG: TrustGuardConfig;
+export declare const DEFAULT_SAFETY_GUARD_CONFIG: SafetyGuardConfig;
+export type GuardRuntime = {
+    guardFetch: (url: string, init: RequestInit, opts?: {
+        dryRun?: boolean;
+    }) => Promise<Response>;
+    now: () => number;
+    log: PayfetchDeps["log"];
+    installId8: string;
+    via: string | null;
+    baseUrls: {
+        trust: string | null;
+        safety: string | null;
+    };
+};

package/dist/src/guards/types.js

@@ -0,0 +1,20 @@
+import { GUARD_DAILY_BUDGET_DEFAULT_USD, SAFETY_BLOCK_DEPLOYER_VERDICTS_DEFAULT, SAFETY_BLOCK_VERDICTS_DEFAULT, SAFETY_GUARD_DEPTH_DEFAULT, SAFETY_ON_DEGRADED_DEFAULT, TRUST_BLOCK_VERDICTS_DEFAULT, } from "../core/constants.js";
+export const DEFAULT_TRUST_GUARD_CONFIG = Object.freeze({
+    enabled: true,
+    mode: "advisory",
+    minScore: null,
+    blockVerdicts: [...TRUST_BLOCK_VERDICTS_DEFAULT],
+    blockUnrated: false,
+    onUnavailable: "block",
+    dailyBudgetUsd: GUARD_DAILY_BUDGET_DEFAULT_USD,
+});
+export const DEFAULT_SAFETY_GUARD_CONFIG = Object.freeze({
+    enabled: false,
+    mode: "enforce",
+    depth: SAFETY_GUARD_DEPTH_DEFAULT,
+    blockVerdicts: [...SAFETY_BLOCK_VERDICTS_DEFAULT],
+    blockDeployerVerdicts: [...SAFETY_BLOCK_DEPLOYER_VERDICTS_DEFAULT],
+    onUnavailable: "block",
+    onDegraded: SAFETY_ON_DEGRADED_DEFAULT,
+    dailyBudgetUsd: GUARD_DAILY_BUDGET_DEFAULT_USD,
+});

package/dist/src/index.d.ts

@@ -0,0 +1,58 @@
+import { type PayfetchFs } from "./core/fs.js";
+import type { Receipt } from "./core/ledger.js";
+import { type Policy } from "./core/policy.js";
+import { PayfetchEngine, type Decision, type FetchOpts, type SpendStatus } from "./core/pipeline.js";
+import { adaptFetch, parseIpv4, type HttpClient } from "./core/transport.js";
+import type { PayfetchDeps, PaymentPayer } from "./payer/types.js";
+import type { PrePayGuard } from "./guards/types.js";
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends readonly (infer U)[] ? U[] : T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+export interface Payfetch {
+    fetch(url: string, init?: RequestInit, opts?: FetchOpts): Promise<{
+        response: Response | null;
+        receipt: Receipt;
+    }>;
+    quote(url: string, init?: RequestInit): Promise<{
+        decision: Decision;
+        receipt: Receipt;
+    }>;
+    status(): Promise<SpendStatus>;
+    receipts(q: {
+        sinceTs?: number;
+        host?: string;
+        outcome?: Receipt["outcome"];
+        limit?: number;
+    }): Promise<Receipt[]>;
+    close(): void;
+    engine: PayfetchEngine;
+}
+export type CreatePayfetchOpts = {
+    deps: PayfetchDeps;
+    policy?: DeepPartial<Policy>;
+    guards?: PrePayGuard[];
+    payers?: PaymentPayer[];
+    fs?: PayfetchFs;
+    httpClient?: HttpClient;
+    resolve?: (host: string) => Promise<string[]>;
+    testMode?: boolean;
+    approver?: boolean;
+    via?: string | null;
+    delay?: (ms: number) => Promise<void>;
+    setTimer?: (fn: () => void, ms: number) => {
+        clear: () => void;
+    };
+    guardBaseUrls?: {
+        trust: string | null;
+        safety: string | null;
+    };
+};
+export declare function createPayfetch(opts: CreatePayfetchOpts): Payfetch;
+export declare function clearAutoDeny(dataDir: string, host: string, io?: {
+    fs?: PayfetchFs;
+    now?: () => number;
+}): boolean;
+export { adaptFetch, parseIpv4 };
+export type { Decision, SpendStatus, FetchOpts };
+export type { Policy } from "./core/policy.js";
+export type { Receipt } from "./core/ledger.js";

package/dist/src/index.js

@@ -0,0 +1,151 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { Readable } from "node:stream";
+import { Agent, request as undiciRequest } from "undici";
+import { P1_SAFETY_BASE_URL, P2_TRUST_BASE_URL, } from "./core/constants.js";
+import { Budget } from "./core/budget.js";
+import { realFs } from "./core/fs.js";
+import { Ledger } from "./core/ledger.js";
+import { configPath, defaultPolicy, loadPolicy, mergePolicy, } from "./core/policy.js";
+import { PayfetchEngine, } from "./core/pipeline.js";
+import { adaptFetch, createPinnedLookup, parseIpv4, } from "./core/transport.js";
+import { X402Payer } from "./payer/x402.js";
+import { createSafetyGuard, createTrustGuard } from "./guards/index.js";
+function hex32(deps) {
+    const b = deps.random();
+    let s = "";
+    for (let i = 0; i < 16; i++)
+        s += b[i].toString(16).padStart(2, "0");
+    return s;
+}
+export function createPayfetch(opts) {
+    if (!opts || !opts.deps)
+        throw new TypeError("createPayfetch: opts.deps is required");
+    const deps = opts.deps;
+    if (!deps.signer)
+        throw new TypeError("createPayfetch: deps.signer is required");
+    if (typeof deps.dataDir !== "string" || deps.dataDir.length === 0) {
+        throw new TypeError("createPayfetch: deps.dataDir is required");
+    }
+    const fs = opts.fs ?? realFs;
+    const dataDir = deps.dataDir;
+    const testMode = opts.testMode ?? process.env.PAYFETCH_TEST_MODE != null;
+    const approver = opts.approver ?? process.env.PAYFETCH_APPROVER === "1";
+    const via = opts.via ?? null;
+    const guardBaseUrls = opts.guardBaseUrls ?? { trust: P2_TRUST_BASE_URL, safety: P1_SAFETY_BASE_URL };
+    const ledger = new Ledger(fs, dataDir, deps.now);
+    ledger.acquireLock();
+    let state = ledger.loadStateRaw();
+    if (!state) {
+        state = ledger.rebuildState(hex32(deps));
+        ledger.saveState(state);
+    }
+    const budget = new Budget(state, ledger, deps.now);
+    const basePolicy = mergePolicy(defaultPolicy(), opts.policy);
+    let cached = {
+        ok: true,
+        policy: basePolicy,
+    };
+    let lastMtime = null;
+    const reload = () => {
+        const load = loadPolicy(dataDir, { fs, log: deps.log }, basePolicy);
+        if (load.ok) {
+            cached = { ok: true, policy: load.policy };
+            lastMtime = load.mtimeMs;
+        }
+        else {
+            cached = { ok: false, error: load.error };
+        }
+    };
+    reload();
+    const policyProvider = () => {
+        const cur = fs.statMtimeMs(configPath(dataDir));
+        if (cur !== lastMtime)
+            reload();
+        return cached;
+    };
+    const resolve = opts.resolve ?? defaultResolve;
+    const initialPolicy = cached.ok ? cached.policy : basePolicy;
+    const httpClient = opts.httpClient ??
+        createPinnedHttpClient(resolve, { allowPrivateTargets: initialPolicy.allowPrivateTargets });
+    const engine = new PayfetchEngine({
+        deps,
+        fs,
+        ledger,
+        budget,
+        payers: opts.payers ?? [new X402Payer()],
+        policyProvider,
+        transportIo: { request: httpClient, resolve, setTimer: opts.setTimer },
+        testMode,
+        approverEnabled: approver,
+        delay: opts.delay,
+        guardBaseUrls,
+        via,
+    });
+    engine.guards =
+        opts.guards ?? buildDefaultGuards(engine, initialPolicy, state.installId, via, guardBaseUrls, deps);
+    return {
+        fetch: (url, init, o) => engine.fetch(url, init, o),
+        quote: (url, init) => engine.quote(url, init),
+        status: () => engine.status(),
+        receipts: async (q) => engine.receipts(q),
+        close: () => ledger.releaseLock(),
+        engine,
+    };
+}
+function buildDefaultGuards(engine, policy, installId, via, baseUrls, deps) {
+    const rtFor = (id, baseUrl) => ({
+        guardFetch: engine.makeGuardFetch(id, () => engine.liveGuardBudgetUsd(id), baseUrl),
+        now: deps.now,
+        log: deps.log,
+        installId8: installId.slice(0, 8),
+        via,
+        baseUrls,
+    });
+    const trust = createTrustGuard(policy.guards.trust, rtFor("trust", baseUrls.trust));
+    const safety = createSafetyGuard(policy.guards.safety, rtFor("safety", baseUrls.safety));
+    return [trust, safety];
+}
+export function clearAutoDeny(dataDir, host, io = {}) {
+    const fs = io.fs ?? realFs;
+    const now = io.now ?? (() => Date.now());
+    const ledger = new Ledger(fs, dataDir, now);
+    const state = ledger.loadStateRaw() ?? ledger.rebuildState("0".repeat(32));
+    const budget = new Budget(state, ledger, now);
+    return budget.clearAutoDeny(host);
+}
+async function defaultResolve(host) {
+    try {
+        const res = await dnsLookup(host, { all: true });
+        return res.map((r) => r.address);
+    }
+    catch {
+        return [];
+    }
+}
+function createPinnedHttpClient(resolve, policy) {
+    const agent = new Agent({
+        connect: { lookup: createPinnedLookup(resolve, policy) },
+    });
+    const client = async (url, init) => {
+        const res = await undiciRequest(url, {
+            method: init.method,
+            headers: init.headers,
+            body: init.body ?? undefined,
+            dispatcher: agent,
+            signal: init.signal,
+        });
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(res.headers)) {
+            if (Array.isArray(v))
+                headers.set(k, v.join(", "));
+            else if (v != null)
+                headers.set(k, String(v));
+        }
+        const body = res.body
+            ? Readable.toWeb(res.body)
+            : null;
+        return { status: res.statusCode, headers, body };
+    };
+    return client;
+}
+export { adaptFetch, parseIpv4 };

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,6 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ElicitFn } from "../payer/types.js";
+import { type ConfigIo, type EnvRecord } from "../config.js";
+export declare const MCP_SERVER_NAME = "payfetch";
+export declare function makeElicitBridge(server: Server): ElicitFn;
+export declare function runStdioServer(env?: EnvRecord, io?: ConfigIo): Promise<void>;

package/dist/src/mcp/server.js

@@ -0,0 +1,125 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { CLIENT_VERSION, USDC_DECIMALS } from "../core/constants.js";
+import { createPayfetch } from "../index.js";
+import { ConfigError, buildFromEnv, realConfigIo, scrubSecrets, } from "../config.js";
+import { PAYFETCH_TOOLS, UnknownToolError, dispatchTool, } from "./tools.js";
+export const MCP_SERVER_NAME = "payfetch";
+export function makeElicitBridge(server) {
+    return async (req) => {
+        const result = await server.elicitInput({
+            message: buildElicitMessage(req),
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    approve: {
+                        type: "boolean",
+                        title: "Approve this payment",
+                        description: "Approve this SINGLE payment (false = deny). This authorizes one payment only; it does not change any spending limit or list.",
+                    },
+                },
+                required: ["approve"],
+            },
+        });
+        if (result.action === "accept") {
+            return { approved: result.content?.approve === true, cancelled: false };
+        }
+        if (result.action === "decline") {
+            return { approved: false, cancelled: false };
+        }
+        return { approved: false, cancelled: true };
+    };
+}
+function fmtUsd(n) {
+    return `$${n.toFixed(USDC_DECIMALS)}`;
+}
+function buildElicitMessage(req) {
+    const lines = [];
+    lines.push(`Approve a payment of ${fmtUsd(req.amountUsd)} to ${req.host}?`);
+    lines.push(`Resource: ${req.resource ?? "(unspecified)"}`);
+    lines.push(`Network / asset: ${req.networkLabel} / ${req.assetLabel}`);
+    const guards = req.guards;
+    if (guards.length > 0) {
+        lines.push("Trust / safety checks:");
+        for (const g of guards) {
+            const score = typeof g.detail?.score === "number" ? ` (score ${g.detail.score})` : "";
+            lines.push(`  - ${g.id}: ${g.verdict}${score}`);
+        }
+    }
+    const b = req.remainingBudgets;
+    const totalStr = b.totalRemainingUsd == null ? "unset" : fmtUsd(b.totalRemainingUsd);
+    lines.push(`Remaining today — day: ${fmtUsd(b.dayRemainingUsd)}, host: ${fmtUsd(b.hostRemainingUsd)}, total: ${totalStr}`);
+    lines.push("Approving authorizes THIS payment only. Spending limits are set by the operator's config and cannot be changed here.");
+    return lines.join("\n");
+}
+function registerHandlers(server, ctx) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: PAYFETCH_TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name } = request.params;
+        const rawArgs = (request.params.arguments ?? {});
+        try {
+            const output = await dispatchTool(ctx, name, rawArgs);
+            return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+        }
+        catch (err) {
+            if (err instanceof UnknownToolError) {
+                throw new McpError(ErrorCode.MethodNotFound, err.message);
+            }
+            const message = scrubSecrets(String(err?.message ?? err), []);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+                isError: true,
+            };
+        }
+    });
+}
+export async function runStdioServer(env = process.env, io = realConfigIo()) {
+    const opts = buildFromEnv(env, io);
+    const server = new Server({ name: MCP_SERVER_NAME, version: CLIENT_VERSION }, { capabilities: { tools: {} } });
+    opts.deps.elicit = makeElicitBridge(server);
+    const pf = createPayfetch(opts);
+    if (opts.approver === true && pf.engine.queueCapableNow()) {
+        pf.close();
+        throw new ConfigError("payfetch: refusing to start — PAYFETCH_APPROVER=1 with a queue-capable " +
+            "approval mode (approval.mode 'queue', or 'elicit' with elicitFallback " +
+            "'queue') lets the tool-driven agent approve its own payments (no " +
+            "requester/approver separation). Use approval.mode 'elicit' with " +
+            "elicitFallback 'deny' (human-in-the-loop via MCP elicitation), or start " +
+            "without PAYFETCH_APPROVER=1. (security fix M6)");
+    }
+    const ctx = { pf, dataDir: opts.deps.dataDir };
+    registerHandlers(server, ctx);
+    let closed = false;
+    const shutdown = () => {
+        if (closed)
+            return;
+        closed = true;
+        try {
+            pf.close();
+        }
+        catch {
+        }
+    };
+    server.onclose = shutdown;
+    process.once("SIGINT", () => {
+        shutdown();
+        process.exit(0);
+    });
+    process.once("SIGTERM", () => {
+        shutdown();
+        process.exit(0);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const clientCaps = server.getClientCapabilities();
+    if (!clientCaps || !clientCaps.elicitation) {
+        opts.deps.elicit = null;
+    }
+}

package/dist/src/mcp/tools.d.ts

@@ -0,0 +1,46 @@
+import type { Payfetch } from "../index.js";
+export declare const TOOL_NAMES: {
+    readonly PAID_FETCH: "paid_fetch";
+    readonly PAYMENT_QUOTE: "payment_quote";
+    readonly SPEND_STATUS: "spend_status";
+    readonly LIST_RECEIPTS: "list_receipts";
+    readonly APPROVE_PENDING: "approve_pending";
+};
+export declare const TOOL_DESCRIPTIONS: {
+    readonly paid_fetch: "Fetch a URL, automatically paying if it requires payment (HTTP 402, x402 protocol) — within the operator's spending policy. Free URLs are fetched normally at no cost. Use payment_quote first if you only want to know the price. Payments above the operator's approval threshold will ask the human for confirmation.";
+    readonly payment_quote: "Check what a paid URL costs and whether the current spending policy would allow paying it, WITHOUT paying. Returns the price, payment terms, trust-check results, and the policy decision.";
+    readonly spend_status: "Show today's agent spending: totals, remaining budgets overall and per host, active holds, and recent payments.";
+    readonly list_receipts: "Query the local payment receipt ledger (audit trail). Filter by time, host, or outcome.";
+    readonly approve_pending: "List or resolve payments waiting for human approval (queue mode). Approving grants a one-time re-run permission for that exact payment.";
+};
+export type JsonSchema = {
+    type: "object";
+    properties?: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+};
+export declare const PAID_FETCH_INPUT_SCHEMA: JsonSchema;
+export declare const PAYMENT_QUOTE_INPUT_SCHEMA: JsonSchema;
+export declare const SPEND_STATUS_INPUT_SCHEMA: JsonSchema;
+export declare const LIST_RECEIPTS_INPUT_SCHEMA: JsonSchema;
+export declare const APPROVE_PENDING_INPUT_SCHEMA: JsonSchema;
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+};
+export declare const PAYFETCH_TOOLS: readonly ToolDefinition[];
+export declare function policyLockNotice(dataDir: string): string;
+export declare class UnknownToolError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
+export declare class ToolInputError extends Error {
+    constructor(message: string);
+}
+export type ToolContext = {
+    pf: Payfetch;
+    dataDir: string;
+};
+export declare function dispatchTool(ctx: ToolContext, name: string, args: Record<string, unknown>): Promise<unknown>;
+export declare const USD_DISPLAY_DECIMALS = 6;