@furlpay/gateway 0.1.0

package/dist/protocol.js

@@ -0,0 +1,186 @@
+import crypto from "node:crypto";
+/** Default dialect for freshly-minted quotes when the client hasn't spoken yet. */
+export const LATEST_X402_VERSION = 2;
+// ── headers ───────────────────────────────────────────────────────────────
+export const HEADER_V1_PAYMENT = "x-payment";
+export const HEADER_V1_RECEIPT = "X-PAYMENT-RESPONSE";
+export const HEADER_V2_PAYMENT = "payment-signature";
+export const HEADER_V2_RECEIPT = "PAYMENT-RESPONSE";
+export const HEADER_V2_REQUIRED = "PAYMENT-REQUIRED";
+/** Web-layer hardening: cap the header before we spend cycles parsing it. */
+export const MAX_HEADER_BYTES = 8192;
+export const DEFAULT_QUOTE_TTL_SECONDS = 300;
+/** Must outlive any EIP-3009 validity window, or a late replay could re-claim a
+ *  freed key. */
+export const REPLAY_CLAIM_TTL_SECONDS = 86_400;
+/** Canonical (native-issuance, not bridged) USDC per network. */
+export const NETWORK_USDC = {
+    arbitrum: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    "arbitrum-sepolia": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
+    base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    polygon: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    solana: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+};
+export const USDC_DECIMALS = 6;
+// ── cache hygiene ─────────────────────────────────────────────────────────
+/** A paid 200 that a CDN caches is a paid resource served free to the next
+ *  unpaid caller. `Vary` covers both dialects' request headers. */
+export const noStoreHeaders = {
+    "Cache-Control": "no-store, private, max-age=0",
+    Vary: "X-PAYMENT, PAYMENT-SIGNATURE",
+};
+// ── value-scaled settlement depth ─────────────────────────────────────────
+export function requiredConfirmations(amountAtomic) {
+    let usd;
+    try {
+        usd = Number(BigInt(amountAtomic)) / 10 ** USDC_DECIMALS;
+    }
+    catch {
+        return 12; // unparseable → demand the strongest gate
+    }
+    if (usd < 1)
+        return 3;
+    if (usd < 10)
+        return 6;
+    return 12;
+}
+export function atomicAmount(priceUsd, decimals = USDC_DECIMALS) {
+    if (!Number.isFinite(priceUsd) || priceUsd <= 0) {
+        throw new RangeError(`price must be a positive finite number (got ${priceUsd})`);
+    }
+    return String(Math.round(priceUsd * 10 ** decimals));
+}
+/**
+ * HMAC binding a quote to exactly one (method, resource, amount) — and, when a
+ * body is present, exactly one body.
+ *
+ * Deliberately version-independent: the same MAC validates a v1 or a v2 payment,
+ * because both dialects carry the quote in `extra`. It is also byte-identical to
+ * apps/web/src/lib/x402.ts, so quotes stay interchangeable with FurlPay's
+ * first-party resources.
+ */
+export function bindingMac(secret, input) {
+    const base = `${input.method} ${input.resource} ${input.amount} ${input.quoteId} ${input.expiresAt}`;
+    const message = input.bodyHash ? `${base} ${input.bodyHash}` : base;
+    return crypto.createHmac("sha256", secret).update(message).digest("hex");
+}
+export function hashBody(body) {
+    return crypto.createHash("sha256").update(body).digest("hex");
+}
+export function timingSafeEqualHex(a, b) {
+    const ba = Buffer.from(a, "utf8");
+    const bb = Buffer.from(b, "utf8");
+    if (ba.length !== bb.length)
+        return false;
+    return crypto.timingSafeEqual(ba, bb);
+}
+// ── codec ─────────────────────────────────────────────────────────────────
+export function b64encode(value) {
+    return Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+}
+export function b64decode(value) {
+    return JSON.parse(Buffer.from(value, "base64").toString("utf8"));
+}
+/** Which dialect did the client speak? `null` when it presented no payment. */
+export function detectVersion(get) {
+    if (get(HEADER_V2_PAYMENT))
+        return 2;
+    if (get(HEADER_V1_PAYMENT))
+        return 1;
+    return null;
+}
+function validAuthorization(auth) {
+    if (!auth || typeof auth !== "object")
+        return false;
+    const a = auth;
+    return ["from", "to", "value", "validAfter", "validBefore", "nonce"].every((f) => typeof a[f] === "string" && a[f].length > 0);
+}
+/**
+ * Strict parse of whichever payment header is present, normalized to one shape.
+ * Malformed input is an error, never a silently-released resource.
+ */
+export function decodePayment(get) {
+    const version = detectVersion(get);
+    if (version === null)
+        return { ok: false, error: "Payment required" };
+    const raw = version === 2 ? get(HEADER_V2_PAYMENT) : get(HEADER_V1_PAYMENT);
+    if (raw.length > MAX_HEADER_BYTES)
+        return { ok: false, error: "Payment header too large" };
+    let parsed;
+    try {
+        parsed = b64decode(raw);
+    }
+    catch {
+        return { ok: false, error: "Payment header is not valid base64 JSON" };
+    }
+    if (version === 2) {
+        const p = parsed;
+        if (p?.x402Version !== 2)
+            return { ok: false, error: "Unsupported x402 version" };
+        if (!p.accepted || typeof p.accepted !== "object") {
+            return { ok: false, error: "Malformed v2 payload (missing `accepted`)" };
+        }
+        if (typeof p.payload?.signature !== "string" || !validAuthorization(p.payload?.authorization)) {
+            return { ok: false, error: "Malformed v2 payload (bad signature/authorization)" };
+        }
+        const extra = (p.accepted.extra ?? {});
+        return {
+            ok: true,
+            payment: {
+                version: 2,
+                scheme: p.accepted.scheme,
+                network: p.accepted.network,
+                signature: p.payload.signature,
+                authorization: p.payload.authorization,
+                quoteId: extra.quoteId,
+                binding: extra.binding,
+                expiresAt: extra.expiresAt,
+                bodyHash: extra.bodyHash,
+            },
+        };
+    }
+    const p = parsed;
+    if (p?.x402Version !== 1)
+        return { ok: false, error: "Unsupported x402 version" };
+    if (typeof p.payload?.signature !== "string" || !validAuthorization(p.payload?.authorization)) {
+        return { ok: false, error: "Malformed v1 payload (bad signature/authorization)" };
+    }
+    const extra = (p.extra ?? {});
+    return {
+        ok: true,
+        payment: {
+            version: 1,
+            scheme: p.scheme,
+            network: p.network,
+            signature: p.payload.signature,
+            authorization: p.payload.authorization,
+            quoteId: extra.quoteId,
+            binding: extra.binding,
+            expiresAt: extra.expiresAt,
+            bodyHash: extra.bodyHash,
+        },
+    };
+}
+/** v1 receipt — FurlPay's own X-PAYMENT-RESPONSE shape. */
+export function encodeReceiptV1(receipt) {
+    return b64encode(receipt);
+}
+/** v2 receipt — the reference SDK's SettleResponse shape. */
+export function encodeReceiptV2(receipt) {
+    return b64encode({
+        success: true,
+        transaction: receipt.transaction,
+        network: receipt.network,
+        payer: receipt.payer,
+        amount: receipt.amountAtomic,
+    });
+}
+export function decodeReceipt(header) {
+    try {
+        return b64decode(header);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,60 @@
+export interface ClaimStore {
+    /**
+     * Atomically claim `key`. Returns true iff THIS caller is the first to claim
+     * it. Must be a genuine compare-and-set — a get-then-set is a race, and the
+     * race is the vulnerability.
+     */
+    claim(key: string, ttlSeconds: number): Promise<boolean>;
+    /** False if claims are not shared across instances. */
+    readonly isDurable: boolean;
+}
+/**
+ * In-memory claim store. Single instance only.
+ *
+ * Bounded so a flood of distinct quoteIds cannot grow it without limit; eviction
+ * is oldest-expiry-first, and expired entries are dropped lazily on access.
+ */
+export declare class MemoryClaimStore implements ClaimStore {
+    private readonly maxEntries;
+    readonly isDurable = false;
+    private readonly entries;
+    constructor(maxEntries?: number);
+    claim(key: string, ttlSeconds: number): Promise<boolean>;
+    private evict;
+    /** Test/introspection helper. */
+    get size(): number;
+}
+/**
+ * Wrap any atomic set-if-not-exists primitive as a ClaimStore, without this
+ * package taking a Redis dependency.
+ *
+ * @example
+ *   import { Redis } from "@upstash/redis";
+ *   const redis = Redis.fromEnv();
+ *   const store = claimStoreFrom(
+ *     (key, ttl) => redis.set(key, 1, { nx: true, ex: ttl }).then((r) => r === "OK")
+ *   );
+ */
+export declare function claimStoreFrom(setNx: (key: string, ttlSeconds: number) => Promise<boolean>, isDurable?: boolean): ClaimStore;
+export interface UpstashClaimStoreOptions {
+    /** Upstash REST endpoint, e.g. https://eu2-xxx.upstash.io */
+    url?: string;
+    token?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Durable claim store backed by Upstash Redis over its REST API.
+ *
+ * Uses `SET key value NX EX ttl`, which is a genuine atomic compare-and-set on
+ * the Redis server — the burn is linearized across every instance, which is the
+ * whole property that makes it safe on serverless. Reads `UPSTASH_REDIS_REST_URL`
+ * and `UPSTASH_REDIS_REST_TOKEN` from the environment when not passed.
+ *
+ * Zero dependencies: it is one HTTP call, so it needs no Redis client library.
+ *
+ * @example
+ *   import { paywall, upstashClaimStore } from "@furlpay/gateway";
+ *   const pay = paywall({ price: 0.01, payTo, quoteSecret, claimStore: upstashClaimStore() });
+ */
+export declare function upstashClaimStore(opts?: UpstashClaimStoreOptions): ClaimStore;

package/dist/store.js

@@ -0,0 +1,134 @@
+// ---------------------------------------------------------------------------
+// Single-use claim store.
+//
+// Two tokens must be burned exactly once per payment: the EIP-3009 nonce (the
+// money-level token) and the quoteId (the resource-level token). "Exactly once"
+// has to hold ACROSS PROCESSES, which is the part that is easy to get wrong.
+//
+// The classic serverless bug: a `Set` in module scope looks like replay
+// protection and passes every local test, because in dev there is one process.
+// In production there are N lambdas, each with its own empty Set, so the same
+// X-PAYMENT replayed N times clears N different Sets and grants the resource N
+// times — one payment, N deliveries. The fix is an ATOMIC claim in shared state
+// (Redis SET NX), which linearizes the burn across every instance.
+//
+// MemoryClaimStore is therefore correct on exactly one instance and is labelled
+// as such. `isDurable` exists so a deployment can assert on it at boot rather
+// than discover it in an incident.
+// ---------------------------------------------------------------------------
+/**
+ * In-memory claim store. Single instance only.
+ *
+ * Bounded so a flood of distinct quoteIds cannot grow it without limit; eviction
+ * is oldest-expiry-first, and expired entries are dropped lazily on access.
+ */
+export class MemoryClaimStore {
+    maxEntries;
+    isDurable = false;
+    entries = new Map(); // key → expiry (ms)
+    constructor(maxEntries = 100_000) {
+        this.maxEntries = maxEntries;
+    }
+    async claim(key, ttlSeconds) {
+        const now = Date.now();
+        const existing = this.entries.get(key);
+        if (existing !== undefined && existing > now)
+            return false; // already burned
+        if (existing !== undefined)
+            this.entries.delete(key); // expired → reclaimable
+        if (this.entries.size >= this.maxEntries)
+            this.evict(now);
+        this.entries.set(key, now + ttlSeconds * 1000);
+        return true;
+    }
+    evict(now) {
+        for (const [k, expiry] of this.entries) {
+            if (expiry <= now)
+                this.entries.delete(k);
+        }
+        // Still full of live entries — drop the soonest-to-expire to stay bounded.
+        if (this.entries.size >= this.maxEntries) {
+            const oldest = [...this.entries.entries()].sort((a, b) => a[1] - b[1]);
+            const drop = Math.ceil(this.maxEntries * 0.1);
+            for (let i = 0; i < drop && i < oldest.length; i++)
+                this.entries.delete(oldest[i][0]);
+        }
+    }
+    /** Test/introspection helper. */
+    get size() {
+        return this.entries.size;
+    }
+}
+/**
+ * Wrap any atomic set-if-not-exists primitive as a ClaimStore, without this
+ * package taking a Redis dependency.
+ *
+ * @example
+ *   import { Redis } from "@upstash/redis";
+ *   const redis = Redis.fromEnv();
+ *   const store = claimStoreFrom(
+ *     (key, ttl) => redis.set(key, 1, { nx: true, ex: ttl }).then((r) => r === "OK")
+ *   );
+ */
+export function claimStoreFrom(setNx, isDurable = true) {
+    return {
+        isDurable,
+        async claim(key, ttlSeconds) {
+            try {
+                return await setNx(key, ttlSeconds);
+            }
+            catch {
+                // A claim store we cannot reach cannot prove single-use. Refusing the
+                // payment loses a sale; granting it risks unbounded duplicate delivery
+                // on a single authorization. Refuse.
+                return false;
+            }
+        },
+    };
+}
+/**
+ * Durable claim store backed by Upstash Redis over its REST API.
+ *
+ * Uses `SET key value NX EX ttl`, which is a genuine atomic compare-and-set on
+ * the Redis server — the burn is linearized across every instance, which is the
+ * whole property that makes it safe on serverless. Reads `UPSTASH_REDIS_REST_URL`
+ * and `UPSTASH_REDIS_REST_TOKEN` from the environment when not passed.
+ *
+ * Zero dependencies: it is one HTTP call, so it needs no Redis client library.
+ *
+ * @example
+ *   import { paywall, upstashClaimStore } from "@furlpay/gateway";
+ *   const pay = paywall({ price: 0.01, payTo, quoteSecret, claimStore: upstashClaimStore() });
+ */
+export function upstashClaimStore(opts = {}) {
+    const url = (opts.url ?? process.env.UPSTASH_REDIS_REST_URL ?? "").replace(/\/+$/, "");
+    const token = opts.token ?? process.env.UPSTASH_REDIS_REST_TOKEN ?? "";
+    const timeoutMs = opts.timeoutMs ?? 5_000;
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    if (!url || !token) {
+        throw new Error("@furlpay/gateway: upstashClaimStore() needs UPSTASH_REDIS_REST_URL and " +
+            "UPSTASH_REDIS_REST_TOKEN (or explicit url/token). Refusing to start with " +
+            "undurable replay protection that looks durable.");
+    }
+    return claimStoreFrom(async (key, ttlSeconds) => {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), timeoutMs);
+        try {
+            // Pipeline-free single command: ["SET", key, "1", "NX", "EX", ttl]
+            const res = await doFetch(url, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+                body: JSON.stringify(["SET", key, "1", "NX", "EX", String(ttlSeconds)]),
+                signal: ctl.signal,
+            });
+            if (!res.ok)
+                return false; // fail closed
+            const body = (await res.json());
+            // Redis returns "OK" when the key was set, null when it already existed.
+            return body?.result === "OK";
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }, true);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@furlpay/gateway",
+  "version": "0.1.0",
+  "description": "Self-hostable x402 monetization gateway — paywall any API, MCP tool, dataset or model endpoint with stablecoin pay-per-call. Framework-agnostic, zero runtime dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "furlpay-gateway": "dist/cli.js"
+  },
+  "files": ["dist", "src", "LICENSE", "SECURITY.md"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/adapters/express.d.ts",
+      "import": "./dist/adapters/express.js"
+    },
+    "./proxy": {
+      "types": "./dist/adapters/proxy.d.ts",
+      "import": "./dist/adapters/proxy.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/protocol.test.js test/gateway.test.js"
+  },
+  "keywords": [
+    "x402",
+    "monetization",
+    "paywall",
+    "agentic-payments",
+    "stablecoin",
+    "usdc",
+    "mcp",
+    "api-monetization",
+    "pay-per-call",
+    "facilitator"
+  ],
+  "repository": { "type": "git", "url": "https://github.com/furlpay/furlpay-gateway" },
+  "homepage": "https://furlpay.com",
+  "engines": { "node": ">=18" },
+  "devDependencies": {
+    "typescript": "5.5.3",
+    "@types/node": "20.14.10"
+  },
+  "publishConfig": { "access": "public" }
+}

