Use OpenAPI examples for probes

Author: TateLyman

README.md

@@ -15,7 +15,8 @@ npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/
 ## What It Checks
 
 - Manifest endpoint discovery from `items[]`, `endpoints[]`, `x402Endpoints`, category arrays, resource strings, and OpenAPI paths
-- Linked discovery documents via `discovery_url`, `discoveryUrl`, `resources_url`, or `resourcesUrl`
+- Linked discovery documents via `discovery_url`, `discoveryUrl`, `resources_url`, `resourcesUrl`, or manifest-level OpenAPI links
+- OpenAPI query/path examples and JSON request-body examples for safer no-payment probes
 - No-payment HTTP 402 challenge shape
 - x402 v1 and v2 price fields, including `accepts[]` and `schemes[]` challenge arrays
 - MPP `WWW-Authenticate: Payment` and x402 V2 `WWW-Authenticate: X402 requirements=...` challenges
@@ -29,7 +30,7 @@ npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/
 - Over-broad public method surfaces
 - Auth, validation, and free/trial responses that appear before a payment challenge, without piling on missing-field findings when no challenge was actually returned
 - Operational health/status endpoints, without treating expected free health checks as paid-route failures
-- Object-valued document metadata such as facilitator objects, without `[object Object]` report artifacts
+- Object-valued document metadata such as facilitator or network objects, without `[object Object]` report artifacts
 
 ## Public Proof
 
@@ -41,7 +42,8 @@ Recent public no-payment checks have found and verified real launch fixes:
 - UZPROOF: schemes-style Solana x402 challenge and browser payment-header behavior verified clean. https://github.com/solana-foundation/pay-skills/pull/28#issuecomment-4455613892
 - HYRE Agent: OpenAPI-declared prices found 10x below live 402 challenge prices. https://github.com/solana-foundation/pay-skills/pull/19#issuecomment-4455641258
 - anchor-x402: multi-rail x402 challenges verified, with browser preflight blockers isolated before merge. https://github.com/solana-foundation/pay-skills/pull/47#issuecomment-4455678163
-- Agent Trust Bench: live discovery URL and browser-compatibility notes for adversarial agent-payment resources. https://github.com/solana-foundation/pay-skills/pull/23#issuecomment-4455484414
+- Agent Trust Bench: linked discovery URL and browser-compatibility notes verified clean for adversarial agent-payment resources. https://github.com/solana-foundation/pay-skills/pull/23#issuecomment-4455722170
+- Solrouter: private LLM inference route verified with HTTPS resource-binding and price-alignment notes. https://github.com/solana-foundation/pay-skills/pull/39#issuecomment-4455800060
 
 Field notes and browser version: https://tateprograms.com/x402-surface-check.html
 

bin/x402-surface-check.mjs

@@ -137,6 +137,7 @@ function linkedDiscoveryUrl(document, sourceUrl) {
     ?? document?.discoveryUrl
     ?? document?.resources_url
     ?? document?.resourcesUrl
+    ?? (/^(https?:\/\/|\/)/i.test(String(document?.openapi ?? '')) ? document.openapi : '')
   if (typeof rawUrl !== 'string' || !rawUrl.trim()) return ''
   return endpointUrl(rawUrl, documentBaseUrl(document, sourceUrl), sourceUrl)
 }
@@ -150,6 +151,79 @@ function operationExpectedPrice(operation) {
   return numeric === null ? null : numeric
 }
 
