x402-surface-check 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tate Programs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# x402 Surface Check
+
+No-payment CLI for checking x402 launch surfaces before a real agent spends.
+
+It accepts an x402 manifest or OpenAPI URL, derives public endpoints, sends no-payment probes, checks browser preflight behavior, and returns a Markdown patch queue. It never sends `X-PAYMENT`, never signs, and never attempts a paid call.
+
+```bash
+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
+```
+
+## What It Checks
+
+- Manifest or OpenAPI endpoint discovery
+- No-payment HTTP 402 challenge shape
+- x402 v1 and v2 price fields
+- `amount` / `maxAmountRequired`, `asset`, `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
+
+## Options
+
+```bash
+x402-surface-check <manifest-or-openapi-url> [output.md]
+
+--origin <url>   Origin to use for browser-style CORS preflight
+--limit <n>      Maximum endpoints to probe, default 6
+--json           Print JSON instead of Markdown
+--help           Show usage
+--version        Show package version
+```
+
+Environment variables are also supported:
+
+```bash
+X402_CHECK_ORIGIN=https://example.com x402-surface-check https://api.example.com/openapi.json
+X402_CHECK_LIMIT=12 x402-surface-check https://api.example.com/.well-known/x402
+```
+
+## Scope
+
+The checker is intentionally external and conservative:
+
+- no wallet access
+- no payment headers
+- no paid calls
+- no exploit attempts
+- no private endpoint guessing
+
+It is meant for launch-readiness review, spend-policy evidence, and pre-demo patch order.
+
+## Web Version
+
+Browser tool: https://tateprograms.com/x402-surface-check.html

package/bin/x402-surface-check.mjs

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises'
+
+const methods = ['get', 'post', 'put', 'patch', 'delete']
+const defaultLimit = 6
+
+const packageJson = JSON.parse(
+  await readFile(new URL('../package.json', import.meta.url), 'utf8'),
+)
+
+function usage() {
+  return `x402-surface-check ${packageJson.version}
+
+Usage:
+  x402-surface-check <manifest-or-openapi-url> [output.md]
+
+Options:
+  --origin <url>   Origin to use for browser-style CORS preflight
+  --limit <n>      Maximum endpoints to probe, default ${defaultLimit}
+  --json           Print JSON instead of Markdown
+  --help           Show this help
+  --version        Show package version
+`
+}
+
+function parseArgs(argv) {
+  const args = {
+    json: false,
+    limit: Number(process.env.X402_CHECK_LIMIT ?? defaultLimit),
+    origin: process.env.X402_CHECK_ORIGIN,
+    outputPath: '',
+    url: '',
+  }
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--help' || arg === '-h') {
+      args.help = true
+    }
+    else if (arg === '--version' || arg === '-v') {
+      args.version = true
+    }
+    else if (arg === '--json') {
+      args.json = true
+    }
+    else if (arg === '--origin') {
+      args.origin = argv[index + 1]
+      index += 1
+    }
+    else if (arg === '--limit') {
+      args.limit = Number(argv[index + 1])
+      index += 1
+    }
+    else if (!args.url) {
+      args.url = arg
+    }
+    else if (!args.outputPath) {
+      args.outputPath = arg
+    }
+    else {
+      throw new Error(`Unexpected argument: ${arg}`)
+    }
+  }
+
+  return args
+}
+
+function moneyFromAtomic(amount, decimals = 6) {
+  const numeric = Number(amount)
+  if (!Number.isFinite(numeric)) return String(amount ?? '')
+  const value = numeric / (10 ** decimals)
+  return `$${value.toLocaleString(undefined, {
+    maximumFractionDigits: 6,
+    minimumFractionDigits: value < 0.01 ? 3 : 2,
+  })}`
+}
+
+function uniqueEntries(entries, limit) {
+  const seen = new Set()
+  return entries
+    .filter(entry => {
+      const key = `${entry.method}:${entry.url}`
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+    .slice(0, Number.isFinite(limit) && limit > 0 ? limit : defaultLimit)
+}
+
+function endpointEntries(document, sourceUrl, limit) {
+  const entries = []
+
+  for (const [name, url] of Object.entries(document.x402Endpoints ?? {})) {
+    if (typeof url === 'string' && url.startsWith('http')) {
+      entries.push({ name, url, method: 'POST' })
+    }
+  }
+
+  for (const [category, items] of Object.entries(document.categories ?? {})) {
+    if (!Array.isArray(items)) continue
+    for (const item of items) {
+      if (typeof item?.endpoint === 'string' && item.endpoint.startsWith('http')) {
+        entries.push({
+          name: item.id ?? item.name ?? category,
+          url: item.endpoint,
+          method: item.method ?? 'POST',
+        })
+      }
+    }
+  }
+
+  if (document.openapi && document.paths && typeof document.paths === 'object') {
+    const baseUrl = document.servers?.find(server => typeof server?.url === 'string')?.url
+      ?? sourceUrl
+
+    for (const [path, operations] of Object.entries(document.paths)) {
+      if (!operations || typeof operations !== 'object') continue
+      for (const method of methods) {
+        const operation = operations[method]
+        if (!operation || typeof operation !== 'object') continue
+        const url = path.startsWith('http') ? path : new URL(path, baseUrl).toString()
+        entries.push({
+          name: operation.operationId ?? `${method.toUpperCase()} ${path}`,
+          url,
+          method: method.toUpperCase(),
+        })
+      }
+    }
+  }
+
+  for (const resource of document.resources ?? []) {
+    if (typeof resource !== 'string') continue
+    const match = resource.match(/^(GET|POST|PUT|PATCH|DELETE)\s+(\S+)/i)
+    if (!match) continue
+    const [, method, rawPath] = match
+    const url = rawPath.startsWith('http')
+      ? rawPath
+      : new URL(rawPath, document.baseUrl ?? sourceUrl).toString()
+    entries.push({
+      name: rawPath.split('/').filter(Boolean).at(-1) ?? rawPath,
+      url,
+      method: method.toUpperCase(),
+    })
+  }
+
+  return uniqueEntries(entries, limit)
+}
+
+async function readText(response) {
+  const text = await response.text()
+  try {
+    return { text, json: JSON.parse(text) }
+  }
+  catch {
+    return { text, json: null }
+  }
+}
+
+function parseEncodedChallenge(value) {
+  if (!value) return null
+  try {
+    const normalized = value.replace(/-/g, '+').replace(/_/g, '/')
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=')
+    return JSON.parse(Buffer.from(padded, 'base64').toString('utf8'))
+  }
+  catch {
+    try {
+      return JSON.parse(value)
+    }
+    catch {
+      return null
+    }
+  }
+}
+
+async function fetchDocument(url) {
+  const response = await fetch(url, {
+    headers: {
+      'user-agent': `x402-surface-check/${packageJson.version}`,
+      accept: 'application/json',
+    },
+  })
+  const body = await readText(response)
+  return {
+    status: response.status,
+    ok: response.ok,
+    headers: Object.fromEntries(response.headers.entries()),
+    url: response.url,
+    body,
+  }
+}
+
+async function probeEndpoint(entry) {
+  const method = entry.method ?? 'POST'
+  const response = await fetch(entry.url, {
+    method,
+    headers: {
+      'user-agent': `x402-surface-check/${packageJson.version}`,
+      accept: 'application/json',
+      'content-type': 'application/json',
+    },
+    body: method === 'GET' || method === 'HEAD' ? undefined : '{}',
+  })
+  const body = await readText(response)
+  const headerChallenge = parseEncodedChallenge(
+    response.headers.get('payment-required') ?? response.headers.get('x-payment-required'),
+  )
+
+  if (headerChallenge && !body.json?.accepts?.length) {
+    body.json = headerChallenge
+  }
+
+  return {
+    ...entry,
+    status: response.status,
+    headers: Object.fromEntries(response.headers.entries()),
+    body,
+  }
+}
+
+async function probePreflight(entry, origin) {
+  const response = await fetch(entry.url, {
+    method: 'OPTIONS',
+    headers: {
+      origin,
+      'access-control-request-method': entry.method ?? 'POST',
+      'access-control-request-headers': 'content-type,x-payment',
+    },
+  })
+
+  return {
+    ...entry,
+    status: response.status,
+    headers: Object.fromEntries(response.headers.entries()),
+  }
+}
+
+function valueList(value) {
+  if (Array.isArray(value)) return value.map(String)
+  if (value && typeof value === 'object') return Object.keys(value)
+  if (typeof value === 'string') return [value]
+  return []
+}
+
+function capabilityList(value) {
+  if (!Array.isArray(value)) return []
+  return value.map(item => item?.id ?? item?.name ?? item).filter(Boolean).map(String)
+}
+
+function challengeAccepts(result) {
+  return Array.isArray(result.body.json?.accepts) ? result.body.json.accepts : []
+}
+
+function challengeSummary(result) {
+  const challenge = result.body.json
+  const firstAccept = challenge?.accepts?.[0] ?? {}
+  const amount = firstAccept.amount ?? firstAccept.maxAmountRequired ?? firstAccept.maxAmount ?? ''
+  const resourceUrl = challenge?.resource?.url ?? firstAccept.resource ?? ''
+  const extraResource = firstAccept.extra?.resource ?? firstAccept.resource ?? ''
+
+  return {
+    status: result.status,
+    resourceUrl,
+    network: firstAccept.network ?? '',
+    amount,
+    price: moneyFromAtomic(amount),
+    payTo: firstAccept.payTo ?? '',
+    asset: firstAccept.asset ?? '',
+    timeout: firstAccept.maxTimeoutSeconds ?? '',
+    extraResource,
+  }
+}
+
+function looksLikeStagingNetwork(network) {
+  return /devnet|testnet|sepolia|local|eip155:84532|solana:EtWTRAB/i.test(String(network ?? ''))
+}
+
+function looksLikePlaceholderPayTo(payTo) {
+  const value = String(payTo ?? '')
+  if (!value) return false
+  if (/^0x0{36,}0?1?$/i.test(value)) return true
+  if (/^1{24,}$/.test(value)) return true
+  return false
+}
+
+function findingList(documentResult, challengeResults, preflightResults, entries) {
+  const document = documentResult.body.json ?? {}
+  const findings = []
+  const networks = valueList(document.networks)
+  const challengeNetworks = new Set()
+
+  if (documentResult.status < 200 || documentResult.status >= 300) {
+    findings.push(`P1 - Document returned HTTP ${documentResult.status}; expected a successful JSON response.`)
+  }
+
+  if (!documentResult.body.json) {
+    findings.push(`P1 - Document did not return parseable JSON; content begins: ${documentResult.body.text.slice(0, 80).replace(/\s+/g, ' ')}.`)
+  }
+
+  if (entries.length === 0) {
+    findings.push('P1 - Document does not expose any manifest, OpenAPI, category, or resource endpoints for no-payment probes.')
+  }
+
+  for (const result of challengeResults) {
+    const summary = challengeSummary(result)
+    if (summary.network) challengeNetworks.add(summary.network)
+
+    if (result.status !== 402) {
+      findings.push(`P1 - ${result.name} returned ${result.status}, not 402, for a no-payment ${result.method ?? 'POST'} probe.`)
+    }
+    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}.`)
+    }
+    if (!summary.amount || !summary.payTo || !summary.asset) {
+      findings.push(`P1 - ${result.name} challenge is missing amount/maxAmountRequired, payTo, or asset metadata.`)
+    }
+    for (const accept of challengeAccepts(result)) {
+      if (looksLikePlaceholderPayTo(accept.payTo)) {
+        findings.push(`P1 - ${result.name} challenge advertises placeholder-looking payTo ${accept.payTo}; production listings should not ask agents to pay placeholder recipients.`)
+      }
+      if (looksLikeStagingNetwork(accept.network)) {
+        findings.push(`P2 - ${result.name} challenge advertises staging/test network ${accept.network}; document this as demo-only until live-value payment rails are active.`)
+      }
+    }
+    if (!summary.resourceUrl || !summary.extraResource) {
+      findings.push(`P2 - ${result.name} challenge does not repeat the resource URL in both resource.url and accepts[0].extra.resource/resource.`)
+    }
+  }
+
+  for (const result of preflightResults) {
+    const allowed = result.headers['access-control-allow-headers'] ?? ''
+    if (!/x-payment/i.test(allowed)) {
+      findings.push(`P1 - ${result.name} CORS preflight does not allow X-PAYMENT; observed allow headers: ${allowed || 'none'}.`)
+    }
+    const allowedMethods = result.headers['access-control-allow-methods'] ?? ''
+    if (/delete|put|patch/i.test(allowedMethods)) {
+      findings.push(`P2 - ${result.name} CORS allow-methods is broader than a narrow public x402 contract: ${allowedMethods}.`)
+    }
+  }
+
+  if (networks.length > 1 && challengeNetworks.size === 1) {
+    findings.push(`P2 - Document lists ${networks.length} networks, while observed 402 challenges exposed one network: ${[...challengeNetworks].join(', ')}.`)
+  }
+
+  if (document.x402Endpoint && document.x402Endpoints) {
+    findings.push(`P3 - Document includes both x402Endpoint (${document.x402Endpoint}) and x402Endpoints; clarify which path clients should prefer.`)
+  }
+
+  return findings
+}
+
+function formatMarkdown(report) {
+  const document = report.document.body.json ?? {}
+  const challengeRows = report.challenges.map(result => {
+    const summary = challengeSummary(result)
+    return `| ${result.name} | ${result.method ?? 'POST'} | ${result.status} | ${summary.price || '-'} | ${summary.network || '-'} | ${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'] ?? '-'} |`
+  })
+
+  return [
+    '# x402 Public Surface Check',
+    '',
+    `Document: ${report.document.url}`,
+    `Checked: ${report.checkedAt}`,
+    'Scope: manifest/OpenAPI parsing, no-payment endpoint probes, and browser-style CORS preflight. No payment headers or paid calls.',
+    `Preflight origin: ${report.origin}`,
+    '',
+    '## Document',
+    '',
+    `- Status: ${report.document.status}`,
+    `- Type: ${document.openapi ? 'OpenAPI' : 'x402 manifest or JSON document'}`,
+    `- Agent: ${document.agent?.name ?? '-'}`,
+    `- Wallet: ${document.agent?.wallet ?? '-'}`,
+    `- Facilitator: ${document.facilitator ?? '-'}`,
+    `- Networks: ${valueList(document.networks).join(', ') || '-'}`,
+    `- Capabilities: ${capabilityList(document.capabilities).join(', ') || '-'}`,
+    `- Probed endpoints: ${report.entries.length}`,
+    '',
+    '## No-Payment Challenge Map',
+    '',
+    '| Endpoint | Method | HTTP | Price | Network | Resource URL |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...(challengeRows.length ? challengeRows : ['| - | - | - | - | - | - |']),
+    '',
+    '## Browser Preflight Map',
+    '',
+    '| Endpoint | Method | HTTP | Allow-Origin | Allow-Headers | Allow-Methods |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...(preflightRows.length ? preflightRows : ['| - | - | - | - | - | - |']),
+    '',
+    '## Findings',
+    '',
+    ...(report.findings.length ? report.findings.map(item => `- ${item}`) : ['- No obvious launch-readiness findings from the public no-payment probes.']),
+    '',
+  ].join('\n')
+}
+
+async function runCheck(options) {
+  const document = await fetchDocument(options.url)
+  const entries = document.body.json ? endpointEntries(document.body.json, document.url, options.limit) : []
+  const origin = options.origin ?? new URL(document.url).origin
+  const challenges = []
+  const preflights = []
+
+  for (const entry of entries) {
+    challenges.push(await probeEndpoint(entry))
+    preflights.push(await probePreflight(entry, origin))
+  }
+
+  const report = {
+    checkedAt: new Date().toISOString(),
+    document,
+    entries,
+    findings: [],
+    origin,
+    challenges,
+    preflights,
+  }
+  report.findings = findingList(document, challenges, preflights, entries)
+  return report
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help) {
+    console.log(usage())
+    return
+  }
+  if (options.version) {
+    console.log(packageJson.version)
+    return
+  }
+  if (!options.url) {
+    console.error(usage())
+    process.exitCode = 2
+    return
+  }
+
+  const report = await runCheck(options)
+  const output = options.json
+    ? `${JSON.stringify(report, null, 2)}\n`
+    : `${formatMarkdown(report)}\n`
+
+  if (options.outputPath) {
+    await writeFile(options.outputPath, output)
+  }
+
+  process.stdout.write(output)
+}
+
+main().catch(error => {
+  console.error(`x402-surface-check: ${error.message}`)
+  process.exitCode = 1
+})

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "x402-surface-check",
+  "version": "0.1.0",
+  "description": "No-payment x402 public-surface checker for manifests, OpenAPI specs, and HTTP 402 challenges.",
+  "type": "module",
+  "bin": {
+    "x402-surface-check": "bin/x402-surface-check.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --check bin/x402-surface-check.mjs && node test/smoke.mjs",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "x402",
+    "agent-payments",
+    "pay-sh",
+    "usdc",
+    "solana",
+    "mcp",
+    "security",
+    "cli"
+  ],
+  "homepage": "https://tateprograms.com/x402-surface-check.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TateLyman/x402-surface-check.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TateLyman/x402-surface-check/issues"
+  },
+  "author": "Tate Programs <hello@tateprograms.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}