@4mica/x402 0.1.0

package/src/server/express/index.ts

@@ -0,0 +1,466 @@
+import {
+  HTTPRequestContext,
+  PaywallConfig,
+  PaywallProvider,
+  x402HTTPResourceServer,
+  x402ResourceServer,
+  RoutesConfig,
+  FacilitatorClient,
+} from '@x402/core/server'
+import { SchemeNetworkServer, Network } from '@x402/core/types'
+import { NextFunction, Request, Response } from 'express'
+import { ExpressAdapter } from './adapter.js'
+import { FourMicaEvmScheme, SUPPORTED_NETWORKS } from '../scheme.js'
+import { FourMicaFacilitatorClient } from '../facilitator.js'
+
+/**
+ * Configuration for payment tab handling
+ */
+interface TabConfig {
+  /**
+   * The full URL endpoint for opening payment tabs. This URL is injected into
+   * paymentRequirements.extra and clients use it to open a payment tab.
+   * When a request matches this endpoint's path, the middleware will parse
+   * the request body and call the 4mica facilitator to open a tab.
+   *
+   * @example "https://api.example.com/x402/tab"
+   */
+  advertisedEndpoint: string
+
+  /**
+   * The lifetime of the payment tab in seconds. Defines how long the tab
+   * remains valid before expiring.
+   *
+   * @example 3600 // 1 hour
+   */
+  ttlSeconds?: number
+}
+
+function registerNetworkServers(httpServer: x402HTTPResourceServer, tabEndpoint: string) {
+  const schemeServer = new FourMicaEvmScheme(tabEndpoint)
+  SUPPORTED_NETWORKS.forEach((network) => {
+    ;(httpServer as any).ResourceServer.register(network, schemeServer)
+  })
+}
+
+function checkIfBazaarNeeded(routes: RoutesConfig): boolean {
+  if ('accepts' in routes) {
+    return !!(routes.extensions && 'bazaar' in routes.extensions)
+  }
+
+  return Object.values(routes).some((routeConfig) => {
+    return !!(routeConfig.extensions && 'bazaar' in routeConfig.extensions)
+  })
+}
+
+/**
+ * Configuration for registering a payment scheme with a specific network
+ */
+export interface SchemeRegistration {
+  /**
+   * The network identifier (e.g., 'eip155:84532', 'solana:mainnet')
+   */
+  network: Network
+
+  /**
+   * The scheme server implementation for this network
+   */
+  server: SchemeNetworkServer
+}
+
+/**
+ * Express payment middleware for x402 protocol (direct HTTP server instance).
+ *
+ * Use this when you need to configure HTTP-level hooks.
+ *
+ * @param httpServer - Pre-configured x402HTTPResourceServer instance
+ * @param tabConfig - Configuration for payment tab handling (endpoint URL and TTL)
+ * @param paywallConfig - Optional configuration for the built-in paywall UI
+ * @param paywall - Optional custom paywall provider (overrides default)
+ * @param syncFacilitatorOnStart - Whether to sync with the facilitator on startup (defaults to true)
+ * @returns Express middleware handler
+ *
+ * @example
+ * ```typescript
+ * import { paymentMiddlewareFromHTTPServer, x402ResourceServer, x402HTTPResourceServer } from "@x402/express";
+ *
+ * const resourceServer = new x402ResourceServer(facilitatorClient)
+ *   .register(NETWORK, new ExactEvmScheme())
+ *
+ * const httpServer = new x402HTTPResourceServer(resourceServer, routes)
+ *   .onProtectedRequest(requestHook);
+ *
+ * app.use(paymentMiddlewareFromHTTPServer(
+ *   httpServer,
+ *   { advertisedEndpoint: "https://api.example.com/x402/tab" },
+ * )); * ```
+ */
+export function paymentMiddlewareFromHTTPServer(
+  httpServer: x402HTTPResourceServer,
+  tabConfig: TabConfig,
+  paywallConfig?: PaywallConfig,
+  paywall?: PaywallProvider,
+  syncFacilitatorOnStart: boolean = true
+) {
+  const facilitatorClient = new FourMicaFacilitatorClient()
+
+  registerNetworkServers(httpServer, tabConfig.advertisedEndpoint)
+
+  // Register custom paywall provider if provided
+  if (paywall) {
+    httpServer.registerPaywallProvider(paywall)
+  }
+
+  // Store initialization promise (not the result)
+  // httpServer.initialize() fetches facilitator support and validates routes
+  let initPromise: Promise<void> | null = syncFacilitatorOnStart ? httpServer.initialize() : null
+
+  // Dynamically register bazaar extension if routes declare it and not already registered
+  // Skip if pre-registered (e.g., in serverless environments where static imports are used)
+  let bazaarPromise: Promise<void> | null = null
+  if (
+    checkIfBazaarNeeded((httpServer as any).routesConfig) &&
+    !(httpServer as any).ResourceServer.hasExtension('bazaar')
+  ) {
+    bazaarPromise = import('@x402/extensions/bazaar')
+      .then(({ bazaarResourceServerExtension }) => {
+        ;(httpServer as any).ResourceServer.registerExtension(bazaarResourceServerExtension)
+      })
+      .catch((err) => {
+        console.error('Failed to load bazaar extension:', err)
+      })
+  }
+
+  return async (req: Request, res: Response, next: NextFunction) => {
+    // Check if this request is for the tab opening endpoint
+    try {
+      const advertisedUrl = new URL(tabConfig.advertisedEndpoint)
+      if (req.path === advertisedUrl.pathname) {
+        // Parse the request body
+        const { userAddress, paymentRequirements } = req.body
+
+        try {
+          // Call the facilitator to open the tab
+          const openTabResponse = await facilitatorClient.openTab(
+            userAddress,
+            paymentRequirements,
+            tabConfig.ttlSeconds
+          )
+
+          // Return the response
+          return res.json(openTabResponse)
+        } catch (error) {
+          if (error instanceof Error && 'status' in error) {
+            const openTabError = error as any
+            return res.status(openTabError.status).json(openTabError.response)
+          }
+          console.error('Failed to open tab:', error)
+          return res.status(500).json({
+            error: 'Failed to open tab',
+            details: error instanceof Error ? error.message : 'Unknown error',
+          })
+        }
+      }
+    } catch (urlError) {
+      console.error('Invalid advertisedEndpoint URL:', urlError)
+    }
+
+    // Create adapter and context
+    const adapter = new ExpressAdapter(req)
+    const context: HTTPRequestContext = {
+      adapter,
+      path: req.path,
+      method: req.method,
+      paymentHeader: adapter.getHeader('payment-signature') || adapter.getHeader('x-payment'),
+    }
+
+    // Check if route requires payment before initializing facilitator
+    if (!httpServer.requiresPayment(context)) {
+      return next()
+    }
+
+    // Only initialize when processing a protected route
+    if (initPromise) {
+      await initPromise
+      initPromise = null // Clear after first await
+    }
+
+    // Await bazaar extension loading if needed
+    if (bazaarPromise) {
+      await bazaarPromise
+      bazaarPromise = null
+    }
+
+    // Process payment requirement check
+    const result = await httpServer.processHTTPRequest(context, paywallConfig)
+
+    // Handle the different result types
+    switch (result.type) {
+      case 'no-payment-required':
+        // No payment needed, proceed directly to the route handler
+        return next()
+
+      case 'payment-error':
+        // Payment required but not provided or invalid
+        const { response } = result
+        res.status(response.status)
+        Object.entries(response.headers).forEach(([key, value]) => {
+          res.setHeader(key, value)
+        })
+        if (response.isHtml) {
+          res.send(response.body)
+        } else {
+          res.json(response.body || {})
+        }
+        return
+
+      case 'payment-verified':
+        // Payment is valid, need to wrap response for settlement
+        const { paymentPayload, paymentRequirements } = result
+
+        // Intercept and buffer all core methods that can commit response to client
+        const originalWriteHead = res.writeHead.bind(res)
+        const originalWrite = res.write.bind(res)
+        const originalEnd = res.end.bind(res)
+        const originalFlushHeaders = res.flushHeaders.bind(res)
+
+        type BufferedCall =
+          | ['writeHead', Parameters<typeof originalWriteHead>]
+          | ['write', Parameters<typeof originalWrite>]
+          | ['end', Parameters<typeof originalEnd>]
+          | ['flushHeaders', []]
+        let bufferedCalls: BufferedCall[] = []
+        let settled = false
+
+        // Create a promise that resolves when the handler finishes and calls res.end()
+        let endCalled: () => void
+        const endPromise = new Promise<void>((resolve) => {
+          endCalled = resolve
+        })
+
+        res.writeHead = function (...args: Parameters<typeof originalWriteHead>) {
+          if (!settled) {
+            bufferedCalls.push(['writeHead', args])
+            return res
+          }
+          return originalWriteHead(...args)
+        } as typeof originalWriteHead
+
+        res.write = function (...args: Parameters<typeof originalWrite>) {
+          if (!settled) {
+            bufferedCalls.push(['write', args])
+            return true
+          }
+          return originalWrite(...args)
+        } as typeof originalWrite
+
+        res.end = function (...args: Parameters<typeof originalEnd>) {
+          if (!settled) {
+            bufferedCalls.push(['end', args])
+            // Signal that the handler has finished
+            endCalled()
+            return res
+          }
+          return originalEnd(...args)
+        } as typeof originalEnd
+
+        res.flushHeaders = function () {
+          if (!settled) {
+            bufferedCalls.push(['flushHeaders', []])
+            return
+          }
+          return originalFlushHeaders()
+        }
+
+        // Proceed to the next middleware or route handler
+        next()
+
+        // Wait for the handler to actually call res.end() before checking status
+        await endPromise
+
+        // If the response from the protected route is >= 400, do not settle payment
+        if (res.statusCode >= 400) {
+          settled = true
+          res.writeHead = originalWriteHead
+          res.write = originalWrite
+          res.end = originalEnd
+          res.flushHeaders = originalFlushHeaders
+          // Replay all buffered calls in order
+          for (const [method, args] of bufferedCalls) {
+            if (method === 'writeHead')
+              originalWriteHead(...(args as Parameters<typeof originalWriteHead>))
+            else if (method === 'write')
+              originalWrite(...(args as Parameters<typeof originalWrite>))
+            else if (method === 'end') originalEnd(...(args as Parameters<typeof originalEnd>))
+            else if (method === 'flushHeaders') originalFlushHeaders()
+          }
+          bufferedCalls = []
+          return
+        }
+
+        try {
+          const settleResult = await httpServer.processSettlement(
+            paymentPayload,
+            paymentRequirements
+          )
+
+          // If settlement fails, return an error and do not send the buffered response
+          if (!settleResult.success) {
+            bufferedCalls = []
+            res.status(402).json({
+              error: 'Settlement failed',
+              details: settleResult.errorReason,
+            })
+            return
+          }
+
+          // Settlement succeeded - add headers to response
+          Object.entries(settleResult.headers).forEach(([key, value]) => {
+            res.setHeader(key, value)
+          })
+        } catch (error) {
+          console.error(error)
+          // If settlement fails, don't send the buffered response
+          bufferedCalls = []
+          res.status(402).json({
+            error: 'Settlement failed',
+            details: error instanceof Error ? error.message : 'Unknown error',
+          })
+          return
+        } finally {
+          settled = true
+          res.writeHead = originalWriteHead
+          res.write = originalWrite
+          res.end = originalEnd
+          res.flushHeaders = originalFlushHeaders
+
+          // Replay all buffered calls in order
+          for (const [method, args] of bufferedCalls) {
+            if (method === 'writeHead')
+              originalWriteHead(...(args as Parameters<typeof originalWriteHead>))
+            else if (method === 'write')
+              originalWrite(...(args as Parameters<typeof originalWrite>))
+            else if (method === 'end') originalEnd(...(args as Parameters<typeof originalEnd>))
+            else if (method === 'flushHeaders') originalFlushHeaders()
+          }
+          bufferedCalls = []
+        }
+        return
+    }
+  }
+}
+
+/**
+ * Express payment middleware for x402 protocol (direct server instance).
+ *
+ * Use this when you want to pass a pre-configured x402ResourceServer instance.
+ * This provides more flexibility for testing, custom configuration, and reusing
+ * server instances across multiple middlewares.
+ *
+ * @param routes - Route configurations for protected endpoints
+ * @param server - Pre-configured x402ResourceServer instance
+ * @param tabConfig - Configuration for payment tab handling (endpoint URL and TTL)
+ * @param paywallConfig - Optional configuration for the built-in paywall UI
+ * @param paywall - Optional custom paywall provider (overrides default)
+ * @param syncFacilitatorOnStart - Whether to sync with the facilitator on startup (defaults to true)
+ * @returns Express middleware handler
+ *
+ * @example
+ * ```typescript
+ * import { paymentMiddleware } from "@x402/express";
+ *
+ * const server = new x402ResourceServer(myFacilitatorClient)
+ *   .register(NETWORK, new ExactEvmScheme());
+ *
+ * app.use(paymentMiddleware(
+ *   routes,
+ *   server,
+ *   { advertisedEndpoint: "https://api.example.com/x402/tab" },
+ * ));
+ * ```
+ */
+export function paymentMiddleware(
+  routes: RoutesConfig,
+  server: x402ResourceServer,
+  tabConfig: TabConfig,
+  paywallConfig?: PaywallConfig,
+  paywall?: PaywallProvider,
+  syncFacilitatorOnStart: boolean = true
+) {
+  // Create the x402 HTTP server instance with the resource server
+  const httpServer = new x402HTTPResourceServer(server, routes)
+
+  return paymentMiddlewareFromHTTPServer(
+    httpServer,
+    tabConfig,
+    paywallConfig,
+    paywall,
+    syncFacilitatorOnStart
+  )
+}
+
+/**
+ * Express payment middleware for x402 protocol (configuration-based).
+ *
+ * Use this when you want to quickly set up middleware with simple configuration.
+ * This function creates and configures the x402ResourceServer internally.
+ *
+ * @param routes - Route configurations for protected endpoints
+ * @param tabConfig - Configuration for payment tab handling
+ * @param facilitatorClients - Optional facilitator client(s) for payment processing
+ * @param schemes - Optional array of scheme registrations for server-side payment processing
+ * @param paywallConfig - Optional configuration for the built-in paywall UI
+ * @param paywall - Optional custom paywall provider (overrides default)
+ * @param syncFacilitatorOnStart - Whether to sync with the facilitator on startup (defaults to true)
+ * @returns Express middleware handler
+ *
+ * @example
+ * ```typescript
+ * import { paymentMiddlewareFromConfig } from "@x402/express";
+ *
+ * app.use(paymentMiddlewareFromConfig(
+ *   routes,
+ *   { advertisedEndpoint: "https://api.example.com/x402/tab" },
+ * ));
+ * ```
+ */
+export function paymentMiddlewareFromConfig(
+  routes: RoutesConfig,
+  tabConfig: TabConfig,
+  facilitatorClients?: FacilitatorClient | FacilitatorClient[],
+  schemes?: SchemeRegistration[],
+  paywallConfig?: PaywallConfig,
+  paywall?: PaywallProvider,
+  syncFacilitatorOnStart: boolean = true
+) {
+  const facilitators = facilitatorClients
+    ? Array.isArray(facilitatorClients)
+      ? facilitatorClients
+      : [facilitatorClients]
+    : []
+
+  if (!facilitators.some((c) => c instanceof FourMicaFacilitatorClient)) {
+    facilitators.push(new FourMicaFacilitatorClient())
+  }
+
+  const ResourceServer = new x402ResourceServer(facilitators)
+
+  if (schemes) {
+    schemes.forEach(({ network, server: schemeServer }) => {
+      ResourceServer.register(network, schemeServer)
+    })
+  }
+
+  // Use the direct paymentMiddleware with the configured server
+  // Note: paymentMiddleware handles dynamic bazaar registration
+  return paymentMiddleware(
+    routes,
+    ResourceServer,
+    tabConfig,
+    paywallConfig,
+    paywall,
+    syncFacilitatorOnStart
+  )
+}
+
+export { ExpressAdapter } from './adapter.js'

