mppx 0.8.17 → 0.8.19

package/src/cli/validate/challenge.ts

@@ -1,565 +0,0 @@
-import type { Chain } from 'viem'
-import * as viemChains from 'viem/chains'
-
-import * as Challenge from '../../Challenge.js'
-import * as Constants from '../../Constants.js'
-import * as x402Header from '../../x402/Header.js'
-import { pc } from '../utils.js'
-import { buildUrl, extractRequestBodyFromDiscovery } from './discovery.js'
-import type { CheckResult, EndpointSpec } from './helpers.js'
-import {
-  check,
-  fail,
-  fetchWithTimeout,
-  isValidAddress,
-  isValidIntegerAmount,
-  parseHeaders,
-  skip,
-  warn,
-} from './helpers.js'
-
-const allChains = Object.values(viemChains) as Chain[]
-
-function detectTestnet(challenge: Challenge.Challenge): boolean {
-  const request = challenge.request as Record<string, unknown>
-  const md = request.methodDetails as Record<string, unknown> | undefined
-  if (typeof md?.chainId !== 'number') return false
-  return allChains.find((c) => c.id === md.chainId)?.testnet === true
-}
-
-export async function validateChallenge(
-  baseUrl: string,
-  endpoint: EndpointSpec,
-  verbose: boolean,
-  options?: {
-    body?: string | undefined
-    bodyIsAutogenerated?: boolean | undefined
-    query?: string[] | undefined
-    extraHeaders?: string[] | undefined
-    discoveryDoc?: Record<string, unknown> | undefined
-  },
-): Promise<{
-  results: CheckResult[]
-  resolvedBody?: string | undefined
-  challenges?: Challenge.Challenge[] | undefined
-}> {
-  const results: CheckResult[] = []
-  const url = buildUrl(baseUrl, endpoint, options?.query)
-  const fetchHeaders: Record<string, string> = parseHeaders(options?.extraHeaders)
-  let fetchBody: string | undefined
-
-  // If the user explicitly provided a body, include it on the first request
-  if (options?.body && !options.bodyIsAutogenerated) {
-    fetchBody = options.body
-    if (!fetchHeaders['content-type']) fetchHeaders['content-type'] = 'application/json'
-  }
-
-  let response: Response
-  try {
-    const init: RequestInit = { method: endpoint.method }
-    if (Object.keys(fetchHeaders).length > 0) init.headers = fetchHeaders
-    if (fetchBody) init.body = fetchBody
-    response = await fetchWithTimeout(url, init)
-  } catch (error) {
-    results.push(fail('Request failed', (error as Error).message))
-    return { results }
-  }
-
-  // If we got 400/422, retry with body (explicit --body or auto-generated from schema)
-  if (!fetchBody && (response.status === 400 || response.status === 422)) {
-    const bodyToTry =
-      options?.body ??
-      (options?.discoveryDoc
-        ? extractRequestBodyFromDiscovery(options.discoveryDoc, endpoint)
-        : undefined)
-    if (bodyToTry) {
-      if (verbose) console.log(pc.dim(`  Retrying with body: ${bodyToTry}`))
-      fetchBody = bodyToTry
-      fetchHeaders['content-type'] = 'application/json'
-      try {
-        response = await fetchWithTimeout(url, {
-          method: endpoint.method,
-          headers: fetchHeaders,
-          body: fetchBody,
-        })
-      } catch (error) {
-        results.push(fail('Request failed', (error as Error).message))
-        return { results }
-      }
-    }
-  }
-
-  // Check 402
-  if (response.status !== 402) {
-    if (response.status === 200) {
-      results.push(
-        skip(
-          'Returns 402 without credentials',
-          'Got 200 (endpoint may not require payment in all cases)',
-        ),
-      )
-    } else if (response.status === 401 || response.status === 403) {
-      results.push(
-        skip(
-          'Returns 402 without credentials',
-          `Got ${response.status} (endpoint requires auth before payment gate)`,
-        ),
-      )
-    } else {
-      results.push(
-        fail(
-          'Returns 402 without credentials',
-          `Got ${response.status} instead`,
-          response.status === 400 || response.status === 422
-            ? 'Server requires a valid request body before returning 402. Add a requestBody schema with examples to your OpenAPI doc, or use --body.'
-            : 'Endpoints that require payment must return HTTP 402 with a WWW-Authenticate: Payment header when no valid credential is provided.',
-        ),
-      )
-    }
-    return { results }
-  }
-  results.push(check('Returns 402 without credentials'))
-
-  // Check WWW-Authenticate header
-  const wwwAuth = response.headers.get(Constants.Headers.wwwAuthenticate)
-  const x402Results = checkX402Headers(response)
-  if (!wwwAuth) {
-    if (x402Results.length > 0) {
-      results.push(
-        skip('Not an MPP endpoint', 'No WWW-Authenticate header — x402 protocol detected'),
-      )
-      results.push(...x402Results)
-    } else {
-      results.push(
-        skip('Not an MPP endpoint', 'No WWW-Authenticate header (may be x402 or other protocol)'),
-      )
-    }
-    return { results }
-  }
-  if (x402Results.length > 0) results.push(...x402Results)
-  if (!wwwAuth.startsWith(`${Constants.Schemes.payment} `)) {
-    results.push(skip('Not an MPP endpoint', `WWW-Authenticate scheme is not Payment`))
-    return { results }
-  }
-  results.push(check('WWW-Authenticate header present', 'Payment scheme'))
-
-  // Parse all challenges
-  let challenges: Challenge.Challenge[]
-  try {
-    challenges = Challenge.fromResponseList(response)
-  } catch (error) {
-    const msg = (error as Error).message
-    results.push(
-      fail(
-        'Challenge parseable',
-        msg,
-        'The Payment challenge must include a request="<base64url>" parameter containing JSON-encoded payment details.',
-      ),
-    )
-    const rawParams = wwwAuth.slice(wwwAuth.indexOf(' ') + 1)
-    results.push(
-      warn('Received', rawParams.length > 200 ? rawParams.slice(0, 200) + '...' : rawParams),
-    )
-    return { results }
-  }
-
-  if (challenges.length === 0) {
-    results.push(fail('Challenge parseable', 'No Payment challenges found in header'))
-    return { results }
-  }
-
-  const methodList = challenges.map((c) => `${c.method}/${c.intent}`).join(', ')
-  results.push(
-    check(
-      'Challenge parseable',
-      challenges.length === 1 ? methodList : `${challenges.length} methods: ${methodList}`,
-    ),
-  )
-
-  // Validate common fields across all challenges
-  const serverHost = new URL(baseUrl).hostname
-  validateIds(challenges, results)
-  validateRealms(challenges, results)
-  validateExpiration(challenges, results)
-  validateRealmMatchesHost(challenges, serverHost, results)
-
-  // Method-specific validation
-  const hasMultipleMethods = challenges.length > 1
-  for (const ch of challenges) {
-    const request = ch.request as Record<string, unknown>
-    validateMethodFields(ch, request, results, hasMultipleMethods)
-  }
-
-  if (verbose) {
-    for (const ch of challenges) {
-      console.log(
-        pc.dim(`    Challenge (${ch.method}/${ch.intent}): ${JSON.stringify(ch, null, 2)}`),
-      )
-    }
-  }
-
-  return { results, resolvedBody: fetchBody, challenges }
-}
-
-function validateIds(challenges: Challenge.Challenge[], results: CheckResult[]): void {
-  const missing = challenges.filter((ch) => !ch.id)
-  if (missing.length === 0) {
-    results.push(check('Challenge has id'))
-  } else {
-    results.push(
-      fail(
-        'Challenge has id',
-        `${missing.length} missing`,
-        'Every challenge must include a unique id field.',
-      ),
-    )
-  }
-}
-
-function validateRealms(challenges: Challenge.Challenge[], results: CheckResult[]): void {
-  const missing = challenges.filter((ch) => !ch.realm)
-  if (missing.length === 0) {
-    results.push(check('Challenge has realm'))
-  } else {
-    results.push(
-      fail(
-        'Challenge has realm',
-        `${missing.length} missing`,
-        "Set realm to your server's hostname.",
-      ),
-    )
-  }
-}
-
-function validateExpiration(challenges: Challenge.Challenge[], results: CheckResult[]): void {
-  const now = new Date()
-  for (const ch of challenges) {
-    if (!ch.expires) {
-      results.push(
-        warn(
-          'Challenge has expiration',
-          'missing expires field',
-          'Add an expires field (ISO 8601) to prevent replay attacks.',
-        ),
-      )
-      return
-    }
-    if (new Date(ch.expires) <= now) {
-      results.push(
-        fail(
-          'Challenge expires in the future',
-          `Expired at ${ch.expires}`,
-          'The expires timestamp must be in the future.',
-        ),
-      )
-      return
-    }
-  }
-  const soonest = Math.min(
-    ...challenges.map((ch) => new Date(ch.expires!).getTime() - now.getTime()),
-  )
-  results.push(check('Challenge expires in the future', `${Math.round(soonest / 60000)}m from now`))
-}
-
-function validateRealmMatchesHost(
-  challenges: Challenge.Challenge[],
-  serverHost: string,
-  results: CheckResult[],
-): void {
-  const realms = [...new Set(challenges.map((ch) => ch.realm ?? ''))]
-  const badRealms = realms.filter((r) => r && r !== serverHost && !serverHost.endsWith(`.${r}`))
-  if (badRealms.length > 0) {
-    results.push(
-      warn(
-        'Realm matches server hostname',
-        `realm="${badRealms[0]}" vs host="${serverHost}"`,
-        'Set the realm to your production hostname (or base domain) in the challenge.',
-      ),
-    )
-  } else {
-    results.push(check('Realm matches server hostname'))
-  }
-}
-
-function validateMethodFields(
-  challenge: Challenge.Challenge,
-  request: Record<string, unknown>,
-  results: CheckResult[],
-  hasMultipleMethods: boolean,
-): void {
-  const tag = hasMultipleMethods ? `[${challenge.method}] ` : ''
-
-  if (challenge.method === Constants.Methods.tempo)
-    validateTempoFields(request, tag, results, challenge)
-  else if (challenge.method === Constants.Methods.stripe)
-    validateStripeFields(request, tag, results)
-  else if (challenge.method === Constants.Methods.evm)
-    validateEvmFields(challenge, request, tag, results)
-}
-
-function validateTempoFields(
-  request: Record<string, unknown>,
-  tag: string,
-  results: CheckResult[],
-  challenge: Challenge.Challenge,
-): void {
-  const methodDetails = request.methodDetails as Record<string, unknown> | undefined
-  const hasSplits = Array.isArray(methodDetails?.splits) && methodDetails.splits.length > 0
-
-  if (isValidAddress(request.recipient)) {
-    results.push(check(`${tag}Valid recipient address`))
-  } else if (request.recipient === undefined && hasSplits) {
-    results.push(check(`${tag}Uses splits (no single recipient)`))
-  } else if (request.recipient === undefined) {
-    results.push(
-      fail(
-        `${tag}Valid recipient address`,
-        'Missing recipient (and no splits defined)',
-        'Set request.recipient to a valid 0x address, or use methodDetails.splits for multiple recipients.',
-      ),
-    )
-  } else {
-    results.push(
-      fail(
-        `${tag}Valid recipient address`,
-        `Got: ${String(request.recipient)}`,
-        'Set request.recipient to a valid 0x-prefixed 40-hex-char address.',
-      ),
-    )
-  }
-
-  if (isValidAddress(request.currency)) {
-    const network = detectTestnet(challenge) ? 'testnet' : 'mainnet'
-    results.push(check(`${tag}Valid currency address`, network))
-  } else {
-    results.push(
-      fail(
-        `${tag}Valid currency address`,
-        `Got: ${String(request.currency)}`,
-        'Set request.currency to a valid token address.',
-      ),
-    )
-  }
-
-  validateAmount(
-    request,
-    tag,
-    results,
-    'token\'s smallest unit (e.g. "10000" = $0.01 for 6-decimal tokens)',
-  )
-}
-
-function validateStripeFields(
-  request: Record<string, unknown>,
-  tag: string,
-  results: CheckResult[],
-): void {
-  validateAmount(request, tag, results, 'currency\'s smallest unit (e.g. "100" = $1.00 for USD)')
-
-  const currency = request.currency as string | undefined
-  const validCurrency = typeof currency === 'string' && /^[a-z]{3}$/i.test(currency)
-  if (validCurrency) {
-    results.push(check(`${tag}Valid currency code`, currency.toUpperCase()))
-  } else {
-    results.push(
-      fail(
-        `${tag}Valid currency code`,
-        currency ? `Got: ${currency}` : 'missing',
-        'Must be a three-letter ISO currency code (e.g. "usd").',
-      ),
-    )
-  }
-
-  const methodDetails = request.methodDetails as Record<string, unknown> | undefined
-  const networkId = methodDetails?.networkId as string | undefined
-  if (networkId) {
-    results.push(check(`${tag}Has networkId`, networkId.slice(0, 20)))
-  } else {
-    results.push(
-      fail(
-        `${tag}Has networkId`,
-        'Missing methodDetails.networkId',
-        'Set methodDetails.networkId to your Stripe Business Network profile ID.',
-      ),
-    )
-  }
-
-  const pmTypes = methodDetails?.paymentMethodTypes as string[] | undefined
-  if (Array.isArray(pmTypes) && pmTypes.length > 0) {
-    results.push(check(`${tag}Has paymentMethodTypes`, pmTypes.join(', ')))
-  } else {
-    results.push(
-      fail(
-        `${tag}Has paymentMethodTypes`,
-        'Missing or empty',
-        'Set methodDetails.paymentMethodTypes to an array (e.g. ["card"]).',
-      ),
-    )
-  }
-}
-
-function validateEvmFields(
-  challenge: Challenge.Challenge,
-  request: Record<string, unknown>,
-  tag: string,
-  results: CheckResult[],
-): void {
-  if (isValidAddress(request.recipient)) {
-    results.push(check(`${tag}Valid recipient address`))
-  } else {
-    results.push(
-      fail(
-        `${tag}Valid recipient address`,
-        `Got: ${String(request.recipient)}`,
-        'Set request.recipient to a valid 0x-prefixed Ethereum address.',
-      ),
-    )
-  }
-
-  if (isValidAddress(request.currency)) {
-    const network = detectTestnet(challenge) ? 'testnet' : 'mainnet'
-    results.push(check(`${tag}Valid currency address`, network))
-  } else {
-    results.push(
-      fail(
-        `${tag}Valid currency address`,
-        `Got: ${String(request.currency)}`,
-        'Set request.currency to a valid ERC-20 token contract address.',
-      ),
-    )
-  }
-
-  validateAmount(request, tag, results, "token's smallest unit")
-
-  const methodDetails = request.methodDetails as Record<string, unknown> | undefined
-  const chainId = methodDetails?.chainId as number | undefined
-  if (typeof chainId === 'number' && chainId > 0) {
-    results.push(check(`${tag}Has chainId`, String(chainId)))
-  } else {
-    results.push(
-      fail(
-        `${tag}Has chainId`,
-        'Missing methodDetails.chainId',
-        'Set methodDetails.chainId to the EVM chain ID.',
-      ),
-    )
-  }
-}
-
-function validateAmount(
-  request: Record<string, unknown>,
-  tag: string,
-  results: CheckResult[],
-  unitHint: string,
-): void {
-  if (isValidIntegerAmount(request.amount)) {
-    results.push(check(`${tag}Amount is valid integer string`))
-  } else if (request.amount === undefined || request.amount === null) {
-    results.push(
-      fail(
-        `${tag}Amount is valid integer string`,
-        'Missing amount',
-        `Set request.amount to a string of digits in the ${unitHint}.`,
-      ),
-    )
-  } else {
-    results.push(
-      fail(
-        `${tag}Amount is valid integer string`,
-        `Got: ${String(request.amount)}`,
-        'request.amount must be a string of digits (no decimals, no prefix).',
-      ),
-    )
-  }
-}
-
-export async function validateErrorHandling(
-  baseUrl: string,
-  endpoint: EndpointSpec,
-  options?: { body?: string | undefined; query?: string[] | undefined },
-): Promise<CheckResult[]> {
-  const results: CheckResult[] = []
-  const url = buildUrl(baseUrl, endpoint, options?.query)
-  const fetchHeaders: Record<string, string> = {
-    [Constants.Headers.authorization]: `${Constants.Schemes.payment} dGhpcyBpcyBnYXJiYWdl`,
-  }
-  let fetchBody: string | undefined
-  if (options?.body) {
-    fetchBody = options.body
-    fetchHeaders['content-type'] = 'application/json'
-  }
-
-  try {
-    const response = await fetchWithTimeout(url, {
-      method: endpoint.method,
-      headers: fetchHeaders,
-      body: fetchBody ?? null,
-    })
-
-    if (response.status === 402) {
-      results.push(check('Malformed credential returns 402', 'not 500'))
-      const wwwAuth = response.headers.get(Constants.Headers.wwwAuthenticate)
-      if (wwwAuth?.startsWith(`${Constants.Schemes.payment} `)) {
-        results.push(check('Error response includes fresh challenge'))
-      } else {
-        results.push(
-          warn(
-            'Error response includes fresh challenge',
-            'No WWW-Authenticate header',
-            'When rejecting an invalid credential, respond with 402 and include a fresh WWW-Authenticate: Payment challenge so the client can retry.',
-          ),
-        )
-      }
-    } else if (response.status >= 500) {
-      results.push(
-        fail(
-          'Malformed credential returns 402',
-          `Got ${response.status} (server error)`,
-          'When the Authorization header contains an invalid credential, respond with 402 (not 500). Catch credential validation errors and return a fresh challenge.',
-        ),
-      )
-    } else {
-      results.push(
-        warn(
-          'Malformed credential returns 402',
-          `Got ${response.status}`,
-          `When the Authorization header contains an invalid Payment credential, respond with 402 and a fresh WWW-Authenticate challenge. Returning ${response.status} prevents the client from retrying with a valid payment.`,
-        ),
-      )
-    }
-  } catch (error) {
-    results.push(fail('Error handling test', (error as Error).message))
-  }
-
-  return results
-}
-
-function checkX402Headers(response: Response): CheckResult[] {
-  const results: CheckResult[] = []
-  const paymentRequiredRaw =
-    response.headers.get('payment-required') ?? response.headers.get('x-payment-required')
-  if (!paymentRequiredRaw) return results
-
-  const headerName = response.headers.get('payment-required')
-    ? 'PAYMENT-REQUIRED'
-    : 'X-Payment-Required'
-
-  try {
-    const decoded = x402Header.decodePaymentRequiredEnvelope(paymentRequiredRaw)
-    results.push(
-      check(
-        'x402 payment challenge',
-        `${headerName} with valid x402 v${decoded.x402Version} payload`,
-      ),
-    )
-  } catch {
-    results.push(
-      warn(
-        'x402 payment challenge',
-        `${headerName} header present but failed schema validation`,
-        'Ensure the PAYMENT-REQUIRED header contains a valid base64-encoded JSON payload matching the x402 schema.',
-      ),
-    )
-  }
-  return results
-}