+function exampleValue(schemaOrParameter) {
+  if (!schemaOrParameter || typeof schemaOrParameter !== 'object') return undefined
+  const schema = schemaOrParameter.schema ?? schemaOrParameter
+  const value = schemaOrParameter.example
+    ?? schema.example
+    ?? schema.default
+    ?? (Array.isArray(schema.enum) ? schema.enum[0] : undefined)
+  if (value !== undefined) return value
+  if (schema.type === 'string') return ''
+  if (schema.type === 'number' || schema.type === 'integer') return 0
+  if (schema.type === 'boolean') return false
+  return undefined
+}
+
+function mediaExample(media) {
+  if (!media || typeof media !== 'object') return undefined
+  if (media.example !== undefined) return media.example
+  const examples = media.examples && typeof media.examples === 'object'
+    ? Object.values(media.examples)
+    : []
+  const firstExample = examples.find(Boolean)
+  if (firstExample?.value !== undefined) return firstExample.value
+  if (firstExample?.externalValue) return undefined
+
+  const schema = media.schema
+  if (!schema || typeof schema !== 'object' || schema.type !== 'object') return undefined
+  const body = {}
+  const properties = schema.properties && typeof schema.properties === 'object'
+    ? schema.properties
+    : {}
+  const required = new Set(Array.isArray(schema.required) ? schema.required : Object.keys(properties))
+
+  for (const [name, property] of Object.entries(properties)) {
+    if (!required.has(name)) continue
+    const value = exampleValue(property)
+    if (value !== undefined) body[name] = value
+  }
+
+  return Object.keys(body).length ? body : undefined
+}
+
+function operationRequestBody(operation) {
+  const content = operation?.requestBody?.content
+  if (!content || typeof content !== 'object') return undefined
+  const media = content['application/json']
+    ?? content['application/*+json']
+    ?? Object.entries(content).find(([type]) => /json/i.test(type))?.[1]
+  return mediaExample(media)
+}
+
+function openApiProbeUrl(path, operation, baseUrl) {
+  const parameters = Array.isArray(operation?.parameters) ? operation.parameters : []
+  let resolvedPath = path
+  const searchParams = new URLSearchParams()
+
+  for (const parameter of parameters) {
+    const value = exampleValue(parameter)
+    if (value === undefined || value === '') continue
+    if (parameter.in === 'path') {
+      resolvedPath = resolvedPath.replaceAll(`{${parameter.name}}`, encodeURIComponent(String(value)))
+    }
+    else if (parameter.in === 'query') {
+      searchParams.set(parameter.name, String(value))
+    }
+  }
+
+  const url = path.startsWith('http') ? new URL(resolvedPath) : new URL(resolvedPath, baseUrl)
+  for (const [name, value] of searchParams.entries()) {
+    url.searchParams.set(name, value)
+  }
+  return url.toString()
+}
+
 function endpointEntries(document, sourceUrl, limit) {
   const entries = []
   const baseUrl = documentBaseUrl(document, sourceUrl)
@@ -207,12 +281,13 @@ function endpointEntries(document, sourceUrl, limit) {
       for (const method of methods) {
         const operation = operations[method]
         if (!operation || typeof operation !== 'object') continue
-        const url = path.startsWith('http') ? path : new URL(path, baseUrl).toString()
+        const url = openApiProbeUrl(path, operation, baseUrl)
         entries.push({
           name: operation.operationId ?? `${method.toUpperCase()} ${path}`,
           url,
           method: method.toUpperCase(),
           expectedPriceUsd: operationExpectedPrice(operation),
+          requestBody: operationRequestBody(operation),
         })
       }
     }
@@ -347,7 +422,9 @@ async function probeEndpoint(entry) {
       accept: 'application/json',
       'content-type': 'application/json',
     },
-    body: method === 'GET' || method === 'HEAD' ? undefined : '{}',
+    body: method === 'GET' || method === 'HEAD'
+      ? undefined
+      : JSON.stringify(entry.requestBody ?? {}),
   })
   const body = await readText(response)
   const headerChallenge = parseEncodedChallenge(
@@ -395,7 +472,7 @@ async function probePreflight(entry, origin) {
 }
 
 function valueList(value) {
-  if (Array.isArray(value)) return value.map(String)
+  if (Array.isArray(value)) return value.map(displayMetadataValue)
   if (value && typeof value === 'object') return Object.keys(value)
   if (typeof value === 'string') return [value]
   return []

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-surface-check",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "No-payment x402 public-surface checker for manifests, OpenAPI specs, and HTTP 402 challenges.",
   "type": "module",
   "bin": {

package.json

@@ -63,6 +63,44 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/examples-openapi.json') {
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({
+      openapi: '3.1.0',
+      info: { title: 'Examples Fixture', version: '1.0.0' },
+      servers: [{ url: serverUrl }],
+      paths: {
+        '/brands': {
+          get: {
+            operationId: 'listBrandsWithExample',
+            parameters: [{
+              name: 'country_code',
+              in: 'query',
+              required: true,
+              schema: { type: 'string', example: 'us' },
+            }],
+          },
+        },
+        '/orders': {
+          post: {
+            operationId: 'createOrderWithExample',
+            requestBody: {
+              content: {
+                'application/json': {
+                  example: {
+                    email: 'agent@example.com',
+                    items: [{ product_id: 'sku_123', product_value: 25 }],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }))
+    return
+  }
+
   if (request.url === '/x402.json') {
     response.setHeader('content-type', 'application/json')
     response.end(JSON.stringify({
@@ -116,6 +154,20 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/openapi-link.json') {
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({
+      name: 'Linked OpenAPI Fixture',
+      openapi: `${serverUrl}/examples-openapi.json`,
+      networks: [{
+        id: 'solana',
+        network: 'solana-mainnet',
+        asset: 'USDC',
+      }],
+    }))
+    return
+  }
+
   if (request.url === '/health') {
     response.statusCode = 200
     response.setHeader('content-type', 'application/json')
@@ -203,6 +255,46 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/brands?country_code=us') {
+    response.statusCode = 200
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({ ok: true, brands: ['Example'] }))
+    return
+  }
+
+  if (request.url === '/orders') {
+    let body = ''
+    request.on('data', chunk => {
+      body += chunk
+    })
+    request.on('end', () => {
+      const parsed = body ? JSON.parse(body) : {}
+      if (parsed.email !== 'agent@example.com' || !Array.isArray(parsed.items)) {
+        response.statusCode = 400
+        response.setHeader('content-type', 'application/json')
+        response.end(JSON.stringify({ error: 'missing order example' }))
+        return
+      }
+      response.statusCode = 402
+      response.setHeader('content-type', 'application/json')
+      response.setHeader('access-control-allow-origin', '*')
+      response.end(JSON.stringify({
+        x402Version: 1,
+        error: 'Payment required',
+        accepts: [{
+          scheme: 'exact',
+          network: 'solana',
+          maxAmountRequired: '25000',
+          asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+          payTo: '2Ynf2xxaiLbPy9p8iWE5ZiUd1wojJ45pRwCEN3mgK8aE',
+          resource: `${serverUrl}/orders`,
+          maxTimeoutSeconds: 60,
+        }],
+      }))
+    })
+    return
+  }
+
   if (request.url === '/mpp/eth') {
     const mppRequest = Buffer.from(JSON.stringify({
       amount: '1000',
@@ -343,6 +435,19 @@ try {
   assert.match(mismatch.stdout, /priceMismatch/)
   assert.match(mismatch.stdout, /documented price \$0\.002 does not match live 402 challenge price \$0\.001/)
 
+  const examples = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    `${serverUrl}/examples-openapi.json`,
+    '--origin',
+    'https://example.com',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(examples.stdout, /listBrandsWithExample/)
+  assert.match(examples.stdout, /createOrderWithExample/)
+  assert.match(examples.stdout, /\$0\.025/)
+  assert.doesNotMatch(examples.stdout, /listBrandsWithExample returned validation HTTP 400/)
+  assert.doesNotMatch(examples.stdout, /createOrderWithExample returned validation HTTP 400/)
+
   const manifest = await execFileAsync('node', [
     'bin/x402-surface-check.mjs',
     `${serverUrl}/x402.json`,
@@ -379,6 +484,18 @@ try {
   assert.match(linkedDiscovery.stdout, new RegExp(`Document: ${serverUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/items\\.json`))
   assert.match(linkedDiscovery.stdout, /Premium routing recommendations/)
 
+  const linkedOpenApi = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    `${serverUrl}/openapi-link.json`,
+    '--origin',
+    'https://example.com',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(linkedOpenApi.stdout, new RegExp(`Source: ${serverUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/openapi-link\\.json`))
+  assert.match(linkedOpenApi.stdout, new RegExp(`Document: ${serverUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/examples-openapi\\.json`))
+  assert.match(linkedOpenApi.stdout, /createOrderWithExample/)
+  assert.doesNotMatch(linkedOpenApi.stdout, /\[object Object\]/)
+
   const mpp = await execFileAsync('node', [
     'bin/x402-surface-check.mjs',
     '--endpoint',