package/src/server/facilitator.ts

@@ -0,0 +1,90 @@
+import { FacilitatorConfig, HTTPFacilitatorClient } from '@x402/core/server'
+import { Network, PaymentRequirements } from '@x402/core/types'
+
+const DEFAULT_FACILITATOR_URL = 'https://x402.4mica.xyz'
+
+export interface OpenTabRequest {
+  userAddress: string
+  recipientAddress: string
+  network?: Network
+  erc20Token?: string
+  ttlSeconds?: number
+}
+
+export interface OpenTabResponse {
+  tabId: string
+  userAddress: string
+  recipientAddress: string
+  assetAddress: string
+  startTimestamp: number
+  ttlSeconds: number
+  nextReqId: string
+}
+
+export class OpenTabError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly response: OpenTabResponse
+  ) {
+    super(`OpenTab failed with status ${status}`)
+    this.name = 'OpenTabError'
+  }
+}
+
+export class FourMicaFacilitatorClient extends HTTPFacilitatorClient {
+  constructor(config?: FacilitatorConfig) {
+    super({ ...config, url: config?.url ?? DEFAULT_FACILITATOR_URL })
+  }
+
+  async openTab(
+    userAddress: string,
+    paymentRequirements: PaymentRequirements,
+    ttlSeconds?: number
+  ): Promise<OpenTabResponse> {
+    let headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+
+    const authHeaders = await this.createAuthHeaders('tabs')
+    headers = { ...headers, ...authHeaders.headers }
+
+    const response = await fetch(`${this.url}/tabs`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(
+        this.safeJson({
+          userAddress,
+          recipientAddress: paymentRequirements.payTo,
+          network: paymentRequirements.network,
+          erc20Token: paymentRequirements.asset,
+          ttlSeconds,
+        })
+      ),
+    })
+
+    const data = await response.json()
+
+    if (typeof data === 'object' && data !== null && 'tabId' in data) {
+      const openTabResponse = data as OpenTabResponse
+      if (!response.ok) {
+        throw new OpenTabError(response.status, openTabResponse)
+      }
+      return openTabResponse
+    }
+
+    throw new Error(`Facilitator openTab failed (${response.status}): ${JSON.stringify(data)}`)
+  }
+
+  /**
+   * Helper to convert objects to JSON-safe format.
+   * Handles BigInt and other non-JSON types.
+   *
+   * @param obj - The object to convert
+   * @returns The JSON-safe representation of the object
+   */
+  private safeJson<T>(obj: T): T {
+    return JSON.parse(
+      JSON.stringify(obj, (_, value) => (typeof value === 'bigint' ? value.toString() : value))
+    )
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,10 @@
+export * from './facilitator.js'
+export * from './scheme.js'
+
+export { x402ResourceServer, x402HTTPResourceServer } from '@x402/core/server'
+
+export type { PaywallProvider, PaywallConfig } from '@x402/core/server'
+
+export { RouteConfigurationError } from '@x402/core/server'
+
+export type { RouteValidationError } from '@x402/core/server'