@runtab/mcp 0.0.1

package/dist/payment-envelope.js

@@ -0,0 +1,145 @@
+import { decodePaymentSignatureHeader } from "@x402/core/http";
+import { getAddress, isAddressEqual, recoverTypedDataAddress } from "viem";
+import { ARBITRUM_NETWORK, ARBITRUM_USDC, BASE_NETWORK, BASE_SEPOLIA_NETWORK, BASE_SEPOLIA_USDC, BASE_USDC, } from "./routing.js";
+const AUTHORIZATION_TYPES = [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+];
+const NETWORKS = {
+    [ARBITRUM_NETWORK]: { asset: ARBITRUM_USDC, chainId: 42_161, name: "USD Coin" },
+    [BASE_NETWORK]: { asset: BASE_USDC, chainId: 8_453, name: "USD Coin" },
+    [BASE_SEPOLIA_NETWORK]: { asset: BASE_SEPOLIA_USDC, chainId: 84_532, name: "USDC" },
+};
+export class PaymentEnvelopeValidationError extends Error {
+    constructor() {
+        super("The persisted payment envelope is invalid.");
+        this.name = "PaymentEnvelopeValidationError";
+    }
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decimal(value) {
+    if (typeof value !== "string" || !/^(0|[1-9][0-9]*)$/.test(value)) {
+        throw new PaymentEnvelopeValidationError();
+    }
+    return value;
+}
+function address(value) {
+    if (typeof value !== "string")
+        throw new PaymentEnvelopeValidationError();
+    try {
+        return getAddress(value);
+    }
+    catch {
+        throw new PaymentEnvelopeValidationError();
+    }
+}
+export function newPaymentEnvelope(payload, paymentSignature, signer) {
+    const authorization = record(payload.payload.authorization)
+        ? payload.payload.authorization
+        : undefined;
+    const signature = payload.payload.signature;
+    const validBefore = authorization?.validBefore;
+    if (typeof signature !== "string" ||
+        typeof validBefore !== "string" ||
+        !/^(0|[1-9][0-9]*)$/.test(validBefore)) {
+        throw new PaymentEnvelopeValidationError();
+    }
+    const validBeforeNumber = Number(validBefore);
+    const receiptId = signer.receiptIdForSignature(signature);
+    if (!paymentSignature ||
+        !Number.isSafeInteger(validBeforeNumber) ||
+        validBeforeNumber < 1 ||
+        !receiptId) {
+        throw new PaymentEnvelopeValidationError();
+    }
+    return { paymentSignature, receiptId, validBefore: validBeforeNumber };
+}
+function networkFor(payload, profile) {
+    const network = payload.accepted.network;
+    const supported = NETWORKS[network];
+    const profileMatch = profile === "base_sepolia_integration"
+        ? network === BASE_SEPOLIA_NETWORK
+        : network === BASE_NETWORK || network === ARBITRUM_NETWORK;
+    if (!supported || !profileMatch)
+        throw new PaymentEnvelopeValidationError();
+    return { ...supported, network: network };
+}
+export async function parsePaymentEnvelope(paymentSignature, expectedAddress, profile) {
+    try {
+        const payload = decodePaymentSignatureHeader(paymentSignature);
+        if (payload.x402Version !== 2 || payload.accepted.scheme !== "exact") {
+            throw new PaymentEnvelopeValidationError();
+        }
+        const selected = networkFor(payload, profile);
+        const authorization = record(payload.payload.authorization)
+            ? payload.payload.authorization
+            : undefined;
+        const signature = payload.payload.signature;
+        if (!authorization ||
+            typeof signature !== "string" ||
+            !/^0x[0-9a-fA-F]{130}$/.test(signature)) {
+            throw new PaymentEnvelopeValidationError();
+        }
+        const from = address(authorization.from);
+        const to = address(authorization.to);
+        const value = decimal(authorization.value);
+        const validAfter = decimal(authorization.validAfter);
+        const validBeforeRaw = decimal(authorization.validBefore);
+        const nonce = authorization.nonce;
+        if (!isAddressEqual(from, expectedAddress) ||
+            !isAddressEqual(to, address(payload.accepted.payTo)) ||
+            !isAddressEqual(address(payload.accepted.asset), getAddress(selected.asset)) ||
+            value !== payload.accepted.amount ||
+            validAfter !== "0" ||
+            typeof nonce !== "string" ||
+            !/^0x[0-9a-fA-F]{64}$/.test(nonce) ||
+            payload.accepted.extra.name !== selected.name ||
+            payload.accepted.extra.version !== "2") {
+            throw new PaymentEnvelopeValidationError();
+        }
+        const recovered = await recoverTypedDataAddress({
+            domain: {
+                chainId: selected.chainId,
+                name: selected.name,
+                verifyingContract: getAddress(selected.asset),
+                version: "2",
+            },
+            message: {
+                from,
+                nonce: nonce,
+                to,
+                validAfter: BigInt(validAfter),
+                validBefore: BigInt(validBeforeRaw),
+                value: BigInt(value),
+            },
+            primaryType: "TransferWithAuthorization",
+            signature: signature,
+            types: { TransferWithAuthorization: AUTHORIZATION_TYPES },
+        });
+        if (!isAddressEqual(recovered, expectedAddress))
+            throw new PaymentEnvelopeValidationError();
+        const validBefore = Number(validBeforeRaw);
+        if (!Number.isSafeInteger(validBefore))
+            throw new PaymentEnvelopeValidationError();
+        return {
+            asset: getAddress(selected.asset),
+            from,
+            network: selected.network,
+            nonce: nonce,
+            payload,
+            signature: signature,
+            validBefore,
+        };
+    }
+    catch (error) {
+        if (error instanceof PaymentEnvelopeValidationError)
+            throw error;
+        throw new PaymentEnvelopeValidationError();
+    }
+}

package/dist/payment-idempotency.d.ts

@@ -0,0 +1,2 @@
+export declare function currentPaymentIdempotencyKey(): string | undefined;
+export declare function withPaymentIdempotencyKey<T>(key: string, task: () => T): T;

package/dist/payment-idempotency.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export function currentPaymentIdempotencyKey() {
+    return storage.getStore();
+}
+export function withPaymentIdempotencyKey(key, task) {
+    return storage.run(key, task);
+}

package/dist/payment-observation-reporter.d.ts

@@ -0,0 +1,31 @@
+import type { PaymentResponseContext } from "@x402/core/client";
+import type { PaymentCorrelations } from "./payment-correlation.js";
+interface PaymentObservationReporterOptions {
+    apiKey: string;
+    attempts: number;
+    correlations: PaymentCorrelations;
+    endpoint: URL;
+    fetch: typeof globalThis.fetch;
+    retryDelayMs: number;
+    timeoutMs: number;
+}
+export type PaymentObservationResult = {
+    status: "failed";
+    verified: true;
+} | {
+    status: "ignored";
+    verified: false;
+} | {
+    status: "pending";
+    verified: false;
+} | {
+    status: "settled";
+    verified: true;
+};
+export declare class PaymentObservationReporter {
+    #private;
+    constructor(options: PaymentObservationReporterOptions);
+    report(context: PaymentResponseContext, address: `0x${string}`): Promise<PaymentObservationResult>;
+    flush(): Promise<void>;
+}
+export {};

package/dist/payment-observation-reporter.js

@@ -0,0 +1,151 @@
+import { parsePaymentSettlementObservation } from "./payment-settlement-observation.js";
+import { readRemoteSignerJson } from "./remote-signer-http.js";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function acknowledgement(value, status) {
+    if (!record(value) || Object.keys(value).sort().join(",") !== "receiptId,status,verified") {
+        return;
+    }
+    if (typeof value.receiptId !== "string")
+        return;
+    if (status === 202 && value.status === "pending" && value.verified === false) {
+        return { receiptId: value.receiptId, status: "pending", verified: false };
+    }
+    if (status === 200 &&
+        (value.status === "settled" || value.status === "failed") &&
+        value.verified === true) {
+        return { receiptId: value.receiptId, status: value.status, verified: true };
+    }
+    return undefined;
+}
+export class PaymentObservationReporter {
+    #apiKey;
+    #attempts;
+    #correlations;
+    #endpoint;
+    #fetch;
+    #inFlight = new Set();
+    #retryDelayMs;
+    #timeoutMs;
+    constructor(options) {
+        this.#apiKey = options.apiKey;
+        this.#attempts = options.attempts;
+        this.#correlations = options.correlations;
+        this.#endpoint = options.endpoint;
+        this.#fetch = options.fetch;
+        this.#retryDelayMs = options.retryDelayMs;
+        this.#timeoutMs = options.timeoutMs;
+    }
+    async #attempt(body) {
+        const controller = new AbortController();
+        let timeout;
+        const deadline = new Promise((resolve) => {
+            timeout = setTimeout(() => {
+                controller.abort();
+                resolve({ retry: true });
+            }, this.#timeoutMs);
+        });
+        const request = async () => {
+            try {
+                const response = await this.#fetch(this.#endpoint, {
+                    body: JSON.stringify(body),
+                    headers: {
+                        accept: "application/json",
+                        authorization: `Bearer ${this.#apiKey}`,
+                        "content-type": "application/json",
+                    },
+                    method: "POST",
+                    redirect: "error",
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    return { retry: response.status === 429 || response.status >= 500 };
+                }
+                if (response.status === 204)
+                    return { retry: false };
+                const parsed = acknowledgement(await readRemoteSignerJson(response, controller.signal), response.status);
+                return {
+                    ...(parsed ? { acknowledgement: parsed } : {}),
+                    retry: parsed?.status === "pending",
+                };
+            }
+            catch {
+                return { retry: true };
+            }
+        };
+        try {
+            return await Promise.race([request(), deadline]);
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
+    }
+    async #send(body, receiptId, signature) {
+        let result = { status: "ignored", verified: false };
+        for (let attempt = 0; attempt < this.#attempts; attempt += 1) {
+            const attempted = await this.#attempt(body);
+            if (attempted.acknowledgement?.receiptId === receiptId) {
+                const verified = attempted.acknowledgement;
+                result =
+                    verified.status === "pending"
+                        ? { status: "pending", verified: false }
+                        : verified.status === "settled"
+                            ? { status: "settled", verified: true }
+                            : { status: "failed", verified: true };
+                if (verified.status === "settled") {
+                    this.#correlations.deleteIf(signature, receiptId);
+                }
+                if (verified.status !== "pending")
+                    return result;
+            }
+            if (!attempted.retry || attempt === this.#attempts - 1)
+                return result;
+            await new Promise((resolve) => setTimeout(resolve, this.#retryDelayMs * (attempt + 1)));
+        }
+        return result;
+    }
+    async report(context, address) {
+        const settlement = parsePaymentSettlementObservation(context.settleResponse, {
+            ...(context.paymentPayload.x402Version === 2
+                ? { amount: context.paymentPayload.accepted.amount }
+                : {}),
+            network: context.requirements.network,
+            payer: address,
+        });
+        const signature = context.paymentPayload.payload.signature;
+        if (!settlement || typeof signature !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(signature)) {
+            return { status: "ignored", verified: false };
+        }
+        const receiptId = this.#correlations.get(signature);
+        if (!receiptId)
+            return { status: "ignored", verified: false };
+        const task = this.#send({
+            outcome: "observed",
+            paymentResponse: {
+                ...(settlement.success
+                    ? {}
+                    : {
+                        ...(settlement.errorMessage ? { errorMessage: settlement.errorMessage } : {}),
+                        errorReason: settlement.errorReason,
+                    }),
+                network: settlement.network,
+                payer: settlement.payer,
+                success: settlement.success,
+                transaction: settlement.transaction,
+            },
+            receiptId,
+        }, receiptId, signature);
+        this.#inFlight.add(task);
+        try {
+            return await task;
+        }
+        finally {
+            this.#inFlight.delete(task);
+        }
+    }
+    async flush() {
+        await Promise.allSettled([...this.#inFlight]);
+    }
+}

package/dist/payment-profile.d.ts

@@ -0,0 +1,3 @@
+export declare const PAYMENT_PROFILES: readonly ["mainnet", "base_sepolia_integration"];
+export type PaymentProfile = (typeof PAYMENT_PROFILES)[number];
+export declare function isPaymentProfile(value: unknown): value is PaymentProfile;

package/dist/payment-profile.js

@@ -0,0 +1,4 @@
+export const PAYMENT_PROFILES = ["mainnet", "base_sepolia_integration"];
+export function isPaymentProfile(value) {
+    return PAYMENT_PROFILES.some((profile) => profile === value);
+}

package/dist/payment-request-fingerprint.d.ts

@@ -0,0 +1,5 @@
+export declare class PaymentRequestFingerprintError extends Error {
+    readonly code = "INVALID_FETCH_REQUEST";
+    constructor();
+}
+export declare function fingerprintPaymentRequest(request: Request): Promise<string>;

package/dist/payment-request-fingerprint.js

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+const MAX_PAYMENT_REQUEST_BODY_BYTES = 1_048_576;
+const IGNORED_HEADERS = new Set([
+    "access-control-expose-headers",
+    "payment-signature",
+    "x-payment",
+]);
+export class PaymentRequestFingerprintError extends Error {
+    code = "INVALID_FETCH_REQUEST";
+    constructor() {
+        super("The fetch request is invalid.");
+        this.name = "PaymentRequestFingerprintError";
+    }
+}
+function part(hash, value) {
+    hash.update(String(Buffer.byteLength(value)));
+    hash.update(":");
+    hash.update(value);
+    hash.update(";");
+}
+export async function fingerprintPaymentRequest(request) {
+    const hash = createHash("sha256");
+    part(hash, request.method.toUpperCase());
+    part(hash, request.url);
+    const headers = [...request.headers]
+        .filter(([name]) => !IGNORED_HEADERS.has(name.toLowerCase()))
+        .sort(([left], [right]) => left.localeCompare(right));
+    for (const [name, value] of headers) {
+        part(hash, name.toLowerCase());
+        part(hash, value);
+    }
+    const body = request.body;
+    if (body) {
+        const reader = body.getReader();
+        let length = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                length += value.byteLength;
+                if (length > MAX_PAYMENT_REQUEST_BODY_BYTES) {
+                    void reader.cancel().catch(() => undefined);
+                    throw new PaymentRequestFingerprintError();
+                }
+                hash.update(value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    return hash.digest("hex");
+}

package/dist/payment-settlement-observation.d.ts

@@ -0,0 +1,9 @@
+import type { SettleResponse } from "@x402/core/types";
+export type PaymentSettlementObservation = SettleResponse & {
+    payer: string;
+};
+export declare function parsePaymentSettlementObservation(value: unknown, expected?: {
+    amount?: string;
+    network?: string;
+    payer?: string;
+}): PaymentSettlementObservation | null;

package/dist/payment-settlement-observation.js

@@ -0,0 +1,74 @@
+import { getAddress, isAddress } from "viem";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactAllowedKeys(value, required, allowed) {
+    return (required.every((key) => Object.hasOwn(value, key)) &&
+        Object.keys(value).every((key) => allowed.includes(key)));
+}
+function boundedJsonRecord(value) {
+    if (!record(value))
+        return false;
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized !== undefined && new TextEncoder().encode(serialized).byteLength <= 4_096;
+    }
+    catch {
+        return false;
+    }
+}
+export function parsePaymentSettlementObservation(value, expected = {}) {
+    if (!record(value) || typeof value.success !== "boolean")
+        return null;
+    const required = value.success
+        ? ["network", "payer", "success", "transaction"]
+        : ["errorReason", "network", "payer", "success", "transaction"];
+    const allowed = value.success
+        ? [...required, "amount", "extensions", "extra"]
+        : [...required, "amount", "errorMessage", "extensions", "extra"];
+    if (!exactAllowedKeys(value, required, allowed))
+        return null;
+    if (typeof value.network !== "string" ||
+        value.network.length < 3 ||
+        value.network.length > 128 ||
+        !value.network.includes(":") ||
+        (expected.network !== undefined && value.network !== expected.network) ||
+        typeof value.payer !== "string" ||
+        !isAddress(value.payer) ||
+        (expected.payer !== undefined &&
+            (!isAddress(expected.payer) || getAddress(value.payer) !== getAddress(expected.payer))) ||
+        typeof value.transaction !== "string" ||
+        !/^0x[0-9a-fA-F]{64}$/.test(value.transaction) ||
+        (value.amount !== undefined &&
+            (typeof value.amount !== "string" ||
+                !/^(0|[1-9][0-9]*)$/.test(value.amount) ||
+                value.amount.length > 78 ||
+                expected.amount === undefined ||
+                value.amount !== expected.amount)) ||
+        (value.extensions !== undefined && !boundedJsonRecord(value.extensions)) ||
+        (value.extra !== undefined && !boundedJsonRecord(value.extra))) {
+        return null;
+    }
+    const common = {
+        network: value.network,
+        payer: getAddress(value.payer),
+        transaction: value.transaction,
+    };
+    if (value.success)
+        return { ...common, success: true };
+    if (typeof value.errorReason !== "string" ||
+        !/\S/.test(value.errorReason) ||
+        value.errorReason.length > 256 ||
+        (value.errorMessage !== undefined &&
+            (typeof value.errorMessage !== "string" ||
+                !/\S/.test(value.errorMessage) ||
+                value.errorMessage.length > 2_048))) {
+        return null;
+    }
+    return {
+        ...common,
+        ...(value.errorMessage === undefined ? {} : { errorMessage: value.errorMessage }),
+        errorReason: value.errorReason,
+        success: false,
+    };
+}

package/dist/payment-signal.d.ts

@@ -0,0 +1,2 @@
+export declare function currentPaymentSignal(): AbortSignal | undefined;
+export declare function withPaymentSignal<T>(signal: AbortSignal, task: () => T): T;

package/dist/payment-signal.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export function currentPaymentSignal() {
+    return storage.getStore();
+}
+export function withPaymentSignal(signal, task) {
+    return storage.run(signal, task);
+}

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

@@ -0,0 +1,16 @@
+export interface PaymentTargetAddress {
+    address: string;
+    family: 4 | 6;
+}
+export type PaymentTargetLookup = (hostname: string) => Promise<readonly PaymentTargetAddress[]>;
+interface PinnedPaymentFetchOptions {
+    allowDevelopmentLoopback?: boolean;
+    fetch: typeof globalThis.fetch;
+    lookup?: PaymentTargetLookup;
+    maxPinnedHosts?: number;
+}
+export declare function createPinnedPaymentFetch(options: PinnedPaymentFetchOptions): {
+    close(): Promise<void>;
+    fetch: typeof globalThis.fetch;
+};
+export {};