x402-surface-check 0.2.34 → 0.2.36

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+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 payment retry headers, 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
@@ -30,6 +30,7 @@ npx --yes x402-surface-check --strict-proof https://api.example.com/openapi.json
 - No-payment HTTP 402 challenge shape
 - x402 v1 and v2 price fields, including `accepts[]` and `schemes[]` challenge arrays
 - MPP `WWW-Authenticate: Payment` and x402 V2 `WWW-Authenticate: X402 requirements=...` challenges
+- MPP descriptor-only 402s that advertise discovery headers but do not return a machine-readable payment retry challenge
 - Atomic-unit `amount` / `maxAmountRequired` fields, plus legacy decimal `amount` + `token` x402 v1 challenges
 - `asset` or token metadata, `network`, and `payTo`
 - OpenAPI-declared `x-payment-info.price.amount` drift versus the live 402 challenge price
@@ -38,7 +39,7 @@ npx --yes x402-surface-check --strict-proof https://api.example.com/openapi.json
 - 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, `X-PAYMENT`, and exposed challenge/session headers on the actual 402 response
+- Browser CORS allowance for the requesting origin, common x402/MPP retry headers, and exposed challenge/session headers on the actual 402 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

package/bin/x402-surface-check.mjs

@@ -785,7 +785,7 @@ async function probePreflight(entry, origin) {
     headers: {
       origin,
       'access-control-request-method': entry.method ?? 'POST',
-      'access-control-request-headers': 'content-type,x-payment',
+      'access-control-request-headers': 'content-type,x-payment,payment-signature,authorization',
     },
   })
 
@@ -1070,6 +1070,35 @@ function missingExposedPaymentHeaders(result) {
   return critical.filter(name => !headerListAllows(expose, name))
 }
 
+function hasX402RetryChallenge(result) {
+  if (['payment-required', 'x-payment-required'].includes(result.challengeHeaderName)) return true
+  return challengeAccepts(result).some(accept => {
+    const scheme = String(accept.scheme ?? '').toLowerCase()
+    return scheme === 'exact' || scheme.includes('x402')
+  })
+}
+
+function hasMppRetryChallenge(result) {
+  const authenticate = String(result.headers?.['www-authenticate'] ?? '')
+  if (/^\s*payment\b/i.test(authenticate)) return true
+  return challengeAccepts(result).some(accept => String(accept.scheme ?? '').toLowerCase() === 'mpp')
+}
+
+function mppDiscoveryHeaders(headers = {}) {
+  return [
+    'x-mpp-descriptor',
+    'x-agent-card',
+  ].filter(name => headers[name] !== undefined && headers[name] !== '')
+}
+
+function advertisesMppDiscovery(result) {
+  return mppDiscoveryHeaders(result.headers).length > 0
+}
+
+function allowsAnyHeader(headerValue = '', names = []) {
+  return names.some(name => headerListAllows(headerValue, name))
+}
+
 function entryKey(entry) {
   return `${entry.method ?? 'POST'} ${entry.url}`
 }
@@ -1142,6 +1171,10 @@ function findingList(documentResult, challengeResults, preflightResults, entries
     }
 
     if (!hasChallenge) {
+      const descriptorHeaders = mppDiscoveryHeaders(result.headers)
+      if (result.status === 402 && descriptorHeaders.length > 0) {
+        findings.push(`P1 - ${result.name} returns 402 and advertises MPP discovery via ${descriptorHeaders.join(', ')}, but does not include a WWW-Authenticate: Payment challenge or machine-readable body challenge; autonomous callers cannot construct a paid retry from this response alone.`)
+      }
       continue
     }
 
@@ -1220,17 +1253,23 @@ function findingList(documentResult, challengeResults, preflightResults, entries
 
   for (const result of preflightResults) {
     const challengeResult = challengesByEntry.get(entryKey(result))
-    if (!challengeResult || (!hasPaymentChallenge(challengeResult) && !advertisesPaymentEnforcement(challengeResult.headers))) continue
+    if (!challengeResult || (!hasPaymentChallenge(challengeResult) && !advertisesPaymentEnforcement(challengeResult.headers) && !advertisesMppDiscovery(challengeResult))) 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.`)
     }
     const allowed = result.headers['access-control-allow-headers'] ?? ''
-    if (allowed !== '*' && !/x-payment/i.test(allowed)) {
+    if (hasX402RetryChallenge(challengeResult) && !allowsAnyHeader(allowed, ['x-payment', 'payment-signature'])) {
       const observed = result.status >= 400
         ? `HTTP ${result.status}; allow headers: ${allowed || 'none'}`
         : `allow headers: ${allowed || 'none'}`
-      findings.push(`P1 - ${result.name} CORS preflight does not allow X-PAYMENT; observed ${observed}.`)
+      findings.push(`P1 - ${result.name} CORS preflight does not allow a known x402 retry header (X-PAYMENT or PAYMENT-SIGNATURE); observed ${observed}.`)
+    }
+    if ((hasMppRetryChallenge(challengeResult) || advertisesMppDiscovery(challengeResult)) && !headerListAllows(allowed, 'authorization')) {
+      const observed = result.status >= 400
+        ? `HTTP ${result.status}; allow headers: ${allowed || 'none'}`
+        : `allow headers: ${allowed || 'none'}`
+      findings.push(`P1 - ${result.name} CORS preflight does not allow Authorization for MPP retry; observed ${observed}.`)
     }
     const allowedMethods = result.headers['access-control-allow-methods'] ?? ''
     if (/delete|put|patch/i.test(allowedMethods)) {
@@ -1256,8 +1295,11 @@ function groupedFindingLabel(finding) {
   if (/CORS preflight does not allow the requesting origin/.test(finding)) {
     return 'P1 - CORS preflight does not allow the requesting origin.'
   }
-  if (/CORS preflight does not allow X-PAYMENT/.test(finding)) {
-    return 'P1 - CORS preflight does not allow X-PAYMENT.'
+  if (/CORS preflight does not allow a known x402 retry header/.test(finding)) {
+    return 'P1 - CORS preflight does not allow a known x402 retry header.'
+  }
+  if (/CORS preflight does not allow Authorization for MPP retry/.test(finding)) {
+    return 'P1 - CORS preflight does not allow Authorization for MPP retry.'
   }
   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.'
@@ -1312,7 +1354,7 @@ function referenceGuides(findings) {
     if (!guides.some(guide => guide.url === url)) guides.push({ label, url })
   }
   const text = findings.join('\n')
-  if (/CORS|402 challenge response does not allow the requesting origin|X-PAYMENT/i.test(text)) {
+  if (/CORS|402 challenge response does not allow the requesting origin|X-PAYMENT|PAYMENT-SIGNATURE|MPP retry/i.test(text)) {
     add('x402 CORS Fix', 'https://tateprograms.com/x402-cors-fix.html')
     add('Cloudflare x402 Worker Starter', 'https://tateprograms.com/cloudflare-x402-worker.html')
   }

package/package.json

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