x402-surface-check 0.2.16 → 0.2.18

package/README.md

@@ -10,6 +10,7 @@ npm: https://www.npmjs.com/package/x402-surface-check
 npx --yes x402-surface-check https://api.example.com/.well-known/x402
 npx --yes x402-surface-check https://api.example.com/openapi.json report.md
 npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/eth
+npx --yes x402-surface-check --endpoint --method POST --body '{"prompt":"price CPI"}' https://api.example.com/paid-post
 ```
 
 ## What It Checks
@@ -17,7 +18,7 @@ npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/
 - Manifest endpoint discovery from `items[]`, `endpoints[]`, `resources[]`, `x402Endpoints`, category arrays, resource strings, and OpenAPI paths
 - Linked discovery documents via `discovery_url`, `discoveryUrl`, `resources_url`, `resourcesUrl`, or manifest-level OpenAPI links
 - OpenAPI `servers[]` base-path preservation, so `/paths` are probed through the documented gateway rather than the domain root
-- OpenAPI query/path examples, JSON request-body examples, and local `$ref` request schemas for safer no-payment probes
+- OpenAPI query/path examples, JSON request-body examples, nested request schemas, local `$ref` request schemas, and explicit direct-endpoint bodies for safer no-payment probes
 - OpenAPI paid-operation prioritization, so docs and discovery routes do not consume the probe limit before payment-bearing operations
 - No-payment HTTP 402 challenge shape
 - x402 v1 and v2 price fields, including `accepts[]` and `schemes[]` challenge arrays
@@ -29,6 +30,7 @@ npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/
 - Testnet or staging rails such as Base Sepolia and Solana devnet
 - HTTPS resource URLs and stable resource metadata
 - Browser CORS allowance for the requesting origin and `X-PAYMENT`, including the actual 402 challenge response
+- Grouped finding summaries for repeated route-wide issues, so large manifests keep the patch order readable
 - 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
@@ -58,6 +60,8 @@ x402-surface-check --endpoint --method POST <paid-endpoint-url> [output.md]
 
 --endpoint       Treat the URL as one paid endpoint instead of a discovery document
 --method <verb>  HTTP method for direct endpoint mode, default POST
+--body <json>    JSON request body for direct endpoint mode
+--body-file <p>  Read JSON request body for direct endpoint mode from a file
 --origin <url>   Origin to use for browser-style CORS preflight
 --limit <n>      Maximum endpoints to probe, default 6
 --json           Print JSON instead of Markdown

package/bin/x402-surface-check.mjs

@@ -18,6 +18,8 @@ Usage:
 Options:
   --endpoint       Treat the URL as one paid endpoint instead of a discovery document
   --method <verb>  HTTP method for direct endpoint mode, default POST
+  --body <json>    JSON request body for direct endpoint mode
+  --body-file <p>  Read JSON request body for direct endpoint mode from a file
   --origin <url>   Origin to use for browser-style CORS preflight
   --limit <n>      Maximum endpoints to probe, default ${defaultLimit}
   --json           Print JSON instead of Markdown
@@ -33,6 +35,8 @@ function parseArgs(argv) {
     limit: Number(process.env.X402_CHECK_LIMIT ?? defaultLimit),
     method: 'POST',
     origin: process.env.X402_CHECK_ORIGIN,
+    body: process.env.X402_CHECK_BODY,
+    bodyFile: process.env.X402_CHECK_BODY_FILE,
     outputPath: '',
     url: '',
   }
@@ -55,6 +59,14 @@ function parseArgs(argv) {
       args.method = String(argv[index + 1] ?? '').toUpperCase()
       index += 1
     }
+    else if (arg === '--body') {
+      args.body = argv[index + 1]
+      index += 1
+    }
+    else if (arg === '--body-file') {
+      args.bodyFile = argv[index + 1]
+      index += 1
+    }
     else if (arg === '--origin') {
       args.origin = argv[index + 1]
       index += 1
@@ -77,6 +89,23 @@ function parseArgs(argv) {
   return args
 }
 
+async function directEndpointRequestBody(options) {
+  if (!options.endpoint) return undefined
+  if (options.body && options.bodyFile) {
+    throw new Error('Use either --body or --body-file, not both.')
+  }
+  const raw = options.bodyFile
+    ? await readFile(options.bodyFile, 'utf8')
+    : options.body
+  if (!raw) return undefined
+  try {
+    return JSON.parse(raw)
+  }
+  catch (error) {
+    throw new Error(`Request body must be valid JSON: ${error.message}`)
+  }
+}
+
 function moneyFromAtomic(amount, decimals = 6) {
   if (amount === '' || amount === null || amount === undefined) return ''
   const numeric = Number(amount)
@@ -176,9 +205,13 @@ function resolveSchema(schema, document, seen = new Set()) {
   return resolveSchema(resolved, document, seen)
 }
 
-function exampleValue(schemaOrParameter, document) {
+function exampleValue(schemaOrParameter, document, depth = 0) {
   if (!schemaOrParameter || typeof schemaOrParameter !== 'object') return undefined
   const schema = resolveSchema(schemaOrParameter.schema ?? schemaOrParameter, document)
+  const composite = schema.oneOf ?? schema.anyOf ?? schema.allOf
+  if (Array.isArray(composite) && composite.length > 0) {
+    return exampleValue(composite[0], document, depth + 1)
+  }
   const value = schemaOrParameter.example
     ?? schema.const
     ?? schema.example
@@ -195,6 +228,25 @@ function exampleValue(schemaOrParameter, document) {
   if (schema.type === 'integer') return Number.isFinite(Number(schema.minimum)) ? Number(schema.minimum) : 1
   if (schema.type === 'number') return Number.isFinite(Number(schema.minimum)) ? Number(schema.minimum) : 1
   if (schema.type === 'boolean') return false
+  if (schema.type === 'array') {
+    if (depth > 4) return []
+    const item = exampleValue(schema.items ?? {}, document, depth + 1)
+    return item === undefined ? [] : [item]
+  }
+  if (schema.type === 'object') {
+    if (depth > 4) return {}
+    const properties = schema.properties && typeof schema.properties === 'object'
+      ? schema.properties
+      : {}
+    const required = new Set(Array.isArray(schema.required) ? schema.required : Object.keys(properties))
+    const result = {}
+    for (const [key, property] of Object.entries(properties)) {
+      if (!required.has(key)) continue
+      const nestedValue = exampleValue(property, document, depth + 1)
+      if (nestedValue !== undefined) result[key] = nestedValue
+    }
+    return result
+  }
   return undefined
 }
 
@@ -762,6 +814,45 @@ function findingList(documentResult, challengeResults, preflightResults, entries
   return findings
 }
 
+function groupedFindingLabel(finding) {
+  if (/402 challenge response does not allow the requesting origin/.test(finding)) {
+    return 'P1 - Actual 402 challenge responses do not allow the requesting origin; browser clients cannot read payment requirements.'
+  }
+  if (/CORS preflight does not allow the requesting origin/.test(finding)) {
+    return 'P1 - CORS preflight does not allow the requesting origin.'
+  }
+  if (/CORS preflight does not allow X-PAYMENT/.test(finding)) {
+    return 'P1 - CORS preflight does not allow X-PAYMENT.'
+  }
+  if (/challenge does not repeat the resource URL/.test(finding)) {
+    return 'P2 - Challenge accept legs do not repeat the resource URL for reconciliation.'
+  }
+  if (/returned validation HTTP \d+ before a payment challenge/.test(finding)) {
+    return 'P1 - Routes return validation before a payment challenge.'
+  }
+  if (/returned auth HTTP \d+ before a payment challenge/.test(finding)) {
+    return 'P2 - Routes return auth before a payment challenge.'
+  }
+  if (/challenge advertises staging\/test network/.test(finding)) {
+    return 'P2 - Challenges advertise staging or test networks.'
+  }
+  if (/challenge advertises placeholder-looking payTo/.test(finding)) {
+    return 'P1 - Challenges advertise placeholder-looking payTo recipients.'
+  }
+  return null
+}
+
+function groupedFindingSummary(findings) {
+  const counts = new Map()
+  for (const finding of findings) {
+    const label = groupedFindingLabel(finding)
+    if (label) counts.set(label, (counts.get(label) ?? 0) + 1)
+  }
+  return [...counts.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([label, count]) => `- ${count} endpoints: ${label}`)
+}
+
 function formatMarkdown(report) {
   const document = report.document.body.json ?? {}
   const challengeRows = report.challenges.map(result => {
@@ -771,6 +862,7 @@ function formatMarkdown(report) {
   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'] ?? '-'} |`
   })
