x402-surface-check 0.2.33 → 0.2.34

package/README.md

@@ -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, `X-PAYMENT`, 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'
+          : '',
   }
 }
 
@@ -1043,6 +1053,23 @@ 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 entryKey(entry) {
   return `${entry.method ?? 'POST'} ${entry.url}`
 }
@@ -1121,6 +1148,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}.`)
     }

package/package.json

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