Support nested x402 discovery manifests

Author: TateLyman

README.md

@@ -18,9 +18,9 @@ npx --yes x402-surface-check --strict-proof https://api.example.com/openapi.json
 
 ## What It Checks
 
-- Manifest endpoint discovery from `items[]`, `endpoints[]`, object-valued `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`, string-valued endpoint maps, `tools` maps, `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
+- Linked discovery documents via `discovery_url`, `discoveryUrl`, `resources_url`, `resourcesUrl`, string `discovery` links, nested `discovery.x402_json` / OpenAPI links, 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
 - OpenAPI paid-operation prioritization, so docs and discovery routes do not consume the probe limit before payment-bearing operations

bin/x402-surface-check.mjs

@@ -178,10 +178,22 @@ function openApiServerBaseUrl(document, sourceUrl) {
 }
 
 function linkedDiscoveryUrl(document, sourceUrl) {
+  const discovery = document?.discovery && typeof document.discovery === 'object'
+    ? document.discovery
+    : {}
   const rawUrl = document?.discovery_url
     ?? document?.discoveryUrl
     ?? document?.resources_url
     ?? document?.resourcesUrl
+    ?? (typeof document?.discovery === 'string' ? document.discovery : undefined)
+    ?? discovery.x402_json
+    ?? discovery.x402Json
+    ?? discovery.resources_json
+    ?? discovery.resourcesJson
+    ?? discovery.resources
+    ?? discovery.openapi
+    ?? discovery.openapi_url
+    ?? discovery.openapiUrl
     ?? (/^(https?:\/\/|\/)/i.test(String(document?.openapi ?? '')) ? document.openapi : '')
   if (typeof rawUrl !== 'string' || !rawUrl.trim()) return ''
   return endpointUrl(rawUrl, documentBaseUrl(document, sourceUrl), sourceUrl)
@@ -331,6 +343,7 @@ 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 (/^\$?\d+(\.\d+)?/.test(String(endpoint.price ?? endpoint.cost ?? endpoint.amount ?? ''))) return 1
   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
@@ -402,10 +415,28 @@ function endpointEntries(document, sourceUrl, limit) {
       })
     }
   }
-  else if (document.endpoints && typeof document.endpoints === 'object') {
-    for (const [key, endpoint] of Object.entries(document.endpoints)) {
+  const endpointMaps = []
+  if (!Array.isArray(document.endpoints) && document.endpoints && typeof document.endpoints === 'object') {
+    endpointMaps.push(document.endpoints)
+  }
+  if (document.tools && typeof document.tools === 'object') {
+    endpointMaps.push(document.tools)
+  }
+  for (const endpointMap of endpointMaps) {
+    for (const [key, endpoint] of Object.entries(endpointMap)) {
+      if (typeof endpoint === 'string') {
+        const methodMatch = key.match(/^(GET|POST|PUT|PATCH|DELETE)\s+(\S+)/i)
+        const rawPath = methodMatch?.[2] ?? key
+        entries.push({
+          name: String(rawPath).split('/').filter(Boolean).at(-1) ?? key,
+          url: endpointUrl(rawPath, baseUrl, sourceUrl),
+          method: String(methodMatch?.[1] ?? 'GET').toUpperCase(),
+        })
+        continue
+      }
       if (!endpoint || typeof endpoint !== 'object') continue
-      const rawPath = endpoint.url ?? endpoint.endpoint ?? endpoint.path
+      const keyPath = key.match(/^(GET|POST|PUT|PATCH|DELETE)\s+(\S+)/i)?.[2] ?? key
+      const rawPath = endpoint.url ?? endpoint.endpoint ?? endpoint.path ?? keyPath
       if (!rawPath) continue
       const method = String(endpoint.method ?? 'POST').toUpperCase()
       const paymentSignal = manifestEndpointPaymentSignal(endpoint)

package-lock.json

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

package.json

@@ -302,6 +302,37 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/nested-discovery.json') {
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({
+      name: 'Nested Discovery Fixture',
+      discovery: {
+        x402_json: '/items.json',
+        openapi: '/unused-openapi.json',
+      },
+    }))
+    return
+  }
+
+  if (request.url === '/string-endpoints.json') {
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({
+      name: 'String Endpoint Fixture',
+      endpoints: {
+        '/string-paid': '$0.04 USDC -- string-valued endpoint metadata',
+        'POST /string-post': '$0.08 USDC -- method-prefixed endpoint metadata',
+      },
+      tools: {
+        '/tool-paid': {
+          method: 'GET',
+          price: '$0.02',
+          description: 'Tool map endpoint metadata',
+        },
+      },
+    }))
+    return
+  }
+
   if (request.url === '/resources.json') {
     response.setHeader('content-type', 'application/json')
     response.end(JSON.stringify({
@@ -323,6 +354,25 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/string-paid' || request.url === '/string-post' || request.url === '/tool-paid') {
+    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: 'eip155:8453',
+        maxAmountRequired: request.url === '/string-post' ? '80000' : request.url === '/tool-paid' ? '20000' : '40000',
+        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        payTo: '0x549c82e6bfc54bdae9a2073744cbc2af5d1fc6d1',
+        resource: `${serverUrl}${request.url}`,
+      }],
+    }))
+    return
+  }
+
   if (request.url === '/registry-leak.json') {
     response.setHeader('content-type', 'application/json')
     response.end(JSON.stringify({
@@ -1115,6 +1165,32 @@ try {
   assert.match(linkedDiscovery.stdout, new RegExp(`Document: ${serverUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/items\\.json`))
   assert.match(linkedDiscovery.stdout, /Premium routing recommendations/)
 
+  const nestedDiscovery = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    `${serverUrl}/nested-discovery.json`,
+    '--origin',
+    'https://example.com',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(nestedDiscovery.stdout, new RegExp(`Source: ${serverUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/nested-discovery\\.json`))
+  assert.match(nestedDiscovery.stdout, new RegExp(`Document: ${serverUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/items\\.json`))
+  assert.match(nestedDiscovery.stdout, /Premium routing recommendations/)
+
+  const stringEndpoints = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    `${serverUrl}/string-endpoints.json`,
+    '--origin',
+    'https://example.com',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(stringEndpoints.stdout, /string-paid/)
+  assert.match(stringEndpoints.stdout, /string-post/)
+  assert.match(stringEndpoints.stdout, /tool-paid/)
+  assert.match(stringEndpoints.stdout, /Probed endpoints: 3/)
+  assert.match(stringEndpoints.stdout, /\$0\.02/)
+  assert.match(stringEndpoints.stdout, /\$0\.04/)
+  assert.match(stringEndpoints.stdout, /\$0\.08/)
+
   const linkedOpenApi = await execFileAsync('node', [
     'bin/x402-surface-check.mjs',
     `${serverUrl}/openapi-link.json`,