Flag MPP descriptor-only payment gates

Author: TateLyman

README.md

@@ -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

bin/x402-surface-check.mjs

@@ -1084,6 +1084,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 +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
     }
 
@@ -1238,7 +1253,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 +1265,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-lock.json

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

package.json

@@ -970,6 +970,21 @@ data: ${JSON.stringify({
     return
   }
 
+  if (request.url === '/mpp/descriptor-only') {
+    response.statusCode = 402
+    response.setHeader('content-type', 'application/json')
+    response.setHeader('access-control-allow-origin', '*')
+    response.setHeader('access-control-expose-headers', 'x-mpp-descriptor, x-agent-card')
+    response.setHeader('cache-control', 'no-store')
+    response.setHeader('x-mpp-descriptor', `${serverUrl}/.well-known/mpp.json`)
+    response.setHeader('x-agent-card', `${serverUrl}/.well-known/agent.json`)
+    response.end(JSON.stringify({
+      error: 'payment_required',
+      message: 'MPP payment required for tools/call',
+    }))
+    return
+  }
+
   if (request.url === '/x402v2/header') {
     const requirements = Buffer.from(JSON.stringify({
       x402Version: 2,
@@ -1440,6 +1455,20 @@ try {
   assert.match(mpp.stdout, /mainnet/)
   assert.match(mpp.stdout, /\$0\.001/)
 
+  const mppDescriptorOnly = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    '--endpoint',
+    '--method',
+    'POST',
+    `${serverUrl}/mpp/descriptor-only`,
+    '--origin',
+    'https://example.com',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(mppDescriptorOnly.stdout, /advertises MPP discovery via x-mpp-descriptor, x-agent-card/)
+  assert.match(mppDescriptorOnly.stdout, /WWW-Authenticate: Payment challenge/)
+  assert.match(mppDescriptorOnly.stdout, /CORS preflight does not allow Authorization for MPP retry/)
+
   const x402Header = await execFileAsync('node', [
     'bin/x402-surface-check.mjs',
     '--endpoint',