@faremeter/facilitator 0.16.0 → 0.17.0

package/dist/src/routes.js

@@ -1,10 +1,41 @@
 import { getLogger } from "@faremeter/logs";
 import { Hono } from "hono";
 import * as x from "@faremeter/types/x402";
+import * as x2 from "@faremeter/types/x402v2";
 import { isValidationError } from "@faremeter/types";
-import {} from "@faremeter/types/x402";
+import { caip2ToLegacyName, legacyNameToCAIP2 } from "@faremeter/info/evm";
+import { caip2ToLegacyNetworkIds, legacyNetworkIdToCAIP2, } from "@faremeter/info/solana";
 import { allSettledWithTimeout } from "./promise.js";
+import { adaptRequirementsV1ToV2, adaptPayloadV1ToV2, adaptVerifyResponseV2ToV1, adaptSettleResponseV2ToV1, adaptRequirementsV2ToV1, extractResourceInfoV1, adaptSupportedKindV2ToV1, } from "./adapters.js";
 const logger = await getLogger(["faremeter", "facilitator"]);
+/**
+ * Translate a CAIP-2 network identifier to a v1 legacy network name.
+ * Falls through to the original identifier if no mapping exists.
+ */
+function translateNetwork(network) {
+    const evmLegacy = caip2ToLegacyName(network);
+    if (evmLegacy)
+        return evmLegacy;
+    const solanaLegacy = caip2ToLegacyNetworkIds(network);
+    const firstSolanaId = solanaLegacy?.[0];
+    if (firstSolanaId)
+        return firstSolanaId;
+    return network;
+}
+/**
+ * Normalize a v1 legacy network name to a CAIP-2 identifier.
+ * Falls through to the original identifier if no mapping exists (it may
+ * already be CAIP-2 or an unknown network).
+ */
+function normalizeNetwork(network) {
+    const evmCaip2 = legacyNameToCAIP2(network);
+    if (evmCaip2)
+        return evmCaip2;
+    const solanaNetwork = legacyNetworkIdToCAIP2(network);
+    if (solanaNetwork)
+        return solanaNetwork.caip2;
+    return network;
+}
 function summarizeRequirements({ scheme, network, asset, payTo, }) {
     return {
         scheme,
@@ -13,181 +44,371 @@ function summarizeRequirements({ scheme, network, asset, payTo, }) {
         payTo,
     };
 }
+export function getClientIP(c) {
+    const xff = c.req.header("X-Forwarded-For");
+    if (xff) {
+        const firstIP = xff.split(",")[0]?.trim();
+        if (firstIP)
+            return firstIP;
+    }
+    return c.req.header("X-Real-IP");
+}
 function processException(step, e, cb) {
-    let msg = undefined;
     // XXX - We can do a better job of determining if it's a chain
     // error, or some other issue.
-    if (e instanceof Error) {
-        msg = e.message;
-    }
-    else {
-        msg = `unknown error handling ${step}`;
-    }
+    const msg = e instanceof Error ? e.message : `unknown error handling ${step}`;
     logger.error(`Caught exception during ${step}`, {
         exception: e,
     });
     return cb(msg);
 }
+/**
+ * Creates a Hono router with x402 facilitator endpoints.
+ *
+ * The router provides the following endpoints:
+ * - POST /verify - Verify a payment without settling
+ * - POST /settle - Verify and settle a payment
+ * - POST /accepts - Get payment requirements for a resource
+ * - GET /supported - List supported payment schemes and networks
+ *
+ * Both v1 and v2 protocol formats are supported on all endpoints.
+ *
+ * @param args - Configuration including payment handlers and timeouts
+ * @returns A Hono router instance with facilitator endpoints
+ */
 export function createFacilitatorRoutes(args) {
     const router = new Hono();
-    function sendVerifyError(c, status, msg) {
-        const response = {
-            isValid: false,
-        };
+    function logRejected(results, label) {
+        for (const r of results) {
+            if (r.status === "rejected") {
+                const message = r.reason instanceof Error ? r.reason.message : "unknown reason";
+                logger.error(`failed to retrieve ${label} from facilitator handler: ${message}`, r.reason);
+            }
+        }
+    }
+    function logError(msg, stepLabel) {
         if (msg !== undefined) {
-            response.invalidReason = msg;
             logger.error(msg);
         }
         else {
-            logger.error("unknown error during verification");
+            logger.error(`unknown error during ${stepLabel}`);
         }
+    }
+    function sendVerifyErrorV1(c, status, msg) {
+        logError(msg, "verification");
         c.status(status);
+        const response = { isValid: false, payer: "" };
+        if (msg !== undefined) {
+            response.invalidReason = msg;
+        }
         return c.json(response);
     }
-    router.post("/verify", async (c) => {
-        const x402Req = x.x402VerifyRequest(await c.req.json());
-        if (isValidationError(x402Req)) {
-            return sendVerifyError(c, 400, `couldn't validate request: ${x402Req.summary}`);
+    function sendSettleErrorV1(c, status, msg) {
+        logError(msg, "settlement");
+        c.status(status);
+        const response = {
+            success: false,
+            payer: "",
+            transaction: "",
+            network: "",
+        };
+        if (msg !== undefined) {
+            response.errorReason = msg;
         }
-        let paymentPayload = x402Req.paymentPayload;
-        if (paymentPayload === undefined) {
-            const decodedHeader = x.x402PaymentHeaderToPayload(x402Req.paymentHeader);
-            if (isValidationError(decodedHeader)) {
-                return sendVerifyError(c, 400, `couldn't validate x402 payload: ${decodedHeader.summary}`);
-            }
-            paymentPayload = decodedHeader;
+        return c.json(response);
+    }
+    // Accepts errors are always v1 format. A v2 request that fails to parse
+    // falls through to v1 parsing, so this path is only reached for v1 errors.
+    function sendAcceptsError(c, status, msg) {
+        logError(msg, "accepts");
+        c.status(status);
+        return c.json({ x402Version: 1, accepts: [], error: msg ?? "" });
+    }
+    function sendVerifyErrorV2(c, status, msg) {
+        logError(msg, "verification");
+        c.status(status);
+        const response = { isValid: false };
+        if (msg !== undefined) {
+            response.invalidReason = msg;
         }
-        logger.debug("starting verifyment attempt for request", x402Req);
+        return c.json(response);
+    }
+    function sendSettleErrorV2(c, status, msg) {
+        logError(msg, "settlement");
+        c.status(status);
+        const response = {
+            success: false,
+            transaction: "",
+            network: "",
+        };
+        if (msg !== undefined) {
+            response.errorReason = msg;
+        }
+        return c.json(response);
+    }
+    /**
+     * Iterate handlers, invoking each until one returns a non-null result.
+     * Returns the handler result, or null if no handler matched.
+     * Throws on handler exceptions (caller decides how to surface the error).
+     */
+    async function tryHandlers(invoke) {
         for (const handler of args.handlers) {
-            let t;
-            if (handler.handleVerify === undefined) {
-                continue;
+            const result = await invoke(handler);
+            if (result !== null) {
+                return result;
             }
+        }
+        return null;
+    }
+    router.post("/verify", async (c) => {
+        const body = await c.req.json();
+        // Try v2 format first
+        const v2Req = x2.x402VerifyRequest(body);
+        if (!isValidationError(v2Req)) {
+            const clientIP = getClientIP(c);
+            logger.debug("starting verification attempt for v2 request", {
+                ...v2Req,
+                clientIP,
+            });
+            let result;
             try {
-                t = await handler.handleVerify(x402Req.paymentRequirements, paymentPayload);
+                result = await tryHandlers((handler) => handler.handleVerify
+                    ? handler.handleVerify(v2Req.paymentRequirements, v2Req.paymentPayload)
+                    : Promise.resolve(null));
             }
             catch (e) {
-                return processException("verify", e, (msg) => sendVerifyError(c, 500, msg));
+                return processException("verify", e, (msg) => sendVerifyErrorV2(c, 500, msg));
             }
-            if (t === null) {
-                continue;
+            if (result === null) {
+                logger.warning("attempt to verify was made with no handler found, requirements summary was", summarizeRequirements(v2Req.paymentRequirements));
+                return sendVerifyErrorV2(c, 400, "no matching payment handler found");
             }
-            logger.debug("facilitator handler agreed to verify and returned", t);
-            logger.info(`${t.isValid ? "succeeded" : "failed"} verifying request`, {
-                ...t,
-                requirements: summarizeRequirements(x402Req.paymentRequirements),
+            logger.info(`${result.isValid ? "succeeded" : "failed"} verifying v2 request`, {
+                ...result,
+                requirements: summarizeRequirements(v2Req.paymentRequirements),
+                clientIP,
             });
-            return c.json(t);
-        }
-        logger.warning("attempt to verify was made with no handler found, requirements summary was", summarizeRequirements(x402Req.paymentRequirements));
-        return sendVerifyError(c, 400, "no matching payment handler found");
-    });
-    function sendSettleError(c, status, msg) {
-        const response = {
-            success: false,
-            txHash: null,
-            networkId: null,
-        };
-        if (msg !== undefined) {
-            response.error = msg;
-            logger.error(msg);
+            return c.json(result);
         }
-        else {
-            logger.error("unknown error during settlement");
+        // Try v1 format
+        const v1Req = x.x402VerifyRequest(body);
+        if (isValidationError(v1Req)) {
+            return sendVerifyErrorV1(c, 400, `couldn't validate request: ${v1Req.summary}`);
         }
-        c.status(status);
-        return c.json(response);
-    }
-    router.post("/settle", async (c) => {
-        const x402Req = x.x402SettleRequest(await c.req.json());
-        if (isValidationError(x402Req)) {
-            return sendSettleError(c, 400, `couldn't validate request: ${x402Req.summary}`);
-        }
-        let paymentPayload = x402Req.paymentPayload;
+        let paymentPayload = v1Req.paymentPayload;
         if (paymentPayload === undefined) {
-            const decodedHeader = x.x402PaymentHeaderToPayload(x402Req.paymentHeader);
+            const decodedHeader = x.x402PaymentHeaderToPayload(v1Req.paymentHeader);
             if (isValidationError(decodedHeader)) {
-                return sendSettleError(c, 400, `couldn't validate x402 payload: ${decodedHeader.summary}`);
+                return sendVerifyErrorV1(c, 400, `couldn't validate x402 payload: ${decodedHeader.summary}`);
             }
             paymentPayload = decodedHeader;
         }
-        logger.debug("starting settlement attempt for request", x402Req);
-        for (const handler of args.handlers) {
-            let t;
+        const clientIP = getClientIP(c);
+        logger.debug("starting verification attempt for v1 request", {
+            ...v1Req,
+            clientIP,
+        });
+        const v2Requirements = adaptRequirementsV1ToV2(v1Req.paymentRequirements, normalizeNetwork);
+        const v2Payload = adaptPayloadV1ToV2(paymentPayload, v1Req.paymentRequirements, normalizeNetwork);
+        let result;
+        try {
+            result = await tryHandlers((handler) => handler.handleVerify
+                ? handler.handleVerify(v2Requirements, v2Payload)
+                : Promise.resolve(null));
+        }
+        catch (e) {
+            return processException("verify", e, (msg) => sendVerifyErrorV1(c, 500, msg));
+        }
+        if (result === null) {
+            logger.warning("attempt to verify was made with no handler found, requirements summary was", summarizeRequirements(v2Requirements));
+            return sendVerifyErrorV1(c, 400, "no matching payment handler found");
+        }
+        logger.info(`${result.isValid ? "succeeded" : "failed"} verifying v1 request`, {
+            ...result,
+            requirements: summarizeRequirements(v2Requirements),
+            clientIP,
+        });
+        return c.json(adaptVerifyResponseV2ToV1(result));
+    });
+    router.post("/settle", async (c) => {
+        const body = await c.req.json();
+        // Try v2 format first
+        const v2Req = x2.x402SettleRequest(body);
+        if (!isValidationError(v2Req)) {
+            const clientIP = getClientIP(c);
+            logger.debug("starting settlement attempt for v2 request", {
+                ...v2Req,
+                clientIP,
+            });
+            let result;
             try {
-                t = await handler.handleSettle(x402Req.paymentRequirements, paymentPayload);
+                result = await tryHandlers((handler) => handler.handleSettle(v2Req.paymentRequirements, v2Req.paymentPayload));
             }
             catch (e) {
-                return processException("settle", e, (msg) => sendSettleError(c, 500, msg));
+                return processException("settle", e, (msg) => sendSettleErrorV2(c, 500, msg));
             }
-            if (t === null) {
-                continue;
+            if (result === null) {
+                logger.warning("attempt to settle was made with no handler found, requirements summary was", summarizeRequirements(v2Req.paymentRequirements));
+                return sendSettleErrorV2(c, 400, "no matching payment handler found");
             }
-            logger.debug("facilitator handler accepted settlement and returned", t);
-            logger.info(`${t.success ? "succeeded" : "failed"} settlement request`, {
-                requirements: summarizeRequirements(x402Req.paymentRequirements),
-                txHash: t.txHash,
+            logger.info(`${result.success ? "succeeded" : "failed"} settlement v2 request`, {
+                requirements: summarizeRequirements(v2Req.paymentRequirements),
+                transaction: result.transaction,
+                clientIP,
             });
-            return c.json(t);
+            return c.json(result);
         }
-        sendSettleError(c, 400, "no matching payment handler found");
-        logger.warning("attempt to settle was made with no handler found, requirements summary was", summarizeRequirements(x402Req.paymentRequirements));
+        // Try v1 format
+        const v1Req = x.x402SettleRequest(body);
+        if (isValidationError(v1Req)) {
+            return sendSettleErrorV1(c, 400, `couldn't validate request: ${v1Req.summary}`);
+        }
+        let paymentPayload = v1Req.paymentPayload;
+        if (paymentPayload === undefined) {
+            const decodedHeader = x.x402PaymentHeaderToPayload(v1Req.paymentHeader);
+            if (isValidationError(decodedHeader)) {
+                return sendSettleErrorV1(c, 400, `couldn't validate x402 payload: ${decodedHeader.summary}`);
+            }
+            paymentPayload = decodedHeader;
+        }
+        const clientIP = getClientIP(c);
+        logger.debug("starting settlement attempt for v1 request", {
+            ...v1Req,
+            clientIP,
+        });
+        const v2Requirements = adaptRequirementsV1ToV2(v1Req.paymentRequirements, normalizeNetwork);
+        const v2Payload = adaptPayloadV1ToV2(paymentPayload, v1Req.paymentRequirements, normalizeNetwork);
+        let result;
+        try {
+            result = await tryHandlers((handler) => handler.handleSettle(v2Requirements, v2Payload));
+        }
+        catch (e) {
+            return processException("settle", e, (msg) => sendSettleErrorV1(c, 500, msg));
+        }
+        if (result === null) {
+            logger.warning("attempt to settle was made with no handler found, requirements summary was", summarizeRequirements(v2Requirements));
+            return sendSettleErrorV1(c, 400, "no matching payment handler found");
+        }
+        logger.info(`${result.success ? "succeeded" : "failed"} settlement v1 request`, {
+            requirements: summarizeRequirements(v2Requirements),
+            transaction: result.transaction,
+            clientIP,
+        });
+        return c.json(adaptSettleResponseV2ToV1(result, translateNetwork));
     });
     router.post("/accepts", async (c) => {
-        const x402Req = x.x402PaymentRequiredResponse(await c.req.json());
-        if (isValidationError(x402Req)) {
-            return sendSettleError(c, 400, `couldn't parse required response: ${x402Req.summary}`);
-        }
-        const results = await allSettledWithTimeout(args.handlers.flatMap((x) => x.getRequirements(x402Req.accepts)), args.timeout?.getRequirements ?? 500);
-        const accepts = results
-            .filter((x) => x.status === "fulfilled")
-            .map((x) => x.value)
+        const body = await c.req.json();
+        const clientIP = getClientIP(c);
+        // The /accepts request body shares the same shape as the payment required
+        // response (resource + accepts array), so we reuse the response validator.
+        const v2Req = x2.x402PaymentRequiredResponse(body);
+        if (!isValidationError(v2Req)) {
+            // Native v2 request - call handlers directly with v2 requirements
+            const results = await allSettledWithTimeout(args.handlers.flatMap((handler) => handler.getRequirements({
+                accepts: v2Req.accepts,
+                resource: v2Req.resource,
+            })), args.timeout?.getRequirements ?? 500);
+            const accepts = results
+                .filter((r) => r.status === "fulfilled")
+                .map((r) => r.value)
+                .flat();
+            logRejected(results, "requirements");
+            logger.debug(`returning ${accepts.length} accepts for v2 request`, {
+                accepts: accepts.map(summarizeRequirements),
+                clientIP,
+            });
+            c.status(200);
+            return c.json({
+                x402Version: 2,
+                resource: v2Req.resource,
+                accepts,
+            });
+        }
+        // Try v1 format (lenient: Coinbase's implementation omits the error field)
+        const v1Req = x.x402PaymentRequiredResponseLenient(body);
+        if (isValidationError(v1Req)) {
+            return sendAcceptsError(c, 400, `couldn't parse required response: ${v1Req.summary}`);
+        }
+        // Adapt v1 accepts to v2, normalizing legacy network names to CAIP-2
+        const v2Accepts = v1Req.accepts.map((req) => adaptRequirementsV1ToV2(req, normalizeNetwork));
+        const resourceInfo = v1Req.accepts[0]
+            ? extractResourceInfoV1(v1Req.accepts[0])
+            : { url: "" };
+        const results = await allSettledWithTimeout(args.handlers.flatMap((handler) => handler.getRequirements({
+            accepts: v2Accepts,
+            resource: resourceInfo,
+        })), args.timeout?.getRequirements ?? 500);
+        const v2Results = results
+            .filter((r) => r.status === "fulfilled")
+            .map((r) => r.value)
             .flat();
-        results.forEach((x) => {
-            if (x.status === "rejected") {
-                let message;
-                if (x.reason instanceof Error) {
-                    message = x.reason.message;
-                }
-                else {
-                    message = "unknown reason";
-                }
-                logger.error(`failed to retrieve requirements from facilitator handler: ${message}`, x.reason);
-            }
-        });
-        logger.debug(`returning ${accepts.length} accepts`, {
-            accepts: accepts.map(summarizeRequirements),
+        logRejected(results, "requirements");
+        // Adapt v2 results back to v1 format
+        const accepts = v2Results.map((r) => adaptRequirementsV2ToV1(r, resourceInfo, translateNetwork));
+        logger.debug(`returning ${accepts.length} accepts for v1 request`, {
+            accepts: accepts.map((a) => ({
+                scheme: a.scheme,
+                network: a.network,
+                asset: a.asset,
+                payTo: a.payTo,
+            })),
+            clientIP,
         });
         c.status(200);
         return c.json({
             x402Version: 1,
             accepts,
+            error: "",
         });
     });
     router.get("/supported", async (c) => {
-        const results = await allSettledWithTimeout(args.handlers.flatMap((x) => (x.getSupported ? x.getSupported() : [])), args.timeout?.getSupported ?? 500);
-        const kinds = results
-            .filter((x) => x.status === "fulfilled")
-            .map((x) => x.value)
+        const clientIP = getClientIP(c);
+        const results = await allSettledWithTimeout(args.handlers.flatMap((handler) => handler.getSupported ? handler.getSupported() : []), args.timeout?.getSupported ?? 500);
+        const v2Kinds = results
+            .filter((r) => r.status === "fulfilled")
+            .map((r) => r.value)
             .flat();
-        results.forEach((x) => {
-            if (x.status === "rejected") {
-                let message;
-                if (x.reason instanceof Error) {
-                    message = x.reason.message;
+        logRejected(results, "supported");
+        // Aggregate signers from handlers
+        const signers = {};
+        for (const handler of args.handlers) {
+            if (handler.getSigners) {
+                try {
+                    const handlerSigners = await handler.getSigners();
+                    for (const [network, addresses] of Object.entries(handlerSigners)) {
+                        if (signers[network]) {
+                            // Merge addresses, avoiding duplicates
+                            const existing = new Set(signers[network]);
+                            for (const addr of addresses) {
+                                if (!existing.has(addr)) {
+                                    signers[network].push(addr);
+                                }
+                            }
+                        }
+                        else {
+                            signers[network] = [...addresses];
+                        }
+                    }
                 }
-                else {
-                    message = "unknown reason";
+                catch (e) {
+                    logger.error("failed to retrieve signers from facilitator handler", {
+                        error: e,
+                    });
                 }
-                logger.error(`failed to retrieve supported from facilitator handler: ${message}`, x.reason);
             }
-        });
-        logger.debug(`returning ${kinds.length} kinds supported`, {
-            kinds,
+        }
+        // Advertise both v1 and v2 support for all kinds
+        const v1Kinds = v2Kinds.map((k) => adaptSupportedKindV2ToV1(k, translateNetwork));
+        const allKinds = [...v1Kinds, ...v2Kinds];
+        logger.debug(`returning ${allKinds.length} kinds supported`, {
+            kinds: allKinds,
+            clientIP,
         });
         c.status(200);
         return c.json({
-            kinds,
+            kinds: allKinds,
+            extensions: [],
+            signers,
         });
     });
     return router;

package/dist/src/routes.test.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env pnpm tsx
+export {};
+//# sourceMappingURL=routes.test.d.ts.map

package/dist/src/routes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.test.d.ts","sourceRoot":"","sources":["../../src/routes.test.ts"],"names":[],"mappings":""}

package/dist/src/routes.test.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env pnpm tsx
+import t from "tap";
+import { getClientIP } from "./routes.js";
+function mockContext(headers) {
+    return {
+        req: {
+            header: (key) => headers[key],
+        },
+    };
+}
+await t.test("getClientIP returns first IP from X-Forwarded-For", async (t) => {
+    const c = mockContext({
+        "X-Forwarded-For": "192.168.1.1, 10.0.0.1, 172.16.0.1",
+    });
+    t.equal(getClientIP(c), "192.168.1.1");
+    t.end();
+});
+await t.test("getClientIP trims whitespace from X-Forwarded-For", async (t) => {
+    const c = mockContext({
+        "X-Forwarded-For": "  192.168.1.1  , 10.0.0.1",
+    });
+    t.equal(getClientIP(c), "192.168.1.1");
+    t.end();
+});
+await t.test("getClientIP returns single IP from X-Forwarded-For", async (t) => {
+    const c = mockContext({
+        "X-Forwarded-For": "192.168.1.1",
+    });
+    t.equal(getClientIP(c), "192.168.1.1");
+    t.end();
+});
+await t.test("getClientIP falls back to X-Real-IP when X-Forwarded-For is missing", async (t) => {
+    const c = mockContext({
+        "X-Real-IP": "10.0.0.1",
+    });
+    t.equal(getClientIP(c), "10.0.0.1");
+    t.end();
+});
+await t.test("getClientIP prefers X-Forwarded-For over X-Real-IP", async (t) => {
+    const c = mockContext({
+        "X-Forwarded-For": "192.168.1.1",
+        "X-Real-IP": "10.0.0.1",
+    });
+    t.equal(getClientIP(c), "192.168.1.1");
+    t.end();
+});
+await t.test("getClientIP returns undefined when no proxy headers present", async (t) => {
+    const c = mockContext({});
+    t.equal(getClientIP(c), undefined);
+    t.end();
+});
+await t.test("getClientIP returns undefined for empty X-Forwarded-For", async (t) => {
+    const c = mockContext({
+        "X-Forwarded-For": "",
+    });
+    t.equal(getClientIP(c), undefined);
+    t.end();
+});
+await t.test("getClientIP returns undefined for whitespace-only X-Forwarded-For", async (t) => {
+    const c = mockContext({
+        "X-Forwarded-For": "   ",
+    });
+    t.equal(getClientIP(c), undefined);
+    t.end();
+});