+  const findingSummary = groupedFindingSummary(report.findings)
 
   return [
     '# x402 Public Surface Check',
@@ -804,6 +896,12 @@ function formatMarkdown(report) {
     '| --- | --- | --- | --- | --- | --- |',
     ...(preflightRows.length ? preflightRows : ['| - | - | - | - | - | - |']),
     '',
+    ...(findingSummary.length ? [
+      '## Finding Summary',
+      '',
+      ...findingSummary,
+      '',
+    ] : []),
     '## Findings',
     '',
     ...(report.findings.length ? report.findings.map(item => `- ${item}`) : ['- No obvious launch-readiness findings from the public no-payment probes.']),
@@ -812,6 +910,7 @@ function formatMarkdown(report) {
 }
 
 async function runCheck(options) {
+  const directRequestBody = await directEndpointRequestBody(options)
   let sourceDocument = null
   let document = options.endpoint
     ? {
@@ -823,7 +922,7 @@ async function runCheck(options) {
       }
     : await fetchDocument(options.url)
   let entries = options.endpoint
-    ? [{ name: new URL(options.url).pathname.split('/').filter(Boolean).at(-1) ?? options.url, url: options.url, method: options.method || 'POST' }]
+    ? [{ name: new URL(options.url).pathname.split('/').filter(Boolean).at(-1) ?? options.url, url: options.url, method: options.method || 'POST', requestBody: directRequestBody }]
     : (document.body.json ? endpointEntries(document.body.json, document.url, options.limit) : [])
 
   if (!options.endpoint && entries.length === 0 && document.body.json) {

package/package.json

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