x402-surface-check 0.2.24 → 0.2.26

package/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
@@ -31,8 +32,10 @@ npx --yes x402-surface-check --strict-cache https://api.example.com/openapi.json
 - Placeholder recipients such as zero addresses and Solana system-program values
 - Testnet or staging rails such as Base Sepolia and Solana devnet
 - HTTPS resource URLs and stable resource metadata
+- Resource binding across top-level `resource.url` and every accept leg, including localhost/private-development resource URLs that should not ship in production
+- Timeout/expiry metadata on challenges, so payment capabilities have an explicit bounded freshness window
 - Browser CORS allowance for the requesting origin and `X-PAYMENT`, including the actual 402 challenge response
-- Cache-Control posture on no-payment challenge responses, with warnings for explicitly cacheable payment gates and optional strict-cache findings for missing policy headers
+- Cache-Control posture on no-payment challenge responses, with P1 warnings for explicitly cacheable payment gates and optional strict-cache findings for missing policy headers
 - Payment-enforcement headers on `200` responses, so public telemetry/free-trial endpoints do not accidentally advertise enforced x402 while returning content before a challenge
 - Grouped finding summaries for repeated route-wide issues, so large manifests keep the patch order readable
 - Contextual reference guides for CORS, cache policy, Worker gates, resource echo, validation/auth ordering, and the May 2026 x402 attack-control map

