x402-surface-check 0.2.36 → 0.2.38

package/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
+- x402 challenges nested inside framework error wrappers such as FastAPI-style `{"detail": {...}}`
 - 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`
@@ -39,6 +40,7 @@ npx --yes x402-surface-check --strict-proof https://api.example.com/openapi.json
 - HTTPS resource URLs and stable resource metadata
 - Resource binding across top-level `resource.url` and every accept leg, including localhost/private-development resource URLs that should not ship in production
 - Timeout/expiry metadata on challenges, so payment capabilities have an explicit bounded freshness window
+- Payment-metadata privacy checks for sensitive resource query context, email/SSN/token-like values, prompt/private-context strings, and credential-like URLs in body or header-carried challenges
 - Browser CORS allowance for the requesting origin, common x402/MPP retry headers, and exposed challenge/session headers on the actual 402 response
 - Cache-Control posture on no-payment challenge responses, with P1 warnings for explicitly cacheable payment gates and optional strict-cache findings for missing policy headers
 - Optional strict proof/idempotency posture: mutating paid routes that do not advertise payment-identifier idempotency, and payment challenges that do not advertise signed offer/receipt evidence

package/bin/x402-surface-check.mjs

@@ -648,6 +648,29 @@ function parseX402Authenticate(value) {
   }
 }
 
+function bodyChallengeJson(value) {
+  if (!value || typeof value !== 'object') return null
+  if (Array.isArray(value.accepts) || Array.isArray(value.schemes)) return value
+
+  const candidates = [
+    value.detail,
+    value.error,
+    value.payment,
+    value.paymentRequired,
+    value.payment_required,
+    value.challenge,
+    value.x402,
+  ]
+
+  for (const candidate of candidates) {
+    if (!candidate || typeof candidate !== 'object') continue
+    const nested = bodyChallengeJson(candidate)
+    if (nested) return nested
+  }
+
+  return null
+}
+
 async function fetchDocument(url) {
   const response = await fetch(url, {
     headers: {
@@ -750,7 +773,11 @@ async function probeEndpoint(entry, origin) {
   const authenticateChallenge = parsePaymentAuthenticate(response.headers.get('www-authenticate'))
     ?? parseX402Authenticate(response.headers.get('www-authenticate'))
 
-  const bodyHasChallenge = Array.isArray(body.json?.accepts) || Array.isArray(body.json?.schemes)
+  const bodyChallenge = bodyChallengeJson(body.json)
+  const bodyHasChallenge = Boolean(bodyChallenge)
+  if (bodyChallenge && body.json !== bodyChallenge) {
+    body.json = bodyChallenge
+  }
   if (!bodyHasChallenge) {
     if (headerChallenge && typeof headerChallenge === 'object') {
       body.json = headerChallenge
@@ -1024,6 +1051,68 @@ function publicUrlCredentialFindings(value, path = 'document', depth = 0) {
   return []
 }
 
+const sensitiveQueryParamPattern =
+  /^(?:account|account[_-]?id|address|birth[_-]?date|customer|customer[_-]?id|dob|email|e[_-]?mail|full[_-]?name|message|name|phone|postal|prompt|reason|session|session[_-]?id|ssn|tax[_-]?id|user|user[_-]?id|zip)$/i
+
+function redactedSensitiveMetadataUrl(value) {
+  if (!/^https?:\/\//i.test(String(value ?? ''))) return null
+  try {
+    const url = new URL(value)
+    let changed = false
+
+    for (const [name] of Array.from(url.searchParams.entries())) {
+      if (sensitiveQueryParamPattern.test(name)) {
+        url.searchParams.set(name, 'REDACTED')
+        changed = true
+      }
+    }
+
+    return changed ? url.toString() : null
+  }
+  catch {
+    return null
+  }
+}
+
+function looksLikeSensitiveMetadataText(value) {
+  const text = String(value ?? '')
+  if (!text) return ''
+  if (/\b\d{3}-\d{2}-\d{4}\b/.test(text)) return 'SSN-like value'
+  if (/\b[A-Z0-9._%+-]+@(?!example\.com\b)(?!example\.org\b)(?!example\.net\b)[A-Z0-9.-]+\.[A-Z]{2,}\b/i.test(text)) return 'email address'
+  if (/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/.test(text)) return 'JWT-like token'
+  if (/\b(?:sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|npm_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{16,})\b/.test(text)) return 'API token-like value'
+  if (/\b(?:prompt|user message|customer note|private context)\s*[:=]\s*\S+/i.test(text)) return 'prompt or private-context text'
+  return ''
+}
+
+function metadataPrivacyFindings(value, path = 'challenge', depth = 0) {
+  if (depth > 8 || value === null || value === undefined) return []
+  if (typeof value === 'string') {
+    const credentialUrl = redactedCredentialUrl(value)
+    if (credentialUrl) {
+      return [`P2 - Payment metadata exposes credential-like URL material at ${path}: ${credentialUrl}. Move provider tokens, signatures, sessions, or API keys out of payment-visible metadata.`]
+    }
+    const sensitiveUrl = redactedSensitiveMetadataUrl(value)
+    if (sensitiveUrl) {
+      return [`P2 - Payment metadata exposes sensitive query context at ${path}: ${sensitiveUrl}. Keep resource URLs coarse and move private user context into server-side records.`]
+    }
+    const sensitiveKind = looksLikeSensitiveMetadataText(value)
+    return sensitiveKind
+      ? [`P2 - Payment metadata includes ${sensitiveKind} at ${path}. Redact or replace private context before it reaches facilitators, providers, logs, or receipts.`]
+      : []
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => metadataPrivacyFindings(item, `${path}[${index}]`, depth + 1))
+  }
+  if (typeof value === 'object') {
+    return Object.entries(value).flatMap(([key, item]) => {
+      const safeKey = /^[a-zA-Z_$][\w$-]*$/.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`
+      return metadataPrivacyFindings(item, `${path}${safeKey}`, depth + 1)
+    })
+  }
+  return []
+}
+
 function cachePolicy(headers = {}) {
   return headers['cache-control'] ?? headers.cacheControl ?? ''
 }
