x402-surface-check 0.2.33 → 0.2.35

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
@@ -38,7 +38,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 and `X-PAYMENT`, including the actual 402 challenge 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

@@ -742,8 +742,10 @@ async function probeEndpoint(entry, origin) {
       : JSON.stringify(entry.requestBody ?? {}),
   })
   const body = await readText(response)
+  const paymentRequiredHeader = response.headers.get('payment-required')
+  const xPaymentRequiredHeader = response.headers.get('x-payment-required')
   const headerChallenge = parseEncodedChallenge(
-    response.headers.get('payment-required') ?? response.headers.get('x-payment-required'),
+    paymentRequiredHeader ?? xPaymentRequiredHeader,
   )
   const authenticateChallenge = parsePaymentAuthenticate(response.headers.get('www-authenticate'))
     ?? parseX402Authenticate(response.headers.get('www-authenticate'))
@@ -766,6 +768,14 @@ async function probeEndpoint(entry, origin) {
     status: response.status,
     headers: Object.fromEntries(response.headers.entries()),
     body,
+    bodyHadChallenge: bodyHasChallenge,
+    challengeHeaderName: paymentRequiredHeader
+      ? 'payment-required'
+      : xPaymentRequiredHeader
+        ? 'x-payment-required'
+        : authenticateChallenge
+          ? 'www-authenticate'
+          : '',
   }
 }
 
@@ -775,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',
     },
   })
 
@@ -1043,6 +1053,41 @@ function looksExplicitlyCacheable(headers = {}) {
   return /\b(public|s-maxage|max-age\s*=)\b/i.test(policy)
 }
 
+function headerListAllows(headerValue = '', requiredName = '') {
+  if (!requiredName) return true
+  const normalizedRequired = requiredName.toLowerCase()
+  return String(headerValue).split(',')
+    .map(item => item.trim().toLowerCase())
+    .some(item => item === '*' || item === normalizedRequired)
+}
+
+function missingExposedPaymentHeaders(result) {
+  const expose = result.headers?.['access-control-expose-headers'] ?? ''
+  const critical = [
+    result.challengeHeaderName,
+    result.headers?.['x-session-id'] !== undefined ? 'x-session-id' : '',
+  ].filter(Boolean)
+  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 allowsAnyHeader(headerValue = '', names = []) {
+  return names.some(name => headerListAllows(headerValue, name))
+}
+
 function entryKey(entry) {
   return `${entry.method ?? 'POST'} ${entry.url}`
 }
@@ -1121,6 +1166,19 @@ function findingList(documentResult, challengeResults, preflightResults, entries
     if (!result.headers?.['access-control-allow-origin']) {
       findings.push(`P1 - ${result.name} 402 challenge response does not allow the requesting origin; browser agents cannot read the payment requirements even if preflight succeeds.`)
     }
+    else {
+      const hiddenHeaders = missingExposedPaymentHeaders(result)
+      if (
+        result.challengeHeaderName
+        && hiddenHeaders.includes(result.challengeHeaderName)
+        && !result.bodyHadChallenge
+      ) {
+        findings.push(`P1 - ${result.name} carries payment requirements only in the ${result.challengeHeaderName} response header, but Access-Control-Expose-Headers does not expose it; browser agents cannot read the challenge after CORS succeeds.`)
+      }
+      if (hiddenHeaders.includes('x-session-id')) {
+        findings.push(`P2 - ${result.name} returns x-session-id for the payment retry flow, but Access-Control-Expose-Headers does not expose it to browser agents.`)
+      }
+    }
     if (summary.resourceUrl.startsWith('http://') || summary.extraResource.startsWith('http://')) {
       findings.push(`P1 - ${result.name} challenge uses a non-HTTPS resource URL: ${summary.resourceUrl || summary.extraResource}.`)
     }
@@ -1186,11 +1244,17 @@ function findingList(documentResult, challengeResults, preflightResults, entries
       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) && !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)) {
@@ -1216,8 +1280,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.'
@@ -1272,7 +1339,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.33",
+  "version": "0.2.35",
   "description": "No-payment x402 public-surface checker for manifests, OpenAPI specs, and HTTP 402 challenges.",
   "type": "module",
   "bin": {