x402-surface-check 0.2.2 → 0.2.4

package/README.md

@@ -17,13 +17,14 @@ 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
 - HTTPS resource URLs and stable resource metadata
 - Browser CORS allowance for `X-PAYMENT`
 - Over-broad public method surfaces
+- Auth, validation, and free/trial responses that appear before a payment challenge, without piling on missing-field findings when no challenge was actually returned
 
 ## Options
 

package/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
     }
   }
 
@@ -350,6 +373,11 @@ function challengeAccepts(result) {
   return Array.isArray(result.body.json?.accepts) ? result.body.json.accepts : []
 }
 
+function hasPaymentChallenge(result) {
+  const challenge = result.body.json
+  return challengeAccepts(result).length > 0 || Boolean(challenge?.resource || challenge?.payment || result.headers?.['www-authenticate'])
+}
+
 function challengeSummary(result) {
   const challenge = result.body.json
   const firstAccept = challenge?.accepts?.[0] ?? {}
@@ -404,10 +432,27 @@ function findingList(documentResult, challengeResults, preflightResults, entries
   for (const result of challengeResults) {
     const summary = challengeSummary(result)
     if (summary.network) challengeNetworks.add(summary.network)
+    const hasChallenge = hasPaymentChallenge(result)
 
     if (result.status !== 402) {
-      findings.push(`P1 - ${result.name} returned ${result.status}, not 402, for a no-payment ${result.method ?? 'POST'} probe.`)
+      if (result.status >= 200 && result.status < 300) {
+        findings.push(`P3 - ${result.name} returned ${result.status} without a payment challenge for a no-payment ${result.method ?? 'POST'} probe; document this as free/trial access or move the 402 challenge before content.`)
+      }
+      else if (result.status === 400 || result.status === 422) {
+        findings.push(`P1 - ${result.name} returned validation HTTP ${result.status} before a payment challenge for a no-payment ${result.method ?? 'POST'} probe.`)
+      }
+      else if (result.status === 401 || result.status === 403) {
+        findings.push(`P2 - ${result.name} returned auth HTTP ${result.status} before a payment challenge for a no-payment ${result.method ?? 'POST'} probe; document the auth/free-tier order if this is intentional.`)
+      }
+      else {
+        findings.push(`P1 - ${result.name} returned ${result.status}, not 402, for a no-payment ${result.method ?? 'POST'} probe.`)
+      }
     }
+
+    if (!hasChallenge) {
+      continue
+    }
+
     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.2",
+  "version": "0.2.4",
   "description": "No-payment x402 public-surface checker for manifests, OpenAPI specs, and HTTP 402 challenges.",
   "type": "module",
   "bin": {