@furlpay/gateway 0.1.0

package/dist/gateway.js

@@ -0,0 +1,369 @@
+import crypto from "node:crypto";
+import { DEFAULT_QUOTE_TTL_SECONDS, HEADER_V1_RECEIPT, HEADER_V2_RECEIPT, HEADER_V2_REQUIRED, LATEST_X402_VERSION, NETWORK_USDC, REPLAY_CLAIM_TTL_SECONDS, USDC_DECIMALS, atomicAmount, b64encode, bindingMac, decodePayment, detectVersion, encodeReceiptV1, encodeReceiptV2, hashBody, noStoreHeaders, requiredConfirmations, timingSafeEqualHex, } from "./protocol.js";
+import { FURLPAY_FACILITATOR, httpFacilitator, } from "./facilitator.js";
+import { MemoryClaimStore } from "./store.js";
+const BODY_METHODS = new Set(["POST", "PUT", "PATCH"]);
+function lookup(headers) {
+    if (typeof headers.get === "function") {
+        return (name) => headers.get(name);
+    }
+    const rec = headers;
+    const lower = {};
+    for (const [k, v] of Object.entries(rec))
+        if (v !== undefined)
+            lower[k.toLowerCase()] = v;
+    return (name) => lower[name.toLowerCase()] ?? null;
+}
+export class Gateway {
+    opts;
+    facilitator;
+    claims;
+    network;
+    asset;
+    ttl;
+    constructor(opts) {
+        this.opts = opts;
+        if (!opts.quoteSecret || opts.quoteSecret.length < 16) {
+            throw new Error("@furlpay/gateway: `quoteSecret` is required and must be at least 16 chars. " +
+                "Generate one with: npx @furlpay/gateway secret");
+        }
+        if (!opts.payTo)
+            throw new Error("@furlpay/gateway: `payTo` is required.");
+        this.network = opts.network ?? "base";
+        const asset = opts.asset ?? NETWORK_USDC[this.network];
+        if (!asset) {
+            throw new Error(`@furlpay/gateway: no canonical USDC address known for network "${this.network}" — pass \`asset\` explicitly.`);
+        }
+        this.asset = asset;
+        this.ttl = opts.quoteTtlSeconds ?? DEFAULT_QUOTE_TTL_SECONDS;
+        this.claims = opts.claimStore ?? new MemoryClaimStore();
+        this.facilitator =
+            typeof opts.facilitator === "string"
+                ? httpFacilitator(opts.facilitator)
+                : (opts.facilitator ?? httpFacilitator(FURLPAY_FACILITATOR));
+    }
+    /** True when replay claims are shared across instances. Assert this at boot in
+     *  any multi-instance deployment. */
+    get replayProtectionDurable() {
+        return this.claims.isDurable;
+    }
+    // ── quoting ─────────────────────────────────────────────────────────────
+    resourceId(method, url) {
+        if (this.opts.resource)
+            return this.opts.resource({ method, url });
+        return `${url.origin}${url.pathname}${url.search}`;
+    }
+    context(input) {
+        const url = input.url instanceof URL ? input.url : new URL(input.url);
+        const method = input.method.toUpperCase();
+        return {
+            method,
+            resource: this.resourceId(method, url),
+            url,
+            headers: input.headers instanceof Headers ? input.headers : new Headers(),
+        };
+    }
+    async priceFor(ctx) {
+        return typeof this.opts.price === "function" ? await this.opts.price(ctx) : this.opts.price;
+    }
+    describe(ctx) {
+        if (typeof this.opts.description === "function")
+            return this.opts.description(ctx);
+        return this.opts.description ?? `${ctx.method} ${ctx.url.pathname} (per call)`;
+    }
+    shouldBindBody(method, body) {
+        if (this.opts.bindBody === false)
+            return false;
+        if (!BODY_METHODS.has(method))
+            return false;
+        if (body === undefined || body === null)
+            return false;
+        return body.length > 0;
+    }
+    /** Mint a fresh quote for this request. */
+    async mint(input) {
+        const ctx = this.context(input);
+        const amount = atomicAmount(await this.priceFor(ctx), USDC_DECIMALS);
+        return {
+            method: ctx.method,
+            resource: ctx.resource,
+            amount,
+            quoteId: crypto.randomBytes(16).toString("hex"),
+            expiresAt: Math.floor(Date.now() / 1000) + this.ttl,
+            bodyHash: this.shouldBindBody(ctx.method, input.body) ? hashBody(input.body) : undefined,
+            description: this.describe(ctx),
+            mimeType: this.opts.mimeType ?? "application/json",
+        };
+    }
+    extraFor(q) {
+        return {
+            name: this.opts.assetName ?? "USD Coin",
+            version: this.opts.assetVersion ?? "2",
+            quoteId: q.quoteId,
+            expiresAt: q.expiresAt,
+            binding: bindingMac(this.opts.quoteSecret, {
+                method: q.method,
+                resource: q.resource,
+                amount: q.amount,
+                quoteId: q.quoteId,
+                expiresAt: q.expiresAt,
+                bodyHash: q.bodyHash,
+            }),
+            ...(q.bodyHash ? { bodyHash: q.bodyHash } : {}),
+        };
+    }
+    toV1(q) {
+        return {
+            scheme: "exact",
+            network: this.network,
+            maxAmountRequired: q.amount,
+            resource: q.resource,
+            description: q.description,
+            mimeType: q.mimeType,
+            payTo: this.opts.payTo,
+            maxTimeoutSeconds: this.ttl,
+            asset: this.asset,
+            extra: this.extraFor(q),
+        };
+    }
+    toV2(q) {
+        return {
+            scheme: "exact",
+            network: this.network,
+            asset: this.asset,
+            amount: q.amount,
+            payTo: this.opts.payTo,
+            maxTimeoutSeconds: this.ttl,
+            extra: this.extraFor(q),
+        };
+    }
+    resourceInfo(q) {
+        return {
+            url: q.resource,
+            description: q.description,
+            mimeType: q.mimeType,
+            ...(this.opts.serviceName ? { serviceName: this.opts.serviceName } : {}),
+            ...(this.opts.tags?.length ? { tags: this.opts.tags } : {}),
+            ...(this.opts.iconUrl ? { iconUrl: this.opts.iconUrl } : {}),
+        };
+    }
+    /** Public quote surface — the v2 402 payload for this request. */
+    async quote(input) {
+        const q = await this.mint(input);
+        return { x402Version: 2, resource: this.resourceInfo(q), accepts: [this.toV2(q)] };
+    }
+    /**
+     * 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.
+     */
+    async challenge(input, error) {
+        const q = await this.mint(input);
+        const v2 = {
+            x402Version: 2,
+            error,
+            resource: this.resourceInfo(q),
+            accepts: [this.toV2(q)],
+        };
+        const v1 = { x402Version: 1, error, accepts: [this.toV1(q)] };
+        return {
+            kind: "challenge",
+            status: 402,
+            body: v1,
+            headers: {
+                ...noStoreHeaders,
+                "Content-Type": "application/json",
+                [HEADER_V2_REQUIRED]: b64encode(v2),
+            },
+        };
+    }
+    reject(error) {
+        return {
+            kind: "reject",
+            status: 400,
+            body: { error },
+            headers: { ...noStoreHeaders, "Content-Type": "application/json" },
+        };
+    }
+    // ── the gate ────────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async authorize(input) {
+        const ctx = this.context(input);
+        const get = lookup(input.headers);
+        const clientVersion = detectVersion(get);
+        if (clientVersion === null)
+            return this.challenge(input, "Payment required");
+        const decoded = decodePayment(get);
+        if (!decoded.ok) {
+            // Malformed is the client's bug, not a pricing failure — a 402 here would
+            // invite the agent to pay again against a payload we could not even read.
+            await this.opts.onRejected?.({ reason: decoded.error, resource: ctx.resource });
+            return this.reject(decoded.error);
+        }
+        const p = decoded.payment;
+        const auth = p.authorization;
+        const fail = async (reason) => {
+            await this.opts.onRejected?.({ reason, resource: ctx.resource, payer: auth.from });
+            return this.challenge(input, reason);
+        };
+        // ── re-derive the expectation; the client's echo is never the source ──
+        const expectedAmount = atomicAmount(await this.priceFor(ctx), USDC_DECIMALS);
+        if (p.scheme !== "exact")
+            return fail("Unsupported scheme");
+        if (p.network !== this.network)
+            return fail(`Wrong network (expected ${this.network})`);
+        if (auth.to.toLowerCase() !== this.opts.payTo.toLowerCase()) {
+            return fail("Payment not addressed to this recipient");
+        }
+        // Integer compare — "9000" > "10000" lexicographically.
+        try {
+            if (BigInt(auth.value) < BigInt(expectedAmount)) {
+                return fail(`Insufficient amount (expected ${expectedAmount} atomic units)`);
+            }
+        }
+        catch {
+            return fail("Invalid amount");
+        }
+        // ── binding: this resource, this price, this body? ──
+        const { quoteId, binding, expiresAt } = p;
+        if (!quoteId || !binding || typeof expiresAt !== "number") {
+            return fail("Missing quote binding (re-request the 402 quote)");
+        }
+        let bodyHash;
+        if (this.shouldBindBody(ctx.method, input.body)) {
+            bodyHash = hashBody(input.body);
+            if (!p.bodyHash)
+                return fail("Quote is not body-bound (re-request the 402 quote)");
+            if (!timingSafeEqualHex(p.bodyHash, bodyHash)) {
+                return fail("Body does not match the body this quote was issued for");
+            }
+        }
+        const expectedMac = bindingMac(this.opts.quoteSecret, {
+            method: ctx.method,
+            resource: ctx.resource,
+            amount: expectedAmount,
+            quoteId,
+            expiresAt,
+            bodyHash,
+        });
+        if (!timingSafeEqualHex(expectedMac, binding)) {
+            // The most important line in this file: a payment minted for a cheap
+            // resource dies here when presented to an expensive one.
+            return fail("Quote binding mismatch (payment bound to a different resource)");
+        }
+        // ── freshness ──
+        const now = Math.floor(Date.now() / 1000);
+        if (now > expiresAt)
+            return fail("Quote expired (re-request the 402 quote)");
+        const validAfter = Number(auth.validAfter);
+        const validBefore = Number(auth.validBefore);
+        if (Number.isFinite(validAfter) && now < validAfter)
+            return fail("Authorization not yet valid");
+        if (Number.isFinite(validBefore) && now > validBefore)
+            return fail("Authorization expired");
+        // ── single-use. Nonce first: it is the money-level token, so burning it
+        // before the quote means a racing replay never reaches settlement. ──
+        if (!(await this.claims.claim(`x402:nonce:${auth.nonce}`, REPLAY_CLAIM_TTL_SECONDS))) {
+            return fail("Authorization already used (replay)");
+        }
+        if (!(await this.claims.claim(`x402:quote:${quoteId}`, REPLAY_CLAIM_TTL_SECONDS))) {
+            return fail("Quote already redeemed (replay)");
+        }
+        // ── verify + settle, in the dialect the facilitator speaks ──
+        const q = {
+            method: ctx.method,
+            resource: ctx.resource,
+            amount: expectedAmount,
+            quoteId,
+            expiresAt,
+            bodyHash,
+            description: this.describe(ctx),
+            mimeType: this.opts.mimeType ?? "application/json",
+        };
+        const fReq = this.facilitatorRequest(q, p, clientVersion);
+        if (this.opts.settle === false) {
+            const verdict = await this.facilitator.verify(fReq);
+            if (!verdict.isValid)
+                return fail(verdict.invalidReason ?? "Payment verification failed");
+            return this.allow(clientVersion, {
+                payer: verdict.payer ?? auth.from,
+                transaction: "",
+                network: this.network,
+                asset: this.asset,
+                amountAtomic: auth.value,
+                resource: ctx.resource,
+                settledAt: new Date().toISOString(),
+            });
+        }
+        const settled = await this.facilitator.settle(fReq);
+        if (!settled.success) {
+            // The nonce stays burned. A settle that errored may STILL land on-chain,
+            // so freeing it would reopen replay against a payment that does confirm.
+            // An honest retry signs a fresh nonce, so this never blocks a real payer.
+            return fail(settled.errorReason ?? "Settlement failed");
+        }
+        const needed = requiredConfirmations(auth.value);
+        if (typeof settled.confirmations === "number" && settled.confirmations < needed) {
+            return fail(`Insufficient confirmations (${settled.confirmations}/${needed})`);
+        }
+        return this.allow(clientVersion, {
+            payer: settled.payer ?? auth.from,
+            transaction: settled.transaction ?? "",
+            network: settled.network ?? this.network,
+            asset: this.asset,
+            // v2's `upto` scheme can settle less than the authorized maximum.
+            amountAtomic: settled.amount ?? auth.value,
+            resource: ctx.resource,
+            confirmations: settled.confirmations,
+            settledAt: new Date().toISOString(),
+        });
+    }
+    /** Rebuild the requirements the quote was minted with, so the facilitator
+     *  checks the payment against the SERVER's terms, not the client's copy. */
+    facilitatorRequest(q, payment, clientVersion) {
+        const version = this.opts.facilitatorVersion ?? clientVersion;
+        if (version === 2) {
+            return {
+                x402Version: 2,
+                paymentPayload: {
+                    x402Version: 2,
+                    resource: this.resourceInfo(q),
+                    accepted: this.toV2(q),
+                    payload: { signature: payment.signature, authorization: payment.authorization },
+                },
+                paymentRequirements: this.toV2(q),
+            };
+        }
+        return {
+            x402Version: 1,
+            paymentPayload: {
+                x402Version: 1,
+                scheme: "exact",
+                network: this.network,
+                payload: { signature: payment.signature, authorization: payment.authorization },
+                extra: this.extraFor(q),
+            },
+            paymentRequirements: this.toV1(q),
+        };
+    }
+    /** Answer in the dialect the client spoke — and, harmlessly, the other one too,
+     *  so a proxy or SDK expecting either finds its receipt. */
+    async allow(version, receipt) {
+        await this.opts.onSettled?.(receipt);
+        return {
+            kind: "allow",
+            receipt,
+            headers: {
+                ...noStoreHeaders,
+                [HEADER_V1_RECEIPT]: encodeReceiptV1(receipt),
+                [HEADER_V2_RECEIPT]: encodeReceiptV2(receipt),
+            },
+        };
+    }
+}
+export { LATEST_X402_VERSION };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { LATEST_X402_VERSION, HEADER_V1_PAYMENT, HEADER_V1_RECEIPT, HEADER_V2_PAYMENT, HEADER_V2_RECEIPT, HEADER_V2_REQUIRED, MAX_HEADER_BYTES, DEFAULT_QUOTE_TTL_SECONDS, REPLAY_CLAIM_TTL_SECONDS, NETWORK_USDC, USDC_DECIMALS, noStoreHeaders, requiredConfirmations, atomicAmount, bindingMac, hashBody, timingSafeEqualHex, b64encode, b64decode, detectVersion, decodePayment, encodeReceiptV1, encodeReceiptV2, decodeReceipt, type X402Version, type EIP3009Authorization, type QuoteExtra, type ResourceInfo, type PaymentRequirementsV1, type PaymentRequiredV1, type PaymentPayloadV1, type PaymentRequirementsV2, type PaymentRequiredV2, type PaymentPayloadV2, type NormalizedPayment, type SettlementReceipt, type BindingInput, type DecodedPayment, type HeaderLookup, } from "./protocol.js";
+export { FURLPAY_FACILITATOR, httpFacilitator, type FacilitatorClient, type FacilitatorRequest, type VerifyResult, type SettleResult, type SupportedKind, type HttpFacilitatorOptions, } from "./facilitator.js";
+export { MemoryClaimStore, claimStoreFrom, upstashClaimStore, type ClaimStore, type UpstashClaimStoreOptions, } from "./store.js";
+export { Gateway, type GatewayOptions, type GatewayDecision, type AuthorizeInput, type RequestContext, type PriceResolver, } from "./gateway.js";
+export { paywall, createGateway, type FetchHandler, type PaidHandler, } from "./adapters/fetch.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { LATEST_X402_VERSION, HEADER_V1_PAYMENT, HEADER_V1_RECEIPT, HEADER_V2_PAYMENT, HEADER_V2_RECEIPT, HEADER_V2_REQUIRED, MAX_HEADER_BYTES, DEFAULT_QUOTE_TTL_SECONDS, REPLAY_CLAIM_TTL_SECONDS, NETWORK_USDC, USDC_DECIMALS, noStoreHeaders, requiredConfirmations, atomicAmount, bindingMac, hashBody, timingSafeEqualHex, b64encode, b64decode, detectVersion, decodePayment, encodeReceiptV1, encodeReceiptV2, decodeReceipt, } from "./protocol.js";
+export { FURLPAY_FACILITATOR, httpFacilitator, } from "./facilitator.js";
+export { MemoryClaimStore, claimStoreFrom, upstashClaimStore, } from "./store.js";
+export { Gateway, } from "./gateway.js";
+export { paywall, createGateway, } from "./adapters/fetch.js";

