x402-surface-check 0.2.9 → 0.2.11

package/README.md

@@ -20,12 +20,14 @@ npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/
 - MPP `WWW-Authenticate: Payment` and x402 V2 `WWW-Authenticate: X402 requirements=...` challenges
 - 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
 - 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
+- Operational health/status endpoints, without treating expected free health checks as paid-route failures
 - Object-valued document metadata such as facilitator objects, without `[object Object]` report artifacts
 
 ## Public Proof
@@ -35,6 +37,8 @@ Recent public no-payment checks have found and verified real launch fixes:
 - TensorFeed: parameter-required premium routes moved behind canonical x402 V2 challenges, then verified clean. https://github.com/solana-foundation/pay-skills/pull/68#issuecomment-4455360068
 - x402jp: weather routes that returned 500 now return structured Base x402 challenges. https://github.com/solana-foundation/pay-skills/pull/58#issuecomment-4455401355
 - Spraay: resource echo and browser payment-header behavior verified clean. https://github.com/solana-foundation/pay-skills/pull/60#issuecomment-4455519760
+- UZPROOF: schemes-style Solana x402 challenge and browser payment-header behavior verified clean. https://github.com/solana-foundation/pay-skills/pull/28#issuecomment-4455613892
+- HYRE Agent: OpenAPI-declared prices found 10x below live 402 challenge prices. https://github.com/solana-foundation/pay-skills/pull/19#issuecomment-4455641258
 - Agent Trust Bench: live discovery URL and browser-compatibility notes for adversarial agent-payment resources. https://github.com/solana-foundation/pay-skills/pull/23#issuecomment-4455484414
 
 Field notes and browser version: https://tateprograms.com/x402-surface-check.html

package/bin/x402-surface-check.mjs

@@ -98,6 +98,11 @@ function moneyFromDecimal(amount) {
   })}`
 }
 
+function numberFromDecimal(amount) {
+  const numeric = Number(amount)
+  return Number.isFinite(numeric) ? numeric : null
+}
+
 function uniqueEntries(entries, limit) {
   const seen = new Set()
   return entries
@@ -127,6 +132,15 @@ function endpointUrl(rawPath, baseUrl, sourceUrl) {
   return new URL(value, base).toString()
 }
 
+function operationExpectedPrice(operation) {
+  const price = operation?.['x-payment-info']?.price
+    ?? operation?.['x-payment']?.price
+    ?? operation?.payment?.price
+  const amount = price?.amount ?? price?.amountUsd ?? price?.usd
+  const numeric = numberFromDecimal(amount)
+  return numeric === null ? null : numeric
+}
+
 function endpointEntries(document, sourceUrl, limit) {
   const entries = []
   const baseUrl = documentBaseUrl(document, sourceUrl)
@@ -189,6 +203,7 @@ function endpointEntries(document, sourceUrl, limit) {
           name: operation.operationId ?? `${method.toUpperCase()} ${path}`,
           url,
           method: method.toUpperCase(),
+          expectedPriceUsd: operationExpectedPrice(operation),
         })
       }
     }
@@ -437,6 +452,14 @@ function challengePrice(accept, result) {
     : moneyFromAtomic(amount, acceptDecimals(accept))
 }
 
+function challengePriceUsd(accept, result) {
+  const amount = acceptAmountValue(accept)
+  if (usesDecimalAmount(accept, result)) return numberFromDecimal(amount)
+  const numeric = Number(amount)
+  if (!Number.isFinite(numeric)) return null
+  return numeric / (10 ** acceptDecimals(accept))
+}
+
 function hasPaymentChallenge(result) {
   const challenge = result.body.json
   return challengeAccepts(result).length > 0 || Boolean(challenge?.resource || challenge?.payment || result.headers?.['www-authenticate'])
@@ -457,6 +480,8 @@ function challengeSummary(result) {
     network: firstAccept.network ?? '',
     amount,
     price: hasChallenge ? challengePrice(firstAccept, result) : '',
+    priceUsd: hasChallenge ? challengePriceUsd(firstAccept, result) : null,
+    expectedPriceUsd: typeof result.expectedPriceUsd === 'number' ? result.expectedPriceUsd : null,
     payTo: firstAccept.payTo ?? '',
     asset: acceptAssetValue(firstAccept),
     timeout: firstAccept.maxTimeoutSeconds ?? '',
@@ -476,11 +501,21 @@ function looksLikePlaceholderPayTo(payTo) {
   return false
 }
 
+function entryKey(entry) {
+  return `${entry.method ?? 'POST'} ${entry.url}`
+}
+
+function looksLikeOperationalHealthEndpoint(result) {
+  const value = `${result.name ?? ''} ${new URL(result.url).pathname}`.toLowerCase()
+  return /(^|[/_\s-])(health|healthz|ready|readiness|live|liveness|status)([/_\s-]|$)/.test(value)
+}
+
 function findingList(documentResult, challengeResults, preflightResults, entries) {
   const document = documentResult.body.json ?? {}
   const findings = []
   const networks = valueList(document.networks)
   const challengeNetworks = new Set()
+  const challengesByEntry = new Map(challengeResults.map(result => [entryKey(result), result]))
 
   if (documentResult.status < 200 || documentResult.status >= 300) {
     findings.push(`P1 - Document returned HTTP ${documentResult.status}; expected a successful JSON response.`)
@@ -501,7 +536,9 @@ function findingList(documentResult, challengeResults, preflightResults, entries
 
     if (result.status !== 402) {
       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.`)
+        if (!looksLikeOperationalHealthEndpoint(result)) {
+          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.`)
@@ -524,6 +561,12 @@ function findingList(documentResult, challengeResults, preflightResults, entries
     if (!summary.amount || !summary.payTo || !summary.asset) {
       findings.push(`P1 - ${result.name} challenge is missing amount/maxAmountRequired, payTo, or asset metadata.`)
     }
+    if (summary.expectedPriceUsd !== null && summary.priceUsd !== null) {
+      const delta = Math.abs(summary.expectedPriceUsd - summary.priceUsd)
+      if (delta > 0.000001) {
+        findings.push(`P1 - ${result.name} documented price ${moneyFromDecimal(summary.expectedPriceUsd)} does not match live 402 challenge price ${moneyFromDecimal(summary.priceUsd)}.`)
+      }
+    }
     for (const accept of challengeAccepts(result)) {
       if (looksLikePlaceholderPayTo(accept.payTo)) {
         findings.push(`P1 - ${result.name} challenge advertises placeholder-looking payTo ${accept.payTo}; production listings should not ask agents to pay placeholder recipients.`)
@@ -538,9 +581,14 @@ function findingList(documentResult, challengeResults, preflightResults, entries
   }
 
   for (const result of preflightResults) {
+    const challengeResult = challengesByEntry.get(entryKey(result))
+    if (!challengeResult || !hasPaymentChallenge(challengeResult)) continue
     const allowed = result.headers['access-control-allow-headers'] ?? ''
     if (allowed !== '*' && !/x-payment/i.test(allowed)) {
-      findings.push(`P1 - ${result.name} CORS preflight does not allow X-PAYMENT; observed allow headers: ${allowed || 'none'}.`)
+      const observed = result.status >= 400
+        ? `HTTP ${result.status}; allow headers: ${allowed || 'none'}`
+        : `allow headers: ${allowed || 'none'}`
+      findings.push(`P1 - ${result.name} CORS preflight does not allow X-PAYMENT; observed ${observed}.`)
     }
     const allowedMethods = result.headers['access-control-allow-methods'] ?? ''
     if (/delete|put|patch/i.test(allowedMethods)) {

package/package.json

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