@runtab/mcp 0.0.1

package/dist/payment-target-network.js

@@ -0,0 +1,178 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+import { Agent, buildConnector } from "undici";
+import { isLoopbackPaymentHostname, PaymentTargetPolicyError, safePaymentRequestInit, validatePaymentTarget, } from "./payment-target-policy.js";
+const DNS_TIMEOUT_MS = 3_000;
+const MAX_DNS_ANSWERS = 16;
+const MAX_PINNED_HOSTS = 128;
+const blockedIpv4 = new BlockList();
+for (const [network, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+]) {
+    blockedIpv4.addSubnet(network, prefix, "ipv4");
+}
+const blockedIpv6 = new BlockList();
+for (const [network, prefix] of [
+    ["::", 128],
+    ["::1", 128],
+    ["::ffff:0:0", 96],
+    ["100::", 64],
+    ["2001::", 32],
+    ["2001:2::", 48],
+    ["2001:10::", 28],
+    ["2001:20::", 28],
+    ["2001:db8::", 32],
+    ["2002::", 16],
+    ["fc00::", 7],
+    ["fe80::", 10],
+    ["fec0::", 10],
+    ["ff00::", 8],
+]) {
+    blockedIpv6.addSubnet(network, prefix, "ipv6");
+}
+function normalizeHostname(value) {
+    const lower = value.toLowerCase();
+    return lower.startsWith("[") && lower.endsWith("]") ? lower.slice(1, -1) : lower;
+}
+function loopbackAddress(value) {
+    const address = normalizeHostname(value);
+    if (address === "::1")
+        return true;
+    return isIP(address) === 4 && Number(address.split(".")[0]) === 127;
+}
+function publicAddress(value, family) {
+    const address = normalizeHostname(value);
+    if (isIP(address) !== family)
+        return false;
+    if (family === 4)
+        return !blockedIpv4.check(address, "ipv4");
+    return /^[23]/.test(address) && !blockedIpv6.check(address, "ipv6");
+}
+const defaultLookup = async (hostname) => {
+    const answers = await dnsLookup(hostname, { all: true, verbatim: true });
+    return answers.flatMap((answer) => answer.family === 4 || answer.family === 6
+        ? [{ address: answer.address, family: answer.family }]
+        : []);
+};
+async function boundedLookup(lookup, hostname) {
+    let timeout;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => reject(new PaymentTargetPolicyError()), DNS_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([lookup(hostname), deadline]);
+    }
+    catch {
+        throw new PaymentTargetPolicyError();
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+export function createPinnedPaymentFetch(options) {
+    const allowDevelopmentLoopback = options.allowDevelopmentLoopback === true;
+    const lookup = options.lookup ?? defaultLookup;
+    const maxPinnedHosts = options.maxPinnedHosts ?? MAX_PINNED_HOSTS;
+    if (!Number.isSafeInteger(maxPinnedHosts) || maxPinnedHosts < 1 || maxPinnedHosts > 1_024) {
+        throw new Error("Payment target pin capacity is invalid");
+    }
+    const pins = new Map();
+    const resolving = new Map();
+    const connector = buildConnector({ timeout: 10_000 });
+    const dispatcher = new Agent({
+        connections: 4,
+        connect(connectOptions, callback) {
+            const hostname = normalizeHostname(connectOptions.hostname);
+            const pin = pins.get(hostname);
+            if (!pin) {
+                callback(new PaymentTargetPolicyError(), null);
+                return;
+            }
+            connector({
+                ...connectOptions,
+                hostname: pin.address,
+                ...(connectOptions.protocol === "https:" && isIP(hostname) === 0
+                    ? { servername: hostname }
+                    : {}),
+            }, callback);
+        },
+        pipelining: 1,
+    });
+    async function resolve(url) {
+        const hostname = normalizeHostname(url.hostname);
+        const existing = pins.get(hostname);
+        if (existing)
+            return existing;
+        const active = resolving.get(hostname);
+        if (active)
+            return active;
+        const occupiedHosts = new Set([...pins.keys(), ...resolving.keys()]);
+        if (occupiedHosts.size >= maxPinnedHosts)
+            throw new PaymentTargetPolicyError();
+        const task = (async () => {
+            const family = isIP(hostname);
+            const lexicalLoopback = isLoopbackPaymentHostname(hostname);
+            let answers;
+            if (family === 4 || family === 6) {
+                answers = [{ address: hostname, family }];
+            }
+            else {
+                answers = await boundedLookup(lookup, hostname);
+            }
+            const developmentTarget = allowDevelopmentLoopback && url.protocol === "http:" && lexicalLoopback;
+            if (answers.length < 1 ||
+                answers.length > MAX_DNS_ANSWERS ||
+                answers.some((answer) => developmentTarget
+                    ? !loopbackAddress(answer.address)
+                    : !publicAddress(answer.address, answer.family))) {
+                throw new PaymentTargetPolicyError();
+            }
+            const selected = answers[0];
+            if (!selected)
+                throw new PaymentTargetPolicyError();
+            pins.set(hostname, selected);
+            return selected;
+        })();
+        resolving.set(hostname, task);
+        try {
+            return await task;
+        }
+        finally {
+            resolving.delete(hostname);
+        }
+    }
+    const fetch = async (input, init) => {
+        const rawUrl = input instanceof Request ? input.url : input.toString();
+        const url = new URL(validatePaymentTarget(rawUrl, {
+            allowDevelopmentLoopback,
+        }));
+        await resolve(url);
+        const requestInit = {
+            ...safePaymentRequestInit(init),
+            dispatcher,
+        };
+        return options.fetch(input, requestInit);
+    };
+    let closePromise;
+    return {
+        close() {
+            closePromise ??= dispatcher.close();
+            return closePromise;
+        },
+        fetch,
+    };
+}

package/dist/payment-target-policy.d.ts

@@ -0,0 +1,10 @@
+export declare class PaymentTargetPolicyError extends Error {
+    readonly code = "UNSAFE_PAYMENT_TARGET";
+    constructor();
+}
+export interface PaymentTargetPolicyOptions {
+    allowDevelopmentLoopback?: boolean;
+}
+export declare function isLoopbackPaymentHostname(hostname: string): boolean;
+export declare function validatePaymentTarget(value: string, options?: PaymentTargetPolicyOptions): string;
+export declare function safePaymentRequestInit(init?: RequestInit): RequestInit;

package/dist/payment-target-policy.js

@@ -0,0 +1,75 @@
+import { isIP } from "node:net";
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
+const PRIVATE_HOST_SUFFIXES = [".home.arpa", ".internal", ".local", ".localhost"];
+export class PaymentTargetPolicyError extends Error {
+    code = "UNSAFE_PAYMENT_TARGET";
+    constructor() {
+        super("The payment target is not permitted by Agent network policy.");
+        this.name = "PaymentTargetPolicyError";
+    }
+}
+function unbracket(hostname) {
+    return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+function privateIpv4(hostname) {
+    const parts = hostname.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part)))
+        return true;
+    const [first = 0, second = 0] = parts;
+    return (first === 0 ||
+        first === 10 ||
+        first === 127 ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && (second === 0 || second === 168)) ||
+        (first === 198 && (second === 18 || second === 19)) ||
+        first >= 224);
+}
+function privateHostname(hostname) {
+    const normalized = unbracket(hostname.toLowerCase());
+    if (LOOPBACK_HOSTS.has(normalized))
+        return true;
+    const version = isIP(normalized);
+    if (version === 4)
+        return privateIpv4(normalized);
+    if (version === 6) {
+        return !/^[23]/.test(normalized) || normalized.startsWith("2001:db8:");
+    }
+    return (!normalized.includes(".") ||
+        normalized === "metadata.google.internal" ||
+        PRIVATE_HOST_SUFFIXES.some((suffix) => normalized.endsWith(suffix)));
+}
+function loopbackHostname(hostname) {
+    const normalized = unbracket(hostname.toLowerCase());
+    if (LOOPBACK_HOSTS.has(normalized))
+        return true;
+    if (isIP(normalized) !== 4)
+        return false;
+    return Number(normalized.split(".")[0]) === 127;
+}
+export function isLoopbackPaymentHostname(hostname) {
+    return loopbackHostname(hostname);
+}
+export function validatePaymentTarget(value, options = {}) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new PaymentTargetPolicyError();
+    }
+    const loopbackDevelopment = options.allowDevelopmentLoopback === true &&
+        url.protocol === "http:" &&
+        loopbackHostname(url.hostname);
+    if ((url.protocol !== "https:" && !loopbackDevelopment) ||
+        url.username.length > 0 ||
+        url.password.length > 0 ||
+        (privateHostname(url.hostname) && !loopbackDevelopment)) {
+        throw new PaymentTargetPolicyError();
+    }
+    return url.toString();
+}
+export function safePaymentRequestInit(init) {
+    return { ...init, redirect: "error" };
+}

