validate: retry on 422, resolve $ref/examples, add --header, fix x402 validation, send explicit body upfront (#649)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

  GIT_VALID_PII_OVERRIDE

Committed-By-Agent: claude

Author: bensandler-stripe

.changeset/validate-small-fixes.md

@@ -0,0 +1,5 @@
+---
+'mppx': patch
+---
+
+`mppx validate`: retry on 422, resolve `$ref` in body generation, add `--header`/`-H` flag, fix x402 validation for non-EVM chains.

src/cli/validate/challenge.ts

@@ -13,6 +13,7 @@ import {
   fetchWithTimeout,
   isValidAddress,
   isValidIntegerAmount,
+  parseHeaders,
   skip,
   warn,
 } from './helpers.js'
@@ -32,7 +33,9 @@ export async function validateChallenge(
   verbose: boolean,
   options?: {
     body?: string | undefined
+    bodyIsAutogenerated?: boolean | undefined
     query?: string[] | undefined
+    extraHeaders?: string[] | undefined
     discoveryDoc?: Record<string, unknown> | undefined
   },
 ): Promise<{
@@ -42,20 +45,28 @@ export async function validateChallenge(
 }> {
   const results: CheckResult[] = []
   const url = buildUrl(baseUrl, endpoint, options?.query)
-  const fetchHeaders: Record<string, string> = {}
+  const fetchHeaders: Record<string, string> = parseHeaders(options?.extraHeaders)
   let fetchBody: string | undefined
 
-  // Make bare unauthenticated request first (no body)
+  // 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 {
-    response = await fetchWithTimeout(url, { method: endpoint.method })
+    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, retry with body (explicit --body or auto-generated from schema)
-  if (response.status === 400) {
+  // 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
@@ -99,7 +110,7 @@ export async function validateChallenge(
         fail(
           'Returns 402 without credentials',
           `Got ${response.status} instead`,
-          response.status === 400
+          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.',
         ),
@@ -111,8 +122,8 @@ export async function validateChallenge(
 
   // Check WWW-Authenticate header
   const wwwAuth = response.headers.get(Constants.Headers.wwwAuthenticate)
+  const x402Results = checkX402Headers(response)
   if (!wwwAuth) {
-    const x402Results = checkX402Headers(response)
     if (x402Results.length > 0) {
       results.push(
         skip('Not an MPP endpoint', 'No WWW-Authenticate header — x402 protocol detected'),
@@ -125,6 +136,7 @@ export async function validateChallenge(
     }
     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 }
@@ -533,7 +545,7 @@ function checkX402Headers(response: Response): CheckResult[] {
     : 'X-Payment-Required'
 
   try {
-    const decoded = x402Header.decodePaymentRequired(paymentRequiredRaw)
+    const decoded = x402Header.decodePaymentRequiredEnvelope(paymentRequiredRaw)
     results.push(
       check(
         'x402 payment challenge',

src/cli/validate/discovery.test.ts

@@ -304,4 +304,132 @@ describe('extractRequestBodyFromDiscovery', () => {
     })
     expect(JSON.parse(body!)).toEqual({ model: 'gpt-4' })
   })
+
+  test('resolves $ref to components/schemas', () => {
+    const doc = {
+      paths: {
+        '/api/orders': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/OrderRequest' },
+                },
+              },
+            },
+          },
+        },
+      },
+      components: {
+        schemas: {
+          OrderRequest: {
+            type: 'object',
+            required: ['product', 'quantity'],
+            properties: {
+              product: { type: 'string', example: 'widget' },
+              quantity: { type: 'integer', minimum: 1 },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/orders',
+    })
+    expect(JSON.parse(body!)).toEqual({ product: 'widget', quantity: 1 })
+  })
+
+  test('resolves nested $ref in properties', () => {
+    const doc = {
+      paths: {
+        '/api/orders': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/OrderRequest' },
+                },
+              },
+            },
+          },
+        },
+      },
+      components: {
+        schemas: {
+          OrderRequest: {
+            type: 'object',
+            required: ['customer'],
+            properties: {
+              customer: { $ref: '#/components/schemas/Customer' },
+            },
+          },
+          Customer: {
+            type: 'object',
+            required: ['name', 'email'],
+            properties: {
+              name: { type: 'string' },
+              email: { type: 'string', format: 'email' },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/orders',
+    })
+    expect(JSON.parse(body!)).toEqual({ customer: { name: 'test', email: 'test@example.com' } })
+  })
+
+  test('uses first named example from examples map', () => {
+    const doc = {
+      paths: {
+        '/api/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  examples: {
+                    basic: { value: { prompt: 'hello', model: 'gpt-4' } },
+                    advanced: { value: { prompt: 'complex', model: 'gpt-4', temp: 0.9 } },
+                  },
+                  schema: { type: 'object' },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(JSON.parse(body!)).toEqual({ prompt: 'hello', model: 'gpt-4' })
+  })
+
+  test('returns undefined for unresolvable $ref', () => {
+    const doc = {
+      paths: {
+        '/api/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/DoesNotExist' },
+                },
+              },
+            },
+          },
+        },
+      },
+      components: { schemas: {} },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(body).toBeUndefined()
+  })
 })

src/cli/validate/discovery.ts

