x402-surface-check 0.2.18 → 0.2.20

package/README.md

@@ -15,7 +15,7 @@ npx --yes x402-surface-check --endpoint --method POST --body '{"prompt":"price C
 
 ## What It Checks
 
-- Manifest endpoint discovery from `items[]`, `endpoints[]`, `resources[]`, `x402Endpoints`, category arrays, resource strings, and OpenAPI paths
+- Manifest endpoint discovery from `items[]`, `endpoints[]`, `resources[]`, `x402Endpoints`, category arrays, raw resource URL strings, method-prefixed resource strings, and OpenAPI paths
 - 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
@@ -30,6 +30,7 @@ npx --yes x402-surface-check --endpoint --method POST --body '{"prompt":"price C
 - Testnet or staging rails such as Base Sepolia and Solana devnet
 - 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
 - Grouped finding summaries for repeated route-wide issues, so large manifests keep the patch order readable
 - Over-broad public method surfaces
 - Auth, validation, and free/trial responses that appear before a payment challenge, without piling on missing-field findings when no challenge was actually returned

package/bin/x402-surface-check.mjs

@@ -394,8 +394,8 @@ function endpointEntries(document, sourceUrl, limit) {
   for (const resource of document.resources ?? []) {
     if (typeof resource === 'string') {
       const match = resource.match(/^(GET|POST|PUT|PATCH|DELETE)\s+(\S+)/i)
-      if (!match) continue
-      const [, method, rawPath] = match
+      const method = match?.[1] ?? 'GET'
+      const rawPath = match?.[2] ?? resource
       const url = rawPath.startsWith('http')
         ? rawPath
         : new URL(rawPath, document.baseUrl ?? sourceUrl).toString()
@@ -701,6 +701,17 @@ function looksLikePlaceholderPayTo(payTo) {
   return false
 }
 
+function cachePolicy(headers = {}) {
+  return headers['cache-control'] ?? headers.cacheControl ?? ''
+}
+
+function looksExplicitlyCacheable(headers = {}) {
+  const policy = cachePolicy(headers)
+  if (!policy) return false
+  if (/\b(no-store|private|no-cache)\b/i.test(policy)) return false
+  return /\b(public|s-maxage|max-age\s*=)\b/i.test(policy)
+}
+
 function entryKey(entry) {
   return `${entry.method ?? 'POST'} ${entry.url}`
 }
@@ -781,6 +792,9 @@ function findingList(documentResult, challengeResults, preflightResults, entries
     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 (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.`)
+    }
   }
 
   for (const result of preflightResults) {
@@ -862,6 +876,9 @@ function formatMarkdown(report) {
   const preflightRows = report.preflights.map(result => {
     return `| ${result.name} | ${result.method ?? 'POST'} | ${result.status} | ${result.headers['access-control-allow-origin'] ?? '-'} | ${result.headers['access-control-allow-headers'] ?? '-'} | ${result.headers['access-control-allow-methods'] ?? '-'} |`
   })
+  const cacheRows = report.challenges.map(result => {
+    return `| ${result.name} | ${result.method ?? 'POST'} | ${result.status} | ${cachePolicy(result.headers) || '-'} |`
+  })
   const findingSummary = groupedFindingSummary(report.findings)
 
   return [
@@ -896,6 +913,12 @@ function formatMarkdown(report) {
     '| --- | --- | --- | --- | --- | --- |',
     ...(preflightRows.length ? preflightRows : ['| - | - | - | - | - | - |']),
     '',
+    '## Cache Policy Map',
+    '',
+    '| Endpoint | Method | HTTP | Cache-Control |',
+    '| --- | --- | --- | --- |',
+    ...(cacheRows.length ? cacheRows : ['| - | - | - | - |']),
+    '',
     ...(findingSummary.length ? [
       '## Finding Summary',
       '',

package/package.json

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