@furlpay/gateway 0.1.0

package/src/adapters/proxy.ts

@@ -0,0 +1,157 @@
+import http from "node:http";
+import { Gateway, type GatewayOptions } from "../gateway.js";
+
+// ---------------------------------------------------------------------------
+// Reverse-proxy mode.
+//
+// Put a paywall in front of an origin you do not want to modify — a legacy API,
+// a model server, an MCP server, a static dataset. The origin stays untouched
+// and never learns that it is being monetized.
+//
+//   furlpay-gateway expose http://localhost:8000 --price 0.01
+//
+// The origin MUST NOT be publicly reachable, or agents will simply route around
+// the paywall. Bind it to loopback, or firewall it to this process.
+// ---------------------------------------------------------------------------
+
+export interface ProxyOptions extends GatewayOptions {
+  /** Origin to forward paid requests to, e.g. "http://localhost:8000". */
+  origin: string;
+  port?: number;
+  hostname?: string;
+  /** Paths served free (health checks, docs, openapi.json). Exact or prefix*. */
+  freePaths?: string[];
+  /** Public base URL, when behind a TLS terminator. Resource identity — and so
+   *  the quote binding — is derived from this, and it must match what the agent
+   *  actually requested or every binding check fails. */
+  publicUrl?: string;
+}
+
+/** 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: string, freePaths: string[]): boolean {
+  return freePaths.some((p) =>
+    p.endsWith("*") ? pathname.startsWith(p.slice(0, -1)) : pathname === p
+  );
+}
+
+function readRequestBody(req: http.IncomingMessage): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => 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: ProxyOptions): http.Server {
+  const gateway = new Gateway(opts);
+  const origin = opts.origin.replace(/\/+$/, "");
+  const freePaths = opts.freePaths ?? [];
+
+  return http.createServer(async (req, res) => {
+    const send = (status: number, body: unknown, headers: Record<string, string> = {}) => {
+      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 as Record<string, string | undefined>,
+          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: Record<string, string> = {};
+      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 as Error).message });
+    }
+  });
+}
+
+export interface RunningProxy {
+  server: http.Server;
+  port: number;
+  close(): Promise<void>;
+}
+
+export function startProxy(opts: ProxyOptions): Promise<RunningProxy> {
+  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<void>((r) => server.close(() => r())),
+      });
+    });
+  });
+}

package/src/cli.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import { startProxy } from "./adapters/proxy.js";
+import { NETWORK_USDC } from "./protocol.js";
+
+// ---------------------------------------------------------------------------
+// furlpay-gateway — put a stablecoin paywall in front of anything, in one line.
+//
+//   furlpay-gateway expose http://localhost:8000 --price 0.01 --pay-to 0xabc...
+//   furlpay-gateway secret
+// ---------------------------------------------------------------------------
+
+interface Flags {
+  [key: string]: string | boolean;
+}
+
+function parseFlags(argv: string[]): { positional: string[]; flags: Flags } {
+  const positional: string[] = [];
+  const flags: 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: string): never {
+  process.stderr.write(`error: ${msg}\n\nRun \`furlpay-gateway --help\` for usage.\n`);
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  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"] as string) || process.env.PAY_TO;
+  if (!payTo) die("--pay-to (or PAY_TO) is required — nobody gets paid otherwise");
+
+  const quoteSecret = (flags.secret as string) || process.env.QUOTE_SECRET;
+  if (!quoteSecret) {
+    die("--secret (or QUOTE_SECRET) is required. Generate one: furlpay-gateway secret");
+  }
+
+  const network = (flags.network as string) || "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 as string) || process.env.FURLPAY_FACILITATOR;
+
+  const running = await startProxy({
+    origin,
+    port,
+    price,
+    payTo,
+    quoteSecret,
+    network,
+    freePaths,
+    settle: flags["no-settle"] !== true,
+    publicUrl: flags["public-url"] as string | undefined,
+    ...(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 as Error).message));

package/src/facilitator.ts

@@ -0,0 +1,133 @@
+import type {
+  PaymentPayloadV1,
+  PaymentPayloadV2,
+  PaymentRequirementsV1,
+  PaymentRequirementsV2,
+} from "./protocol.js";
+
+// ---------------------------------------------------------------------------
+// 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";
+
+/** 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 function httpFacilitator(
+  baseUrl: string = FURLPAY_FACILITATOR,
+  opts: HttpFacilitatorOptions = {}
+): FacilitatorClient {
+  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<T>(path: string, body: unknown, onError: (reason: string) => T): Promise<T> {
+    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()) as T;
+    } catch (e) {
+      const reason = (e as Error)?.name === "AbortError" ? "facilitator_timeout" : "facilitator_unreachable";
+      return onError(reason);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return {
+    verify(req) {
+      return post<VerifyResult>("/verify", req, (invalidReason) => ({ isValid: false, invalidReason }));
+    },
+    settle(req) {
+      const network =
+        req.x402Version === 2 ? req.paymentRequirements.network : req.paymentRequirements.network;
+      return post<SettleResult>("/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()) as { kinds?: SupportedKind[] } | SupportedKind[];
+        return Array.isArray(body) ? body : (body.kinds ?? []);
+      } catch {
+        return [];
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}