@armory-sh/middleware-hono 0.3.19 → 0.3.21

package/README.md

@@ -0,0 +1,220 @@
+# @armory-sh/middleware-hono
+
+x402 payment middleware for Hono applications.
+
+## Installation
+
+```bash
+bun add @armory-sh/middleware-hono
+```
+
+## Features
+
+- Simple payment middleware for Hono
+- Route-aware payment configuration
+- Multi-network, multi-token support
+- Per-route facilitator configuration
+- Full TypeScript support
+
+## Basic Usage
+
+```typescript
+import { Hono } from "hono";
+import { paymentMiddleware } from "@armory-sh/middleware-hono";
+
+const app = new Hono();
+
+app.use("/*", paymentMiddleware({
+  payTo: "0xYourAddress...",
+  chain: "base",
+  token: "usdc",
+  amount: "1.0",
+}));
+
+app.get("/api/data", (c) => {
+  const payment = c.get("payment");
+  return c.json({
+    data: "protected data",
+    payerAddress: payment?.payload?.authorization?.from,
+  });
+});
+```
+
+## Route-Aware Middleware
+
+Configure different payment requirements for different routes:
+
+```typescript
+import { routeAwarePaymentMiddleware } from "@armory-sh/middleware-hono";
+
+const app = new Hono();
+
+// Single route with wildcard
+app.use("/api/premium/*", routeAwarePaymentMiddleware({
+  routes: ["/api/premium/*"],
+  payTo: "0xYourAddress...",
+  amount: "$5.00",
+  network: "base"
+}));
+
+// Multiple routes with per-route configuration
+app.use("/api/*", routeAwarePaymentMiddleware({
+  routes: ["/api/basic", "/api/premium/*"],
+  payTo: "0xYourAddress...",
+  amount: "$1.00",  // Default amount
+  network: "base",
+  perRoute: {
+    "/api/premium/*": {
+      amount: "$5.00",  // Override for premium routes
+      network: "ethereum",
+    }
+  }
+}));
+```
+
+## Configuration Options
+
+### PaymentConfig
+
+```typescript
+interface PaymentConfig {
+  payTo: string;                    // Payment recipient address
+  chain?: string | number;          // Network (name or chain ID)
+  chains?: Array<string | number>;  // Multiple networks
+  token?: string;                   // Token symbol
+  tokens?: string[];                // Multiple tokens
+  amount?: string;                  // Amount (default: "1.0")
+  maxTimeoutSeconds?: number;       // Payment timeout (default: 300)
+
+  // Per-chain configuration
+  payToByChain?: Record<string, string>;
+  facilitatorUrlByChain?: Record<string, string>;
+
+  // Per-token-per-chain configuration
+  payToByToken?: Record<string, Record<string, string>>;
+  facilitatorUrlByToken?: Record<string, Record<string, string>>;
+}
+```
+
+### RouteAwarePaymentConfig
+
+```typescript
+interface RouteAwarePaymentConfig extends PaymentConfig {
+  route?: string;    // Single exact route (no wildcards)
+  routes?: string[];  // Multiple routes (allows wildcards)
+  perRoute?: Record<string, Partial<PaymentConfig>>;
+}
+```
+
+## Payment Context
+
+The middleware adds payment information to the Hono context:
+
+```typescript
+app.get("/api/data", (c) => {
+  const payment = c.get("payment");
+  // payment.payload: PaymentPayloadV2
+  // payment.verified: boolean
+  // payment.route: string (only for route-aware middleware)
+});
+```
+
+## Input Formats
+
+**Networks** - Use any format:
+```typescript
+'base'              // name
+8453                // chain ID
+'eip155:8453'       // CAIP-2
+```
+
+**Tokens** - Use any format:
+```typescript
+'usdc'              // symbol (case-insensitive)
+'0x8335...'         // EVM address
+'eip155:8453/erc20:0x8335...'  // CAIP Asset ID
+```
+
+## Route Pattern Matching
+
+- **Exact**: `/api/users` - matches only `/api/users`
+- **Wildcard**: `/api/*` - matches `/api/users`, `/api/posts/123`
+- **Parameterized**: `/api/users/:id` - matches `/api/users/123`
+
+Priority order: Exact matches > Parameterized routes > Wildcard routes
+
+## Examples
+
+### Multi-Network Support
+
+```typescript
+app.use("/*", paymentMiddleware({
+  payTo: "0xYourAddress...",
+  chains: ["base", "ethereum", "skale-base"],
+  tokens: ["usdc", "eurc"],
+  amount: "1.0"
+}));
+```
+
+### Per-Chain Configuration
+
+```typescript
+app.use("/*", paymentMiddleware({
+  payTo: "0xDefaultAddress...",
+  payToByChain: {
+    base: "0xBaseAddress...",
+    ethereum: "0xEthAddress...",
+  },
+  chain: "base",
+  token: "usdc"
+}));
+```
+
+### Route-Specific Pricing
+
+```typescript
+app.use("/api/*", routeAwarePaymentMiddleware({
+  routes: ["/api/basic", "/api/pro", "/api/enterprise"],
+  payTo: "0xYourAddress...",
+  amount: "$1.00",
+  network: "base",
+  perRoute: {
+    "/api/pro": {
+      amount: "$5.00",
+    },
+    "/api/enterprise": {
+      amount: "$50.00",
+      network: "ethereum",
+    }
+  }
+}));
+```
+
+## API
+
+### `paymentMiddleware(config)`
+
+Creates a basic payment middleware for Hono.
+
+**Parameters:**
+- `config`: Payment configuration
+
+**Returns:** Hono middleware function
+
+### `createPaymentRequirements(config)`
+
+Creates payment requirements from configuration (for advanced use).
+
+**Parameters:**
+- `config`: Payment configuration
+
+**Returns:** Object with `requirements` array and optional `error`
+
+### `routeAwarePaymentMiddleware(config)`
+
+Creates a route-aware payment middleware for Hono.
+
+**Parameters:**
+- `config`: Route-aware payment configuration
+
+**Returns:** Hono middleware function

