mppx 0.8.2 → 0.8.4

package/src/cli/validate/challenge.ts

@@ -0,0 +1,335 @@
+import * as Challenge from '../../Challenge.js'
+import * as Constants from '../../Constants.js'
+import { chainId as tempoChainIds } from '../../tempo/internal/defaults.js'
+import { pc } from '../utils.js'
+import { extractRequestBodyFromDiscovery } from './discovery.js'
+import type { CheckResult, EndpointSpec } from './helpers.js'
+import {
+  buildUrl,
+  check,
+  fail,
+  fetchWithTimeout,
+  isValidAddress,
+  isValidIntegerAmount,
+  skip,
+  warn,
+} from './helpers.js'
+
+function detectTestnet(challenge: Challenge.Challenge): boolean {
+  const request = challenge.request as Record<string, unknown>
+  const methodDetails = request.methodDetails as Record<string, unknown> | undefined
+  if (typeof methodDetails?.chainId === 'number') {
+    return methodDetails.chainId !== tempoChainIds.mainnet
+  }
+  return false
+}
+
+export async function validateChallenge(
+  baseUrl: string,
+  endpoint: EndpointSpec,
+  verbose: boolean,
+  options?: {
+    body?: string | undefined
+    query?: string[] | undefined
+    discoveryDoc?: Record<string, unknown> | undefined
+  },
+): Promise<{ results: CheckResult[]; resolvedBody?: string | undefined }> {
+  const results: CheckResult[] = []
+  const url = buildUrl(baseUrl, endpoint, options?.query)
+  const fetchHeaders: Record<string, string> = {}
+  let fetchBody: string | undefined
+
+  // Make bare unauthenticated request first (no body)
+  let response: Response
+  try {
+    response = await fetchWithTimeout(url, { method: endpoint.method })
+  } catch (error) {
+    results.push(fail('Request failed', (error as Error).message))
+    return { results }
+  }
+
+  // If we got 400, retry with body (explicit --body or auto-generated from schema)
+  if (response.status === 400) {
+    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
+            ? '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)
+  if (!wwwAuth) {
+    results.push(
+      skip('Not an MPP endpoint', 'No WWW-Authenticate header (may be x402 or other protocol)'),
+    )
+    return { results }
+  }
+  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 challenge
+  let challenge: Challenge.Challenge
+  try {
+    challenge = Challenge.fromResponse(response)
+  } catch (error) {
+    results.push(fail('Challenge parseable', (error as Error).message))
+    return { results }
+  }
+  results.push(check('Challenge parseable', `${challenge.method}/${challenge.intent}`))
+
+  // Validate required fields
+  if (!challenge.id)
+    results.push(
+      fail(
+        'Challenge has id',
+        undefined,
+        'Every challenge must include a unique id field. Generate a random string or hash per challenge.',
+      ),
+    )
+  else results.push(check('Challenge has id'))
+
+  if (!challenge.realm)
+    results.push(
+      fail(
+        'Challenge has realm',
+        undefined,
+        "Set realm to your server's hostname. It tells clients who they are paying.",
+      ),
+    )
+  else results.push(check('Challenge has realm'))
+
+  if (!challenge.method)
+    results.push(
+      fail(
+        'Challenge has method',
+        undefined,
+        'Set method to the payment method (e.g. "tempo", "stripe").',
+      ),
+    )
+  if (!challenge.intent)
+    results.push(
+      fail(
+        'Challenge has intent',
+        undefined,
+        'Set intent to the payment type (e.g. "charge", "session").',
+      ),
+    )
+
+  // Semantic checks
+  if (challenge.expires) {
+    const expiresDate = new Date(challenge.expires)
+    const now = new Date()
+    if (expiresDate <= now) {
+      results.push(
+        fail(
+          'Challenge expires in the future',
+          `Expired at ${challenge.expires}`,
+          'The expires timestamp must be in the future when the challenge is issued. Use a 5-10 minute window from the current time.',
+        ),
+      )
+    } else {
+      const diffMs = expiresDate.getTime() - now.getTime()
+      const diffMin = Math.round(diffMs / 60000)
+      results.push(check('Challenge expires in the future', `${diffMin}m from now`))
+    }
+  } else {
+    results.push(
+      warn(
+        'Challenge has expiration',
+        'No expires field set',
+        'Add an expires field (ISO 8601 datetime) to prevent replay attacks. Recommended: 5 minutes from issuance.',
+      ),
+    )
+  }
+
+  // Realm check (allow subdomain matches)
+  try {
+    const serverHost = new URL(baseUrl).hostname
+    const realm = challenge.realm ?? ''
+    const matches = serverHost === realm || serverHost.endsWith(`.${realm}`)
+    if (matches) {
+      results.push(check('Realm matches server hostname'))
+    } else {
+      results.push(
+        warn(
+          'Realm matches server hostname',
+          `realm="${realm}" vs host="${serverHost}"`,
+          'Set the realm to your production hostname (or base domain) in the challenge. Clients use realm to verify they are paying the right server.',
+        ),
+      )
+    }
+  } catch {}
+
+  // Method-specific validation
+  const request = challenge.request as Record<string, unknown>
+  if (challenge.method === Constants.Methods.tempo) {
+    if (isValidAddress(request.recipient)) {
+      results.push(check('Valid recipient address'))
+    } else {
+      results.push(
+        fail(
+          'Valid recipient address',
+          `Got: ${String(request.recipient)}`,
+          'Set request.recipient to a valid 0x-prefixed 40-hex-char address. This is where payment will be sent.',
+        ),
+      )
+    }
+
+    if (isValidAddress(request.currency)) {
+      const isTestnet = detectTestnet(challenge)
+      const network = isTestnet ? 'testnet' : 'mainnet'
+      results.push(check('Valid currency address', `${network}`))
+    } else {
+      results.push(
+        fail(
+          'Valid currency address',
+          `Got: ${String(request.currency)}`,
+          'Set request.currency to a valid token address. Common: "0x20c0000000000000000000000000000000000000" (PathUSD).',
+        ),
+      )
+    }
+
+    if (isValidIntegerAmount(request.amount)) {
+      results.push(check('Amount is valid integer string'))
+    } else if (request.amount === undefined || request.amount === null) {
+      results.push(
+        warn(
+          'Amount is valid integer string',
+          'No amount (dynamic pricing?)',
+          'Set request.amount to a string of digits in the token\'s smallest unit (e.g. "10000" = $0.01 for 6-decimal tokens).',
+        ),
+      )
+    } else {
+      results.push(
+        fail(
+          'Amount is valid integer string',
+          `Got: ${String(request.amount)}`,
+          'request.amount must be a string of digits (no decimals, no prefix). Example: "10000" for $0.01 with 6-decimal tokens.',
+        ),
+      )
+    }
+  } else if (challenge.method === Constants.Methods.stripe) {
+    if (request.amount !== undefined) {
+      results.push(check('Stripe challenge has amount'))
+    } else {
+      results.push(warn('Stripe challenge has amount', 'No amount field'))
+    }
+  }
+
+  if (verbose) {
+    console.log(pc.dim(`    Challenge: ${JSON.stringify(challenge, null, 2)}`))
+  }
+
+  return { results, resolvedBody: fetchBody }
+}
+
+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
+}

