x402-surface-check 0.2.6 → 0.2.8

package/README.md

@@ -18,13 +18,26 @@ npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/
 - No-payment HTTP 402 challenge shape
 - x402 v1 and v2 price fields
 - MPP `WWW-Authenticate: Payment` and x402 V2 `WWW-Authenticate: X402 requirements=...` challenges
-- `amount` / `maxAmountRequired`, `asset`, `network`, and `payTo`
+- Atomic-unit `amount` / `maxAmountRequired` fields, plus legacy decimal `amount` + `token` x402 v1 challenges
+- `asset` or token metadata, `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
+- Object-valued document metadata such as facilitator objects, without `[object Object]` report artifacts
+
+## Public Proof
+
+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
+- 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
 
 ## Options
 

package/bin/x402-surface-check.mjs

@@ -88,6 +88,16 @@ function moneyFromAtomic(amount, decimals = 6) {
   })}`
 }
 
+function moneyFromDecimal(amount) {
+  if (amount === '' || amount === null || amount === undefined) return ''
+  const numeric = Number(amount)
+  if (!Number.isFinite(numeric)) return String(amount ?? '')
+  return `$${numeric.toLocaleString(undefined, {
+    maximumFractionDigits: 6,
+    minimumFractionDigits: numeric < 0.01 ? 3 : 2,
+  })}`
+}
+
 function uniqueEntries(entries, limit) {
   const seen = new Set()
   return entries
@@ -264,6 +274,7 @@ function parsePaymentAuthenticate(value) {
       maxTimeoutSeconds: '',
       extra: {
         description: request.description ?? '',
+        decimals: request.methodDetails?.decimals ?? '',
         expires: params.expires ?? '',
         id: params.id ?? '',
         intent: params.intent ?? '',
@@ -365,6 +376,24 @@ function valueList(value) {
   return []
 }
 
+function displayMetadataValue(value) {
+  if (value === null || value === undefined || value === '') return '-'
+  if (Array.isArray(value)) {
+    return value.map(displayMetadataValue).filter(item => item && item !== '-').join(', ') || '-'
+  }
+  if (typeof value === 'object') {
+    const parts = [
+      value.name,
+      value.operator,
+      value.url,
+      value.jurisdiction,
+      value.network,
+    ].filter(item => item !== null && item !== undefined && item !== '').map(String)
+    return parts.join(' / ') || Object.keys(value).join(', ') || '-'
+  }
+  return String(value)
+}
+
 function capabilityList(value) {
   if (!Array.isArray(value)) return []
   return value.map(item => item?.id ?? item?.name ?? item).filter(Boolean).map(String)
@@ -374,6 +403,36 @@ function challengeAccepts(result) {
   return Array.isArray(result.body.json?.accepts) ? result.body.json.accepts : []
 }
 
+function acceptAmountValue(accept) {
+  return accept.maxAmountRequired ?? accept.maxAmount ?? accept.amount ?? ''
+}
+
+function acceptAssetValue(accept) {
+  return accept.asset ?? accept.token ?? accept.currency ?? ''
+}
+
+function acceptDecimals(accept) {
+  const value = accept.decimals ?? accept.extra?.decimals ?? accept.methodDetails?.decimals
+  const numeric = Number(value)
+  return Number.isFinite(numeric) ? numeric : 6
+}
+
+function usesDecimalAmount(accept, result) {
+  if (accept.maxAmountRequired !== undefined || accept.maxAmount !== undefined) return false
+  if (accept.amount === undefined || accept.amount === null || accept.amount === '') return false
+  const amount = String(accept.amount)
+  if (amount.includes('.')) return true
+  if (!accept.asset && (accept.token || result.headers?.['x-payment-token'])) return true
+  return result.headers?.['x-payment-amount'] === amount
+}
+
+function challengePrice(accept, result) {
+  const amount = acceptAmountValue(accept)
+  return usesDecimalAmount(accept, result)
+    ? moneyFromDecimal(amount)
+    : moneyFromAtomic(amount, acceptDecimals(accept))
+}
+
 function hasPaymentChallenge(result) {
   const challenge = result.body.json
   return challengeAccepts(result).length > 0 || Boolean(challenge?.resource || challenge?.payment || result.headers?.['www-authenticate'])
@@ -383,7 +442,7 @@ function challengeSummary(result) {
   const challenge = result.body.json
   const firstAccept = challenge?.accepts?.[0] ?? {}
   const hasChallenge = hasPaymentChallenge(result)
-  const amount = firstAccept.amount ?? firstAccept.maxAmountRequired ?? firstAccept.maxAmount ?? ''
+  const amount = acceptAmountValue(firstAccept)
   const resourceUrl = challenge?.resource?.url ?? firstAccept.resource ?? ''
   const extraResource = firstAccept.extra?.resource ?? firstAccept.resource ?? ''
 
@@ -393,9 +452,9 @@ function challengeSummary(result) {
     resourceUrl,
     network: firstAccept.network ?? '',
     amount,
-    price: moneyFromAtomic(amount),
+    price: hasChallenge ? challengePrice(firstAccept, result) : '',
     payTo: firstAccept.payTo ?? '',
-    asset: firstAccept.asset ?? '',
+    asset: acceptAssetValue(firstAccept),
     timeout: firstAccept.maxTimeoutSeconds ?? '',
     extraResource,
   }
@@ -520,7 +579,7 @@ function formatMarkdown(report) {
     `- Type: ${report.directEndpoint ? 'direct endpoint' : (document.openapi ? 'OpenAPI' : 'x402 manifest or JSON document')}`,
     `- Agent: ${document.agent?.name ?? '-'}`,
     `- Wallet: ${document.agent?.wallet ?? '-'}`,
-    `- Facilitator: ${document.facilitator ?? '-'}`,
+    `- Facilitator: ${displayMetadataValue(document.facilitator)}`,
     `- Networks: ${valueList(document.networks).join(', ') || '-'}`,
     `- Capabilities: ${capabilityList(document.capabilities).join(', ') || '-'}`,
     `- Probed endpoints: ${report.entries.length}`,

package/package.json

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