@armory-sh/middleware-express 0.4.6 → 0.4.8

package/README.md

@@ -0,0 +1,77 @@
+# @armory-sh/middleware-express
+
+x402 payment middleware for Express applications.
+
+## Installation
+
+```bash
+bun add @armory-sh/middleware-express
+```
+
+## Features
+
+- Simple payment middleware for Express
+- Route-aware payment configuration
+- Multi-network, multi-token support
+- Full TypeScript support
+
+## Basic Usage
+
+```typescript
+import express from "express";
+import { paymentMiddleware } from "@armory-sh/middleware-express";
+
+const app = express();
+
+const requirements = {
+  scheme: "exact" as const,
+  network: "eip155:8453",
+  amount: "1000000",
+  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as `0x${string}`,
+  payTo: "0xYourAddress..." as `0x${string}`,
+  maxTimeoutSeconds: 300,
+  extra: {},
+};
+
+app.use(paymentMiddleware({ requirements }));
+
+app.get("/api/data", (req, res) => {
+  const payment = (req as AugmentedRequest).payment;
+  res.json({
+    data: "protected data",
+    payerAddress: payment?.payerAddress,
+  });
+});
+```
+
+## Route-Aware Middleware
+
+```typescript
+import { routeAwarePaymentMiddleware } from "@armory-sh/middleware-express";
+import type { PaymentRequirementsV2 } from "@armory-sh/base";
+
+const premiumRequirements: PaymentRequirementsV2 = {
+  scheme: "exact",
+  network: "eip155:8453",
+  amount: "5000000",
+  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as `0x${string}`,
+  payTo: "0xYourAddress..." as `0x${string}`,
+  maxTimeoutSeconds: 300,
+  extra: {},
+};
+
+app.use("/api/premium", routeAwarePaymentMiddleware({
+  "/api/premium": { requirements: premiumRequirements },
+  "/api/basic": { requirements: basicRequirements },
+}));
+```
+
+## API
+
+### `paymentMiddleware(config)`
+
+Creates a payment middleware for Express.
+
+### `routeAwarePaymentMiddleware(perRouteConfig)`
+
+Creates a route-aware payment middleware for Express. Takes a record mapping route patterns to payment configuration entries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armory-sh/middleware-express",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "license": "MIT",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
   "type": "module",
