Support object-valued x402 endpoints

Author: TateLyman

README.md

@@ -17,7 +17,8 @@ npx --yes x402-surface-check --strict-cache https://api.example.com/openapi.json
 
 ## What It Checks
 
-- Manifest endpoint discovery from `items[]`, `endpoints[]`, `resources[]`, `x402Endpoints`, category arrays, raw resource URL strings, method-prefixed resource strings, and OpenAPI paths
+- Manifest endpoint discovery from `items[]`, `endpoints[]`, object-valued `endpoints`, `resources[]`, `x402Endpoints`, category arrays, raw resource URL strings, method-prefixed resource strings, and OpenAPI paths
+- Object-valued manifest endpoint query examples, public catalog/discovery GETs, and payment-bearing two-phase operations without treating expected public catalog reads as failed payment gates
 - Linked discovery documents via `discovery_url`, `discoveryUrl`, `resources_url`, `resourcesUrl`, or manifest-level OpenAPI links
 - OpenAPI `servers[]` base-path preservation, so `/paths` are probed through the documented gateway rather than the domain root
 - OpenAPI query/path examples, JSON request-body examples, nested request schemas, local `$ref` request schemas, and explicit direct-endpoint bodies for safer no-payment probes

bin/x402-surface-check.mjs

@@ -322,6 +322,47 @@ function openApiProbeUrl(path, operation, baseUrl, document) {
   return url.toString()
 }
 
+function manifestEndpointPaymentSignal(endpoint) {
+  if (!endpoint || typeof endpoint !== 'object') return 0
+  if (Number(endpoint.phase1_response?.status) === 402) return 2
+  if (/payment-required|x-payment|402/i.test(String(endpoint.phase1_response?.header ?? ''))) return 2
+  if (/payment|required|402/i.test(String(endpoint.description ?? ''))) return 1
+  if (endpoint.accepts || endpoint.schemes || endpoint.payment || endpoint['x-payment-info']) return 1
+  return 0
+}
+
+function manifestEndpointBody(endpoint, document) {
+  const body = endpoint?.request_body ?? endpoint?.requestBody
+  if (!body || typeof body !== 'object') return undefined
+  if (body.example !== undefined) return body.example
+  if (body.safe_example !== undefined) return body.safe_example
+  if (body.safeExample !== undefined) return body.safeExample
+  return exampleValue(body, document)
+}
+
+function manifestEndpointUrl(rawPath, endpoint, baseUrl, sourceUrl) {
+  const url = new URL(endpointUrl(rawPath, baseUrl, sourceUrl))
+  const parameters = endpoint?.parameters
+  if (!parameters || typeof parameters !== 'object') return url.toString()
+
+  for (const [name, parameter] of Object.entries(parameters)) {
+    if (url.pathname.includes(`{${name}}`)) {
+      const pathValue = parameter?.example ?? parameter?.default
+      if (pathValue !== undefined && pathValue !== '') {
+        url.pathname = url.pathname.replaceAll(`{${name}}`, encodeURIComponent(String(pathValue)))
+      }
+      continue
+    }
+
+    const value = parameter?.example ?? parameter?.default
+    if (value !== undefined && value !== '') {
+      url.searchParams.set(name, String(value))
+    }
+  }
+
+  return url.toString()
+}
+
 function endpointEntries(document, sourceUrl, limit) {
   const entries = []
   const baseUrl = documentBaseUrl(document, sourceUrl)
@@ -356,6 +397,24 @@ function endpointEntries(document, sourceUrl, limit) {
       })
     }
   }