package/dist/extensions.d.ts

@@ -0,0 +1,39 @@
+import { Extensions } from '@armory-sh/base';
+
+/**
+ * Extension handling for Hono middleware
+ * Integrates with @armory-sh/extensions package
+ */
+
+type BazaarDiscoveryConfig = {
+    input?: unknown;
+    inputSchema?: Record<string, unknown>;
+    bodyType?: "json" | "form-data" | "text";
+    output?: {
+        example?: unknown;
+        schema?: Record<string, unknown>;
+    };
+};
+type SIWxExtensionConfig = {
+    domain?: string;
+    resourceUri?: string;
+    network?: string | string[];
+    statement?: string;
+    version?: string;
+    expirationSeconds?: number;
+};
+type Extension<T = unknown> = {
+    info: T;
+    schema: Record<string, unknown>;
+};
+interface ExtensionConfig {
+    bazaar?: BazaarDiscoveryConfig;
+    signInWithX?: SIWxExtensionConfig;
+}
+interface PaymentConfigWithExtensions {
+    extensions?: ExtensionConfig;
+}
+declare function buildExtensions(config: ExtensionConfig): Extensions;
+declare function extractExtension<T>(extensions: Extensions | undefined, key: string): Extension<T> | null;
+
+export { type ExtensionConfig, type PaymentConfigWithExtensions, buildExtensions, extractExtension };

package/dist/extensions.js

@@ -0,0 +1,60 @@
+// src/extensions.ts
+var declareDiscoveryExtension = (config = {}) => {
+  const info = {};
+  if (config.input !== void 0) {
+    info.input = config.input;
+  }
+  if (config.inputSchema !== void 0) {
+    info.inputSchema = config.inputSchema;
+  }
+  if (config.output !== void 0) {
+    info.output = config.output;
+  }
+  return { info, schema: { type: "object" } };
+};
+var declareSIWxExtension = (config = {}) => {
+  const info = {};
+  if (config.domain !== void 0) {
+    info.domain = config.domain;
+  }
+  if (config.resourceUri !== void 0) {
+    info.resourceUri = config.resourceUri;
+  }
+  if (config.network !== void 0) {
+    info.network = config.network;
+  }
+  if (config.statement !== void 0) {
+    info.statement = config.statement;
+  }
+  if (config.version !== void 0) {
+    info.version = config.version;
+  }
+  if (config.expirationSeconds !== void 0) {
+    info.expirationSeconds = config.expirationSeconds;
+  }
+  return { info, schema: { type: "object" } };
+};
+function buildExtensions(config) {
+  const extensions = {};
+  if (config.bazaar) {
+    extensions.bazaar = declareDiscoveryExtension(config.bazaar);
+  }
+  if (config.signInWithX) {
+    extensions["sign-in-with-x"] = declareSIWxExtension(config.signInWithX);
+  }
+  return extensions;
+}
+function extractExtension(extensions, key) {
+  if (!extensions || typeof extensions !== "object") {
+    return null;
+  }
+  const extension = extensions[key];
+  if (!extension || typeof extension !== "object") {
+    return null;
+  }
+  return extension;
+}
+export {
+  buildExtensions,
+  extractExtension
+};

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { Context, Next } from 'hono';
 import { PaymentRequirementsV2, ValidationError, PaymentRequirements, PaymentPayloadV2 } from '@armory-sh/base';
