x402-surface-check 0.2.27 → 0.2.30

package/README.md

@@ -13,13 +13,14 @@ npx --yes x402-surface-check https://api.example.com/openapi.json report.md
 npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/eth
 npx --yes x402-surface-check --endpoint --method POST --body '{"prompt":"price CPI"}' https://api.example.com/paid-post
 npx --yes x402-surface-check --strict-cache https://api.example.com/openapi.json
+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
@@ -36,6 +37,7 @@ npx --yes x402-surface-check --strict-cache https://api.example.com/openapi.json
 - 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 P1 warnings for explicitly cacheable payment gates and optional strict-cache findings for missing policy headers
+- Optional strict proof/idempotency posture: mutating paid routes that do not advertise payment-identifier idempotency, and payment challenges that do not advertise signed offer/receipt evidence
 - Payment-enforcement headers on `200` responses, so public telemetry/free-trial endpoints do not accidentally advertise enforced x402 while returning content before a challenge
 - Credential-like query params and URL userinfo inside public registry/discovery endpoint URLs, reported with redacted values so provider API keys and tokens are not repeated in scan output
 - Grouped finding summaries for repeated route-wide issues, so large manifests keep the patch order readable
@@ -75,6 +77,7 @@ x402-surface-check --endpoint --method POST <paid-endpoint-url> [output.md]
 --origin <url>   Origin to use for browser-style CORS preflight
 --limit <n>      Maximum endpoints to probe, default 6
 --strict-cache   Flag missing Cache-Control on no-payment 402 responses
+--strict-proof   Flag missing idempotency and signed offer/receipt extensions
 --json           Print JSON instead of Markdown
 --help           Show usage
 --version        Show package version
@@ -86,6 +89,7 @@ Environment variables are also supported:
 X402_CHECK_ORIGIN=https://example.com x402-surface-check https://api.example.com/openapi.json
 X402_CHECK_LIMIT=12 x402-surface-check https://api.example.com/.well-known/x402
 X402_STRICT_CACHE=1 x402-surface-check https://api.example.com/.well-known/x402
+X402_STRICT_PROOF=1 x402-surface-check https://api.example.com/.well-known/x402
 ```
 
 ## Scope

package/bin/x402-surface-check.mjs

@@ -23,6 +23,7 @@ Options:
   --origin <url>   Origin to use for browser-style CORS preflight
   --limit <n>      Maximum endpoints to probe, default ${defaultLimit}
   --strict-cache   Flag missing Cache-Control on no-payment 402 responses
+  --strict-proof   Flag missing idempotency and signed offer/receipt extensions
   --json           Print JSON instead of Markdown
   --help           Show this help
   --version        Show package version
@@ -40,6 +41,7 @@ function parseArgs(argv) {
     bodyFile: process.env.X402_CHECK_BODY_FILE,
     outputPath: '',
     strictCache: process.env.X402_STRICT_CACHE === '1',
+    strictProof: process.env.X402_STRICT_PROOF === '1',
     url: '',
   }
 
@@ -60,6 +62,9 @@ function parseArgs(argv) {
     else if (arg === '--strict-cache') {
       args.strictCache = true
     }
+    else if (arg === '--strict-proof') {
+      args.strictProof = true
+    }
     else if (arg === '--method') {
       args.method = String(argv[index + 1] ?? '').toUpperCase()
       index += 1
@@ -173,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)
@@ -326,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
@@ -397,10 +415,46 @@ 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' && !Array.isArray(document.tools)) {
+    endpointMaps.push(document.tools)
+  }
+  if (Array.isArray(document.tools)) {
+    for (const tool of document.tools) {
+      if (!tool || typeof tool !== 'object') continue
+      const rawPath = tool.url ?? tool.endpoint ?? tool.path
+      if (!rawPath) continue
+      const method = String(tool.method ?? 'POST').toUpperCase()
+      const paymentSignal = manifestEndpointPaymentSignal(tool)
+      const hasPathParameters = /\{[^}]+\}/.test(String(rawPath))
+      if (paymentSignal === 0 && (method !== 'GET' || hasPathParameters)) continue
+      entries.push({
+        name: tool.id ?? tool.name ?? String(rawPath).split('/').filter(Boolean).at(-1) ?? String(rawPath),
+        url: manifestEndpointUrl(rawPath, tool, baseUrl, sourceUrl),
+        method,
+        requestBody: manifestEndpointBody(tool, document),
+        publicDiscovery: paymentSignal === 0,
+      })
+    }
+  }
+  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)
@@ -685,6 +739,23 @@ function challengeAccepts(result) {
   return []
 }
 
+function extensionKeys(container) {
+  const extensions = container?.extensions
+  if (!extensions || typeof extensions !== 'object' || Array.isArray(extensions)) return []
+  return Object.keys(extensions)
+}
+
+function challengeExtensionKeys(result) {
+  return new Set([
+    ...extensionKeys(result.body.json),
+    ...challengeAccepts(result).flatMap(accept => extensionKeys(accept)),
+  ].map(key => key.toLowerCase()))
+}
+
+function hasChallengeExtension(result, pattern) {
+  return [...challengeExtensionKeys(result)].some(key => pattern.test(key))
+}
+
 function acceptAmountValue(accept) {
   return accept.maxAmountRequired ?? accept.maxAmount ?? accept.amount ?? ''
 }
@@ -898,6 +969,10 @@ function looksLikeOperationalHealthEndpoint(result) {
   return /(^|[/_\s-])(health|healthz|ready|readiness|live|liveness|status)([/_\s-]|$)/.test(value)
 }
 
+function isMutatingMethod(method) {
+  return !['GET', 'HEAD', 'OPTIONS'].includes(String(method ?? 'POST').toUpperCase())
+}
+
 function findingList(documentResult, challengeResults, preflightResults, entries, options = {}) {
   const document = documentResult.body.json ?? {}
   const findings = []
@@ -1005,6 +1080,15 @@ function findingList(documentResult, challengeResults, preflightResults, entries
     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.`)
     }
