@armory-sh/middleware-express-v4 0.1.1

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@armory-sh/middleware-express-v4",
+  "version": "0.1.1",
+  "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
+  "module": "index.ts",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thegreataxios/armory.git",
+    "directory": "packages/middleware-express-v4"
+  },
+  "peerDependencies": {
+    "express": "^4"
+  },
+  "dependencies": {
+    "@armory-sh/base": "0.2.20"
+  },
+  "scripts": {
+    "test": "bun test"
+  }
+}

package/src/core.ts

@@ -0,0 +1,292 @@
+import type {
+  PaymentRequirements,
+  PaymentRequirementsV1,
+  PaymentRequirementsV2,
+  PaymentPayloadV1,
+  SettlementResponseV1,
+  SettlementResponseV2,
+  PayToV2,
+  X402SettlementResponse,
+  X402PaymentRequiredV1,
+  X402PaymentRequirementsV1,
+} from "@armory-sh/base";
+import {
+  getNetworkConfig,
+  getNetworkByChainId,
+  encodeSettlementResponse,
+  encodeX402PaymentRequiredV1,
+  normalizeNetworkName,
+} from "@armory-sh/base";
+import type {
+  MiddlewareConfig,
+  FacilitatorConfig,
+  FacilitatorVerifyResult,
+  FacilitatorSettleResult,
+  HttpRequest,
+} from "./types";
+
+/**
+ * Convert eip155 format to slug, or slug to slug (no-op)
+ * Handles both "eip155:84532" and "base-sepolia" inputs
+ */
+const toSlug = (network: string | number): string => {
+  if (typeof network === "number") {
+    const net = getNetworkByChainId(network);
+    if (!net) throw new Error(`No network found for chainId: ${network}`);
+    return normalizeNetworkName(net.name);
+  }
+
+  // Handle eip155 format input
+  if (network.startsWith("eip155:")) {
+    const chainIdStr = network.split(":")[1];
+    if (!chainIdStr) throw new Error(`Invalid eip155 format: ${network}`);
+    const chainId = parseInt(chainIdStr, 10);
+    const net = getNetworkByChainId(chainId);
+    if (!net) throw new Error(`No network found for chainId: ${chainId}`);
+    return normalizeNetworkName(net.name);
+  }
+
+  return normalizeNetworkName(network);
+};
+
+/**
+ * Convert slug to eip155 format
+ */
+const toEip155 = (network: string | number): string => {
+  if (typeof network === "number") {
+    const net = getNetworkByChainId(network);
+    if (!net) throw new Error(`No network found for chainId: ${network}`);
+    return net.caip2Id;
+  }
+
+  // Already in eip155 format
+  if (network.startsWith("eip155:")) {
+    const net = getNetworkConfig(network);
+    if (!net) throw new Error(`No network found for: ${network}`);
+    return net.caip2Id;
+  }
+
+  // Slug input - convert to eip155
+  const slug = normalizeNetworkName(network);
+  const net = getNetworkConfig(slug);
+  if (!net) throw new Error(`No network found for: ${slug}`);
+  return net.caip2Id;
+};
+
+const getNetworkName = (network: string | number): string => toSlug(network);
+
+const getChainId = (network: string | number): string => toEip155(network);
+
+const createV1Requirements = (
+  config: MiddlewareConfig,
+  expiry: number
+): PaymentRequirementsV1 => {
+  const networkName = getNetworkName(config.network);
+  const network = getNetworkConfig(networkName);
+  if (!network) throw new Error(`Unsupported network: ${networkName}`);
+
+  return {
+    amount: config.amount,
+    network: networkName,
+    contractAddress: network.usdcAddress,
+    payTo: config.payTo as string,
+    expiry,
+  };
+};
+
+const createV2Requirements = (
+  config: MiddlewareConfig,
+  _expiry: number
+): PaymentRequirementsV2 => {
+  const networkName = getNetworkName(config.network);
+  const network = getNetworkConfig(networkName);
+  if (!network) throw new Error(`Unsupported network: ${networkName}`);
+
+  // Extract address from payTo - should be a valid Ethereum address
+  const payToAddress = typeof config.payTo === "string" && config.payTo.startsWith("0x")
+    ? config.payTo as `0x${string}`
+    : network.usdcAddress as `0x${string}`;
+
+  return {
+    scheme: "exact",
+    network: getChainId(config.network) as `eip155:${string}`,
+    amount: config.amount,
+    asset: network.usdcAddress as `0x${string}`,
+    payTo: payToAddress,
+    maxTimeoutSeconds: 300,
+  };
+};
+
+export const createPaymentRequirements = (
+  config: MiddlewareConfig,
+  version: 1 | 2 = 1
+): PaymentRequirements => {
+  const networkName = getNetworkName(config.network);
+  const network = getNetworkConfig(networkName);
+  if (!network) throw new Error(`Unsupported network: ${networkName}`);
+  const expiry = Math.floor(Date.now() / 1000) + 3600;
+
+  return version === 1 ? createV1Requirements(config, expiry) : createV2Requirements(config, expiry);
+};
+
+const findHeaderValue = (
+  headers: Record<string, string | string[] | undefined>,
+  name: string
+): string | undefined => {
+  const value = headers[name];
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.length > 0) return value[0];
+
+  const lowerName = name.toLowerCase();
+  for (const [key, val] of Object.entries(headers)) {
+    if (key.toLowerCase() === lowerName) {
+      if (typeof val === "string") return val;
+      if (Array.isArray(val) && val.length > 0) return val[0];
+    }
+  }
+  return undefined;
+};
+
+const parseHeader = (header: string): Record<string, unknown> | null => {
+  try {
+    if (header.startsWith("{")) return JSON.parse(header);
+    return JSON.parse(atob(header));
+  } catch {
+    return null;
+  }
+};
+
+const extractPaymentPayload = (request: HttpRequest): Record<string, unknown> | null => {
+  const v1Header = findHeaderValue(request.headers, "X-PAYMENT");
+  if (v1Header) return parseHeader(v1Header);
+
+  const v2Header = findHeaderValue(request.headers, "PAYMENT-SIGNATURE");
+  if (v2Header) return parseHeader(v2Header);
+
+  return null;
+};
+
+const postFacilitator = async (
+  url: string,
+  headers: Record<string, string>,
+  body: unknown
+): Promise<unknown> => {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(error || `Request failed: ${response.status}`);
+  }
+
+  return response.json();
+};
+
+export const verifyWithFacilitator = async (
+  request: HttpRequest,
+  facilitator: FacilitatorConfig
+): Promise<FacilitatorVerifyResult> => {
+  const payload = extractPaymentPayload(request);
+  if (!payload) {
+    return { success: false, error: "No payment payload found in request headers" };
+  }
+
+  try {
+    const url = new URL("/verify", facilitator.url);
+    const headers = facilitator.createHeaders?.() ?? {};
+    const data = await postFacilitator(url.toString(), headers, { payload, headers: request.headers });
+
+    return {
+      success: true,
+      payerAddress: (data as { payerAddress?: string }).payerAddress,
+      balance: (data as { balance?: string }).balance,
+      requiredAmount: (data as { requiredAmount?: string }).requiredAmount,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown verification error",
+    };
+  }
+};
+
+export const settleWithFacilitator = async (
+  request: HttpRequest,
+  facilitator: FacilitatorConfig
+): Promise<FacilitatorSettleResult> => {
+  const payload = extractPaymentPayload(request);
+  if (!payload) {
+    return { success: false, error: "No payment payload found in request headers" };
+  }
+
+  try {
+    const url = new URL("/settle", facilitator.url);
+    const headers = facilitator.createHeaders?.() ?? {};
+    const data = await postFacilitator(url.toString(), headers, { payload, headers: request.headers });
+
+    return {
+      success: true,
+      txHash: (data as { txHash?: string }).txHash,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown settlement error",
+    };
+  }
+};
+
+const encode = (data: unknown): string => btoa(JSON.stringify(data));
+
+export const createPaymentRequiredHeaders = (
+  requirements: PaymentRequirements,
+  version: 1 | 2
+): Record<string, string> => {
+  if (version === 1) {
+    // For V1, wrap in X402PaymentRequiredV1 format and encode
+    const v1Requirements: X402PaymentRequiredV1 = {
+      x402Version: 1,
+      error: "Payment required",
+      accepts: [requirements as unknown as X402PaymentRequirementsV1],
+    };
+    return { "X-PAYMENT-REQUIRED": encodeX402PaymentRequiredV1(v1Requirements) };
+  }
+  // For V2/x402 - base64 encode the JSON
+  return { "PAYMENT-REQUIRED": Buffer.from(JSON.stringify(requirements)).toString("base64") };
+};
+
+/**
+ * Accepts both X402SettlementResponse and legacy SettlementResponseV1/V2
+ * For V1, manually constructs the header. For V2/x402, uses the x402 encoder.
+ */
+export const createSettlementHeaders = (
+  response: X402SettlementResponse | SettlementResponseV1 | SettlementResponseV2,
+  version: 1 | 2
+): Record<string, string> => {
+  // Extract success and txHash from any response format
+  const isSuccess = "success" in response ? response.success : false;
+  const txHash = "transaction" in response 
+    ? response.transaction 
+    : "txHash" in response 
+      ? response.txHash 
+      : "";
+
+  if (version === 1) {
+    // V1 settlement response
+    const settlementJson = JSON.stringify({
+      success: isSuccess,
+      transaction: txHash,
+    });
+    return { "X-PAYMENT-RESPONSE": Buffer.from(settlementJson).toString("base64") };
+  }
+  
+  // V2/x402 settlement response
+  const settlementJson = JSON.stringify({
+    success: isSuccess,
+    transaction: txHash,
+  });
+  return { "PAYMENT-RESPONSE": Buffer.from(settlementJson).toString("base64") };
+};

