x402-surface-check 0.2.35 → 0.2.37

package/README.md

@@ -30,6 +30,8 @@ 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
+- x402 challenges nested inside framework error wrappers such as FastAPI-style `{"detail": {...}}`
+- 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

package/bin/x402-surface-check.mjs

@@ -648,6 +648,29 @@ function parseX402Authenticate(value) {
   }
 }
 
+function bodyChallengeJson(value) {
+  if (!value || typeof value !== 'object') return null
+  if (Array.isArray(value.accepts) || Array.isArray(value.schemes)) return value
+
+  const candidates = [
+    value.detail,
+    value.error,
+    value.payment,
+    value.paymentRequired,
+    value.payment_required,
+    value.challenge,
+    value.x402,
+  ]
+
+  for (const candidate of candidates) {
+    if (!candidate || typeof candidate !== 'object') continue
+    const nested = bodyChallengeJson(candidate)
+    if (nested) return nested
+  }
+
+  return null
+}
+
 async function fetchDocument(url) {
   const response = await fetch(url, {
     headers: {
@@ -750,7 +773,11 @@ async function probeEndpoint(entry, origin) {
   const authenticateChallenge = parsePaymentAuthenticate(response.headers.get('www-authenticate'))
     ?? parseX402Authenticate(response.headers.get('www-authenticate'))
 
-  const bodyHasChallenge = Array.isArray(body.json?.accepts) || Array.isArray(body.json?.schemes)
+  const bodyChallenge = bodyChallengeJson(body.json)
+  const bodyHasChallenge = Boolean(bodyChallenge)
+  if (bodyChallenge && body.json !== bodyChallenge) {
+    body.json = bodyChallenge
+  }
   if (!bodyHasChallenge) {
     if (headerChallenge && typeof headerChallenge === 'object') {
       body.json = headerChallenge
@@ -1084,6 +1111,17 @@ function hasMppRetryChallenge(result) {
   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))
 }
@@ -1160,6 +1198,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
     }
 
@@ -1238,7 +1280,7 @@ 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.`)
@@ -1250,7 +1292,7 @@ function findingList(documentResult, challengeResults, preflightResults, entries
         : `allow headers: ${allowed || 'none'}`
       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')) {
+    if ((hasMppRetryChallenge(challengeResult) || advertisesMppDiscovery(challengeResult)) && !headerListAllows(allowed, 'authorization')) {
       const observed = result.status >= 400
         ? `HTTP ${result.status}; allow headers: ${allowed || 'none'}`
         : `allow headers: ${allowed || 'none'}`

package/package.json

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