@@ -77,10 +77,19 @@ export function extractRequestBodyFromDiscovery(
 
   if (jsonContent.example) return JSON.stringify(jsonContent.example)
 
-  const schema = jsonContent.schema as Record<string, unknown> | undefined
+  if (jsonContent.examples && typeof jsonContent.examples === 'object') {
+    const first = Object.values(jsonContent.examples as Record<string, unknown>)[0] as
+      | Record<string, unknown>
+      | undefined
+    if (first?.value) return JSON.stringify(first.value)
+  }
+
+  let schema = jsonContent.schema as Record<string, unknown> | undefined
+  const seen = new Set<string>()
+  schema = resolveRef(schema, doc, seen)
   if (!schema || schema.type !== 'object') return undefined
 
-  const result = generateValueFromSchema(schema)
+  const result = generateValueFromSchema(schema, doc, seen)
   if (result && typeof result === 'object' && Object.keys(result as object).length > 0) {
     return JSON.stringify(result)
   }
@@ -149,34 +158,60 @@ function substitutePathParams(path: string, params: PathParameter[]): string {
   })
 }
 
-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
+// Dereferences a JSON Schema $ref (e.g. "#/components/schemas/Foo") against the root doc.
+function resolveRef(
+  schema: Record<string, unknown> | undefined,
+  doc: Record<string, unknown>,
+  seen?: Set<string>,
+): Record<string, unknown> | undefined {
+  if (!schema || typeof schema.$ref !== 'string') return schema
+  if (seen?.has(schema.$ref)) return undefined
+  const path = schema.$ref.replace(/^#\//, '').split('/')
+  let resolved: unknown = doc
+  for (const segment of path) {
+    if (resolved && typeof resolved === 'object') resolved = (resolved as any)[segment]
+    else return undefined
+  }
+  return resolved as Record<string, unknown> | undefined
+}
 
-  switch (schema.type) {
+// Generates a plausible value for a JSON Schema node (required fields only for objects).
+function generateValueFromSchema(
+  schema: Record<string, unknown>,
+  doc: Record<string, unknown>,
+  seen?: Set<string>,
+): unknown {
+  const resolved = resolveRef(schema, doc, seen) ?? schema
+  if (resolved.const !== undefined) return resolved.const
+  if (resolved.example !== undefined) return resolved.example
+  if (resolved.default !== undefined) return resolved.default
+
+  switch (resolved.type) {
     case 'string': {
-      if (schema.enum && Array.isArray(schema.enum)) return schema.enum[0]
-      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 (resolved.enum && Array.isArray(resolved.enum)) return resolved.enum[0]
+      if (resolved.format === 'email') return 'test@example.com'
+      if (resolved.format === 'uuid') return '00000000-0000-0000-0000-000000000000'
+      if (resolved.format === 'uri' || resolved.format === 'url') return 'https://example.com'
+      if (resolved.format === 'date') return '2026-01-01'
+      if (resolved.pattern === '^\\d{5}(?:-\\d{4})?$') return '10001'
+      if (resolved.pattern === '^[A-Z]{2}$') return 'US'
       return 'test'
     }
     case 'number':
     case 'integer':
-      return (schema.minimum as number) ?? 1
+      return (resolved.minimum as number) ?? 1
     case 'boolean':
       return true
     case 'array':
       return []
     case 'object': {
-      const properties = schema.properties as Record<string, Record<string, unknown>> | undefined
+      const properties = resolved.properties as Record<string, Record<string, unknown>> | undefined
       if (!properties) return {}
-      const required = (schema.required as string[]) || []
+      const required = (resolved.required as string[]) || []
       const obj: Record<string, unknown> = {}
       for (const key of required) {
         const prop = properties[key]
-        if (prop) obj[key] = generateValueFromSchema(prop)
+        if (prop) obj[key] = generateValueFromSchema(prop, doc, seen)
       }
       return obj
     }

src/cli/validate/helpers.ts

@@ -154,3 +154,13 @@ export function resolveBodyForEndpoint(
   } catch {}
   return rawBody
 }
+
+export function parseHeaders(raw: string[] | undefined): Record<string, string> {
+  if (!raw) return {}
+  const headers: Record<string, string> = {}
+  for (const h of raw) {
+    const idx = h.indexOf(':')
+    if (idx > 0) headers[h.slice(0, idx).trim().toLowerCase()] = h.slice(idx + 1).trim()
+  }
+  return headers
+}

src/cli/validate/index.ts

@@ -19,12 +19,14 @@ const validate = Cli.create('validate', {
         'Request body. With --endpoint, used directly. In discovery mode, JSON with / keys is a per-path mapping.',
       ),
     query: z.array(z.string()).optional().describe('Query parameter (key=value, repeatable)'),
+    header: z.array(z.string()).optional().describe('Request header (key:value, repeatable)'),
     verbose: z.number().default(0).meta({ count: true }).describe('Verbosity level'),
     yes: z.boolean().default(false).describe('Auto-approve mainnet payments'),
     outputJson: z.boolean().default(false).describe('Output results as JSON'),
   }),
   alias: {
     endpoint: 'e',
+    header: 'H',
     verbose: 'v',
     yes: 'y',
     outputJson: 'j',
@@ -37,6 +39,7 @@ const validate = Cli.create('validate', {
         endpoint: c.options.endpoint,
         body: c.options.body,
         query: c.options.query,
+        headers: c.options.header,
         verbose: c.options.verbose > 0,
         yes: c.options.yes,
         interactive: false,
@@ -66,6 +69,7 @@ const validate = Cli.create('validate', {
       endpoint: c.options.endpoint,
       body: c.options.body,
       query: c.options.query,
+      headers: c.options.header,
       verbose: c.options.verbose > 0,
       yes: c.options.yes,
       interactive: !!process.stdin.isTTY,