@faremeter/middleware 0.12.0 → 0.14.0

package/README.md

@@ -0,0 +1,41 @@
+# @faremeter/middleware
+
+Server middleware for adding payment walls to API endpoints using the x402 protocol.
+
+## Installation
+
+```bash
+pnpm install @faremeter/middleware
+```
+
+## Features
+
+- Paywall any endpoint - Add `middleware` to any route
+- Framework agnostic - Express, Hono, or custom
+- Multi-chain support - Solana, EVM, extensible
+- Fast validation - Payment requirements caching
+- Facilitator integration - Handles settlement verification
+
+## API Reference
+
+<!-- TSDOC_START -->
+
+<!-- TSDOC_END -->
+
+## Examples
+
+See working examples in the [faremeter repository](https://github.com/faremeter/faremeter/tree/main/scripts):
+
+- [Express + Solana](https://github.com/faremeter/faremeter/blob/main/scripts/solana-example/server-express.ts)
+- [Express + EVM](https://github.com/faremeter/faremeter/blob/main/scripts/evm-example/server-express.ts)
+- [Hono + Solana](https://github.com/faremeter/faremeter/blob/main/scripts/solana-example/server-hono.ts)
+
+## Related Packages
+
+- [@faremeter/fetch](https://www.npmjs.com/package/@faremeter/fetch) - Client-side fetch wrapper
+- [@faremeter/info](https://www.npmjs.com/package/@faremeter/info) - Network/asset configuration helpers
+- [@faremeter/facilitator](https://www.npmjs.com/package/@faremeter/facilitator) - Payment facilitator service
+
+## License
+
+LGPL-3.0-only

package/dist/src/common.d.ts

@@ -49,6 +49,12 @@ export type HandleMiddlewareRequestArgs<MiddlewareResponse = unknown> = CommonMi
     getHeader: (key: string) => string | undefined;
     getPaymentRequiredResponse: typeof getPaymentRequiredResponse;
     sendJSONResponse: (status: PossibleStatusCodes, obj: PossibleJSONResponse) => MiddlewareResponse;
+    body: (context: {
+        paymentRequirements: x402PaymentRequirements;
+        paymentPayload: x402PaymentPayload;
+        settle: () => Promise<MiddlewareResponse | undefined>;
+        verify: () => Promise<MiddlewareResponse | undefined>;
+    }) => Promise<MiddlewareResponse | undefined>;
 };
 export declare function handleMiddlewareRequest<MiddlewareResponse>(args: HandleMiddlewareRequestArgs<MiddlewareResponse>): Promise<MiddlewareResponse | undefined>;
 export type createPaymentRequiredResponseCacheOpts = AgedLRUCacheOpts & {

package/dist/src/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/common.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EAKxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,gBAAgB,EAAgB,MAAM,SAAS,CAAC;AAI9D,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,uBAAuB,EAAE,EAClC,OAAO,EAAE,kBAAkB;;;;;;;;;;;;cA6B5B;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,QAAQ,QAS3D;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAEnE,KAAK,8BAA8B,GAAG;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,8BAA8B;;;;;;;;;;;;oBApC5B,CAAA;aAAuB,CAAC;;;GAkEjC;AAED,KAAK,mBAAmB,GAAG,GAAG,CAAC;AAC/B,KAAK,oBAAoB,GAAG,MAAM,CAAC;AAEnC,MAAM,MAAM,oBAAoB,GAAG;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,CAAC,mBAAmB,GAAG,mBAAmB,EAAE,CAAC,EAAE,CAAC;IACzD,WAAW,CAAC,EAAE,sCAAsC,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,kBAAkB,GAAG,OAAO,IAClE,oBAAoB,GAAG;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,gBAAgB,EAAE,CAChB,MAAM,EAAE,mBAAmB,EAC3B,GAAG,EAAE,oBAAoB,KACtB,kBAAkB,CAAC;CACzB,CAAC;AAEJ,wBAAsB,uBAAuB,CAAC,kBAAkB,EAC9D,IAAI,EAAE,2BAA2B,CAAC,kBAAkB,CAAC,2CAiEtD;AAED,MAAM,MAAM,sCAAsC,GAAG,gBAAgB,GAAG;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AACF,wBAAgB,kCAAkC,CAChD,IAAI,GAAE,sCAA2C;;EA8BlD"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/common.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EAOxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,gBAAgB,EAAgB,MAAM,SAAS,CAAC;AAI9D,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,uBAAuB,EAAE,EAClC,OAAO,EAAE,kBAAkB;;;;;;;;;;;;cA6B5B;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,QAAQ,QAS3D;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAEnE,KAAK,8BAA8B,GAAG;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,8BAA8B;;;;;;;;;;;;oBAtCoB,CAAC;aACtC,CAAC;;;GAmErB;AAED,KAAK,mBAAmB,GAAG,GAAG,CAAC;AAC/B,KAAK,oBAAoB,GAAG,MAAM,CAAC;AAEnC,MAAM,MAAM,oBAAoB,GAAG;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,CAAC,mBAAmB,GAAG,mBAAmB,EAAE,CAAC,EAAE,CAAC;IACzD,WAAW,CAAC,EAAE,sCAAsC,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,kBAAkB,GAAG,OAAO,IAClE,oBAAoB,GAAG;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,gBAAgB,EAAE,CAChB,MAAM,EAAE,mBAAmB,EAC3B,GAAG,EAAE,oBAAoB,KACtB,kBAAkB,CAAC;IACxB,IAAI,EAAE,CAAC,OAAO,EAAE;QACd,mBAAmB,EAAE,uBAAuB,CAAC;QAC7C,cAAc,EAAE,kBAAkB,CAAC;QACnC,MAAM,EAAE,MAAM,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;QACtD,MAAM,EAAE,MAAM,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;KACvD,KAAK,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;CAC/C,CAAC;AAEJ,wBAAsB,uBAAuB,CAAC,kBAAkB,EAC9D,IAAI,EAAE,2BAA2B,CAAC,kBAAkB,CAAC,2CA4GtD;AAED,MAAM,MAAM,sCAAsC,GAAG,gBAAgB,GAAG;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AACF,wBAAgB,kCAAkC,CAChD,IAAI,GAAE,sCAA2C;;EA8BlD"}

package/dist/src/common.js

@@ -1,5 +1,5 @@
 import { isValidationError } from "@faremeter/types";
-import { x402PaymentRequiredResponse, x402PaymentHeaderToPayload, x402SettleRequest, x402SettleResponse, } from "@faremeter/types/x402";
+import { x402PaymentRequiredResponse, x402PaymentHeaderToPayload, x402VerifyRequest, x402VerifyResponse, x402SettleRequest, x402SettleResponse, } from "@faremeter/types/x402";
 import { AgedLRUCache } from "./cache.js";
 import { logger } from "./logger.js";
 export function findMatchingPaymentRequirements(accepts, payload) {
@@ -64,39 +64,74 @@ export async function handleMiddlewareRequest(args) {
     if (!paymentHeader) {
         return sendPaymentRequired();
     }
-    const payload = x402PaymentHeaderToPayload(paymentHeader);
-    if (isValidationError(payload)) {
-        logger.debug(`couldn't validate client payload: ${payload.summary}`);
+    const paymentPayload = x402PaymentHeaderToPayload(paymentHeader);
+    if (isValidationError(paymentPayload)) {
+        logger.debug(`couldn't validate client payload: ${paymentPayload.summary}`);
         return sendPaymentRequired();
     }
-    const paymentRequirements = findMatchingPaymentRequirements(paymentRequiredResponse.accepts, payload);
+    const paymentRequirements = findMatchingPaymentRequirements(paymentRequiredResponse.accepts, paymentPayload);
     if (!paymentRequirements) {
-        logger.warning(`couldn't find matching payment requirements for payload`, payload);
+        logger.warning(`couldn't find matching payment requirements for payload`, paymentPayload);
         return sendPaymentRequired();
     }
-    const settleRequest = {
-        x402Version: 1,
-        paymentHeader,
-        paymentRequirements,
+    const settle = async () => {
+        const settleRequest = {
+            x402Version: 1,
+            paymentHeader,
+            paymentPayload,
+            paymentRequirements,
+        };
+        const t = await fetch(`${args.facilitatorURL}/settle`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(settleRequest),
+        });
+        const settlementResponse = x402SettleResponse(await t.json());
+        if (isValidationError(settlementResponse)) {
+            const msg = `error getting response from facilitator for settlement: ${settlementResponse.summary}`;
+            logger.error(msg);
+            throw new Error(msg);
+        }
+        if (!settlementResponse.success) {
+            logger.warning("failed to settle payment: {error}", settlementResponse);
+            return sendPaymentRequired();
+        }
     };
-    const t = await fetch(`${args.facilitatorURL}/settle`, {
-        method: "POST",
-        headers: {
-            Accept: "application/json",
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify(settleRequest),
+    const verify = async () => {
+        const verifyRequest = {
+            x402Version: 1,
+            paymentHeader,
+            paymentPayload,
+            paymentRequirements,
+        };
+        const t = await fetch(`${args.facilitatorURL}/verify`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(verifyRequest),
+        });
+        const verifyResponse = x402VerifyResponse(await t.json());
+        if (isValidationError(verifyResponse)) {
+            const msg = `error getting response from facilitator for verification: ${verifyResponse.summary}`;
+            logger.error(msg);
+            throw new Error(msg);
+        }
+        if (!verifyResponse.isValid) {
+            logger.warning("failed to settle payment: {invalidReason}", verifyResponse);
+            return sendPaymentRequired();
+        }
+    };
+    return await args.body({
+        paymentRequirements,
+        paymentPayload,
+        settle,
+        verify,
     });
-    const settlementResponse = x402SettleResponse(await t.json());
-    if (isValidationError(settlementResponse)) {
-        const msg = `error getting response from facilitator for settlement: ${settlementResponse.summary}`;
-        logger.error(msg);
-        throw new Error(msg);
-    }
-    if (!settlementResponse.success) {
-        logger.warning("failed to settle payment: {error}", settlementResponse);
-        return sendPaymentRequired();
-    }
 }
 export function createPaymentRequiredResponseCache(opts = {}) {
     if (opts.disable) {

package/dist/src/express.d.ts

@@ -1,6 +1,6 @@
 import { type CommonMiddlewareArgs } from "./common.js";
 import type { NextFunction, Request, Response } from "express";
 type createMiddlewareArgs = CommonMiddlewareArgs;
-export declare function createMiddleware(args: createMiddlewareArgs): Promise<(req: Request, res: Response, next: NextFunction) => Promise<void>>;
+export declare function createMiddleware(args: createMiddlewareArgs): Promise<(req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>>;
 export {};
 //# sourceMappingURL=express.d.ts.map

package/dist/src/express.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,KAAK,oBAAoB,GAAG,oBAAoB,CAAC;AAEjD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,iBAK5C,OAAO,OAAO,QAAQ,QAAQ,YAAY,oBAe9D"}
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,KAAK,oBAAoB,GAAG,oBAAoB,CAAC;AAEjD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,iBAK5C,OAAO,OAAO,QAAQ,QAAQ,YAAY,8DAiB9D"}

package/dist/src/express.js

@@ -2,16 +2,19 @@ import { handleMiddlewareRequest, createPaymentRequiredResponseCache, } from "./
 export async function createMiddleware(args) {
     const { getPaymentRequiredResponse } = createPaymentRequiredResponseCache(args.cacheConfig);
     return async (req, res, next) => {
-        const response = await handleMiddlewareRequest({
+        return await handleMiddlewareRequest({
             ...args,
             resource: `${req.protocol}://${req.headers.host}${req.path}`,
             getPaymentRequiredResponse,
             getHeader: (key) => req.header(key),
             sendJSONResponse: (status, body) => res.status(status).json(body),
+            body: async ({ settle }) => {
+                const response = await settle();
+                if (response !== undefined) {
+                    return response;
+                }
+                next();
+            },
         });
-        if (response) {
-            return;
-        }
-        next();
     };
 }

package/dist/src/hono.d.ts

@@ -1,6 +1,8 @@
 import { type CommonMiddlewareArgs } from "./common.js";
 import type { MiddlewareHandler } from "hono";
-type CreateMiddlewareArgs = CommonMiddlewareArgs;
+type CreateMiddlewareArgs = {
+    verifyBeforeSettle?: boolean;
+} & CommonMiddlewareArgs;
 export declare function createMiddleware(args: CreateMiddlewareArgs): Promise<MiddlewareHandler>;
 export {};
 //# sourceMappingURL=hono.d.ts.map

package/dist/src/hono.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/hono.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C,KAAK,oBAAoB,GAAG,oBAAoB,CAAC;AAEjD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAuB5B"}
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/hono.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C,KAAK,oBAAoB,GAAG;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,oBAAoB,CAAC;AAEzB,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAoD5B"}

package/dist/src/hono.js

@@ -2,7 +2,7 @@ import { handleMiddlewareRequest, createPaymentRequiredResponseCache, } from "./
 export async function createMiddleware(args) {
     const { getPaymentRequiredResponse } = createPaymentRequiredResponseCache(args.cacheConfig);
     return async (c, next) => {
-        const response = await handleMiddlewareRequest({
+        return await handleMiddlewareRequest({
             ...args,
             resource: c.req.url,
             getHeader: (key) => c.req.header(key),
@@ -11,10 +11,39 @@ export async function createMiddleware(args) {
                 c.status(status);
                 return c.json(body);
             },
+            body: async ({ verify, settle }) => {
+                if (args.verifyBeforeSettle) {
+                    // If configured, try to verify the transaction before running
+                    // the next operation.
+                    const verifyResult = await verify();
+                    if (verifyResult !== undefined) {
+                        return verifyResult;
+                    }
+                }
+                else {
+                    // Otherwise just settle the payment beforehand, like we've
+                    // done historically.
+                    const settleResult = await settle();
+                    if (settleResult !== undefined) {
+                        return settleResult;
+                    }
+                }
+                await next();
+                if (args.verifyBeforeSettle) {
+                    // Close out the verification, by actually settling the
+                    // payment.
+                    const settleResult = await settle();
+                    if (settleResult !== undefined) {
+                        // If the settlement fails, we need to explicitly
+                        // overwrite the downstream result.  See:
+                        //
+                        // https://hono.dev/docs/guides/middleware#modify-the-response-after-next
+                        //
+                        c.res = undefined;
+                        c.res = settleResult;
+                    }
+                }
+            },
         });
-        if (response) {
-            return response;
-        }
-        await next();
     };
 }