+import { ExtensionConfig } from './extensions.js';
+export { buildExtensions, extractExtension } from './extensions.js';
 
 /**
  * Simplified middleware API for easy x402 payment integration
@@ -16,6 +18,12 @@ interface PaymentConfig {
     token?: TokenId;
     amount?: string;
     maxTimeoutSeconds?: number;
+    payToByChain?: Record<NetworkId, string>;
+    payToByToken?: Record<NetworkId, Record<TokenId, string>>;
+    facilitatorUrl?: string;
+    facilitatorUrlByChain?: Record<NetworkId, string>;
+    facilitatorUrlByToken?: Record<NetworkId, Record<TokenId, string>>;
+    extensions?: ExtensionConfig;
 }
 interface ResolvedSimpleConfig {
     requirements: PaymentRequirementsV2[];
@@ -24,10 +32,16 @@ interface ResolvedSimpleConfig {
 declare function createPaymentRequirements(config: PaymentConfig): ResolvedSimpleConfig;
 declare function paymentMiddleware(config: PaymentConfig): (c: Context, next: Next) => Promise<Response | void>;
 
+interface RouteAwarePaymentConfig extends PaymentConfig {
+    route?: string;
+    routes?: string[];
+    perRoute?: Record<string, Partial<PaymentConfig>>;
+}
+declare const routeAwarePaymentMiddleware: (config: RouteAwarePaymentConfig) => (c: Context, next: Next) => Promise<Response | void>;
+
 interface AdvancedPaymentConfig {
     requirements: PaymentRequirements;
     facilitatorUrl?: string;
-    skipVerification?: boolean;
     network?: string;
 }
 interface AugmentedRequest extends Request {
@@ -39,4 +53,4 @@ interface AugmentedRequest extends Request {
 }
 declare const advancedPaymentMiddleware: (config: AdvancedPaymentConfig) => (c: Context, next: Next) => Promise<Response | void>;
 
-export { type AdvancedPaymentConfig, type AugmentedRequest, type PaymentConfig, advancedPaymentMiddleware, createPaymentRequirements, paymentMiddleware };
+export { type AdvancedPaymentConfig, type AugmentedRequest, ExtensionConfig, type PaymentConfig, type RouteAwarePaymentConfig, advancedPaymentMiddleware, createPaymentRequirements, paymentMiddleware, routeAwarePaymentMiddleware };

package/dist/index.js

@@ -16,6 +16,65 @@ import {
 import {
   TOKENS
 } from "@armory-sh/base";
+
+// src/extensions.ts
+var declareDiscoveryExtension = (config = {}) => {
+  const info = {};
+  if (config.input !== void 0) {
+    info.input = config.input;
+  }
+  if (config.inputSchema !== void 0) {
+    info.inputSchema = config.inputSchema;
+  }
+  if (config.output !== void 0) {
+    info.output = config.output;
+  }
+  return { info, schema: { type: "object" } };
+};
+var declareSIWxExtension = (config = {}) => {
+  const info = {};
+  if (config.domain !== void 0) {
+    info.domain = config.domain;
+  }
+  if (config.resourceUri !== void 0) {
+    info.resourceUri = config.resourceUri;
+  }
+  if (config.network !== void 0) {
+    info.network = config.network;
+  }
+  if (config.statement !== void 0) {
+    info.statement = config.statement;
+  }
+  if (config.version !== void 0) {
+    info.version = config.version;
+  }
+  if (config.expirationSeconds !== void 0) {
+    info.expirationSeconds = config.expirationSeconds;
+  }
+  return { info, schema: { type: "object" } };
+};
+function buildExtensions(config) {
+  const extensions = {};
+  if (config.bazaar) {
+    extensions.bazaar = declareDiscoveryExtension(config.bazaar);
+  }
+  if (config.signInWithX) {
+    extensions["sign-in-with-x"] = declareSIWxExtension(config.signInWithX);
+  }
+  return extensions;
+}
+function extractExtension(extensions, key) {
+  if (!extensions || typeof extensions !== "object") {
+    return null;
+  }
+  const extension = extensions[key];
+  if (!extension || typeof extension !== "object") {
+    return null;
+  }
+  return extension;
+}
+
+// src/simple.ts
 var isValidationError = (value) => {
   return typeof value === "object" && value !== null && "code" in value;
 };
@@ -83,6 +142,56 @@ function toAtomicUnits(amount) {
   }
   return `${amount}000000`;
 }
+function resolvePayTo(config, network, token) {
+  const chainId = network.config.chainId;
+  if (config.payToByToken) {
+    for (const [chainKey, tokenMap] of Object.entries(config.payToByToken)) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (!isValidationError(resolvedChain) && resolvedChain.config.chainId === chainId) {
+        for (const [tokenKey, address] of Object.entries(tokenMap)) {
+          const resolvedToken = resolveToken(tokenKey, network);
+          if (!isValidationError(resolvedToken) && resolvedToken.config.contractAddress.toLowerCase() === token.config.contractAddress.toLowerCase()) {
+            return address;
+          }
+        }
+      }
+    }
+  }
+  if (config.payToByChain) {
+    for (const [chainKey, address] of Object.entries(config.payToByChain)) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (!isValidationError(resolvedChain) && resolvedChain.config.chainId === chainId) {
+        return address;
+      }
+    }
+  }
+  return config.payTo;
+}
+function resolveFacilitatorUrl(config, network, token) {
+  const chainId = network.config.chainId;
+  if (config.facilitatorUrlByToken) {
+    for (const [chainKey, tokenMap] of Object.entries(config.facilitatorUrlByToken)) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (!isValidationError(resolvedChain) && resolvedChain.config.chainId === chainId) {
+        for (const [tokenKey, url] of Object.entries(tokenMap)) {
+          const resolvedToken = resolveToken(tokenKey, network);
+          if (!isValidationError(resolvedToken) && resolvedToken.config.contractAddress.toLowerCase() === token.config.contractAddress.toLowerCase()) {
+            return url;
+          }
+        }
+      }
+    }
+  }
+  if (config.facilitatorUrlByChain) {
+    for (const [chainKey, url] of Object.entries(config.facilitatorUrlByChain)) {
+      const resolvedChain = resolveNetwork(chainKey);
+      if (!isValidationError(resolvedChain) && resolvedChain.config.chainId === chainId) {
+        return url;
+      }
+    }
+  }
+  return config.facilitatorUrl;
+}
 function createPaymentRequirements(config) {
   ensureTokensRegistered();
   const {
@@ -111,16 +220,19 @@ function createPaymentRequirements(config) {
       }
       const atomicAmount = toAtomicUnits(amount);
       const tokenConfig = resolvedToken.config;
+      const resolvedPayTo = resolvePayTo(config, network, resolvedToken);
+      const resolvedFacilitatorUrl = resolveFacilitatorUrl(config, network, resolvedToken);
       requirements.push({
         scheme: "exact",
         network: network.caip2,
         amount: atomicAmount,
         asset: tokenConfig.contractAddress,
-        payTo,
+        payTo: resolvedPayTo,
         maxTimeoutSeconds,
         extra: {
           name: tokenConfig.name,
-          version: tokenConfig.version
+          version: tokenConfig.version,
+          ...resolvedFacilitatorUrl && { facilitatorUrl: resolvedFacilitatorUrl }
         }
       });
     }
@@ -148,7 +260,8 @@ function paymentMiddleware(config) {
         x402Version: 2,
         error: "Payment required",
         resource,
-        accepts: requirements
+        accepts: requirements,
+        extensions: config.extensions ? buildExtensions(config.extensions) : void 0
       };
       c.status(402);
       c.header(V2_HEADERS.PAYMENT_REQUIRED, safeBase64Encode(JSON.stringify(paymentRequired)));
@@ -178,9 +291,104 @@ function paymentMiddleware(config) {
   };
 }
 
+// src/routes.ts
+import {
+  safeBase64Encode as safeBase64Encode2,
+  V2_HEADERS as V2_HEADERS2,
+  matchRoute,
+  validateRouteConfig
+} from "@armory-sh/base";
+var resolveRouteConfig = (config) => {
+  const validationError = validateRouteConfig(config);
+  if (validationError) {
+    return { routes: [], error: validationError };
+  }
+  const { route, routes, perRoute, ...baseConfig } = config;
+  const routePatterns = route ? [route] : routes || [];
+  const resolvedRoutes = [];
+  for (const pattern of routePatterns) {
+    const perRouteOverride = perRoute?.[pattern];
+    const mergedConfig = {
+      ...baseConfig,
+      ...perRouteOverride
+    };
+    resolvedRoutes.push({
+      pattern,
+      config: mergedConfig
+    });
+  }
+  return { routes: resolvedRoutes };
+};
+var routeAwarePaymentMiddleware = (config) => {
+  const { routes, error } = resolveRouteConfig(config);
+  return async (c, next) => {
+    if (error) {
+      c.status(500);
+      return c.json({
+        error: "Payment middleware configuration error",
+        details: error.message
+      });
+    }
+    const path = new URL(c.req.url).pathname;
+    const matchedRoute = routes.find((r) => matchRoute(r.pattern, path));
+    if (!matchedRoute) {
+      return next();
+    }
+    const { requirements, error: requirementsError } = createPaymentRequirements(matchedRoute.config);
+    if (requirementsError) {
+      c.status(500);
+      return c.json({
+        error: "Payment middleware configuration error",
+        details: requirementsError.message
+      });
+    }
+    const paymentHeader = c.req.header(V2_HEADERS2.PAYMENT_SIGNATURE);
+    if (!paymentHeader) {
+      const resource = {
+        url: c.req.url,
+        description: "API Access",
+        mimeType: "application/json"
+      };
+      const paymentRequired = {
+        x402Version: 2,
+        error: "Payment required",
+        resource,
+        accepts: requirements
+      };
+      c.status(402);
+      c.header(
+        V2_HEADERS2.PAYMENT_REQUIRED,
+        safeBase64Encode2(JSON.stringify(paymentRequired))
+      );
+      return c.json({
+        error: "Payment required",
+        accepts: requirements
+      });
+    }
+    let parsedPayload;
+    try {
+      const decoded = atob(paymentHeader);
+      parsedPayload = JSON.parse(decoded);
+    } catch {
+      try {
+        parsedPayload = JSON.parse(paymentHeader);
+      } catch {
+        c.status(400);
+        return c.json({ error: "Invalid payment payload" });
+      }
+    }
+    c.set("payment", {
+      payload: parsedPayload,
+      verified: false,
+      route: matchedRoute.pattern
+    });
+    return next();
+  };
+};
+
 // src/index.ts
 var advancedPaymentMiddleware = (config) => {
-  const { requirements, facilitatorUrl, skipVerification = false, network = "base" } = config;
+  const { requirements, facilitatorUrl, network = "base" } = config;
   return async (c, next) => {
     const paymentHeader = c.req.header(PAYMENT_SIGNATURE_HEADER);
     if (!paymentHeader) {
@@ -209,13 +417,16 @@ var advancedPaymentMiddleware = (config) => {
     c.set("payment", {
       payload: paymentPayload,
       payerAddress,
-      verified: !skipVerification
+      verified: true
     });
     return next();
   };
 };
 export {
   advancedPaymentMiddleware,
+  buildExtensions,
   createPaymentRequirements,
-  paymentMiddleware
+  extractExtension,
+  paymentMiddleware,
+  routeAwarePaymentMiddleware
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armory-sh/middleware-hono",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "license": "MIT",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
   "type": "module",
@@ -11,6 +11,11 @@
       "types": "./dist/index.d.ts",
       "bun": "./src/index.ts",
       "default": "./dist/index.js"
+    },
+    "./extensions": {
+      "types": "./dist/extensions.d.ts",
+      "bun": "./src/extensions.ts",
+      "default": "./dist/extensions.js"
     }
   },
   "files": [
@@ -28,10 +33,12 @@
     "hono": "^4"
   },
   "dependencies": {
-    "@armory-sh/base": "0.2.19"
+    "@armory-sh/base": "0.2.21",
+    "@armory-sh/extensions": "0.1.2"
   },
   "devDependencies": {
     "bun-types": "latest",
+    "tsup": "^8.5.1",
     "typescript": "5.9.3",
     "hono": "^4"
   },