package/src/adapters/express.ts

@@ -0,0 +1,122 @@
+import { Gateway, type GatewayOptions } from "../gateway.js";
+import type { SettlementReceipt } from "../protocol.js";
+
+// ---------------------------------------------------------------------------
+// Express / Connect adapter.
+//
+// Structurally typed against Express rather than importing it, so this package
+// keeps its zero-runtime-dependency promise and works with Connect, Polka, and
+// anything else with the same middleware shape.
+// ---------------------------------------------------------------------------
+
+interface ExpressLikeRequest {
+  method: string;
+  originalUrl?: string;
+  url: string;
+  headers: Record<string, string | string[] | undefined>;
+  protocol?: string;
+  secure?: boolean;
+  get?(name: string): string | undefined;
+  /** Raw body bytes — see `captureRawBody`. */
+  rawBody?: Buffer | string;
+  /** Set by this middleware once payment is confirmed. */
+  payment?: SettlementReceipt;
+}
+
+interface ExpressLikeResponse {
+  status(code: number): ExpressLikeResponse;
+  set(field: string, value: string): ExpressLikeResponse;
+  json(body: unknown): unknown;
+}
+
+type Next = (err?: unknown) => void;
+
+/**
+ * `express.json()` discards the raw bytes, but body binding needs to hash
+ * exactly what the client sent — a re-serialized `req.body` is a different byte
+ * string (key order, whitespace) and would hash differently every time.
+ *
+ * @example
+ *   app.use(express.json({ verify: captureRawBody }));
+ */
+export function captureRawBody(req: ExpressLikeRequest, _res: unknown, buf: Buffer): void {
+  req.rawBody = buf;
+}
+
+function absoluteUrl(req: ExpressLikeRequest): string {
+  const headerHost = req.get?.("host") ?? (req.headers.host as string | undefined);
+  const host = headerHost ?? "localhost";
+  const proto = req.secure ? "https" : (req.protocol ?? "http");
+  return `${proto}://${host}${req.originalUrl ?? req.url}`;
+}
+
+function flatHeaders(req: ExpressLikeRequest): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (typeof v === "string") out[k.toLowerCase()] = v;
+    else if (Array.isArray(v)) out[k.toLowerCase()] = v[0] ?? "";
+  }
+  return out;
+}
+
+const BODY_METHODS = new Set(["POST", "PUT", "PATCH"]);
+
+/**
+ * Express middleware that paywalls everything mounted after it.
+ *
+ * On success `req.payment` holds the settlement receipt, so the route handler
+ * can meter, log, or attribute the call to the paying agent.
+ *
+ * @example
+ *   app.get("/api/weather", expressPaywall({ ... }), (req, res) => {
+ *     res.json({ tempC: 17, paidBy: req.payment.payer });
+ *   });
+ */
+export function expressPaywall(opts: GatewayOptions) {
+  const gateway = new Gateway(opts);
+  const bindBody = opts.bindBody !== false;
+
+  return async function middleware(
+    req: ExpressLikeRequest,
+    res: ExpressLikeResponse,
+    next: Next
+  ): Promise<void> {
+    try {
+      const method = req.method.toUpperCase();
+
+      // Fail closed rather than silently downgrade: if body binding is on and we
+      // cannot see the raw bytes, a payment for one body would unlock any other.
+      if (bindBody && BODY_METHODS.has(method) && req.rawBody === undefined) {
+        res
+          .status(500)
+          .set("Cache-Control", "no-store")
+          .json({
+            error:
+              "gateway_misconfigured: body binding is enabled but req.rawBody is unset. " +
+              "Add `app.use(express.json({ verify: captureRawBody }))`, or pass `bindBody: false` " +
+              "to accept that a payment for one body unlocks any other.",
+          });
+        return;
+      }
+
+      const decision = await gateway.authorize({
+        method,
+        url: absoluteUrl(req),
+        headers: flatHeaders(req),
+        body: req.rawBody,
+      });
+
+      if (decision.kind !== "allow") {
+        for (const [k, v] of Object.entries(decision.headers)) res.set(k, v);
+        res.status(decision.status).json(decision.body);
+        return;
+      }
+
+      for (const [k, v] of Object.entries(decision.headers)) res.set(k, v);
+      req.payment = decision.receipt;
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}

package/src/adapters/fetch.ts

@@ -0,0 +1,88 @@
+import { Gateway, type GatewayDecision, type GatewayOptions } from "../gateway.js";
+import type { SettlementReceipt } from "../protocol.js";
+
+// ---------------------------------------------------------------------------
+// Web-standard adapter — Next.js App Router, Hono, Cloudflare Workers, Deno,
+// Bun, and anything else that speaks Request → Response.
+//
+// On Workers, node:crypto requires the `nodejs_compat` compatibility flag.
+// ---------------------------------------------------------------------------
+
+export type FetchHandler<Ctx = unknown> = (
+  req: Request,
+  ctx: Ctx
+) => Response | Promise<Response>;
+
+/** A handler that also receives the settlement receipt for the request. */
+export type PaidHandler<Ctx = unknown> = (
+  req: Request,
+  ctx: Ctx,
+  receipt: SettlementReceipt
+) => Response | Promise<Response>;
+
+function toResponse(decision: Exclude<GatewayDecision, { kind: "allow" }>): Response {
+  return new Response(JSON.stringify(decision.body), {
+    status: decision.status,
+    headers: decision.headers,
+  });
+}
+
+/** Read the body without consuming it for the wrapped handler. */
+async function readBody(req: Request): Promise<string | undefined> {
+  if (!req.body) return undefined;
+  try {
+    return await req.clone().text();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Wrap a fetch-style handler so it only runs after payment.
+ *
+ * @example
+ *   // app/api/weather/route.ts
+ *   import { paywall } from "@furlpay/gateway";
+ *
+ *   const pay = paywall({
+ *     price: 0.01,
+ *     payTo: process.env.MERCHANT_WALLET!,
+ *     quoteSecret: process.env.QUOTE_SECRET!,
+ *     network: "base",
+ *   });
+ *
+ *   export const GET = pay(async () => Response.json({ tempC: 17 }));
+ */
+export function paywall(opts: GatewayOptions) {
+  const gateway = new Gateway(opts);
+
+  function wrap<Ctx = unknown>(handler: PaidHandler<Ctx>): FetchHandler<Ctx> {
+    return async (req: Request, ctx: Ctx): Promise<Response> => {
+      const decision = await gateway.authorize({
+        method: req.method,
+        url: req.url,
+        headers: req.headers,
+        body: await readBody(req),
+      });
+
+      if (decision.kind !== "allow") return toResponse(decision);
+
+      const res = await handler(req, ctx, decision.receipt);
+
+      // Stamp the receipt and no-store onto whatever the handler returned. A
+      // paid 200 that a CDN caches is a paid resource served free to the next
+      // unpaid caller, so this is not optional.
+      const out = new Response(res.body, res);
+      for (const [k, v] of Object.entries(decision.headers)) out.headers.set(k, v);
+      return out;
+    };
+  }
+
+  wrap.gateway = gateway;
+  return wrap;
+}
+
+/** Escape hatch for hand-rolled routing: get the decision, do what you like. */
+export function createGateway(opts: GatewayOptions): Gateway {
+  return new Gateway(opts);
+}