Expose header-only x402 challenge gaps

Author: TateLyman

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

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-lock.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": {

package.json

@@ -986,6 +986,35 @@ data: ${JSON.stringify({
     return
   }
 
+  if (request.url === '/hidden-header-challenge') {
+    const requirements = Buffer.from(JSON.stringify({
+      x402Version: 2,
+      error: 'payment_required',
+      resource: {
+        url: `${serverUrl}/hidden-header-challenge`,
+        description: 'Header-only browser exposure fixture',
+        mimeType: 'application/json',
+      },
+      accepts: [{
+        scheme: 'exact',
+        network: 'eip155:8453',
+        amount: '10000',
+        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        payTo: '0x549c82e6bfc54bdae9a2073744cbc2af5d1fc6d1',
+        maxTimeoutSeconds: 60,
+        resource: `${serverUrl}/hidden-header-challenge`,
+      }],
+    })).toString('base64url')
+    response.statusCode = 402
+    response.setHeader('content-type', 'application/json')
+    response.setHeader('access-control-allow-origin', '*')
+    response.setHeader('access-control-expose-headers', 'link, total')
+    response.setHeader('x-session-id', 'fixture-session')
+    response.setHeader('payment-required', requirements)
+    response.end(JSON.stringify({ error: 'payment_required' }))
+    return
+  }
+
   if (request.url === '/no-origin') {
     response.statusCode = 402
     response.setHeader('content-type', 'application/json')
@@ -1461,6 +1490,20 @@ try {
   assert.match(noOrigin.stdout, /x402 CORS Fix/)
   assert.match(noOrigin.stdout, /Cloudflare x402 Worker Starter/)
 
+  const hiddenHeader = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    '--endpoint',
+    '--method',
+    'GET',
+    `${serverUrl}/hidden-header-challenge`,
+    '--origin',
+    'https://example.com',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(hiddenHeader.stdout, /payment requirements only in the payment-required response header/)
+  assert.match(hiddenHeader.stdout, /Access-Control-Expose-Headers does not expose it/)
+  assert.match(hiddenHeader.stdout, /returns x-session-id/)
+
   const groupedNoOrigin = await execFileAsync('node', [
     'bin/x402-surface-check.mjs',
     `${serverUrl}/no-origin-list.json`,