+
+    if (options.strictProof) {
+      if (isMutatingMethod(result.method) && !hasChallengeExtension(result, /payment[-_]?identifier|idempotenc/)) {
+        findings.push(`P2 - ${result.name} is a mutating paid route but does not advertise payment-identifier idempotency; retries after network or client failures can duplicate charges or lose paid responses without a shared payment ID.`)
+      }
+      if (!hasChallengeExtension(result, /offer[-_]?receipt|signed[-_]?(offer|receipt)/)) {
+        findings.push(`P3 - ${result.name} challenge does not advertise signed offer/receipt metadata; clients have weaker proof of committed terms and service delivery for audits or disputes.`)
+      }
+    }
   }
 
   for (const result of preflightResults) {
@@ -1072,6 +1156,12 @@ function groupedFindingLabel(finding) {
   if (/payment challenge response is explicitly cacheable/.test(finding)) {
     return 'P1 - Payment challenge responses are explicitly cacheable.'
   }
+  if (/does not advertise payment-identifier idempotency/.test(finding)) {
+    return 'P2 - Mutating paid routes do not advertise payment-identifier idempotency.'
+  }
+  if (/does not advertise signed offer\/receipt metadata/.test(finding)) {
+    return 'P3 - Payment challenges do not advertise signed offer/receipt metadata.'
+  }
   if (/content while payment headers advertise enforcement/.test(finding)) {
     return 'P2 - Payment headers advertise enforcement on a 200 response.'
   }
@@ -1111,6 +1201,11 @@ function referenceGuides(findings) {
     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')
   }
+  if (/payment-identifier|idempotency|signed offer|signed offer\/receipt|service delivery|audits|disputes/i.test(text)) {
+    add('x402 Payment-Identifier', 'https://docs.x402.org/extensions/payment-identifier')
+    add('x402 Signed Offers & Receipts', 'https://docs.x402.org/extensions/offer-receipt')
+    add('x402 Attack Map 2026', 'https://tateprograms.com/x402-attack-map-2026.html')
+  }
   if (/credential-like URL material|provider tokens|API keys|registry-visible endpoint URLs/i.test(text)) {
     add('x402 Metadata Filter', 'https://tateprograms.com/x402-metadata-filter.html')
     add('Agent Commerce Gate', 'https://tateprograms.com/agent-commerce-gate.html')
@@ -1243,6 +1338,7 @@ async function runCheck(options) {
   }
   report.findings = findingList(document, challenges, preflights, entries, {
     strictCache: options.strictCache,
+    strictProof: options.strictProof,
   })
   return report
 }

package/package.json

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