package/src/cli/validate/discovery.ts

@@ -0,0 +1,120 @@
+import type { EndpointSpec } from './helpers.js'
+import { fetchWithTimeout, HTTP_METHODS } from './helpers.js'
+
+export async function fetchDiscoveryDoc(
+  baseUrl: string,
+): Promise<{ doc: unknown; raw: string } | { error: string }> {
+  const url = new URL('/openapi.json', baseUrl).href
+  try {
+    const response = await fetchWithTimeout(url, {})
+    if (!response.ok) return { error: `HTTP ${response.status}` }
+    const raw = await response.text()
+    const doc = JSON.parse(raw)
+    return { doc, raw }
+  } catch (error) {
+    if (error instanceof DOMException && error.name === 'AbortError')
+      return { error: 'Request timed out after 15s' }
+    if (error instanceof SyntaxError) return { error: 'Invalid JSON' }
+    return { error: (error as Error).message }
+  }
+}
+
+// Extracts testable endpoints from an OpenAPI doc. Prefers endpoints with
+// explicit x-payment-info (the server declares them as paid). Falls back to
+// endpoints that list a 402 response (weaker signal, but still worth testing).
+export function extractEndpointsFromDiscovery(doc: Record<string, unknown>): EndpointSpec[] {
+  const withPaymentInfo: EndpointSpec[] = []
+  const with402Response: EndpointSpec[] = []
+  const paths = doc.paths as Record<string, Record<string, unknown>> | undefined
+  if (!paths) return []
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (!HTTP_METHODS.has(method)) continue
+      if (!operation || typeof operation !== 'object' || Array.isArray(operation)) continue
+      const op = operation as Record<string, unknown>
+      if (op['x-payment-info']) {
+        const payInfo = op['x-payment-info'] as Record<string, unknown>
+        withPaymentInfo.push({
+          method: method.toUpperCase(),
+          path: pathKey,
+          amount: payInfo.amount as string | undefined,
+        })
+      } else {
+        const responses = op.responses as Record<string, unknown> | undefined
+        if (responses && '402' in responses) {
+          with402Response.push({ method: method.toUpperCase(), path: pathKey })
+        }
+      }
+    }
+  }
+  return withPaymentInfo.length > 0 ? withPaymentInfo : with402Response
+}
+
+// Recursively generates a minimal valid value from a JSON Schema definition.
+// Fills only required fields, preferring const > example > default > synthetic.
+function generateValueFromSchema(schema: Record<string, unknown>): unknown {
+  if (schema.const !== undefined) return schema.const
+  if (schema.example !== undefined) return schema.example
+  if (schema.default !== undefined) return schema.default
+
+  switch (schema.type) {
+    case 'string': {
+      if (schema.format === 'email') return 'test@example.com'
+      if (schema.format === 'uuid') return '00000000-0000-0000-0000-000000000000'
+      if (schema.format === 'uri' || schema.format === 'url') return 'https://example.com'
+      if (schema.enum && Array.isArray(schema.enum)) return schema.enum[0]
+      return 'test'
+    }
+    case 'number':
+    case 'integer':
+      return schema.minimum ?? 1
+    case 'boolean':
+      return true
+    case 'array':
+      return []
+    case 'object': {
+      const properties = schema.properties as Record<string, Record<string, unknown>> | undefined
+      if (!properties) return {}
+      const required = (schema.required as string[]) || []
+      const obj: Record<string, unknown> = {}
+      for (const key of required) {
+        const prop = properties[key]
+        if (prop) obj[key] = generateValueFromSchema(prop)
+      }
+      return obj
+    }
+    default:
+      return null
+  }
+}
+
+// Looks up the requestBody schema for an endpoint in the OpenAPI doc and
+// returns a JSON string suitable for the request. Uses the doc's example
+// if one exists, otherwise generates a minimal body from the schema.
+export function extractRequestBodyFromDiscovery(
+  doc: Record<string, unknown>,
+  endpoint: EndpointSpec,
+): string | undefined {
+  const paths = doc.paths as Record<string, Record<string, unknown>> | undefined
+  if (!paths) return undefined
+  const pathItem = paths[endpoint.path]
+  if (!pathItem) return undefined
+  const op = pathItem[endpoint.method.toLowerCase()] as Record<string, unknown> | undefined
+  if (!op?.requestBody) return undefined
+
+  const rb = op.requestBody as Record<string, unknown>
+  const content = rb.content as Record<string, unknown> | undefined
+  const jsonContent = content?.['application/json'] as Record<string, unknown> | undefined
+  if (!jsonContent) return undefined
+
+  if (jsonContent.example) return JSON.stringify(jsonContent.example)
+
+  const schema = jsonContent.schema as Record<string, unknown> | undefined
+  if (!schema || schema.type !== 'object') return undefined
+
+  const result = generateValueFromSchema(schema)
+  if (result && typeof result === 'object' && Object.keys(result as object).length > 0) {
+    return JSON.stringify(result)
+  }
+  return undefined
+}

