mppx 0.8.6 → 0.8.8

package/src/validation/core.ts

@@ -0,0 +1,374 @@
+import type { Chain } from 'viem'
+import * as viemChains from 'viem/chains'
+
+import { validateChallenge, validateErrorHandling } from '../cli/validate/challenge.js'
+import {
+  buildUrl,
+  extractEndpointsFromDiscovery,
+  extractRequestBodyFromDiscovery,
+  fetchDiscoveryDoc,
+} from '../cli/validate/discovery.js'
+import type { CheckResult, EndpointSpec, PathParameter } from '../cli/validate/helpers.js'
+import {
+  isValidIntegerAmount,
+  parseEndpointArg,
+  resolveBodyForEndpoint,
+} from '../cli/validate/helpers.js'
+import { validatePaymentFlow } from '../cli/validate/payment.js'
+import { validate as validateDiscoveryDoc } from '../discovery/Validate.js'
+
+export { buildUrl }
+export type { CheckResult, EndpointSpec, PathParameter }
+
+export type ValidateOptions = {
+  url: string
+  endpoint?: string | undefined
+  body?: string | undefined
+  query?: string[] | undefined
+  verbose?: boolean | undefined
+  yes?: boolean | undefined
+  skipPayment?: boolean | undefined
+  interactive?: boolean | undefined
+  discoveryPath?: string | undefined
+  onPaymentResults?: (results: CheckResult[]) => void
+}
+
+export type DiscoveryResult = {
+  found: boolean
+  valid: boolean
+  endpoints: EndpointSpec[]
+  checks: CheckResult[]
+  doc: Record<string, unknown> | null
+}
+
+export type EndpointValidationResult = {
+  method: string
+  path: string
+  challenge: CheckResult[]
+  errorHandling: CheckResult[]
+  payment: CheckResult[]
+}
+
+export type ValidateResult = {
+  url: string
+  discovery: DiscoveryResult
+  endpoints: EndpointValidationResult[]
+  summary: { passed: number; failed: number; warnings: number; skipped: number }
+  suggestions: string[]
+}
+
+export type ValidateEvent =
+  | { phase: 'discovery'; discovery: DiscoveryResult; results: CheckResult[] }
+  | { phase: 'endpoint'; endpoint: EndpointSpec }
+  | {
+      phase: 'challenge'
+      endpoint: EndpointSpec
+      results: CheckResult[]
+      isMpp: boolean
+      isTestnet: boolean
+      isMainnet: boolean
+      isNonMppPayment: boolean
+      isMalformedChallenge: boolean
+      methods: string[]
+    }
+  | { phase: 'errorHandling'; endpoint: EndpointSpec; results: CheckResult[] }
+  | {
+      phase: 'payment'
+      endpoint: EndpointSpec
+      results: CheckResult[]
+      succeeded: boolean
+      body?: string | undefined
+    }
+
+/** Streams validation results as each phase completes. */
+export async function* validateStream(options: ValidateOptions): AsyncGenerator<ValidateEvent> {
+  const baseUrl = options.url.replace(/\/$/, '').replace(/\/openapi\.json$/i, '')
+  const verbose = options.verbose ?? false
+
+  const discovery = await runDiscovery(baseUrl, options)
+  yield { phase: 'discovery', discovery, results: discovery.checks }
+
+  for (const endpoint of discovery.endpoints) {
+    yield { phase: 'endpoint', endpoint }
+
+    let body: string | undefined
+    if (options.endpoint) {
+      body = options.body
+    } else {
+      body = resolveBodyForEndpoint(options.body, endpoint.path)
+      if (!body && discovery.doc) {
+        body = extractRequestBodyFromDiscovery(discovery.doc, endpoint)
+      }
+    }
+
+    const {
+      results: challengeResults,
+      resolvedBody,
+      challenges: parsedChallenges,
+    } = await validateChallenge(baseUrl, endpoint, verbose, {
+      body,
+      query: options.query,
+      discoveryDoc: discovery.doc ?? undefined,
+    })
+    const effectiveBody = resolvedBody ?? body
+    const isMpp = challengeResults.some(
+      (r) => r.severity === 'pass' && r.label === 'Challenge parseable',
+    )
+    const chainIds = (parsedChallenges ?? [])
+      .filter((ch) => ch.method !== 'stripe')
+      .map((ch) => ((ch.request as Record<string, unknown>).methodDetails as any)?.chainId)
+      .filter((id): id is number => typeof id === 'number')
+    const isTestnet = chainIds.some(chainIsTestnet)
+    const isMainnet = chainIds.some((id) => !chainIsTestnet(id))
+    const isNonMppPayment =
+      !isMpp && challengeResults.some((r) => r.label === 'Not an MPP endpoint')
+    const hasPaymentScheme = challengeResults.some(
+      (r) => r.severity === 'pass' && r.label === 'WWW-Authenticate header present',
+    )
+    const challengeFailed = challengeResults.some(
+      (r) => r.severity === 'fail' && r.label === 'Challenge parseable',
+    )
+    const isMalformedChallenge = !isMpp && hasPaymentScheme && challengeFailed
+
+    const methods = parsedChallenges?.map((c) => c.method) ?? []
+
+    yield {
+      phase: 'challenge',
+      endpoint,
+      results: challengeResults,
+      isMpp,
+      isTestnet,
+      isMainnet,
+      isNonMppPayment,
+      isMalformedChallenge,
+      methods,
+    }
+
+    if (isMpp) {
+      const errorResults = await validateErrorHandling(baseUrl, endpoint, {
+        body: effectiveBody,
+        query: options.query,
+      })
+      yield { phase: 'errorHandling', endpoint, results: errorResults }
+
+      if (!options.skipPayment) {
+        const onResults = options.onPaymentResults
+        const paymentResults = await validatePaymentFlow(baseUrl, endpoint, verbose, {
+          body: effectiveBody,
+          query: options.query,
+          yes: options.yes,
+          silent: !onResults,
+          interactive: options.interactive,
+          ...(onResults && { onResults }),
+        })
+        const succeeded = paymentResults.some(
+          (r) => r.severity === 'pass' && r.label === 'Payment: successful',
+        )
+        yield { phase: 'payment', endpoint, results: paymentResults, succeeded }
+      }
+    }
+  }
+}
+
+/** Runs the full validation suite and returns all results as a batch. */
+export async function validate(options: ValidateOptions): Promise<ValidateResult> {
+  const baseUrl = options.url.replace(/\/$/, '').replace(/\/openapi\.json$/i, '')
+  let discovery: DiscoveryResult | undefined
+  const endpointResults: EndpointValidationResult[] = []
+  let current: EndpointValidationResult | undefined
+
+  let sawTestnet = false
+  let sawMainnet = false
+
+  for await (const event of validateStream(options)) {
+    switch (event.phase) {
+      case 'discovery':
+        discovery = event.discovery
+        break
+      case 'endpoint':
+        current = {
+          method: event.endpoint.method,
+          path: event.endpoint.path,
+          challenge: [],
+          errorHandling: [],
+          payment: [],
+        }
+        endpointResults.push(current)
+        break
+      case 'challenge':
+        if (current) current.challenge = event.results
+        if (event.isMpp) {
+          if (event.isTestnet) sawTestnet = true
+          if (event.isMainnet) sawMainnet = true
+        }
+        break
+      case 'errorHandling':
+        if (current) current.errorHandling = event.results
+        break
+      case 'payment':
+        if (current) current.payment = event.results
+        break
+    }
+  }
+
+  const summary = { passed: 0, failed: 0, warnings: 0, skipped: 0 }
+  if (discovery) {
+    for (const r of discovery.checks) {
+      if (r.severity === 'pass') summary.passed++
+      else if (r.severity === 'fail') summary.failed++
+      else if (r.severity === 'warn') summary.warnings++
+      else if (r.severity === 'skip') summary.skipped++
+    }
+  }
+  for (const ep of endpointResults) {
+    for (const r of [...ep.challenge, ...ep.errorHandling, ...ep.payment]) {
+      if (r.severity === 'pass') summary.passed++
+      else if (r.severity === 'fail') summary.failed++
+      else if (r.severity === 'warn') summary.warnings++
+      else if (r.severity === 'skip') summary.skipped++
+    }
+  }
+
+  if (!discovery) throw new Error('Discovery phase did not complete')
+
+  const suggestions = computeSuggestions(endpointResults, { sawTestnet, sawMainnet })
+
+  return {
+    url: baseUrl,
+    discovery,
+    endpoints: endpointResults,
+    summary,
+    suggestions,
+  }
+}
+
+function computeSuggestions(
+  endpoints: EndpointValidationResult[],
+  flags: { sawTestnet: boolean; sawMainnet: boolean },
+): string[] {
+  const steps: string[] = []
+  const allResults = endpoints.flatMap((ep) => [...ep.challenge, ...ep.payment])
+
+  const sawCryptoMainnet = flags.sawMainnet
+  const sawCryptoTestnet = flags.sawTestnet
+  const sawStripeLive = allResults.some(
+    (r) => r.label.includes('[stripe]') && r.label.includes('livemode'),
+  )
+
+  if (sawCryptoMainnet && !sawCryptoTestnet) {
+    steps.push(
+      'Validate your testnet server to test without real funds (Tempo wallets are automatically provisioned).',
+    )
+  } else if (sawCryptoTestnet && !sawCryptoMainnet) {
+    steps.push('Validate your mainnet server to confirm real payments work end-to-end.')
+  }
+  if (sawStripeLive) {
+    steps.push(
+      'Validate your testmode Stripe server to test card payments end-to-end (auto-pays with test card).',
+    )
+  }
+
+  return steps
+}
+
+const allChains = Object.values(viemChains) as Chain[]
+
+function chainIsTestnet(chainId: number): boolean {
+  return allChains.find((c) => c.id === chainId)?.testnet === true
+}
+
+async function runDiscovery(baseUrl: string, options: ValidateOptions): Promise<DiscoveryResult> {
+  const checks: CheckResult[] = []
+  let endpoints: EndpointSpec[] = []
+  let discoveryDoc: Record<string, unknown> | null = null
+  let found = false
+  let valid = false
+
+  // Try the user's path first, then root, then /api.
+  const origin = new URL(baseUrl).origin
+  let candidates: string[]
+  if (options.discoveryPath) {
+    candidates = [
+      new URL(options.discoveryPath, baseUrl + '/').href.replace(/\/openapi\.json$/i, ''),
+    ]
+  } else {
+    candidates = [baseUrl, origin, `${origin}/api`]
+    candidates = [...new Set(candidates)]
+  }
+  let discoveryResult: Awaited<ReturnType<typeof fetchDiscoveryDoc>> | undefined
+  const attemptedErrors: string[] = []
+  for (const candidate of candidates) {
+    discoveryResult = await fetchDiscoveryDoc(candidate)
+    if ('error' in discoveryResult) {
+      attemptedErrors.push(`${candidate}/openapi.json: ${discoveryResult.error}`)
+    } else {
+      break
+    }
+  }
+
+  if (!discoveryResult || 'error' in discoveryResult) {
+    checks.push({
+      label: 'Document found',
+      detail: attemptedErrors.join('; '),
+      hint: 'MPP servers must serve an OpenAPI document at /openapi.json with x-payment-info extensions.',
+      severity: 'fail',
+    })
+  } else {
+    found = true
+    checks.push({ label: 'Document found and parseable', severity: 'pass' })
+
+    const issues = validateDiscoveryDoc(discoveryResult.doc)
+    const errors = issues.filter((i) => i.severity === 'error')
+    const warnings = issues.filter((i) => i.severity === 'warning')
+
+    if (errors.length > 0) {
+      checks.push({
+        label: 'Valid OpenAPI structure',
+        detail: `${errors.length} error(s)`,
+        severity: 'fail',
+      })
+      for (const e of errors) {
+        checks.push({ label: e.message, detail: e.path, severity: 'fail' })
+      }
+    } else {
+      valid = true
+      checks.push({ label: 'Valid OpenAPI structure', severity: 'pass' })
+    }
+
+    for (const w of warnings) {
+      checks.push({ label: w.message, detail: w.path, severity: 'warn' })
+    }
+
+    discoveryDoc = discoveryResult.doc as Record<string, unknown>
+  }
+
+  if (options.endpoint) {
+    const parsed = parseEndpointArg(options.endpoint)
+    if (parsed) endpoints.push(parsed)
+  } else if (discoveryDoc) {
+    endpoints = extractEndpointsFromDiscovery(discoveryDoc)
+
+    const NO_AMOUNT = BigInt('999999999999999999')
+    endpoints.sort((a, b) => {
+      const aAmt = isValidIntegerAmount(a.amount) ? BigInt(a.amount!) : NO_AMOUNT
+      const bAmt = isValidIntegerAmount(b.amount) ? BigInt(b.amount!) : NO_AMOUNT
+      return aAmt < bAmt ? -1 : aAmt > bAmt ? 1 : 0
+    })
+
+    if (endpoints.length > 0) {
+      checks.push({
+        label: 'Paid endpoints found',
+        detail: `${endpoints.length} endpoint(s)`,
+        severity: 'pass',
+      })
+    } else {
+      checks.push({
+        label: 'Paid endpoints found',
+        detail: 'No endpoints with x-payment-info',
+        severity: 'warn',
+      })
+    }
+  }
+
+  return { found, valid, endpoints, checks, doc: discoveryDoc }
+}

