Add grouped finding summary

Author: TateLyman

README.md

@@ -30,6 +30,7 @@ npx --yes x402-surface-check --endpoint --method POST --body '{"prompt":"price C
 - 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

bin/x402-surface-check.mjs

@@ -814,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 => {
@@ -823,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',
@@ -856,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.']),

package-lock.json

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

package.json

@@ -6,7 +6,7 @@ import { strict as assert } from 'node:assert'
 const execFileAsync = promisify(execFile)
 
 const server = createServer((request, response) => {
-  if (request.method === 'OPTIONS' && request.url === '/no-origin') {
+  if (request.method === 'OPTIONS' && (request.url === '/no-origin' || request.url === '/no-origin-2')) {
     response.statusCode = 204
     response.setHeader('access-control-allow-headers', 'content-type,x-payment')
     response.setHeader('access-control-allow-methods', 'GET, OPTIONS')
@@ -267,6 +267,23 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/no-origin-list.json') {
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({
+      x402Version: 2,
+      endpoints: [{
+        path: '/no-origin',
+        method: 'GET',
+        description: 'No CORS fixture one',
+      }, {
+        path: '/no-origin-2',
+        method: 'GET',
+        description: 'No CORS fixture two',
+      }],
+    }))
+    return
+  }
+
   if (request.url === '/well-known.json') {
     response.setHeader('content-type', 'application/json')
     response.end(JSON.stringify({
@@ -642,6 +659,24 @@ const server = createServer((request, response) => {
     return
   }
 
+  if (request.url === '/no-origin-2') {
+    response.statusCode = 402
+    response.setHeader('content-type', 'application/json')
+    response.end(JSON.stringify({
+      x402Version: 2,
+      error: 'Payment required',
+      resource: { url: `${serverUrl}/no-origin-2` },
+      accepts: [{
+        scheme: 'exact',
+        network: 'eip155:8453',
+        amount: '20000',
+        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        payTo: '0x549c82e6bfc54bdae9a2073744cbc2af5d1fc6d1',
+      }],
+    }))
+    return
+  }
+
   if (request.url === '/legacy/v1') {
     response.statusCode = 402
     response.setHeader('content-type', 'application/json')
@@ -922,6 +957,17 @@ try {
   assert.match(noOrigin.stdout, /CORS preflight does not allow the requesting origin/)
   assert.match(noOrigin.stdout, /402 challenge response does not allow the requesting origin/)
 
+  const groupedNoOrigin = await execFileAsync('node', [
+    'bin/x402-surface-check.mjs',
+    `${serverUrl}/no-origin-list.json`,
+    '--origin',
+    'https://example.com',
+  ], { cwd: new URL('..', import.meta.url) })
+
+  assert.match(groupedNoOrigin.stdout, /## Finding Summary/)
+  assert.match(groupedNoOrigin.stdout, /2 endpoints: P1 - Actual 402 challenge responses do not allow the requesting origin/)
+  assert.match(groupedNoOrigin.stdout, /2 endpoints: P1 - CORS preflight does not allow the requesting origin/)
+
   const needsParam = await execFileAsync('node', [
     'bin/x402-surface-check.mjs',
     '--endpoint',