+  else if (document.endpoints && typeof document.endpoints === 'object') {
+    for (const [key, endpoint] of Object.entries(document.endpoints)) {
+      if (!endpoint || typeof endpoint !== 'object') continue
+      const rawPath = endpoint.url ?? endpoint.endpoint ?? endpoint.path
+      if (!rawPath) continue
+      const method = String(endpoint.method ?? 'POST').toUpperCase()
+      const paymentSignal = manifestEndpointPaymentSignal(endpoint)
+      const hasPathParameters = /\{[^}]+\}/.test(String(rawPath))
+      if (paymentSignal === 0 && (method !== 'GET' || hasPathParameters)) continue
+      entries.push({
+        name: endpoint.id ?? endpoint.name ?? key,
+        url: manifestEndpointUrl(rawPath, endpoint, baseUrl, sourceUrl),
+        method,
+        requestBody: manifestEndpointBody(endpoint, document),
+        publicDiscovery: paymentSignal === 0,
+      })
+    }
+  }
 
   if (Array.isArray(document.items)) {
     for (const item of document.items) {
@@ -768,6 +827,13 @@ function findingList(documentResult, challengeResults, preflightResults, entries
     if (summary.network) challengeNetworks.add(summary.network)
     const hasChallenge = hasPaymentChallenge(result)
 
+    if (result.publicDiscovery && !hasChallenge) {
+      if (result.status < 200 || result.status >= 300) {
+        findings.push(`P2 - ${result.name} is documented as a public discovery route but returned HTTP ${result.status}; check the manifest example parameters or route availability.`)
+      }
+      continue
+    }
+
     if (result.status !== 402) {
       if (result.status >= 200 && result.status < 300) {
         if (!looksLikeOperationalHealthEndpoint(result)) {

package-lock.json

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

package.json

@@ -323,6 +323,58 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/object-endpoints.json') {
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({
+      version: '1.0',
+      service: {
+        name: 'Object Endpoint Fixture',
+        url: serverUrl,
+      },
+      networks: [{ id: 'base', network: 'eip155:8453' }],
+      endpoints: {
+        brandsObject: {
+          method: 'GET',
+          path: '/object/brands',
+          description: 'Discover public brands before checkout.',
+          parameters: {
+            country_code: { type: 'string', required: true, example: 'us' },
+          },
+        },
+        catalogObject: {
+          method: 'GET',
+          path: '/object/catalog',
+          description: 'Get public catalog products before checkout.',
+          parameters: {
+            country_code: { type: 'string', required: true, example: 'us' },
+            brand_name: { type: 'string', required: false, example: 'Example Store' },
+          },
+        },
+        createOrderObject: {
+          method: 'POST',
+          path: '/object/order',
+          description: 'Two-phase endpoint. First call returns 402 PAYMENT-REQUIRED.',
+          request_body: {
+            example: {
+              email: 'agent@example.com',
+              items: [{ product_id: 'sku_123', beneficiary_account: 'recipient@example.com' }],
+            },
+          },
+          phase1_response: {
+            status: 402,
+            header: 'PAYMENT-REQUIRED',
+          },
+        },
+        getOrderObject: {
+          method: 'GET',
+          path: '/object/orders/{order_id}',
+          description: 'Poll after a paid order exists.',
+        },
+      },
+    }))
+    return
+  }
+
   if (request.url === '/openapi-link.json') {
     response.setHeader('content-type', 'application/json')
     response.end(JSON.stringify({
@@ -424,6 +476,54 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/object/brands?country_code=us') {
+    response.statusCode = 200
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify([{ brand_name: 'Example Store' }]))
+    return
+  }
+
+  if (request.url === '/object/catalog?country_code=us&brand_name=Example+Store') {
+    response.statusCode = 200
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify([{ product_id: 'sku_123', price_usdc: '0.02' }]))
+    return
+  }
+
+  if (request.url === '/object/order') {
+    let body = ''
+    request.on('data', chunk => {
+      body += chunk
+    })
+    request.on('end', () => {
+      const parsed = body ? JSON.parse(body) : {}
+      if (parsed.email !== 'agent@example.com' || parsed.items?.[0]?.product_id !== 'sku_123') {
+        response.statusCode = 400
+        response.setHeader('content-type', 'application/json')
+        response.end(JSON.stringify({ error: 'missing object endpoint body example' }))
+        return
+      }
+      response.statusCode = 402
+      response.setHeader('content-type', 'application/json')
+      response.setHeader('access-control-allow-origin', '*')
+      response.end(JSON.stringify({
+        x402Version: 2,
+        error: 'Payment required',
+        resource: { url: `${serverUrl}/object/order` },
+        accepts: [{
+          scheme: 'exact',
+          network: 'eip155:8453',
+          amount: '20000',
+          asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+          payTo: '0x549c82e6bfc54bdae9a2073744cbc2af5d1fc6d1',
+          resource: `${serverUrl}/object/order`,
+          extra: { resource: `${serverUrl}/object/order` },
+        }],
+      }))
+    })
+    return
+  }
+
   if (request.url === '/gateway/pay/v1/protected') {
     response.statusCode = 402
     response.setHeader('content-type', 'application/json')
@@ -933,6 +1033,24 @@ try {
   assert.match(resourceManifest.stdout, /eip155:8453/)
   assert.doesNotMatch(resourceManifest.stdout, /Document does not expose/)
 
+  const objectEndpoints = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    `${serverUrl}/object-endpoints.json`,
+    '--origin',
+    'https://example.com',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(objectEndpoints.stdout, /brandsObject/)
+  assert.match(objectEndpoints.stdout, /catalogObject/)
+  assert.match(objectEndpoints.stdout, /createOrderObject/)
+  assert.match(objectEndpoints.stdout, /Probed endpoints: 3/)
+  assert.match(objectEndpoints.stdout, /\$0\.02/)
+  assert.doesNotMatch(objectEndpoints.stdout, /getOrderObject/)
+  assert.doesNotMatch(objectEndpoints.stdout, /Document does not expose/)
+  assert.doesNotMatch(objectEndpoints.stdout, /brandsObject returned 200 without a payment challenge/)
+  assert.doesNotMatch(objectEndpoints.stdout, /catalogObject returned 200 without a payment challenge/)
+  assert.doesNotMatch(objectEndpoints.stdout, /createOrderObject returned validation HTTP 400/)
+
   const linkedDiscovery = await execFileAsync('node', [
     'bin/x402-surface-check.mjs',
     `${serverUrl}/well-known.json`,