package/src/cli/validate/helpers.ts

@@ -0,0 +1,154 @@
+import { pc } from '../utils.js'
+
+export type CheckResult = {
+  label: string
+  detail?: string | undefined
+  hint?: string | undefined
+  severity: 'pass' | 'fail' | 'warn' | 'skip'
+}
+
+export type EndpointSpec = {
+  method: string
+  path: string
+  amount?: string | undefined
+}
+
+export function check(label: string, detail?: string): CheckResult {
+  return detail ? { label, detail, severity: 'pass' } : { label, severity: 'pass' }
+}
+
+export function fail(label: string, detail?: string, hint?: string): CheckResult {
+  const r: CheckResult = { label, severity: 'fail' }
+  if (detail) r.detail = detail
+  if (hint) r.hint = hint
+  return r
+}
+
+export function warn(label: string, detail?: string, hint?: string): CheckResult {
+  const r: CheckResult = { label, severity: 'warn' }
+  if (detail) r.detail = detail
+  if (hint) r.hint = hint
+  return r
+}
+
+export function skip(label: string, detail?: string, hint?: string): CheckResult {
+  const r: CheckResult = detail ? { label, detail, severity: 'skip' } : { label, severity: 'skip' }
+  if (hint) r.hint = hint
+  return r
+}
+
+const SEVERITY_ICONS = {
+  pass: pc.green('✓'),
+  fail: pc.red('✗'),
+  warn: pc.yellow('⚠'),
+  skip: pc.dim('○'),
+} as const
+
+export function printCheck(result: CheckResult) {
+  const icon = SEVERITY_ICONS[result.severity]
+  const text = result.detail ? `${result.label} (${result.detail})` : result.label
+  console.log(`  ${icon} ${text}`)
+  if (result.hint && result.severity !== 'pass') {
+    console.log(pc.dim(`    → ${result.hint}`))
+  }
+}
+
+export function printSection(title: string) {
+  console.log(`\n${pc.bold(title)}`)
+}
+
+export type Counts = { passed: number; failed: number; warnings: number; skipped: number }
+
+export function printResults(results: CheckResult[], counts: Counts) {
+  for (const result of results) {
+    printCheck(result)
+    if (result.severity === 'pass') counts.passed++
+    else if (result.severity === 'fail') counts.failed++
+    else if (result.severity === 'warn') counts.warnings++
+    else if (result.severity === 'skip') counts.skipped++
+  }
+}
+
+export async function fetchWithTimeout(
+  url: string,
+  init: RequestInit,
+  timeoutMs = 15_000,
+): Promise<Response> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetch(url, { ...init, signal: controller.signal })
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export function buildUrl(baseUrl: string, endpoint: EndpointSpec, query?: string[]): string {
+  let url = new URL(endpoint.path, baseUrl).href
+  if (query) {
+    const u = new URL(url)
+    for (const q of query) {
+      const [key, ...rest] = q.split('=')
+      if (key) u.searchParams.set(key, rest.join('='))
+    }
+    url = u.href
+  }
+  return url
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`
+}
+
+export const HTTP_METHODS = new Set([
+  'get',
+  'post',
+  'put',
+  'patch',
+  'delete',
+  'head',
+  'options',
+  'trace',
+])
+
+export function isValidAddress(addr: unknown): boolean {
+  return typeof addr === 'string' && /^0x[0-9a-fA-F]{40}$/.test(addr)
+}
+
+export function isValidIntegerAmount(amount: unknown): boolean {
+  return typeof amount === 'string' && /^(0|[1-9][0-9]*)$/.test(amount)
+}
+
+export function parseEndpointArg(input: string): EndpointSpec | null {
+  const sep = input.indexOf(':')
+  if (sep < 1) return null
+  const method = input.slice(0, sep).toLowerCase()
+  if (!HTTP_METHODS.has(method)) return null
+  const path = input.slice(sep + 1)
+  if (!path) return null
+  const normalizedPath = path.startsWith('/') ? path : '/' + path
+  return { method: method.toUpperCase(), path: normalizedPath }
+}
+
+// Resolves --body input: if JSON with all keys starting with /, it's a
+// per-path mapping. Otherwise it's a global body for all endpoints.
+export function resolveBodyForEndpoint(
+  rawBody: string | undefined,
+  endpointPath: string,
+): string | undefined {
+  if (!rawBody) return undefined
+  try {
+    const parsed = JSON.parse(rawBody)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      const keys = Object.keys(parsed)
+      if (keys.length > 0 && keys.every((k) => k.startsWith('/'))) {
+        const value = parsed[endpointPath]
+        if (value === undefined) return undefined
+        return typeof value === 'string' ? value : JSON.stringify(value)
+      }
+    }
+  } catch {}
+  return rawBody
+}