x402-surface-check 0.2.37 → 0.2.39

package/README.md

@@ -20,7 +20,7 @@ npx --yes x402-surface-check --strict-proof https://api.example.com/openapi.json
 
 ## What It Checks
 
-- Manifest endpoint discovery from `items[]`, `endpoints[]`, object-valued `endpoints`, string-valued endpoint maps, `tools` maps, `resources[]`, `x402Endpoints`, category arrays, raw resource URL strings, method-prefixed resource strings, and OpenAPI paths
+- Manifest endpoint discovery from `items[]`, `endpoints[]`, marketplace `skills[]` / `catalog.skills[]`, object-valued `endpoints`, string-valued endpoint maps, `tools` maps, `resources[]`, `x402Endpoints`, category arrays, raw resource URL strings, method-prefixed resource strings, and OpenAPI paths
 - Streamable HTTP MCP tool catalogs via safe JSON-RPC `tools/list` probes with `Accept: application/json, text/event-stream`
 - Object-valued manifest endpoint query examples, public catalog/discovery GETs, and payment-bearing two-phase operations without treating expected public catalog reads as failed payment gates
 - Linked discovery documents via `discovery_url`, `discoveryUrl`, `resources_url`, `resourcesUrl`, string `discovery` links, nested `discovery.x402_json` / OpenAPI links, or manifest-level OpenAPI links
@@ -40,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

@@ -358,6 +358,24 @@ function manifestEndpointBody(endpoint, document) {
   return exampleValue(body, document)
 }
 
+function marketplaceSkillBody(skill) {
+  return skill?.example?.input
+    ?? skill?.exampleInput
+    ?? skill?.input?.example
+    ?? skill?.input?.safe_example
+    ?? skill?.input?.safeExample
+    ?? manifestEndpointBody(skill, {})
+}
+
+function marketplaceSkillPriceUsd(skill) {
+  const value = skill?.price?.amount
+    ?? skill?.price?.usd
+    ?? skill?.priceUsd
+    ?? skill?.price_usd
+    ?? skill?.pricePerCall
+  return numberFromDecimal(value)
+}
+
 function manifestEndpointUrl(rawPath, endpoint, baseUrl, sourceUrl) {
   const url = new URL(endpointUrl(rawPath, baseUrl, sourceUrl))
   const parameters = endpoint?.parameters
@@ -404,6 +422,29 @@ function endpointEntries(document, sourceUrl, limit) {
     }
   }
 
+  const marketplaceSkillLists = [
+    document.skills,
+    document.services,
+    document.catalog?.skills,
+    document.catalog?.services,
+  ].filter(Array.isArray)
+
+  for (const skillList of marketplaceSkillLists) {
+    for (const skill of skillList) {
+      if (!skill || typeof skill !== 'object') continue
+      const rawPath = skill.endpoint ?? skill.url ?? skill.path
+      if (!rawPath) continue
+      if (redactedCredentialUrl(rawPath)) continue
+      entries.push({
+        name: skill.slug ?? skill.id ?? skill.name ?? String(rawPath).split('/').filter(Boolean).at(-1) ?? String(rawPath),
+        url: endpointUrl(rawPath, baseUrl, sourceUrl),
+        method: String(skill.method ?? 'POST').toUpperCase(),
+        expectedPriceUsd: marketplaceSkillPriceUsd(skill),
+        requestBody: marketplaceSkillBody(skill),
+      })
+    }
+  }
+
   if (Array.isArray(document.endpoints)) {
     for (const endpoint of document.endpoints) {
       const rawPath = endpoint?.url ?? endpoint?.endpoint ?? endpoint?.path
@@ -1051,6 +1092,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 ?? ''
 }
@@ -1222,11 +1325,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.`)
     }
@@ -1358,6 +1462,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.'
   }
@@ -1402,13 +1509,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
@@ -1416,7 +1531,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.37",
+  "version": "0.2.39",
   "description": "No-payment x402 public-surface checker for manifests, OpenAPI specs, and HTTP 402 challenges.",
   "type": "module",
   "bin": {