package/src/validation/index.ts

@@ -0,0 +1,11 @@
+export { buildUrl, validate, validateStream } from './core.js'
+export type {
+  CheckResult,
+  DiscoveryResult,
+  EndpointSpec,
+  EndpointValidationResult,
+  PathParameter,
+  ValidateEvent,
+  ValidateOptions,
+  ValidateResult,
+} from './core.js'

package/src/x402/Assets.test.ts

@@ -208,4 +208,46 @@ describe('x402 assets', () => {
       },
     })
   })
+
+  test('exports Celo USDC metadata', () => {
+    expect(Assets.isAsset(Assets.celo.USDC)).toBe(true)
+    expect(Assets.celo.USDC).toMatchObject({
+      address: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
+      decimals: 6,
+      network: 'eip155:42220',
+      transfer: {
+        name: 'USDC',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+
+  test('exports Celo USDT metadata', () => {
+    expect(Assets.isAsset(Assets.celo.USDT)).toBe(true)
+    expect(Assets.celo.USDT).toMatchObject({
+      address: '0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e',
+      decimals: 6,
+      network: 'eip155:42220',
+      transfer: {
+        name: 'Tether USD',
+        type: 'eip3009',
+        version: '1',
+      },
+    })
+  })
+
+  test('exports Celo Sepolia USDC metadata', () => {
+    expect(Assets.isAsset(Assets.celoSepolia.USDC)).toBe(true)
+    expect(Assets.celoSepolia.USDC).toMatchObject({
+      address: '0x01C5C0122039549AD1493B8220cABEdD739BC44E',
+      decimals: 6,
+      network: 'eip155:11142220',
+      transfer: {
+        name: 'USDC',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
 })

package/src/x402/Assets.ts

@@ -91,6 +91,46 @@ export const baseSepolia = {
   }),
 } as const
 
+/** Celo network known assets. */
+export const celo = {
+  USDC: define({
+    address: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C',
+    decimals: 6,
+    network: 'eip155:42220',
+    transfer: {
+      // Celo USDC signs with the shorter EIP-712 domain name.
+      name: 'USDC',
+      type: 'eip3009',
+      version: '2',
+    },
+  }),
+  USDT: define({
+    address: '0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e',
+    decimals: 6,
+    network: 'eip155:42220',
+    transfer: {
+      // Celo USDT signs with domain version "1", unlike Circle's FiatToken "2".
+      name: 'Tether USD',
+      type: 'eip3009',
+      version: '1',
+    },
+  }),
+} as const
+
+/** Celo Sepolia known assets. */
+export const celoSepolia = {
+  USDC: define({
+    address: '0x01C5C0122039549AD1493B8220cABEdD739BC44E',
+    decimals: 6,
+    network: 'eip155:11142220',
+    transfer: {
+      name: 'USDC',
+      type: 'eip3009',
+      version: '2',
+    },
+  }),
+} as const
+
 /** Returns true when a value is known x402 asset metadata. */
 export function isAsset(value: unknown): value is KnownAsset {
   if (typeof value !== 'object' || value === null) return false