@@ -27,10 +27,11 @@
     "express": "^5"
   },
   "dependencies": {
-    "@armory-sh/base": "0.2.19"
+    "@armory-sh/base": "0.2.21"
   },
   "devDependencies": {
     "bun-types": "latest",
+    "tsup": "^8.5.1",
     "typescript": "5.9.3",
     "express": "^5",
     "@types/express": "^5"

package/src/index.ts

@@ -13,7 +13,6 @@ import {
 export interface PaymentMiddlewareConfig {
   requirements: PaymentRequirements;
   facilitatorUrl?: string;
-  skipVerification?: boolean;
   network?: string;
 }
 
@@ -26,7 +25,7 @@ export interface AugmentedRequest extends Request {
 }
 
 export const paymentMiddleware = (config: PaymentMiddlewareConfig) => {
-  const { requirements, facilitatorUrl, skipVerification = false, network = "base" } = config;
+  const { requirements, facilitatorUrl, network = "base" } = config;
 
   return async (req: AugmentedRequest, res: Response, next: NextFunction): Promise<void> => {
     try {
@@ -59,12 +58,6 @@ export const paymentMiddleware = (config: PaymentMiddlewareConfig) => {
 
       const payerAddress = paymentPayload.payload.authorization.from;
 
-      // TODO: Add verification with facilitator if not skipVerification
-      // if (!skipVerification && facilitatorUrl) {
-      //   const result = await verifyWithFacilitator(...);
-      //   if (!result.success) { ... }
-      // }
-
       const settlement = {
         success: true,
         transaction: "",
@@ -76,7 +69,7 @@ export const paymentMiddleware = (config: PaymentMiddlewareConfig) => {
         res.setHeader(key, value);
       }
 
-      req.payment = { payload: paymentPayload, payerAddress, verified: !skipVerification };
+      req.payment = { payload: paymentPayload, payerAddress, verified: true };
       next();
     } catch (error) {
       res.statusCode = 500;
@@ -87,3 +80,5 @@ export const paymentMiddleware = (config: PaymentMiddlewareConfig) => {
     }
   };
 };
+
+export { routeAwarePaymentMiddleware, type RouteAwarePaymentMiddlewareConfig, type PaymentMiddlewareConfigEntry } from "./routes";

package/src/payment-utils.ts

@@ -74,7 +74,6 @@ export const decodePayload = (
     }
   }
 
-  // Check for x402 V2 format
   if (isPaymentPayload(payload)) {
     return { payload };
   }
@@ -87,7 +86,6 @@ export const decodePayload = (
 };
 
 export const extractPayerAddress = (payload: AnyPaymentPayload): string => {
-  // Check for x402 format with nested payload
   if (isPaymentPayload(payload)) {
     const p = payload.payload;
     if (isExactEvmPayload(p) && p.authorization?.from) {
@@ -95,7 +93,6 @@ export const extractPayerAddress = (payload: AnyPaymentPayload): string => {
     }
   }
 
-  // Check for direct `from` field (legacy format)
   if ("from" in payload && typeof payload.from === "string") {
     return payload.from;
   }

package/src/routes.ts

@@ -0,0 +1,155 @@
+import type { Request, Response, NextFunction } from "express";
+import type {
+  PaymentPayloadV2,
+  PaymentRequirements,
+} from "@armory-sh/base";
+import {
+  decodePaymentV2,
+  createPaymentRequiredHeaders,
+  createSettlementHeaders,
+  PAYMENT_SIGNATURE_HEADER,
+  matchRoute,
+  validateRouteConfig,
+  type RouteValidationError,
+} from "@armory-sh/base";
+
+export interface RouteAwarePaymentMiddlewareConfig {
+  route?: string;
+  routes?: string[];
+  perRoute?: Record<string, PaymentMiddlewareConfigEntry>;
+}
+
+export interface PaymentMiddlewareConfigEntry {
+  requirements: PaymentRequirements;
+  facilitatorUrl?: string;
+  network?: string;
+}
+
+export interface AugmentedRequest extends Request {
+  payment?: {
+    payload: PaymentPayloadV2;
+    payerAddress: string;
+    verified: boolean;
+    route?: string;
+  };
+}
+
+interface ResolvedRouteConfig {
+  pattern: string;
+  config: PaymentMiddlewareConfigEntry;
+}
+
+const resolveRouteConfig = (
+  config: RouteAwarePaymentMiddlewareConfig
+): { routes: ResolvedRouteConfig[]; error?: RouteValidationError } => {
+  const validationError = validateRouteConfig(config);
+  if (validationError) {
+    return { routes: [], error: validationError };
+  }
+
+  const { route, routes, perRoute } = config;
+  const routePatterns = route ? [route] : routes || [];
+
+  const resolvedRoutes: ResolvedRouteConfig[] = [];
+
+  for (const pattern of routePatterns) {
+    const routeConfig = perRoute?.[pattern];
+    if (routeConfig) {
+      resolvedRoutes.push({
+        pattern,
+        config: routeConfig,
+      });
+    }
+  }
+
+  return { routes: resolvedRoutes };
+};
+
+export const routeAwarePaymentMiddleware = (
+  perRouteConfig: Record<string, PaymentMiddlewareConfigEntry>
+) => {
+  const config: RouteAwarePaymentMiddlewareConfig = {
+    routes: Object.keys(perRouteConfig),
+    perRoute: perRouteConfig,
+  };
+
+  const { routes: resolvedRoutes, error: configError } = resolveRouteConfig(config);
+
+  return async (req: AugmentedRequest, res: Response, next: NextFunction): Promise<void> => {
+    try {
+      if (configError) {
+        res.statusCode = 500;
+        res.json({
+          error: "Payment middleware configuration error",
+          details: configError.message,
+        });
+        return;
+      }
+
+      const path = req.path;
+      const matchedRoute = resolvedRoutes.find((r) => matchRoute(r.pattern, path));
+
+      if (!matchedRoute) {
+        next();
+        return;
+      }
+
+      const routeConfig = matchedRoute.config;
+      const { requirements, facilitatorUrl, network = "base" } = routeConfig;
+
+      const paymentHeader = req.headers[PAYMENT_SIGNATURE_HEADER.toLowerCase()] as string | undefined;
+
+      if (!paymentHeader) {
+        const requiredHeaders = createPaymentRequiredHeaders(requirements);
+        res.statusCode = 402;
+        for (const [key, value] of Object.entries(requiredHeaders)) {
+          res.setHeader(key, value);
+        }
+        res.json({
+          error: "Payment required",
+          accepts: [requirements],
+        });
+        return;
+      }
+
+      let paymentPayload: PaymentPayloadV2;
+      try {
+        paymentPayload = decodePaymentV2(paymentHeader);
+      } catch (error) {
+        res.statusCode = 400;
+        res.json({
+          error: "Invalid payment payload",
+          message: error instanceof Error ? error.message : "Unknown error",
+        });
+        return;
+      }
+
+      const payerAddress = paymentPayload.payload.authorization.from;
+
+      const settlement = {
+        success: true,
+        transaction: "",
+        network,
+      };
+
+      const settlementHeaders = createSettlementHeaders(settlement);
+      for (const [key, value] of Object.entries(settlementHeaders)) {
+        res.setHeader(key, value);
+      }
+
+      req.payment = {
+        payload: paymentPayload,
+        payerAddress,
+        verified: true,
+        route: matchedRoute.pattern,
+      };
+      next();
+    } catch (error) {
+      res.statusCode = 500;
+      res.json({
+        error: "Payment middleware error",
+        message: error instanceof Error ? error.message : "Unknown error",
+      });
+    }
+  };
+};