@furlpay/gateway 0.1.0

package/dist/adapters/proxy.js

@@ -0,0 +1,119 @@
+import http from "node:http";
+import { Gateway } from "../gateway.js";
+/** Headers that are meaningful only for a single hop and must not be forwarded. */
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+    "content-length",
+]);
+function isFree(pathname, freePaths) {
+    return freePaths.some((p) => p.endsWith("*") ? pathname.startsWith(p.slice(0, -1)) : pathname === p);
+}
+function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+/**
+ * Build (but do not start) the paywalling reverse proxy.
+ * Returns a standard `http.Server` — call `.listen()` yourself, or use
+ * `startProxy` which does it for you.
+ */
+export function createProxy(opts) {
+    const gateway = new Gateway(opts);
+    const origin = opts.origin.replace(/\/+$/, "");
+    const freePaths = opts.freePaths ?? [];
+    return http.createServer(async (req, res) => {
+        const send = (status, body, headers = {}) => {
+            const payload = JSON.stringify(body);
+            res.writeHead(status, {
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(payload),
+                ...headers,
+            });
+            res.end(payload);
+        };
+        try {
+            const base = opts.publicUrl ?? `http://${req.headers.host ?? "localhost"}`;
+            const url = new URL(req.url ?? "/", base);
+            const method = (req.method ?? "GET").toUpperCase();
+            const body = await readRequestBody(req);
+            if (!isFree(url.pathname, freePaths)) {
+                const decision = await gateway.authorize({
+                    method,
+                    url,
+                    headers: req.headers,
+                    body: body.length ? body : undefined,
+                });
+                if (decision.kind !== "allow") {
+                    send(decision.status, decision.body, decision.headers);
+                    return;
+                }
+                // Both dialects' receipts, plus the cache guards.
+                for (const [k, v] of Object.entries(decision.headers))
+                    res.setHeader(k, v);
+            }
+            // Forward to the origin.
+            const forwardHeaders = {};
+            for (const [k, v] of Object.entries(req.headers)) {
+                const key = k.toLowerCase();
+                if (HOP_BY_HOP.has(key))
+                    continue;
+                // The origin has no use for the payment credential, in either dialect.
+                if (key === "x-payment" || key === "payment-signature")
+                    continue;
+                if (typeof v === "string")
+                    forwardHeaders[k] = v;
+                else if (Array.isArray(v))
+                    forwardHeaders[k] = v.join(", ");
+            }
+            const upstream = await fetch(`${origin}${url.pathname}${url.search}`, {
+                method,
+                headers: forwardHeaders,
+                body: method === "GET" || method === "HEAD" ? undefined : body,
+            });
+            upstream.headers.forEach((v, k) => {
+                const key = k.toLowerCase();
+                if (HOP_BY_HOP.has(key))
+                    return;
+                // Never let the origin's cache policy override ours on a paid response.
+                if (key === "cache-control" || key === "vary")
+                    return;
+                res.setHeader(k, v);
+            });
+            res.writeHead(upstream.status);
+            const buf = Buffer.from(await upstream.arrayBuffer());
+            res.end(buf);
+        }
+        catch (e) {
+            send(502, { error: "origin_unreachable", detail: e.message });
+        }
+    });
+}
+export function startProxy(opts) {
+    const server = createProxy(opts);
+    const port = opts.port ?? 4402;
+    const hostname = opts.hostname ?? "0.0.0.0";
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, hostname, () => {
+            const addr = server.address();
+            const actual = typeof addr === "object" && addr ? addr.port : port;
+            resolve({
+                server,
+                port: actual,
+                close: () => new Promise((r) => server.close(() => r())),
+            });
+        });
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import { startProxy } from "./adapters/proxy.js";
+import { NETWORK_USDC } from "./protocol.js";
+function parseFlags(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                flags[key] = true;
+            }
+            else {
+                flags[key] = next;
+                i++;
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, flags };
+}
+const USAGE = `
+furlpay-gateway — x402 monetization gateway
+
+USAGE
+  furlpay-gateway expose <origin> [options]
+  furlpay-gateway secret
+
+COMMANDS
+  expose <origin>   Paywall an origin and serve it on a public port.
+  secret            Generate a quote secret.
+
+OPTIONS (expose)
+  --price <usd>          Price per call in USD.            (required)
+  --pay-to <address>     Wallet that receives payment.     (required, or PAY_TO)
+  --secret <hex>         Quote HMAC secret.                (or QUOTE_SECRET)
+  --network <name>       ${Object.keys(NETWORK_USDC).join(", ")}   (default: base)
+  --port <n>             Listen port.                      (default: 4402)
+  --facilitator <url>    x402 facilitator.                 (default: FurlPay)
+  --free <paths>         Comma-separated free paths, e.g. /health,/docs*
+  --public-url <url>     Public base URL if behind TLS termination.
+  --no-settle            Verify only; do not settle on-chain. (unsafe)
+
+ENVIRONMENT
+  PAY_TO, QUOTE_SECRET, FURLPAY_FACILITATOR
+
+EXAMPLE
+  furlpay-gateway secret
+  export QUOTE_SECRET=<the value it printed>
+  furlpay-gateway expose http://localhost:8000 \\
+    --price 0.01 --pay-to 0xYourWallet --network base --free /health
+
+SECURITY
+  The origin must NOT be publicly reachable, or agents will route around the
+  paywall. Bind it to loopback or firewall it to this process.
+`;
+function die(msg) {
+    process.stderr.write(`error: ${msg}\n\nRun \`furlpay-gateway --help\` for usage.\n`);
+    process.exit(1);
+}
+async function main() {
+    const { positional, flags } = parseFlags(process.argv.slice(2));
+    const command = positional[0];
+    if (!command || flags.help || flags.h) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (command === "secret") {
+        process.stdout.write(crypto.randomBytes(32).toString("hex") + "\n");
+        return;
+    }
+    if (command !== "expose")
+        die(`unknown command "${command}"`);
+    const origin = positional[1];
+    if (!origin)
+        die("expose requires an origin, e.g. http://localhost:8000");
+    if (!/^https?:\/\//.test(origin))
+        die(`origin must start with http:// or https:// (got "${origin}")`);
+    const price = Number(flags.price);
+    if (!Number.isFinite(price) || price <= 0)
+        die("--price must be a positive number of USD");
+    const payTo = flags["pay-to"] || process.env.PAY_TO;
+    if (!payTo)
+        die("--pay-to (or PAY_TO) is required — nobody gets paid otherwise");
+    const quoteSecret = flags.secret || process.env.QUOTE_SECRET;
+    if (!quoteSecret) {
+        die("--secret (or QUOTE_SECRET) is required. Generate one: furlpay-gateway secret");
+    }
+    const network = flags.network || "base";
+    if (!NETWORK_USDC[network]) {
+        die(`unknown network "${network}" — one of: ${Object.keys(NETWORK_USDC).join(", ")}`);
+    }
+    const freePaths = typeof flags.free === "string" ? flags.free.split(",").map((s) => s.trim()) : [];
+    const port = flags.port ? Number(flags.port) : 4402;
+    const facilitator = flags.facilitator || process.env.FURLPAY_FACILITATOR;
+    const running = await startProxy({
+        origin,
+        port,
+        price,
+        payTo,
+        quoteSecret,
+        network,
+        freePaths,
+        settle: flags["no-settle"] !== true,
+        publicUrl: flags["public-url"],
+        ...(facilitator ? { facilitator } : {}),
+        onSettled: (r) => {
+            process.stdout.write(`paid  $${(Number(r.amountAtomic) / 1e6).toFixed(6)}  ${r.payer.slice(0, 10)}…  ${r.resource}\n`);
+        },
+    });
+    const lines = [
+        ``,
+        `  FurlPay Gateway`,
+        ``,
+        `  paywalling   ${origin}`,
+        `  listening    http://localhost:${running.port}`,
+        `  price        $${price.toFixed(6)} per call`,
+        `  pay to       ${payTo}`,
+        `  network      ${network} (USDC ${NETWORK_USDC[network].slice(0, 10)}…)`,
+        `  facilitator  ${facilitator ?? "furlpay.com (default)"}`,
+        freePaths.length ? `  free         ${freePaths.join(", ")}` : ``,
+        flags["no-settle"] === true ? `  WARNING      --no-settle: payments are verified but NOT collected` : ``,
+        ``,
+        `  Replay protection is in-memory: correct for ONE instance only.`,
+        `  Run more than one and pass a shared claim store (see README).`,
+        ``,
+    ].filter(Boolean);
+    process.stdout.write(lines.join("\n") + "\n");
+    const shutdown = async () => {
+        await running.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((e) => die(e.message));

package/dist/facilitator.d.ts

@@ -0,0 +1,55 @@
+import type { PaymentPayloadV1, PaymentPayloadV2, PaymentRequirementsV1, PaymentRequirementsV2 } from "./protocol.js";
+export declare const FURLPAY_FACILITATOR = "https://furlpay.com/api/x402/facilitator";
+/** The envelope is versioned: v1 and v2 carry different inner shapes. */
+export type FacilitatorRequest = {
+    x402Version: 1;
+    paymentPayload: PaymentPayloadV1;
+    paymentRequirements: PaymentRequirementsV1;
+} | {
+    x402Version: 2;
+    paymentPayload: PaymentPayloadV2;
+    paymentRequirements: PaymentRequirementsV2;
+};
+export interface VerifyResult {
+    isValid: boolean;
+    payer?: string;
+    invalidReason?: string;
+    invalidMessage?: string;
+}
+export interface SettleResult {
+    success: boolean;
+    transaction?: string;
+    network: string;
+    payer?: string;
+    errorReason?: string;
+    errorMessage?: string;
+    /** Actual amount settled. v2's `upto` scheme can settle LESS than the
+     *  authorized maximum, so the receipt must report this, not the authorization. */
+    amount?: string;
+    confirmations?: number;
+    requiredConfirmations?: number;
+}
+export interface SupportedKind {
+    x402Version: number;
+    scheme: string;
+    network: string;
+}
+export interface FacilitatorClient {
+    verify(req: FacilitatorRequest): Promise<VerifyResult>;
+    settle(req: FacilitatorRequest): Promise<SettleResult>;
+    supported(): Promise<SupportedKind[]>;
+}
+export interface HttpFacilitatorOptions {
+    apiKey?: string;
+    /** A hung facilitator must not hang the origin. */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * HTTP facilitator client.
+ *
+ * Every failure path fails CLOSED: a timeout, a non-2xx, or an unparseable body
+ * resolves to "not valid" / "not settled", never to a released resource. A
+ * facilitator you cannot reach must cost you a sale, not the resource.
+ */
+export declare function httpFacilitator(baseUrl?: string, opts?: HttpFacilitatorOptions): FacilitatorClient;

package/dist/facilitator.js

@@ -0,0 +1,78 @@
+// ---------------------------------------------------------------------------
+// Facilitator client.
+//
+// The facilitator is the only party that touches a chain: it verifies the
+// EIP-3009 authorization, submits it, and pays the gas. Keeping it behind an
+// interface is the whole point — the gateway needs no private key, no RPC
+// endpoint and no gas balance, which is what makes it safe to self-host.
+//
+// Default: FurlPay's facilitator. Any x402-compliant facilitator works; point
+// `baseUrl` at Coinbase's and settlement goes through Coinbase, unchanged.
+// ---------------------------------------------------------------------------
+export const FURLPAY_FACILITATOR = "https://furlpay.com/api/x402/facilitator";
+/**
+ * HTTP facilitator client.
+ *
+ * Every failure path fails CLOSED: a timeout, a non-2xx, or an unparseable body
+ * resolves to "not valid" / "not settled", never to a released resource. A
+ * facilitator you cannot reach must cost you a sale, not the resource.
+ */
+export function httpFacilitator(baseUrl = FURLPAY_FACILITATOR, opts = {}) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+        throw new Error("No fetch implementation available — pass `fetchImpl` (Node >=18 has a global fetch).");
+    }
+    async function post(path, body, onError) {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), timeoutMs);
+        try {
+            const res = await doFetch(`${base}${path}`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...(opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {}),
+                },
+                body: JSON.stringify(body),
+                signal: ctl.signal,
+            });
+            if (!res.ok)
+                return onError(`facilitator_http_${res.status}`);
+            return (await res.json());
+        }
+        catch (e) {
+            const reason = e?.name === "AbortError" ? "facilitator_timeout" : "facilitator_unreachable";
+            return onError(reason);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        verify(req) {
+            return post("/verify", req, (invalidReason) => ({ isValid: false, invalidReason }));
+        },
+        settle(req) {
+            const network = req.x402Version === 2 ? req.paymentRequirements.network : req.paymentRequirements.network;
+            return post("/settle", req, (errorReason) => ({ success: false, network, errorReason }));
+        },
+        async supported() {
+            const ctl = new AbortController();
+            const timer = setTimeout(() => ctl.abort(), timeoutMs);
+            try {
+                const res = await doFetch(`${base}/supported`, { signal: ctl.signal });
+                if (!res.ok)
+                    return [];
+                const body = (await res.json());
+                return Array.isArray(body) ? body : (body.kinds ?? []);
+            }
+            catch {
+                return [];
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}

package/dist/gateway.d.ts

@@ -0,0 +1,122 @@
+import { LATEST_X402_VERSION, type PaymentRequiredV1, type PaymentRequiredV2, type SettlementReceipt, type X402Version } from "./protocol.js";
+import { type FacilitatorClient } from "./facilitator.js";
+import { type ClaimStore } from "./store.js";
+export interface RequestContext {
+    method: string;
+    /** Canonical resource identity — the absolute URL, including query. */
+    resource: string;
+    url: URL;
+    headers: Headers;
+}
+export type PriceResolver = number | ((ctx: RequestContext) => number | Promise<number>);
+export interface GatewayOptions {
+    price: PriceResolver;
+    payTo: string;
+    /** HMAC secret binding quotes to resources. No default — a published default
+     *  would be a forgeable quote for every deployment that didn't override it. */
+    quoteSecret: string;
+    network?: string;
+    asset?: string;
+    assetName?: string;
+    assetVersion?: string;
+    facilitator?: FacilitatorClient | string;
+    /** Pin the dialect used to talk to the facilitator. Default: mirror the
+     *  client. Set to 1 when pointing at a v1-only facilitator. */
+    facilitatorVersion?: X402Version;
+    claimStore?: ClaimStore;
+    quoteTtlSeconds?: number;
+    description?: string | ((ctx: RequestContext) => string);
+    mimeType?: string;
+    /** v2 discovery metadata. These are the protocol's native fields — a
+     *  facilitator can crawl them, so filling them in is how the resource becomes
+     *  discoverable without any proprietary index. */
+    serviceName?: string;
+    tags?: string[];
+    iconUrl?: string;
+    /** Bind the quote to a hash of the request body (default on for POST/PUT/PATCH).
+     *  Without it, a payment for {"model":"small"} also unlocks {"model":"large"}. */
+    bindBody?: boolean;
+    /** Settle on-chain before releasing (default). `false` verifies but does not
+     *  collect — only correct if you settle out of band. */
+    settle?: boolean;
+    resource?: (ctx: {
+        method: string;
+        url: URL;
+    }) => string;
+    onSettled?: (receipt: SettlementReceipt) => void | Promise<void>;
+    onRejected?: (info: {
+        reason: string;
+        resource: string;
+        payer?: string;
+    }) => void | Promise<void>;
+}
+export type GatewayDecision = {
+    kind: "allow";
+    receipt: SettlementReceipt;
+    headers: Record<string, string>;
+} | {
+    kind: "challenge";
+    status: 402;
+    body: PaymentRequiredV1;
+    headers: Record<string, string>;
+} | {
+    kind: "reject";
+    status: 400;
+    body: {
+        error: string;
+    };
+    headers: Record<string, string>;
+};
+export interface AuthorizeInput {
+    method: string;
+    url: string | URL;
+    headers: Headers | Record<string, string | undefined>;
+    /** Raw request body. Required for body binding on POST/PUT/PATCH. */
+    body?: string | Buffer;
+}
+export declare class Gateway {
+    private readonly opts;
+    private readonly facilitator;
+    private readonly claims;
+    private readonly network;
+    private readonly asset;
+    private readonly ttl;
+    constructor(opts: GatewayOptions);
+    /** True when replay claims are shared across instances. Assert this at boot in
+     *  any multi-instance deployment. */
+    get replayProtectionDurable(): boolean;
+    private resourceId;
+    private context;
+    private priceFor;
+    private describe;
+    private shouldBindBody;
+    /** Mint a fresh quote for this request. */
+    private mint;
+    private extraFor;
+    private toV1;
+    private toV2;
+    private resourceInfo;
+    /** Public quote surface — the v2 402 payload for this request. */
+    quote(input: AuthorizeInput): Promise<PaymentRequiredV2>;
+    /**
+     * A 402 advertises BOTH dialects: v2 in the PAYMENT-REQUIRED header, v1 in the
+     * body. v2 moving payment data out of the body is exactly what makes this
+     * possible — a v2 client reads the header, a v1 client reads the body, and
+     * neither needs to know the other exists.
+     */
+    private challenge;
+    private reject;
+    /**
+     * Returns `allow` only when a payment has been verified against a
+     * server-derived quote, burned as single-use, and settled to the confirmation
+     * depth its value requires.
+     */
+    authorize(input: AuthorizeInput): Promise<GatewayDecision>;
+    /** Rebuild the requirements the quote was minted with, so the facilitator
+     *  checks the payment against the SERVER's terms, not the client's copy. */
+    private facilitatorRequest;
+    /** Answer in the dialect the client spoke — and, harmlessly, the other one too,
+     *  so a proxy or SDK expecting either finds its receipt. */
+    private allow;
+}
+export { LATEST_X402_VERSION };