@perkos/middleware-x402 1.0.0

package/README.md

@@ -0,0 +1,177 @@
+# @perkos/middleware-x402
+
+x402 v2 payment protocol middleware and utilities for building vendor services with micropayments.
+
+## Installation
+
+```bash
+npm install @perkos/middleware-x402
+# or
+pnpm add @perkos/middleware-x402
+# or
+yarn add @perkos/middleware-x402
+```
+
+## Features
+
+- **x402 v2 Protocol Support**: Full implementation of the x402 v2 payment specification
+- **Multi-Network Support**: Avalanche, Base, Celo (mainnet and testnets)
+- **Payment Middleware**: Easy integration with Next.js API routes
+- **EIP-712 Signatures**: TransferWithAuthorization support for USDC
+- **Type-Safe**: Full TypeScript support with comprehensive types
+
+## Quick Start
+
+### Next.js Integration
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import { verifyX402PaymentNext, type PaymentConfig, type PaymentRoutes } from "@perkos/middleware-x402";
+
+// Configure your payment settings
+const config: PaymentConfig = {
+  payTo: "0xYourWalletAddress" as `0x${string}`,
+  facilitatorUrl: "https://stack.perkos.xyz",
+  network: "avalanche",
+  priceUsd: "0.05",
+};
+
+// Define payment routes
+const routes: PaymentRoutes = {
+  "/api/ai/translate": 0.03,
+  "/api/ai/analyze": 0.05,
+  "/api/ai/generate": 0.15,
+};
+
+export async function POST(request: NextRequest) {
+  // Verify payment
+  const paymentResult = await verifyX402PaymentNext(request, "/api/ai/translate", {
+    config,
+    routes,
+  });
+
+  if (!paymentResult.isValid) {
+    return paymentResult.response;
+  }
+
+  // Process request - payment verified!
+  const result = await processRequest(request);
+
+  // Return response with payment header
+  const headers: Record<string, string> = {};
+  if (paymentResult.paymentResponseHeader) {
+    headers["PAYMENT-RESPONSE"] = paymentResult.paymentResponseHeader;
+  }
+
+  return NextResponse.json({ success: true, data: result }, { headers });
+}
+```
+
+### Utilities
+
+```typescript
+import {
+  getUSDCAddress,
+  toCAIP2Network,
+  parsePriceToUSDC,
+  generateNonce,
+  createEIP712Domain,
+} from "@perkos/middleware-x402";
+
+// Get USDC address for a network
+const usdcAddress = getUSDCAddress("avalanche");
+// => "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E"
+
+// Convert network to CAIP-2 format
+const caip2 = toCAIP2Network("base-sepolia");
+// => "eip155:84532"
+
+// Parse USD price to USDC atomic units
+const amount = parsePriceToUSDC("$0.05");
+// => 50000n
+
+// Generate payment nonce
+const nonce = generateNonce();
+// => "0x..."
+
+// Create EIP-712 domain for signing
+const domain = createEIP712Domain("avalanche");
+// => { name: "USD Coin", version: "2", chainId: 43114, verifyingContract: "0x..." }
+```
+
+## API Reference
+
+### Types
+
+#### `PaymentConfig`
+```typescript
+interface PaymentConfig {
+  payTo: `0x${string}`;      // Recipient wallet address
+  facilitatorUrl: string;     // x402 facilitator URL
+  network: NetworkName;       // Network name
+  priceUsd: string;          // Default price in USD
+}
+```
+
+#### `PaymentRoutes`
+```typescript
+type PaymentRoutes = Record<string, number>;
+// Example: { "/api/endpoint": 0.05 }
+```
+
+#### `PaymentEnvelope`
+```typescript
+interface PaymentEnvelope {
+  network: string;
+  authorization: {
+    from: string;
+    to: string;
+    value: string;
+    nonce: string;
+    validBefore: string;
+  };
+  signature: string;
+}
+```
+
+### Constants
+
+- `USDC_ADDRESSES` - USDC contract addresses by network
+- `CHAIN_IDS` - Chain IDs by network
+- `NETWORK_TO_CAIP2` - Network to CAIP-2 mapping
+- `VALID_NETWORKS` - List of supported networks
+
+### Functions
+
+#### `verifyX402PaymentNext(request, route, options)`
+Verify x402 payment in Next.js API route.
+
+#### `getUSDCAddress(network)`
+Get USDC contract address for a network.
+
+#### `toCAIP2Network(network)`
+Convert network name to CAIP-2 format.
+
+#### `parsePriceToUSDC(price)`
+Parse USD price string to USDC atomic units.
+
+#### `generateNonce()`
+Generate random 32-byte nonce for payment.
+
+#### `createEIP712Domain(network, tokenAddress?, tokenName?)`
+Create EIP-712 domain for TransferWithAuthorization.
+
+## Supported Networks
+
+| Network | Chain ID | CAIP-2 |
+|---------|----------|--------|
+| Avalanche | 43114 | eip155:43114 |
+| Avalanche Fuji | 43113 | eip155:43113 |
+| Base | 8453 | eip155:8453 |
+| Base Sepolia | 84532 | eip155:84532 |
+| Celo | 42220 | eip155:42220 |
+| Celo Sepolia | 11142220 | eip155:11142220 |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,320 @@
+import { Address } from 'viem';
+
+/**
+ * x402 Core Types
+ * Type definitions for x402 v2 payment protocol
+ */
+
+/**
+ * Payment envelope containing authorization and signature
+ */
+interface PaymentEnvelope {
+    network: string;
+    authorization: {
+        from: string;
+        to: string;
+        value: string;
+        nonce: string;
+        validAfter?: string;
+        validBefore: string;
+    };
+    signature: string;
+}
+/**
+ * Payment requirements for a protected resource
+ */
+interface PaymentRequirements {
+    endpoint?: string;
+    method?: string;
+    price?: string;
+    network: string;
+    payTo: string;
+    facilitator?: string;
+    maxAmountRequired?: string;
+    resource?: string;
+    scheme?: string;
+    asset?: string;
+    tokenName?: string;
+    tokenVersion?: string;
+}
+/**
+ * Payment configuration for x402 middleware
+ */
+interface PaymentConfig {
+    payTo: `0x${string}`;
+    facilitatorUrl: string;
+    network: NetworkName;
+    priceUsd: string;
+}
+/**
+ * Result of payment verification
+ */
+interface PaymentVerificationResult {
+    isValid: boolean;
+    payer?: string;
+    invalidReason?: string;
+    transactionHash?: string;
+}
+/**
+ * Result of verifyX402Payment middleware
+ */
+interface X402PaymentResult {
+    isValid: boolean;
+    response?: any;
+    payer?: string;
+    envelope?: PaymentEnvelope;
+    paymentResponseHeader?: string;
+}
+/**
+ * Supported network names
+ */
+type NetworkName = "base" | "base-sepolia" | "avalanche" | "avalanche-fuji" | "celo" | "celo-sepolia";
+/**
+ * CAIP-2 network identifier
+ */
+type CAIP2Network = "eip155:8453" | "eip155:84532" | "eip155:43114" | "eip155:43113" | "eip155:42220" | "eip155:11142220";
+/**
+ * Token information for EIP-712 domain
+ */
+interface TokenInfo {
+    address: Address;
+    name: string;
+    symbol: string;
+    decimals: number;
+    chainId: number;
+}
+/**
+ * Settlement result from facilitator
+ */
+interface SettlementResult {
+    success: boolean;
+    transactionHash?: string;
+    error?: string;
+}
+/**
+ * Payment route configuration (path → price in USD)
+ */
+type PaymentRoutes = Record<string, number>;
+/**
+ * Options for x402 middleware
+ */
+interface X402MiddlewareOptions {
+    config: PaymentConfig;
+    routes: PaymentRoutes;
+    tokenDetector?: (address: Address, network: string) => Promise<TokenInfo | null>;
+    logger?: {
+        log: (...args: any[]) => void;
+        error: (...args: any[]) => void;
+    };
+}
+
+/**
+ * x402 Core Constants
+ * Network configurations, addresses, and mappings
+ */
+
+/**
+ * USDC Contract Addresses by Network
+ */
+declare const USDC_ADDRESSES: Record<NetworkName, Address>;
+/**
+ * Chain IDs by Network
+ */
+declare const CHAIN_IDS: Record<string, number>;
+/**
+ * Network to CAIP-2 mapping
+ */
+declare const NETWORK_TO_CAIP2: Record<NetworkName, CAIP2Network>;
+/**
+ * CAIP-2 to Network mapping
+ */
+declare const CAIP2_TO_NETWORK: Record<string, NetworkName>;
+/**
+ * Default RPC URLs by Network
+ */
+declare const DEFAULT_RPC_URLS: Record<NetworkName, string>;
+/**
+ * Valid network names
+ */
+declare const VALID_NETWORKS: NetworkName[];
+/**
+ * EIP-712 TransferWithAuthorization types
+ */
+declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+
+/**
+ * x402 Core Utilities
+ * Helper functions for x402 payment processing
+ */
+
+/**
+ * Get USDC address for a network
+ */
+declare function getUSDCAddress(network: string): Address;
+/**
+ * Get chain ID for a network
+ */
+declare function getChainId(network: string): number;
+/**
+ * Get RPC URL for a network (with environment variable override support)
+ */
+declare function getRpcUrl(network: string, envOverrides?: Record<string, string | undefined>): string;
+/**
+ * Convert network name to CAIP-2 format for x402 V2
+ * e.g., "base-sepolia" → "eip155:84532"
+ */
+declare function toCAIP2Network(network: string): string;
+/**
+ * Convert CAIP-2 network format to legacy format
+ * e.g., "eip155:43114" → "avalanche"
+ */
+declare function toLegacyNetwork(network: string): string;
+/**
+ * Parse USD price string to USDC amount (6 decimals)
+ * e.g., "$0.05" → 50000n
+ */
+declare function parsePriceToUSDC(price: string): bigint;
+/**
+ * Format USDC amount to USD string
+ * e.g., 50000n → "$0.05"
+ */
+declare function formatUSDCToPrice(amount: bigint): string;
+/**
+ * Generate random nonce for payment (32 bytes)
+ */
+declare function generateNonce(): `0x${string}`;
+/**
+ * Create EIP-712 domain for token transferWithAuthorization
+ */
+declare function createEIP712Domain(network: string, tokenAddress?: Address, tokenName?: string): {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+};
+/**
+ * Format payment payload for x402 v2 PAYMENT-SIGNATURE header
+ * Per spec: https://www.x402.org/writing/x402-v2-launch
+ */
+declare function formatPaymentSignature(envelope: PaymentEnvelope, network: string, encodeBase64?: boolean): string;
+/**
+ * Parse payment signature from header
+ */
+declare function parsePaymentSignature(header: string): PaymentEnvelope | null;
+/**
+ * Validate network name
+ */
+declare function isValidNetwork(network: string): network is NetworkName;
+/**
+ * Get valid before timestamp (default: 30 minutes from now)
+ */
+declare function getValidBefore(minutes?: number): string;
+/**
+ * Get valid after timestamp (default: now)
+ */
+declare function getValidAfter(): string;
+
+/**
+ * x402 Payment Middleware
+ * Payment verification and settlement for API routes
+ */
+
+interface MiddlewareContext {
+    config: PaymentConfig;
+    routes: PaymentRoutes;
+    tokenDetector?: (address: string, network: string) => Promise<TokenInfo | null>;
+    createResponse?: (body: any, options: {
+        status: number;
+        headers?: Record<string, string>;
+    }) => any;
+    getHeader?: (request: any, name: string) => string | null;
+}
+/**
+ * Extract payment envelope from request headers
+ */
+declare function extractPaymentEnvelope(request: any, getHeader?: (req: any, name: string) => string | null): PaymentEnvelope | null;
+/**
+ * Verify payment with facilitator
+ */
+declare function verifyPayment(envelope: PaymentEnvelope, route: string, ctx: MiddlewareContext): Promise<PaymentVerificationResult>;
+/**
+ * Settle payment with facilitator
+ */
+declare function settlePayment(envelope: PaymentEnvelope, ctx: MiddlewareContext): Promise<SettlementResult>;
+/**
+ * Create 402 Payment Required response
+ */
+declare function create402Response(route: string, ctx: MiddlewareContext): {
+    body: any;
+    status: number;
+    headers: Record<string, string>;
+};
+/**
+ * Main middleware function to verify x402 payment
+ */
+declare function verifyX402Payment$1(request: any, route: string, ctx: MiddlewareContext): Promise<X402PaymentResult>;
+
+/**
+ * x402 Next.js Integration
+ * Helper functions for Next.js API routes
+ */
+
+/**
+ * Next.js specific middleware context
+ */
+interface NextX402Options {
+    config: PaymentConfig;
+    routes: PaymentRoutes;
+    tokenDetector?: (address: string, network: string) => Promise<TokenInfo | null>;
+}
+/**
+ * Verify x402 payment in Next.js API route
+ *
+ * @example
+ * ```typescript
+ * import { verifyX402Payment } from "@perkos/x402-core/next";
+ *
+ * export async function POST(request: NextRequest) {
+ *   const result = await verifyX402Payment(request, "/api/ai/translate", {
+ *     config: x402Config,
+ *     routes: paymentRoutes,
+ *   });
+ *
+ *   if (!result.isValid) {
+ *     return result.response;
+ *   }
+ *
+ *   // Process request...
+ * }
+ * ```
+ */
+declare function verifyX402Payment(request: any, route: string, options: NextX402Options): Promise<X402PaymentResult>;
+/**
+ * Create a configured middleware instance for Next.js
+ */
+declare function createX402Middleware(options: NextX402Options): {
+    verify: (request: any, route: string) => Promise<X402PaymentResult>;
+    options: NextX402Options;
+};
+
+export { type CAIP2Network, CAIP2_TO_NETWORK, CHAIN_IDS, DEFAULT_RPC_URLS, type MiddlewareContext, NETWORK_TO_CAIP2, type NetworkName, type NextX402Options, type PaymentConfig, type PaymentEnvelope, type PaymentRequirements, type PaymentRoutes, type PaymentVerificationResult, type SettlementResult, TRANSFER_WITH_AUTHORIZATION_TYPES, type TokenInfo, USDC_ADDRESSES, VALID_NETWORKS, type X402MiddlewareOptions, type X402PaymentResult, create402Response, createEIP712Domain, createX402Middleware, extractPaymentEnvelope, formatPaymentSignature, formatUSDCToPrice, generateNonce, getChainId, getRpcUrl, getUSDCAddress, getValidAfter, getValidBefore, isValidNetwork, parsePaymentSignature, parsePriceToUSDC, settlePayment, toCAIP2Network, toLegacyNetwork, verifyPayment, verifyX402Payment$1 as verifyX402Payment, verifyX402Payment as verifyX402PaymentNext };