package/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) {
@@ -640,6 +699,37 @@ function acceptDecimals(accept) {
   return Number.isFinite(numeric) ? numeric : 6
 }
 
+function acceptResourceValue(accept) {
+  return accept.resource
+    ?? accept.extra?.resource
+    ?? accept.resourceUrl
+    ?? accept.extra?.resourceUrl
+    ?? ''
+}
+
+function challengeResourceValue(challenge) {
+  return challenge?.resource?.url
+    ?? challenge?.resourceUrl
+    ?? ''
+}
+
+function hasFreshnessMetadata(challenge, accept) {
+  return [
+    challenge?.expires,
+    challenge?.expiresAt,
+    challenge?.validBefore,
+    challenge?.maxTimeoutSeconds,
+    accept?.maxTimeoutSeconds,
+    accept?.maxTimeout,
+    accept?.timeout,
+    accept?.expires,
+    accept?.expiresAt,
+    accept?.validBefore,
+    accept?.extra?.expires,
+    accept?.extra?.validBefore,
+  ].some(value => value !== undefined && value !== null && value !== '')
+}
+
 function usesDecimalAmount(accept, result) {
   const rawAmount = acceptAmountValue(accept)
   if (rawAmount === undefined || rawAmount === null || rawAmount === '') return false
@@ -675,8 +765,8 @@ function challengeSummary(result) {
   const firstAccept = challengeAccepts(result)[0] ?? {}
   const hasChallenge = hasPaymentChallenge(result)
   const amount = acceptAmountValue(firstAccept)
-  const resourceUrl = challenge?.resource?.url ?? firstAccept.resource ?? ''
-  const extraResource = firstAccept.extra?.resource ?? firstAccept.resource ?? ''
+  const resourceUrl = challengeResourceValue(challenge) || acceptResourceValue(firstAccept)
+  const extraResource = acceptResourceValue(firstAccept)
 
   return {
     status: result.status,
@@ -706,6 +796,21 @@ function looksLikePlaceholderPayTo(payTo) {
   return false
 }
 
+function looksLikeLocalResourceUrl(value) {
+  if (!/^https?:\/\//i.test(String(value ?? ''))) return false
+  try {
+    const host = new URL(value).hostname.toLowerCase()
+    return host === 'localhost'
+      || host === '0.0.0.0'
+      || host === '127.0.0.1'
+      || host === '::1'
+      || host.endsWith('.local')
+  }
+  catch {
+    return false
+  }
+}
+
 function cachePolicy(headers = {}) {
   return headers['cache-control'] ?? headers.cacheControl ?? ''
 }
@@ -768,6 +873,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)) {
@@ -798,6 +910,9 @@ function findingList(documentResult, challengeResults, preflightResults, entries
     if (summary.resourceUrl.startsWith('http://') || summary.extraResource.startsWith('http://')) {
       findings.push(`P1 - ${result.name} challenge uses a non-HTTPS resource URL: ${summary.resourceUrl || summary.extraResource}.`)
     }
+    if (looksLikeLocalResourceUrl(summary.resourceUrl) || looksLikeLocalResourceUrl(summary.extraResource)) {
+      findings.push(`P1 - ${result.name} challenge binds payment to a localhost/private-development resource URL: ${summary.resourceUrl || summary.extraResource}.`)
+    }
     if (!summary.amount || !summary.payTo || !summary.asset) {
       findings.push(`P1 - ${result.name} challenge is missing amount/maxAmountRequired, payTo, or asset metadata.`)
     }
@@ -807,7 +922,12 @@ function findingList(documentResult, challengeResults, preflightResults, entries
         findings.push(`P1 - ${result.name} documented price ${moneyFromDecimal(summary.expectedPriceUsd)} does not match live 402 challenge price ${moneyFromDecimal(summary.priceUsd)}.`)
       }
     }
-    for (const accept of challengeAccepts(result)) {
+    const accepts = challengeAccepts(result)
+    const topResource = challengeResourceValue(result.body.json)
+    const acceptResources = accepts.map(acceptResourceValue)
+    const populatedAcceptResources = acceptResources.filter(Boolean)
+
+    for (const accept of accepts) {
       if (looksLikePlaceholderPayTo(accept.payTo)) {
         findings.push(`P1 - ${result.name} challenge advertises placeholder-looking payTo ${accept.payTo}; production listings should not ask agents to pay placeholder recipients.`)
       }
@@ -815,11 +935,20 @@ function findingList(documentResult, challengeResults, preflightResults, entries
         findings.push(`P2 - ${result.name} challenge advertises staging/test network ${accept.network}; document this as demo-only until live-value payment rails are active.`)
       }
     }
-    if (!summary.resourceUrl || !summary.extraResource) {
-      findings.push(`P2 - ${result.name} challenge does not repeat the resource URL in both resource.url and accepts[0].extra.resource/resource.`)
+    if (!topResource && populatedAcceptResources.length === 0) {
+      findings.push(`P2 - ${result.name} challenge does not expose a signed/intended resource URL at the top level or in any accept leg.`)
+    }
+    else if (accepts.length > 0 && populatedAcceptResources.length < accepts.length) {
+      findings.push(`P2 - ${result.name} challenge does not repeat the resource URL in every accept leg for spend-map and replay binding.`)
+    }
+    if (topResource && populatedAcceptResources.some(resource => resource !== topResource)) {
+      findings.push(`P2 - ${result.name} challenge resource URL differs between resource.url and one or more accept legs; agents may bind the payment to inconsistent resources.`)
+    }
+    if (accepts.length > 0 && !accepts.some(accept => hasFreshnessMetadata(result.body.json, accept))) {
+      findings.push(`P2 - ${result.name} challenge does not expose timeout/expiry metadata; bounded freshness helps reduce replay windows for payment capabilities.`)
     }
     if (looksExplicitlyCacheable(result.headers)) {
-      findings.push(`P2 - ${result.name} payment challenge response is explicitly cacheable (${cachePolicy(result.headers)}); paid routes should use no-store/private cache policy or bypass shared caches.`)
+      findings.push(`P1 - ${result.name} payment challenge response is explicitly cacheable (${cachePolicy(result.headers)}); paid routes should use no-store/private cache policy or bypass shared caches.`)
     }
     else if (options.strictCache && !cachePolicy(result.headers)) {
       findings.push(`P3 - ${result.name} payment challenge response did not expose Cache-Control; for payment-gated routes, document or send no-store/private cache policy and confirm paid 200 responses are never shared-cacheable.`)
@@ -867,8 +996,8 @@ function groupedFindingLabel(finding) {
   if (/CORS preflight does not allow X-PAYMENT/.test(finding)) {
     return 'P1 - CORS preflight does not allow X-PAYMENT.'
   }
-  if (/challenge does not repeat the resource URL/.test(finding)) {
-    return 'P2 - Challenge accept legs do not repeat the resource URL for reconciliation.'
+  if (/challenge does not expose a signed\/intended resource URL|challenge does not repeat the resource URL|challenge resource URL differs/.test(finding)) {
+    return 'P2 - Challenges have incomplete or inconsistent resource binding.'
   }
   if (/returned validation HTTP \d+ before a payment challenge/.test(finding)) {
     return 'P1 - Routes return validation before a payment challenge.'
@@ -882,9 +1011,15 @@ function groupedFindingLabel(finding) {
   if (/challenge advertises placeholder-looking payTo/.test(finding)) {
     return 'P1 - Challenges advertise placeholder-looking payTo recipients.'
   }
+  if (/challenge does not expose timeout\/expiry metadata/.test(finding)) {
+    return 'P2 - Challenges do not expose timeout or expiry metadata for replay-window control.'
+  }
   if (/payment challenge response did not expose Cache-Control/.test(finding)) {
     return 'P3 - Payment challenge responses do not expose Cache-Control in strict cache mode.'
   }
+  if (/payment challenge response is explicitly cacheable/.test(finding)) {
+    return 'P1 - Payment challenge responses are explicitly cacheable.'
+  }
   if (/content while payment headers advertise enforcement/.test(finding)) {
     return 'P2 - Payment headers advertise enforcement on a 200 response.'
   }
@@ -916,11 +1051,13 @@ function referenceGuides(findings) {
     add('Cloudflare x402 Worker Starter', 'https://tateprograms.com/cloudflare-x402-worker.html')
     add('x402 Attack Map 2026', 'https://tateprograms.com/x402-attack-map-2026.html')
   }
-  if (/validation HTTP \d+ before a payment challenge|auth HTTP \d+ before a payment challenge|replay|idempotency/i.test(text)) {
+  if (/validation HTTP \d+ before a payment challenge|auth HTTP \d+ before a payment challenge|replay|idempotency|timeout\/expiry|freshness/i.test(text)) {
     add('x402 Launch Checklist', 'https://tateprograms.com/x402-launch-checklist.html')
+    add('x402 Attack Map 2026', 'https://tateprograms.com/x402-attack-map-2026.html')
   }
-  if (/resource URL|resource echo|accepts\[0\]\.extra\.resource/i.test(text)) {
+  if (/resource URL|resource echo|resource binding|accept leg|accepts\[0\]\.extra\.resource/i.test(text)) {
     add('x402 Surface Check notes', 'https://tateprograms.com/x402-surface-check.html')
+    add('x402 Attack Map 2026', 'https://tateprograms.com/x402-attack-map-2026.html')
   }
   return guides.map(guide => `- ${guide.label}: ${guide.url}`)
 }

package/package.json

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