@4mica/x402 1.2.4 → 2.0.0-alpha.2

package/src/server/express/index.ts

@@ -1,499 +0,0 @@
-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
-}
-
-interface ResourceServerInternals {
-  register: (network: Network, server: SchemeNetworkServer) => unknown
-  hasExtension: (extension: string) => boolean
-  registerExtension: (extension: unknown) => unknown
-}
-
-interface HTTPServerInternals {
-  ResourceServer: ResourceServerInternals
-  routesConfig: RoutesConfig
-}
-
-function getHTTPServerInternals(httpServer: x402HTTPResourceServer): HTTPServerInternals {
-  return httpServer as unknown as HTTPServerInternals
-}
-
-function registerNetworkServers(httpServer: x402HTTPResourceServer, tabEndpoint: string) {
-  const schemeServer = new FourMicaEvmScheme(tabEndpoint)
-  const server = getHTTPServerInternals(httpServer)
-  SUPPORTED_NETWORKS.forEach((network) => {
-    server.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)
-  })
-}
-
-interface OpenTabHttpError {
-  status: number
-  response: unknown
-}
-
-function isOpenTabHttpError(error: unknown): error is OpenTabHttpError {
-  if (typeof error !== 'object' || error === null) {
-    return false
-  }
-
-  const candidate = error as { status?: unknown; response?: unknown }
-  return typeof candidate.status === 'number' && 'response' in candidate
-}
-
-/**
- * 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
-  const httpServerInternals = getHTTPServerInternals(httpServer)
-  if (
-    checkIfBazaarNeeded(httpServerInternals.routesConfig) &&
-    !httpServerInternals.ResourceServer.hasExtension('bazaar')
-  ) {
-    bazaarPromise = import('@x402/extensions/bazaar')
-      .then(({ bazaarResourceServerExtension }) => {
-        httpServerInternals.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, x402Version } = req.body
-
-        try {
-          // Call the facilitator to open the tab
-          const openTabResponse = await facilitatorClient.openTab(
-            userAddress,
-            paymentRequirements,
-            tabConfig.ttlSeconds,
-            x402Version
-          )
-
-          // Return the response
-          return res.json(openTabResponse)
-        } catch (error) {
-          if (isOpenTabHttpError(error)) {
-            return res.status(error.status).json(error.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

@@ -1,206 +0,0 @@
-import { FacilitatorConfig, HTTPFacilitatorClient } from '@x402/core/server'
-import { Network, PaymentPayload, PaymentRequirements, SettleResponse } 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 interface CertificateResponse {
-  claims: string
-  signature: string
-}
-
-export type FourMicaSettleResponse = SettleResponse & {
-  certificate?: CertificateResponse
-  txHash?: string
-  networkId?: string
-  error?: 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,
-    guaranteeVersion?: 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,
-          guaranteeVersion: guaranteeVersion ?? 1,
-        })
-      ),
-    })
-
-    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)}`)
-  }
-
-  async settle(
-    paymentPayload: PaymentPayload,
-    paymentRequirements: PaymentRequirements
-  ): Promise<FourMicaSettleResponse> {
-    let headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-    }
-
-    const authHeaders = await this.createAuthHeaders('settle')
-    headers = { ...headers, ...authHeaders.headers }
-
-    const response = await fetch(`${this.url}/settle`, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(
-        this.safeJson({
-          x402Version: paymentPayload.x402Version,
-          paymentPayload,
-          paymentRequirements,
-        })
-      ),
-    })
-
-    const data = (await response.json()) as Record<string, unknown>
-    const normalized = normalizeSettleResponse(data, paymentRequirements)
-
-    if (!response.ok || !normalized.success) {
-      throw new Error(
-        `Facilitator settle failed (${response.status}): ${normalized.errorReason ?? normalized.error ?? 'unknown error'}`
-      )
-    }
-
-    return normalized
-  }
-
-  /**
-   * 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))
-    )
-  }
-}
-
-function normalizeSettleResponse(
-  payload: Record<string, unknown>,
-  requirements: PaymentRequirements
-): FourMicaSettleResponse {
-  const transaction = String(
-    payload.transaction ??
-      payload.transactionHash ??
-      payload.txHash ??
-      payload.tx_hash ??
-      payload.hash ??
-      ''
-  )
-  const network = String(
-    payload.network ?? payload.networkId ?? payload.network_id ?? requirements.network
-  ) as Network
-  const errorReason =
-    typeof payload.errorReason === 'string'
-      ? payload.errorReason
-      : typeof payload.error_reason === 'string'
-        ? payload.error_reason
-        : typeof payload.error === 'string'
-          ? payload.error
-          : typeof payload.message === 'string'
-            ? payload.message
-            : undefined
-
-  const certificate =
-    payload.certificate &&
-    typeof payload.certificate === 'object' &&
-    typeof (payload.certificate as Record<string, unknown>).claims === 'string' &&
-    typeof (payload.certificate as Record<string, unknown>).signature === 'string'
-      ? {
-          claims: (payload.certificate as Record<string, string>).claims,
-          signature: (payload.certificate as Record<string, string>).signature,
-        }
-      : undefined
-
-  return {
-    success: Boolean(payload.success ?? errorReason === undefined),
-    errorReason,
-    payer:
-      typeof payload.payer === 'string'
-        ? payload.payer
-        : typeof payload.userAddress === 'string'
-          ? payload.userAddress
-          : typeof payload.user_address === 'string'
-            ? payload.user_address
-            : undefined,
-    transaction,
-    network,
-    certificate,
-    txHash:
-      typeof payload.txHash === 'string'
-        ? payload.txHash
-        : typeof payload.tx_hash === 'string'
-          ? payload.tx_hash
-          : transaction || undefined,
-    networkId:
-      typeof payload.networkId === 'string'
-        ? payload.networkId
-        : typeof payload.network_id === 'string'
-          ? payload.network_id
-          : network,
-    error: typeof payload.error === 'string' ? payload.error : undefined,
-  }
-}