package/src/index.ts

@@ -0,0 +1,79 @@
+import type { Request, Response, NextFunction } from "express";
+import type {
+  X402PaymentPayload,
+  X402PaymentRequirements,
+} from "@armory-sh/base";
+import type {
+  PaymentPayload,
+  PaymentRequirements,
+} from "./payment-utils";
+import {
+  PAYMENT_HEADERS,
+  encodeRequirements,
+  decodePayload,
+  verifyPaymentWithRetry,
+  extractPayerAddress,
+} from "./payment-utils";
+
+export interface PaymentMiddlewareConfig {
+  requirements: X402PaymentRequirements;
+  facilitatorUrl?: string;
+}
+
+export interface AugmentedRequest extends Request {
+  payment?: {
+    payload: X402PaymentPayload;
+    payerAddress: string;
+    verified: boolean;
+  };
+}
+
+const sendError = (
+  res: Response,
+  status: number,
+  headers: Record<string, string>,
+  body: unknown
+): void => {
+  res.status(status);
+  Object.entries(headers).forEach(([k, v]) => res.setHeader(k, v));
+  res.json(body);
+};
+
+export const paymentMiddleware = (config: PaymentMiddlewareConfig) => {
+  const { requirements, facilitatorUrl } = config;
+
+  return async (req: AugmentedRequest, res: Response, next: NextFunction): Promise<void> => {
+    try {
+      const paymentHeader = req.headers[PAYMENT_HEADERS.PAYMENT.toLowerCase()] as string | undefined;
+
+      if (!paymentHeader) {
+        sendError(res, 402, { [PAYMENT_HEADERS.REQUIRED]: encodeRequirements(requirements), "Content-Type": "application/json" }, { error: "Payment required", accepts: [requirements] });
+        return;
+      }
+
+      let payload: X402PaymentPayload;
+      try {
+        ({ payload } = decodePayload(paymentHeader) as { payload: X402PaymentPayload });
+      } catch (error) {
+        sendError(res, 400, {}, { error: "Invalid payment payload", message: error instanceof Error ? error.message : "Unknown error" });
+        return;
+      }
+
+      const result = await verifyPaymentWithRetry(payload, requirements, facilitatorUrl);
+      if (!result.success) {
+        sendError(res, 402, { [PAYMENT_HEADERS.RESPONSE]: JSON.stringify({ status: "verified", payerAddress: result.payerAddress, version: 2 }) }, { error: result.error });
+        return;
+      }
+
+      const payerAddress = result.payerAddress!;
+
+      req.payment = { payload, payerAddress, verified: true };
+      res.setHeader(PAYMENT_HEADERS.RESPONSE, JSON.stringify({ status: "verified", payerAddress, version: 2 }));
+      next();
+    } catch (error) {
+      sendError(res, 500, {}, { error: "Payment middleware error", message: error instanceof Error ? error.message : "Unknown error" });
+    }
+  };
+};
+
+export { routeAwarePaymentMiddleware, type RouteAwarePaymentMiddlewareConfig, type PaymentMiddlewareConfigEntry } from "./routes";