@@ -1195,11 +1284,12 @@ function findingList(documentResult, challengeResults, preflightResults, entries
       }
     }
     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}.`)
+      findings.push(`P1 - ${result.name} challenge uses a non-HTTPS resource URL: ${displayPaymentMetadataValue(summary.resourceUrl || summary.extraResource)}.`)
     }
     if (looksLikeLocalResourceUrl(summary.resourceUrl) || looksLikeLocalResourceUrl(summary.extraResource)) {
-      findings.push(`P1 - ${result.name} challenge binds payment to a localhost/private-development resource URL: ${summary.resourceUrl || summary.extraResource}.`)
+      findings.push(`P1 - ${result.name} challenge binds payment to a localhost/private-development resource URL: ${displayPaymentMetadataValue(summary.resourceUrl || summary.extraResource)}.`)
     }
+    findings.push(...metadataPrivacyFindings(result.body.json, `${result.name} challenge`))
     if (!summary.amount || !summary.payTo || !summary.asset) {
       findings.push(`P1 - ${result.name} challenge is missing amount/maxAmountRequired, payTo, or asset metadata.`)
     }
@@ -1331,6 +1421,9 @@ function groupedFindingLabel(finding) {
   if (/does not advertise signed offer\/receipt metadata/.test(finding)) {
     return 'P3 - Payment challenges do not advertise signed offer/receipt metadata.'
   }
+  if (/Payment metadata exposes|Payment metadata includes/.test(finding)) {
+    return 'P2 - Payment metadata exposes private or sensitive context.'
+  }
   if (/content while payment headers advertise enforcement/.test(finding)) {
     return 'P2 - Payment headers advertise enforcement on a 200 response.'
   }
@@ -1375,13 +1468,21 @@ function referenceGuides(findings) {
     add('x402 Signed Offers & Receipts', 'https://docs.x402.org/extensions/offer-receipt')
     add('x402 Attack Map 2026', 'https://tateprograms.com/x402-attack-map-2026.html')
   }
-  if (/credential-like URL material|provider tokens|API keys|registry-visible endpoint URLs/i.test(text)) {
+  if (/credential-like URL material|provider tokens|API keys|registry-visible endpoint URLs|Payment metadata exposes|Payment metadata includes|private user context|facilitators, providers, logs, or receipts/i.test(text)) {
     add('x402 Metadata Filter', 'https://tateprograms.com/x402-metadata-filter.html')
     add('Agent Commerce Gate', 'https://tateprograms.com/agent-commerce-gate.html')
   }
   return guides.map(guide => `- ${guide.label}: ${guide.url}`)
 }
 
+function displayPaymentMetadataValue(value) {
+  if (value === null || value === undefined || value === '') return '-'
+  if (typeof value !== 'string') return displayMetadataValue(value)
+  return redactedCredentialUrl(value)
+    ?? redactedSensitiveMetadataUrl(value)
+    ?? value
+}
+
 function formatMarkdown(report) {
   const document = report.document.body.json ?? {}
   const documentType = report.directEndpoint
@@ -1389,7 +1490,7 @@ function formatMarkdown(report) {
     : (report.mcpCatalog?.tools?.length ? 'Streamable HTTP MCP endpoint' : (document.openapi ? 'OpenAPI' : 'x402 manifest or JSON document'))
   const challengeRows = report.challenges.map(result => {
     const summary = challengeSummary(result)
-    return `| ${result.name} | ${result.method ?? 'POST'} | ${result.status} | ${summary.protocol || '-'} | ${summary.price || '-'} | ${summary.network || '-'} | ${summary.resourceUrl || '-'} |`
+    return `| ${result.name} | ${result.method ?? 'POST'} | ${result.status} | ${summary.protocol || '-'} | ${summary.price || '-'} | ${summary.network || '-'} | ${displayPaymentMetadataValue(summary.resourceUrl)} |`
   })
   const preflightRows = report.preflights.map(result => {
     return `| ${result.name} | ${result.method ?? 'POST'} | ${result.status} | ${result.headers['access-control-allow-origin'] ?? '-'} | ${result.headers['access-control-allow-headers'] ?? '-'} | ${result.headers['access-control-allow-methods'] ?? '-'} |`

package/package.json

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