package/dist/protocol.d.ts

@@ -0,0 +1,173 @@
+export type X402Version = 1 | 2;
+/** Default dialect for freshly-minted quotes when the client hasn't spoken yet. */
+export declare const LATEST_X402_VERSION: X402Version;
+export declare const HEADER_V1_PAYMENT = "x-payment";
+export declare const HEADER_V1_RECEIPT = "X-PAYMENT-RESPONSE";
+export declare const HEADER_V2_PAYMENT = "payment-signature";
+export declare const HEADER_V2_RECEIPT = "PAYMENT-RESPONSE";
+export declare const HEADER_V2_REQUIRED = "PAYMENT-REQUIRED";
+/** Web-layer hardening: cap the header before we spend cycles parsing it. */
+export declare const MAX_HEADER_BYTES = 8192;
+export declare const DEFAULT_QUOTE_TTL_SECONDS = 300;
+/** Must outlive any EIP-3009 validity window, or a late replay could re-claim a
+ *  freed key. */
+export declare const REPLAY_CLAIM_TTL_SECONDS = 86400;
+/** Canonical (native-issuance, not bridged) USDC per network. */
+export declare const NETWORK_USDC: Record<string, string>;
+export declare const USDC_DECIMALS = 6;
+export interface EIP3009Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+/** The quote fields we carry in `extra` — identical across v1 and v2, which is
+ *  what lets one binding scheme serve both. */
+export interface QuoteExtra {
+    name: string;
+    version: string;
+    quoteId: string;
+    expiresAt: number;
+    binding: string;
+    bodyHash?: string;
+    [k: string]: unknown;
+}
+export interface PaymentRequirementsV1 {
+    scheme: "exact";
+    network: string;
+    maxAmountRequired: string;
+    resource: string;
+    description: string;
+    mimeType: string;
+    outputSchema?: Record<string, unknown>;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    asset: string;
+    extra: QuoteExtra;
+}
+export interface PaymentRequiredV1 {
+    x402Version: 1;
+    error: string;
+    accepts: PaymentRequirementsV1[];
+}
+export interface PaymentPayloadV1 {
+    x402Version: 1;
+    scheme: string;
+    network: string;
+    payload: {
+        signature: string;
+        authorization: EIP3009Authorization;
+    };
+    extra?: Partial<QuoteExtra>;
+}
+/** v2 hoists resource metadata out of each requirement. `tags` / `serviceName`
+ *  / `iconUrl` are the protocol's native discovery fields — a facilitator can
+ *  crawl these, which is why a proprietary discovery index is the wrong build. */
+export interface ResourceInfo {
+    url: string;
+    description?: string;
+    mimeType?: string;
+    serviceName?: string;
+    tags?: string[];
+    iconUrl?: string;
+}
+export interface PaymentRequirementsV2 {
+    scheme: "exact";
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: QuoteExtra;
+}
+export interface PaymentRequiredV2 {
+    x402Version: 2;
+    error?: string;
+    resource: ResourceInfo;
+    accepts: PaymentRequirementsV2[];
+    extensions?: Record<string, unknown>;
+}
+export interface PaymentPayloadV2 {
+    x402Version: 2;
+    resource?: ResourceInfo;
+    /** The client echoes the FULL requirements it is paying against. Still not
+     *  trusted — every field is re-derived server-side and compared. */
+    accepted: PaymentRequirementsV2;
+    payload: {
+        signature: string;
+        authorization: EIP3009Authorization;
+    };
+    extensions?: Record<string, unknown>;
+}
+/** One internal shape both dialects collapse to, so the gate is written once. */
+export interface NormalizedPayment {
+    version: X402Version;
+    scheme: string;
+    network: string;
+    signature: string;
+    authorization: EIP3009Authorization;
+    /** Quote echo — the lookup key, never an assertion. */
+    quoteId?: string;
+    binding?: string;
+    expiresAt?: number;
+    bodyHash?: string;
+}
+/** 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 declare const noStoreHeaders: Record<string, string>;
+export declare function requiredConfirmations(amountAtomic: string): number;
+export declare function atomicAmount(priceUsd: number, decimals?: number): string;
+export interface BindingInput {
+    method: string;
+    resource: string;
+    amount: string;
+    quoteId: string;
+    expiresAt: number;
+    bodyHash?: string;
+}
+/**
+ * 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 declare function bindingMac(secret: string | Buffer, input: BindingInput): string;
+export declare function hashBody(body: string | Buffer): string;
+export declare function timingSafeEqualHex(a: string, b: string): boolean;
+export declare function b64encode(value: unknown): string;
+export declare function b64decode<T>(value: string): T;
+export type HeaderLookup = (name: string) => string | null;
+/** Which dialect did the client speak? `null` when it presented no payment. */
+export declare function detectVersion(get: HeaderLookup): X402Version | null;
+export type DecodedPayment = {
+    ok: true;
+    payment: NormalizedPayment;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Strict parse of whichever payment header is present, normalized to one shape.
+ * Malformed input is an error, never a silently-released resource.
+ */
+export declare function decodePayment(get: HeaderLookup): DecodedPayment;
+export interface SettlementReceipt {
+    payer: string;
+    transaction: string;
+    network: string;
+    asset: string;
+    amountAtomic: string;
+    resource: string;
+    confirmations?: number;
+    settledAt: string;
+}
+/** v1 receipt — FurlPay's own X-PAYMENT-RESPONSE shape. */
+export declare function encodeReceiptV1(receipt: SettlementReceipt): string;
+/** v2 receipt — the reference SDK's SettleResponse shape. */
+export declare function encodeReceiptV2(receipt: SettlementReceipt): string;
+export declare function decodeReceipt(header: string): SettlementReceipt | null;