package/src/middleware-config.ts

@@ -0,0 +1,279 @@
+/**
+ * Simple one-line middleware API for Armory merchants
+ * Focus on DX/UX - "everything just magically works"
+ */
+
+import type {
+  Address,
+  PaymentRequirements,
+  PaymentRequirementsV1,
+  PaymentRequirementsV2,
+} from "@armory-sh/base";
+import type {
+  NetworkId,
+  TokenId,
+  FacilitatorConfig,
+  AcceptPaymentOptions,
+  ResolvedPaymentConfig,
+  ValidationError,
+  PricingConfig,
+} from "@armory-sh/base";
+import {
+  resolveNetwork,
+  resolveToken,
+  validateAcceptConfig,
+  isValidationError,
+  getNetworkConfig,
+  getNetworkByChainId,
+  normalizeNetworkName,
+} from "@armory-sh/base";
+import {
+  createPaymentRequirements,
+  createPaymentRequiredHeaders,
+} from "./core";
+import type { MiddlewareConfig, FacilitatorConfig as CoreFacilitatorConfig } from "./types";
+
+// ═══════════════════════════════════════════════════════════════
+// Simple Middleware Configuration
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Simple configuration for acceptPaymentsViaArmory middleware
+ */
+export interface SimpleMiddlewareConfig {
+  /** Address to receive payments */
+  payTo: Address;
+  /** Default amount to charge (default: "1.0") */
+  amount?: string;
+  /** Payment acceptance options */
+  accept?: AcceptPaymentOptions;
+  /** Fallback facilitator URL (if not using accept.facilitators) */
+  facilitatorUrl?: string;
+  /** Per-network/token/facilitator pricing overrides */
+  pricing?: PricingConfig[];
+}
+
+/**
+ * Resolved middleware configuration with all options validated
+ */
+export interface ResolvedMiddlewareConfig {
+  /** All valid payment configurations (network/token combinations) */
+  configs: ResolvedPaymentConfigWithPricing[];
+  /** Protocol version */
+  version: 1 | 2 | "auto";
+  /** Facilitator configs */
+  facilitators: CoreFacilitatorConfig[];
+}
+
+/** Extended config with pricing info */
+export interface ResolvedPaymentConfigWithPricing extends ResolvedPaymentConfig {
+  /** Facilitator URL (for per-facilitator pricing) */
+  facilitatorUrl?: string;
+  /** Pricing config entry (if any) */
+  pricing?: PricingConfig;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Configuration Resolution
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Find matching pricing config for a network/token/facilitator combination
+ */
+const findPricingConfig = (
+  pricing: PricingConfig[] | undefined,
+  network: string,
+  token: string,
+  facilitatorUrl: string
+): PricingConfig | undefined => {
+  if (!pricing) return undefined;
+
+  // First try exact match with facilitator
+  const withFacilitator = pricing.find(
+    p =>
+      p.network === network &&
+      p.token === token &&
+      p.facilitator === facilitatorUrl
+  );
+  if (withFacilitator) return withFacilitator;
+
+  // Then try network/token match (any facilitator)
+  const withNetworkToken = pricing.find(
+    p =>
+      p.network === network &&
+      p.token === token &&
+      !p.facilitator
+  );
+  if (withNetworkToken) return withNetworkToken;
+
+  // Then try network-only match
+  const networkOnly = pricing.find(
+    p => p.network === network && !p.token && !p.facilitator
+  );
+  if (networkOnly) return networkOnly;
+
+  return undefined;
+};
+
+/**
+ * Resolve simple middleware config to full config
+ */
+export const resolveMiddlewareConfig = (
+  config: SimpleMiddlewareConfig
+): ResolvedMiddlewareConfig | ValidationError => {
+  const { payTo, amount = "1.0", accept = {}, facilitatorUrl, pricing } = config;
+
+  // If using legacy facilitatorUrl, convert to AcceptPaymentOptions
+  const acceptOptions: AcceptPaymentOptions = facilitatorUrl
+    ? {
+        ...accept,
+        facilitators: accept.facilitators
+          ? [...(Array.isArray(accept.facilitators) ? accept.facilitators : [accept.facilitators]), { url: facilitatorUrl }]
+          : { url: facilitatorUrl },
+      }
+    : accept;
+
+  const result = validateAcceptConfig(acceptOptions, payTo, amount);
+  if (!result.success) {
+    return result.error;
+  }
+
+  const facilitatorConfigs: CoreFacilitatorConfig[] = result.config[0]?.facilitators.map((f) => ({
+    url: f.url,
+    createHeaders: f.input.headers,
+  })) ?? [];
+
+  const enrichedConfigs: ResolvedPaymentConfigWithPricing[] = result.config.map((c) => {
+    const networkName = normalizeNetworkName(c.network.config.name);
+    const tokenSymbol = c.token.config.symbol;
+
+    const facilitatorPricing: { url: string; pricing?: PricingConfig }[] = c.facilitators.map((f) => {
+      const pricingConfig = findPricingConfig(pricing, networkName, tokenSymbol, f.url);
+      return { url: f.url, pricing: pricingConfig };
+    });
+
+    const defaultPricing = findPricingConfig(pricing, networkName, tokenSymbol, "");
+
+    return {
+      ...c,
+      amount: defaultPricing?.amount ?? c.amount,
+      facilitatorUrl: facilitatorPricing[0]?.url,
+      pricing: defaultPricing,
+    };
+  });
+
+  return {
+    configs: enrichedConfigs,
+    version: acceptOptions.version ?? "auto",
+    facilitators: facilitatorConfigs,
+  };
+};
+
+/**
+ * Get payment requirements for a specific network/token combination
+ */
+export const getRequirements = (
+  config: ResolvedMiddlewareConfig,
+  network: NetworkId,
+  token: TokenId
+): PaymentRequirements | ValidationError => {
+  // Find matching config
+  const resolvedNetwork = resolveNetwork(network);
+  if (isValidationError(resolvedNetwork)) {
+    return resolvedNetwork;
+  }
+
+  const resolvedToken = resolveToken(token, resolvedNetwork);
+  if (isValidationError(resolvedToken)) {
+    return resolvedToken;
+  }
+
+  const matchingConfig = config.configs.find(
+    (c) =>
+      c.network.config.chainId === resolvedNetwork.config.chainId &&
+      c.token.config.contractAddress.toLowerCase() === resolvedToken.config.contractAddress.toLowerCase()
+  );
+
+  if (!matchingConfig) {
+    return {
+      code: "TOKEN_NOT_ON_NETWORK",
+      message: `No configuration found for network "${network}" with token "${token}"`,
+    } as ValidationError;
+  }
+
+  // Determine version
+  const version = config.version === "auto" ? 2 : config.version;
+
+  return createPaymentRequirements(
+    {
+      payTo: matchingConfig.payTo,
+      network: normalizeNetworkName(matchingConfig.network.config.name),
+      amount: matchingConfig.amount,
+      facilitator: config.facilitators[0],
+    },
+    version
+  );
+};
+
+// ═══════════════════════════════════════════════════════════════
+// Helper to get default config from first result
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Get primary/default middleware config for legacy middlewares
+ */
+export const getPrimaryConfig = (resolved: ResolvedMiddlewareConfig): MiddlewareConfig => {
+  const primary = resolved.configs[0];
+  if (!primary) {
+    throw new Error("No valid payment configurations found");
+  }
+
+  return {
+    payTo: primary.payTo,
+    network: normalizeNetworkName(primary.network.config.name),
+    amount: primary.amount,
+    facilitator: resolved.facilitators[0],
+    settlementMode: "verify",
+  };
+};
+
+/**
+ * Get all supported networks from config
+ */
+export const getSupportedNetworks = (config: ResolvedMiddlewareConfig): string[] => {
+  const networks = new Set(config.configs.map((c) => normalizeNetworkName(c.network.config.name)));
+  return Array.from(networks);
+};
+
+/**
+ * Get all supported tokens from config
+ */
+export const getSupportedTokens = (config: ResolvedMiddlewareConfig): string[] => {
+  const tokens = new Set(config.configs.map((c) => c.token.config.symbol));
+  return Array.from(tokens);
+};
+
+/**
+ * Check if a network/token combination is supported
+ */
+export const isSupported = (
+  config: ResolvedMiddlewareConfig,
+  network: NetworkId,
+  token: TokenId
+): boolean => {
+  const resolvedNetwork = resolveNetwork(network);
+  if (isValidationError(resolvedNetwork)) {
+    return false;
+  }
+
+  const resolvedToken = resolveToken(token, resolvedNetwork);
+  if (isValidationError(resolvedToken)) {
+    return false;
+  }
+
+  return config.configs.some(
+    (c) =>
+      c.network.config.chainId === resolvedNetwork.config.chainId &&
+      c.token.config.contractAddress.toLowerCase() === resolvedToken.config.contractAddress.toLowerCase()
+  );
+};

package/src/payment-utils.ts

@@ -0,0 +1,183 @@
+import type {
+  X402PaymentPayload,
+  X402PaymentRequirements,
+  PaymentRequirements,
+} from "@armory-sh/base";
+import { extractPaymentFromHeaders, PAYMENT_SIGNATURE_HEADER } from "@armory-sh/base";
+
+// Legacy V2 payload type for backward compatibility
+export interface LegacyPaymentPayloadV2 {
+  to: string;
+  from: string;
+  amount: string;
+  chainId: string;
+  assetId: string;
+  nonce: string;
+  expiry: number;
+  signature: string; // 0x-prefixed hex signature
+}
+
+// Union type for V2 payload formats
+export type AnyPaymentPayload = X402PaymentPayload | LegacyPaymentPayloadV2;
+
+// Re-export types for use in index.ts
+export type PaymentPayload = AnyPaymentPayload;
+export type { X402PaymentRequirements as PaymentRequirements } from "@armory-sh/base";
+
+export interface PaymentVerificationResult {
+  success: boolean;
+  payload?: AnyPaymentPayload;
+  payerAddress?: string;
+  error?: string;
+}
+
+// V2 hardcoded headers
+export const PAYMENT_HEADERS = {
+  PAYMENT: "PAYMENT-SIGNATURE",
+  REQUIRED: "PAYMENT-REQUIRED",
+  RESPONSE: "PAYMENT-RESPONSE",
+} as const;
+
+export const encodeRequirements = (requirements: X402PaymentRequirements): string =>
+  JSON.stringify(requirements);
+
+/**
+ * Detect if a payload is legacy V2 format
+ */
+function isLegacyV2(payload: unknown): payload is LegacyPaymentPayloadV2 {
+  return (
+    typeof payload === "object" &&
+    payload !== null &&
+    "chainId" in payload &&
+    "assetId" in payload &&
+    "signature" in payload &&
+    typeof (payload as LegacyPaymentPayloadV2).signature === "string"
+  );
+}
+
+export const decodePayload = (
+  headerValue: string
+): { payload: AnyPaymentPayload } => {
+  // Try to parse as JSON first
+  let parsed: unknown;
+  let isJsonString = false;
+  try {
+    if (headerValue.startsWith("{")) {
+      parsed = JSON.parse(headerValue);
+      isJsonString = true;
+    } else {
+      parsed = JSON.parse(atob(headerValue));
+    }
+  } catch {
+    throw new Error("Invalid payment payload");
+  }
+
+  const base64Value = isJsonString
+    ? Buffer.from(headerValue).toString("base64")
+    : headerValue;
+  const headers = new Headers();
+  headers.set(PAYMENT_SIGNATURE_HEADER, base64Value);
+  const x402Payload = extractPaymentFromHeaders(headers);
+  if (x402Payload) {
+    return { payload: x402Payload };
+  }
+
+  if (isLegacyV2(parsed)) {
+    return { payload: parsed };
+  }
+
+  throw new Error("Unrecognized payment payload format");
+};
+
+export const createVerificationError = (
+  message: string,
+  details?: unknown
+): string => JSON.stringify({ error: message, details });
+
+export const verifyWithFacilitator = async (
+  facilitatorUrl: string,
+  payload: AnyPaymentPayload,
+  requirements: X402PaymentRequirements
+): Promise<PaymentVerificationResult> => {
+  try {
+    const response = await fetch(`${facilitatorUrl}/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ payload, requirements }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      return { success: false, error: JSON.stringify(error) };
+    }
+
+    const result = await response.json() as { success: boolean; error?: string; payerAddress?: string };
+    if (!result.success) {
+      return { success: false, error: result.error ?? "Verification failed" };
+    }
+
+    return { success: true, payerAddress: result.payerAddress ?? "" };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown facilitator error",
+    };
+  }
+};
+
+export const verifyLocally = async (
+  payload: AnyPaymentPayload,
+  requirements: X402PaymentRequirements
+): Promise<PaymentVerificationResult> => {
+  // For legacy format, we'd need to convert to x402 format first
+  if (isLegacyV2(payload)) {
+    return {
+      success: false,
+      error: "Local verification not supported for legacy payload format. Use a facilitator.",
+    };
+  }
+
+  // For x402 format, verify locally
+  return {
+    success: true,
+    payerAddress: (payload as X402PaymentPayload).payload.authorization.from,
+  };
+};
+
+export const verifyPaymentWithRetry = async (
+  payload: AnyPaymentPayload,
+  requirements: X402PaymentRequirements,
+  facilitatorUrl?: string
+): Promise<PaymentVerificationResult> =>
+  facilitatorUrl
+    ? verifyWithFacilitator(facilitatorUrl, payload, requirements)
+    : verifyLocally(payload, requirements);
+
+/**
+ * Extract payer address from various payload formats
+ */
+export const extractPayerAddress = (payload: AnyPaymentPayload): string => {
+  // x402 format
+  if ("payload" in payload) {
+    const x402Payload = payload as X402PaymentPayload;
+    if ("authorization" in x402Payload.payload) {
+      return x402Payload.payload.authorization.from;
+    }
+  }
+
+  // Legacy V2 format
+  if ("from" in payload && typeof payload.from === "string") {
+    return payload.from;
+  }
+
+  throw new Error("Unable to extract payer address from payload");
+};
+
+export const createResponseHeaders = (
+  payerAddress: string
+): Record<string, string> => ({
+  [PAYMENT_HEADERS.RESPONSE]: JSON.stringify({
+    status: "verified",
+    payerAddress,
+  }),
+});

package/src/routes.ts

@@ -0,0 +1,139 @@
+import type { Request, Response, NextFunction } from "express";
+import type {
+  X402PaymentPayload,
+  X402PaymentRequirements,
+} from "@armory-sh/base";
+import type {
+  PaymentPayload,
+  PaymentRequirements,
+} from "./payment-utils";
+import {
+  PAYMENT_HEADERS,
+  encodeRequirements,
+  decodePayload,
+  verifyPaymentWithRetry,
+  extractPayerAddress,
+} from "./payment-utils";
+import { matchRoute, validateRouteConfig, type RouteValidationError } from "@armory-sh/base";
+
+export interface RouteAwarePaymentMiddlewareConfig {
+  route?: string;
+  routes?: string[];
+  perRoute?: Record<string, PaymentMiddlewareConfigEntry>;
+}
+
+export interface PaymentMiddlewareConfigEntry {
+  requirements: X402PaymentRequirements;
+  facilitatorUrl?: string;
+}
+
+export interface AugmentedRequest extends Request {
+  payment?: {
+    payload: X402PaymentPayload;
+    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 };
+};
+
+const sendError = (
+  res: Response,
+  status: number,
+  headers: Record<string, string>,
+  body: unknown
+): void => {
+  res.status(status);
+  Object.entries(headers).forEach(([k, v]) => res.setHeader(k, v));
+  res.json(body);
+};
+
+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) {
+        sendError(res, 500, {}, { 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 } = routeConfig;
+
+      const paymentHeader = req.headers[PAYMENT_HEADERS.PAYMENT.toLowerCase()] as string | undefined;
+
+      if (!paymentHeader) {
+        sendError(res, 402, { [PAYMENT_HEADERS.REQUIRED]: encodeRequirements(requirements), "Content-Type": "application/json" }, { error: "Payment required", accepts: [requirements] });
+        return;
+      }
+
+      let payload: X402PaymentPayload;
+      try {
+        ({ payload } = decodePayload(paymentHeader) as { payload: X402PaymentPayload });
+      } catch (error) {
+        sendError(res, 400, {}, { error: "Invalid payment payload", message: error instanceof Error ? error.message : "Unknown error" });
+        return;
+      }
+
+      const result = await verifyPaymentWithRetry(payload, requirements, facilitatorUrl);
+      if (!result.success) {
+        sendError(res, 402, { [PAYMENT_HEADERS.RESPONSE]: JSON.stringify({ status: "verified", payerAddress: result.payerAddress, version: 2 }) }, { error: result.error });
+        return;
+      }
+
+      const payerAddress = result.payerAddress!;
+
+      req.payment = { payload, payerAddress, verified: true, route: matchedRoute.pattern };
+      res.setHeader(PAYMENT_HEADERS.RESPONSE, JSON.stringify({ status: "verified", payerAddress, version: 2 }));
+      next();
+    } catch (error) {
+      sendError(res, 500, {}, { error: "Payment middleware error", message: error instanceof Error ? error.message : "Unknown error" });
+    }
+  };
+};

package/src/types.ts

@@ -0,0 +1,44 @@
+import type { Address, CAIP2ChainId, CAIPAssetId } from "@armory-sh/base";
+
+export interface FacilitatorConfig {
+  url: string;
+  createHeaders?: () => Record<string, string>;
+}
+
+export type SettlementMode = "verify" | "settle" | "async";
+export type PayToAddress = Address | CAIP2ChainId | CAIPAssetId;
+
+export interface MiddlewareConfig {
+  payTo: PayToAddress;
+  network: string | number;
+  amount: string;
+  facilitator?: FacilitatorConfig;
+  settlementMode?: SettlementMode;
+}
+
+export interface HttpRequest {
+  headers: Record<string, string | string[] | undefined>;
+  body?: unknown;
+  method?: string;
+  url?: string;
+}
+
+export interface HttpResponse {
+  status: number;
+  headers: Record<string, string>;
+  body?: unknown;
+}
+
+export interface FacilitatorVerifyResult {
+  success: boolean;
+  payerAddress?: string;
+  balance?: string;
+  requiredAmount?: string;
+  error?: string;
+}
+
+export interface FacilitatorSettleResult {
+  success: boolean;
+  txHash?: string;
+  error?: string;
+}