Parse x402 v2 authenticate headers

Author: TateLyman

README.md

@@ -17,7 +17,7 @@ npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/
 - Manifest endpoint discovery from `items[]`, `endpoints[]`, `x402Endpoints`, category arrays, resource strings, and OpenAPI paths
 - No-payment HTTP 402 challenge shape
 - x402 v1 and v2 price fields
-- MPP `WWW-Authenticate: Payment` challenges
+- MPP `WWW-Authenticate: Payment` and x402 V2 `WWW-Authenticate: X402 requirements=...` challenges
 - `amount` / `maxAmountRequired`, `asset`, `network`, and `payTo`
 - Placeholder recipients such as zero addresses and Solana system-program values
 - Testnet or staging rails such as Base Sepolia and Solana devnet

bin/x402-surface-check.mjs

@@ -228,17 +228,25 @@ function parseEncodedChallenge(value) {
   }
 }
 
-function parsePaymentAuthenticate(value) {
-  if (!value || !/^Payment\s+/i.test(value)) return null
+function authenticateParams(value, scheme) {
+  const header = String(value ?? '').replace(/^www-authenticate:\s*/i, '').trim()
+  if (!header || !new RegExp(`^${scheme}\\s+`, 'i').test(header)) return null
   const params = {}
   const pattern = /([a-zA-Z][\w-]*)="([^"]*)"/g
-  let match = pattern.exec(value)
+  let match = pattern.exec(header)
 
   while (match) {
     params[match[1]] = match[2]
-    match = pattern.exec(value)
+    match = pattern.exec(header)
   }
 
+  return params
+}
+
+function parsePaymentAuthenticate(value) {
+  const params = authenticateParams(value, 'Payment')
+  if (!params) return null
+
   const request = parseEncodedChallenge(params.request)
   if (!request) return null
 
@@ -264,6 +272,19 @@ function parsePaymentAuthenticate(value) {
   }
 }
 
+function parseX402Authenticate(value) {
+  const params = authenticateParams(value, 'X402')
+  if (!params) return null
+
+  const requirements = parseEncodedChallenge(params.requirements ?? params.request)
+  if (!requirements || !Array.isArray(requirements.accepts)) return null
+
+  return {
+    protocol: requirements.protocol ?? 'x402',
+    ...requirements,
+  }
+}
+
 async function fetchDocument(url) {
   const response = await fetch(url, {
     headers: {
@@ -296,16 +317,18 @@ async function probeEndpoint(entry) {
   const headerChallenge = parseEncodedChallenge(
     response.headers.get('payment-required') ?? response.headers.get('x-payment-required'),
   )
-  const paymentChallenge = parsePaymentAuthenticate(response.headers.get('www-authenticate'))
+  const authenticateChallenge = parsePaymentAuthenticate(response.headers.get('www-authenticate'))
+    ?? parseX402Authenticate(response.headers.get('www-authenticate'))
 
   if (!body.json?.accepts?.length) {
     if (headerChallenge) {
       body.json = headerChallenge
     }
-    else if (paymentChallenge) {
-      paymentChallenge.resource.url = entry.url
-      paymentChallenge.accepts[0].resource = entry.url
-      body.json = paymentChallenge
+    else if (authenticateChallenge) {
+      authenticateChallenge.resource = authenticateChallenge.resource ?? { url: entry.url }
+      authenticateChallenge.resource.url = authenticateChallenge.resource.url || entry.url
+      authenticateChallenge.accepts[0].resource = authenticateChallenge.accepts[0].resource || entry.url
+      body.json = authenticateChallenge
     }
   }
 

package-lock.json

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

package.json

@@ -149,6 +149,31 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/x402v2/header') {
+    const requirements = Buffer.from(JSON.stringify({
+      x402Version: 2,
+      error: 'payment_required',
+      resource: {
+        url: `${serverUrl}/x402v2/header`,
+        description: 'Header-only x402 V2 fixture',
+        mimeType: 'application/json',
+      },
+      accepts: [{
+        scheme: 'exact',
+        network: 'eip155:8453',
+        amount: '20000',
+        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        payTo: '0x549c82e6bfc54bdae9a2073744cbc2af5d1fc6d1',
+        maxTimeoutSeconds: 60,
+      }],
+    })).toString('base64url')
+    response.statusCode = 402
+    response.setHeader('content-type', 'application/json')
+    response.setHeader('www-authenticate', `X402 requirements="${requirements}"`)
+    response.end(JSON.stringify({ error: 'payment_required' }))
+    return
+  }
+
   response.statusCode = 404
   response.end('not found')
 })
@@ -211,6 +236,19 @@ try {
   assert.match(mpp.stdout, /mpp/)
   assert.match(mpp.stdout, /mainnet/)
   assert.match(mpp.stdout, /\$0\.001/)
+
+  const x402Header = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    '--endpoint',
+    '--method',
+    'GET',
+    `${serverUrl}/x402v2/header`,
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(x402Header.stdout, /direct endpoint/)
+  assert.match(x402Header.stdout, /x402/)
+  assert.match(x402Header.stdout, /eip155:8453/)
+  assert.match(x402Header.stdout, /\$0\.02/)
 }
 finally {
   await new Promise(resolve => server.close(resolve))