x402-surface-check 0.2.23 → 0.2.25

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
@@ -33,6 +34,7 @@ npx --yes x402-surface-check --strict-cache https://api.example.com/openapi.json
 - HTTPS resource URLs and stable resource metadata
 - 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
+- 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
 - Over-broad public method surfaces
@@ -51,6 +53,7 @@ Recent public no-payment checks have found and verified real launch fixes:
 - 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: three no-payment passes converged on zero findings after discovery, browser preflight, cache, and resource-echo fixes. https://github.com/solana-foundation/pay-skills/pull/23#issuecomment-4467597309
+- SolSentry: x402 stats endpoint flagged for returning `200` content while headers advertised payment enforcement and browser preflight omitted `X-PAYMENT`. https://github.com/solsentry/solsentry-app/issues/2
 - 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
 - Tetrac: Solana market-data payment gates verified, with browser payment-header preflight blocker isolated. https://github.com/solana-foundation/pay-skills/pull/32#issuecomment-4455923744
 

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) {
@@ -710,6 +769,24 @@ function cachePolicy(headers = {}) {
   return headers['cache-control'] ?? headers.cacheControl ?? ''
 }
 
+function paymentSignalHeaders(headers = {}) {
+  return [
+    'x-payment-required',
+    'x-payment-enforce',
+    'x-price-usdc',
+    'x-payment-address',
+    'x-payment-network',
+    'x-payment-token',
+    'x-payment-protocol',
+  ].filter(name => headers[name] !== undefined && headers[name] !== '')
+}
+
+function advertisesPaymentEnforcement(headers = {}) {
+  const required = String(headers['x-payment-required'] ?? '').toLowerCase() === 'true'
+  const enforced = String(headers['x-payment-enforce'] ?? '').toLowerCase() === 'true'
+  return required || enforced || (required && paymentSignalHeaders(headers).length > 1)
+}
+
 function looksExplicitlyCacheable(headers = {}) {
   const policy = cachePolicy(headers)
   if (!policy) return false
@@ -750,11 +827,21 @@ 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)) {
           findings.push(`P3 - ${result.name} returned ${result.status} without a payment challenge for a no-payment ${result.method ?? 'POST'} probe; document this as free/trial access or move the 402 challenge before content.`)
         }
+        if (advertisesPaymentEnforcement(result.headers)) {
+          findings.push(`P2 - ${result.name} returned ${result.status} content while payment headers advertise enforcement (${paymentSignalHeaders(result.headers).join(', ')}); either return a 402 before content or document this endpoint as public telemetry.`)
+        }
       }
       else if (result.status === 400 || result.status === 422) {
         findings.push(`P1 - ${result.name} returned validation HTTP ${result.status} before a payment challenge for a no-payment ${result.method ?? 'POST'} probe.`)
@@ -807,7 +894,7 @@ function findingList(documentResult, challengeResults, preflightResults, entries
 
   for (const result of preflightResults) {
     const challengeResult = challengesByEntry.get(entryKey(result))
-    if (!challengeResult || !hasPaymentChallenge(challengeResult)) continue
+    if (!challengeResult || (!hasPaymentChallenge(challengeResult) && !advertisesPaymentEnforcement(challengeResult.headers))) continue
     const allowedOrigin = result.headers['access-control-allow-origin'] ?? ''
     if (!allowedOrigin) {
       findings.push(`P1 - ${result.name} CORS preflight does not allow the requesting origin; observed allow-origin: none.`)
@@ -864,6 +951,9 @@ function groupedFindingLabel(finding) {
   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 (/content while payment headers advertise enforcement/.test(finding)) {
+    return 'P2 - Payment headers advertise enforcement on a 200 response.'
+  }
   return null
 }
 

package/package.json

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