package/dist/proxy.d.ts

@@ -0,0 +1,47 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { SettleResponse } from "@x402/core/types";
+import type { DurableMcpPayment } from "./durable-mcp-payment.js";
+interface LeashProxyOptions {
+    payment?: DurableMcpPayment;
+    upstream: Client;
+}
+export declare function readMcpSettlementMetadata(result: unknown, expected?: {
+    amount?: string;
+    network?: string;
+}): SettleResponse | null;
+export declare function createLeashProxyServer(options: LeashProxyOptions): Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
+export {};

package/dist/proxy.js

@@ -0,0 +1,72 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { MCP_PAYMENT_META_KEY, MCP_PAYMENT_RESPONSE_META_KEY } from "@x402/mcp";
+import { detectMcpPaymentRequired } from "./detect.js";
+import { SignerNotConfiguredError } from "./errors.js";
+import { withPaymentOrigin, withPaymentResourceUrl } from "./origin-context.js";
+import { parsePaymentSettlementObservation } from "./payment-settlement-observation.js";
+import { withPaymentSignal } from "./payment-signal.js";
+function record(value) {
+    return typeof value === "object" && value !== null;
+}
+export function readMcpSettlementMetadata(result, expected = {}) {
+    if (!record(result) || !record(result._meta))
+        return null;
+    return parsePaymentSettlementObservation(result._meta[MCP_PAYMENT_RESPONSE_META_KEY], expected);
+}
+export function createLeashProxyServer(options) {
+    const server = new Server({ name: "tab-mcp", version: "0.0.1" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, (request, extra) => options.upstream.listTools(request.params, { signal: extra.signal }));
+    async function paidCall(params, context, signal) {
+        const paidResult = await options.upstream.callTool({
+            ...params,
+            _meta: {
+                ...params._meta,
+                [MCP_PAYMENT_META_KEY]: context.payload,
+            },
+        }, undefined, { signal });
+        const settlement = readMcpSettlementMetadata(paidResult, {
+            amount: context.payload.accepted.amount,
+            network: context.payload.accepted.network,
+        });
+        if (settlement)
+            await options.payment?.observe(context, settlement);
+        return paidResult;
+    }
+    server.setRequestHandler(CallToolRequestSchema, (request, extra) => {
+        const signal = AbortSignal.any([extra.signal, AbortSignal.timeout(30_000)]);
+        return withPaymentSignal(signal, () => withPaymentOrigin({
+            clientName: server.getClientVersion()?.name ?? "Unknown client",
+            toolName: request.params.name,
+            transport: "mcp",
+        }, async () => {
+            const pending = await options.payment?.load(request.params);
+            if (pending)
+                return paidCall(request.params, pending, signal);
+            let challenge = null;
+            let initialResult;
+            try {
+                initialResult = await options.upstream.callTool(request.params, undefined, {
+                    signal,
+                });
+                challenge = detectMcpPaymentRequired(initialResult);
+            }
+            catch (error) {
+                challenge = detectMcpPaymentRequired(error);
+                if (!challenge)
+                    throw error;
+            }
+            if (!challenge) {
+                if (!initialResult)
+                    throw new Error("Upstream tool returned no result");
+                return initialResult;
+            }
+            const payment = options.payment;
+            if (!payment)
+                throw new SignerNotConfiguredError();
+            const context = await withPaymentResourceUrl(challenge.resource.url, () => payment.create(request.params, challenge));
+            return paidCall(request.params, context, signal);
+        }));
+    });
+    return server;
+}

package/dist/remote-signer-http.d.ts

@@ -0,0 +1,16 @@
+export declare class RemoteSignerError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+export declare function readRemoteSignerJson(response: Response, signal?: AbortSignal): Promise<unknown>;
+interface SignerPostOptions {
+    apiKey: string;
+    body: unknown;
+    endpoint: URL;
+    fetch: typeof globalThis.fetch;
+    signal?: AbortSignal;
+    timeoutMs: number;
+}
+export declare function postRemoteSignerJson(options: SignerPostOptions): Promise<unknown>;
+export {};

package/dist/remote-signer-http.js

@@ -0,0 +1,182 @@
+const MAX_SIGNER_RESPONSE_BYTES = 64 * 1_024;
+const SAFE_SERVER_MESSAGES = {
+    AGENT_CANCELLED: "The signing request cannot proceed.",
+    AGENT_FROZEN: "The signing request cannot proceed.",
+    AGENT_PAUSED: "The signing request cannot proceed.",
+    AUTHORIZATION_EXPIRED: "The signing authorization has expired.",
+    CAP_CYCLE_CHANGED: "The signing request cannot proceed.",
+    FLOAT_CHECK_UNAVAILABLE: "The agent balance could not be verified.",
+    FLOAT_EMPTY: "The agent does not have enough available funds.",
+    INVALID_AGENT_KEY: "The agent key was rejected.",
+    INVALID_SIGN_REQUEST: "The signing request is invalid.",
+    CAP_EXCEEDED: "The signing request exceeds the active cap.",
+    CAP_NOT_SET: "The agent does not have an active cap.",
+    SIGNER_IDENTITY_MISMATCH: "The signing provider returned the wrong identity.",
+    SIGNER_NOT_CONFIGURED: "Agent signing is not configured for this agent.",
+    SIGNER_PROVIDER_INVALID_RESPONSE: "The signing provider returned an invalid response.",
+    SIGNER_PROVIDER_RATE_LIMITED: "The signing provider is rate limited.",
+    SIGNER_PROVIDER_REJECTED: "The signing provider rejected the request.",
+    SIGNER_PROVIDER_TIMEOUT: "The signing provider timed out.",
+    SIGNER_PROVIDER_UNAVAILABLE: "The signing provider is unavailable.",
+    SIGN_RATE_LIMITED: "Signing is temporarily rate limited.",
+    SIGN_REQUEST_CONFLICT: "The signing request conflicts with an existing request.",
+    SIGN_REQUEST_IN_PROGRESS: "A matching signing request is already in progress.",
+    SIGN_REQUEST_RECONCILING: "A matching signing request is being reconciled.",
+};
+export class RemoteSignerError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "RemoteSignerError";
+    }
+}
+function invalidResponse() {
+    throw new RemoteSignerError("INVALID_SIGNER_RESPONSE", "The signer response is invalid.", 502);
+}
+function isJsonContentType(value) {
+    if (!value)
+        return false;
+    const mediaType = value.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    return (mediaType === "application/json" || /^application\/[a-z0-9!#$&^_.+-]+\+json$/.test(mediaType));
+}
+function contentLength(response) {
+    const value = response.headers.get("content-length");
+    if (value === null)
+        return null;
+    if (!/^(0|[1-9]\d*)$/.test(value))
+        invalidResponse();
+    const length = Number(value);
+    if (!Number.isSafeInteger(length))
+        invalidResponse();
+    return length;
+}
+export async function readRemoteSignerJson(response, signal) {
+    const cancelBody = () => response.body?.cancel().catch(() => undefined);
+    if (!isJsonContentType(response.headers.get("content-type"))) {
+        await cancelBody();
+        invalidResponse();
+    }
+    let declaredLength;
+    try {
+        declaredLength = contentLength(response);
+    }
+    catch {
+        await cancelBody();
+        invalidResponse();
+    }
+    if (declaredLength !== null && declaredLength > MAX_SIGNER_RESPONSE_BYTES) {
+        await cancelBody();
+        invalidResponse();
+    }
+    if (!response.body)
+        invalidResponse();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        rejectAbort = reject;
+    });
+    const onAbort = () => {
+        void reader.cancel().catch(() => undefined);
+        rejectAbort?.(signal?.reason ?? new Error("Aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        if (signal?.aborted)
+            onAbort();
+        while (true) {
+            const result = signal ? await Promise.race([reader.read(), aborted]) : await reader.read();
+            if (result.done)
+                break;
+            length += result.value.byteLength;
+            if (length > MAX_SIGNER_RESPONSE_BYTES) {
+                await reader.cancel().catch(() => undefined);
+                invalidResponse();
+            }
+            chunks.push(result.value);
+        }
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        invalidResponse();
+    }
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function serverError(response, body) {
+    const code = record(body) && record(body.error) ? body.error.code : undefined;
+    if (typeof code === "string" && Object.hasOwn(SAFE_SERVER_MESSAGES, code)) {
+        return new RemoteSignerError(code, SAFE_SERVER_MESSAGES[code], response.status);
+    }
+    return new RemoteSignerError("SIGNER_REQUEST_FAILED", "The signer request failed.", response.status);
+}
+function jsonBody(value) {
+    return JSON.stringify(value, (_key, field) => typeof field === "bigint" ? field.toString() : field);
+}
+export async function postRemoteSignerJson(options) {
+    const controller = new AbortController();
+    let timedOut = false;
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+            reject(new RemoteSignerError("SIGNER_REQUEST_TIMEOUT", "The agent control plane timed out.", 504));
+        }, options.timeoutMs);
+    });
+    const request = async () => {
+        const signal = options.signal
+            ? AbortSignal.any([controller.signal, options.signal])
+            : controller.signal;
+        const response = await options.fetch(options.endpoint, {
+            body: jsonBody(options.body),
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${options.apiKey}`,
+                "content-type": "application/json",
+            },
+            method: "POST",
+            redirect: "error",
+            signal,
+        });
+        const body = await readRemoteSignerJson(response, signal);
+        if (!response.ok)
+            throw serverError(response, body);
+        return body;
+    };
+    try {
+        return await Promise.race([request(), deadline]);
+    }
+    catch (error) {
+        if (error instanceof RemoteSignerError)
+            throw error;
+        if (options.signal?.aborted) {
+            throw new RemoteSignerError("SIGNER_REQUEST_CANCELLED", "The Agent signing request was cancelled.", 499);
+        }
+        if (timedOut) {
+            throw new RemoteSignerError("SIGNER_REQUEST_TIMEOUT", "The agent control plane timed out.", 504);
+        }
+        throw new RemoteSignerError("SIGNER_REQUEST_UNAVAILABLE", "The agent control plane could not be reached.", 503);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/remote-signer.d.ts

@@ -0,0 +1,34 @@
+import type { ClientEvmSigner } from "@x402/evm";
+import { type SignerRequest } from "./eip3009-authorization.js";
+export { RemoteSignerError } from "./remote-signer-http.js";
+export interface PaymentOrigin {
+    clientName: string;
+    toolName: string;
+    transport: "http" | "mcp";
+}
+interface RemoteSignerOptions {
+    address: `0x${string}`;
+    apiBaseUrl: string;
+    apiKey: string;
+    fetch?: typeof globalThis.fetch;
+    nowSeconds?: () => number;
+    origin?: () => PaymentOrigin | undefined;
+    paymentProfile: import("./payment-profile.js").PaymentProfile;
+    resourceUrl?: () => string | undefined;
+    reportAttempts?: number;
+    reportRetryDelayMs?: number;
+    reportTimeoutMs?: number;
+    signal?: () => AbortSignal | undefined;
+    signTimeoutMs?: number;
+}
+export declare class TabRemoteSigner implements ClientEvmSigner {
+    #private;
+    readonly address: `0x${string}`;
+    constructor(options: RemoteSignerOptions);
+    signTypedData(signerRequest: SignerRequest): Promise<`0x${string}`>;
+    receiptIdForSignature(signature: string): string | null;
+    restorePaymentCorrelation(signature: string, receiptId: string, validBeforeSeconds: number): void;
+    reconcileExpiredPayment(receiptId: string): Promise<boolean>;
+    reportPaymentObservation(context: import("@x402/core/client").PaymentResponseContext): Promise<import("./payment-observation-reporter.js").PaymentObservationResult>;
+    flushPaymentObservations(): Promise<void>;
+}