x402-surface-check 0.2.21 → 0.2.23

package/README.md

@@ -5,12 +5,14 @@ No-payment CLI for checking x402 launch surfaces before a real agent spends.
 It accepts an x402 manifest or OpenAPI URL, derives public endpoints, sends no-payment probes, checks browser preflight behavior, and returns a Markdown patch queue. It never sends `X-PAYMENT`, never signs, and never attempts a paid call.
 
 npm: https://www.npmjs.com/package/x402-surface-check
+Attack-map field note: https://tateprograms.com/x402-attack-map-2026.html
 
 ```bash
 npx --yes x402-surface-check https://api.example.com/.well-known/x402
 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
 ```
 
 ## What It Checks
@@ -30,9 +32,9 @@ 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
+- Cache-Control posture on no-payment challenge responses, with warnings for explicitly cacheable payment gates and optional strict-cache findings for missing policy headers
 - 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 launch controls
+- 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
 - Auth, validation, and free/trial responses that appear before a payment challenge, without piling on missing-field findings when no challenge was actually returned
 - Operational health/status endpoints, without treating expected free health checks as paid-route failures
@@ -48,7 +50,7 @@ Recent public no-payment checks have found and verified real launch fixes:
 - UZPROOF: schemes-style Solana x402 challenge and browser payment-header behavior verified clean. https://github.com/solana-foundation/pay-skills/pull/28#issuecomment-4455613892
 - 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: linked discovery URL and browser-compatibility notes verified clean for adversarial agent-payment resources. https://github.com/solana-foundation/pay-skills/pull/23#issuecomment-4455722170
+- 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
 - 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
 
@@ -66,6 +68,7 @@ x402-surface-check --endpoint --method POST <paid-endpoint-url> [output.md]
 --body-file <p>  Read JSON request body for direct endpoint mode from a file
 --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
 --json           Print JSON instead of Markdown
 --help           Show usage
 --version        Show package version
@@ -76,6 +79,7 @@ Environment variables are also supported:
 ```bash
 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
 ```
 
 ## Scope

package/bin/x402-surface-check.mjs

@@ -22,6 +22,7 @@ Options:
   --body-file <p>  Read JSON request body for direct endpoint mode from a file
   --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
   --json           Print JSON instead of Markdown
   --help           Show this help
   --version        Show package version
@@ -38,6 +39,7 @@ function parseArgs(argv) {
     body: process.env.X402_CHECK_BODY,
     bodyFile: process.env.X402_CHECK_BODY_FILE,
     outputPath: '',
+    strictCache: process.env.X402_STRICT_CACHE === '1',
     url: '',
   }
 
@@ -55,6 +57,9 @@ function parseArgs(argv) {
     else if (arg === '--endpoint') {
       args.endpoint = true
     }
+    else if (arg === '--strict-cache') {
+      args.strictCache = true
+    }
     else if (arg === '--method') {
       args.method = String(argv[index + 1] ?? '').toUpperCase()
       index += 1
@@ -721,7 +726,7 @@ function looksLikeOperationalHealthEndpoint(result) {
   return /(^|[/_\s-])(health|healthz|ready|readiness|live|liveness|status)([/_\s-]|$)/.test(value)
 }
 
-function findingList(documentResult, challengeResults, preflightResults, entries) {
+function findingList(documentResult, challengeResults, preflightResults, entries, options = {}) {
   const document = documentResult.body.json ?? {}
   const findings = []
   const networks = valueList(document.networks)
@@ -795,6 +800,9 @@ function findingList(documentResult, challengeResults, preflightResults, entries
     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.`)
     }
+    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.`)
+    }
   }
 
   for (const result of preflightResults) {
@@ -853,6 +861,9 @@ function groupedFindingLabel(finding) {
   if (/challenge advertises placeholder-looking payTo/.test(finding)) {
     return 'P1 - Challenges advertise placeholder-looking payTo recipients.'
   }
+  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.'
+  }
   return null
 }
 
@@ -1013,7 +1024,9 @@ async function runCheck(options) {
     preflights,
     sourceDocument,
   }
-  report.findings = findingList(document, challenges, preflights, entries)
+  report.findings = findingList(document, challenges, preflights, entries, {
+    strictCache: options.strictCache,
+  })
   return report
 }
 

package/package.json

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