x402-surface-check 0.1.0 → 0.2.2

package/README.md

@@ -4,16 +4,20 @@ 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.
 
+npm: https://www.npmjs.com/package/x402-surface-check
+
 ```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
+npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/eth
 ```
 
 ## What It Checks
 
-- Manifest or OpenAPI endpoint discovery
+- Manifest endpoint discovery from `items[]`, `endpoints[]`, `x402Endpoints`, category arrays, resource strings, and OpenAPI paths
 - No-payment HTTP 402 challenge shape
 - x402 v1 and v2 price fields
+- MPP `WWW-Authenticate: Payment` challenges
 - `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
@@ -25,7 +29,10 @@ npx --yes x402-surface-check https://api.example.com/openapi.json report.md
 
 ```bash
 x402-surface-check <manifest-or-openapi-url> [output.md]
+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
 --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

@@ -13,8 +13,11 @@ function usage() {
 
 Usage:
   x402-surface-check <manifest-or-openapi-url> [output.md]
+  x402-surface-check --endpoint --method POST <paid-endpoint-url> [output.md]
 
 Options:
+  --endpoint       Treat the URL as one paid endpoint instead of a discovery document
+  --method <verb>  HTTP method for direct endpoint mode, default POST
   --origin <url>   Origin to use for browser-style CORS preflight
   --limit <n>      Maximum endpoints to probe, default ${defaultLimit}
   --json           Print JSON instead of Markdown
@@ -26,7 +29,9 @@ Options:
 function parseArgs(argv) {
   const args = {
     json: false,
+    endpoint: false,
     limit: Number(process.env.X402_CHECK_LIMIT ?? defaultLimit),
+    method: 'POST',
     origin: process.env.X402_CHECK_ORIGIN,
     outputPath: '',
     url: '',
@@ -43,6 +48,13 @@ function parseArgs(argv) {
     else if (arg === '--json') {
       args.json = true
     }
+    else if (arg === '--endpoint') {
+      args.endpoint = true
+    }
+    else if (arg === '--method') {
+      args.method = String(argv[index + 1] ?? '').toUpperCase()
+      index += 1
+    }
     else if (arg === '--origin') {
       args.origin = argv[index + 1]
       index += 1
@@ -87,8 +99,26 @@ function uniqueEntries(entries, limit) {
     .slice(0, Number.isFinite(limit) && limit > 0 ? limit : defaultLimit)
 }
 
+function documentBaseUrl(document, sourceUrl) {
+  if (typeof document.service_url === 'string') return document.service_url
+  if (typeof document.serviceUrl === 'string') return document.serviceUrl
+  if (typeof document.baseUrl === 'string') return document.baseUrl
+  if (typeof document.base_url === 'string') return document.base_url
+  return new URL('/', sourceUrl).toString()
+}
+
+function endpointUrl(rawPath, baseUrl, sourceUrl) {
+  const value = String(rawPath ?? '')
+  if (!value) return ''
+  if (/^https?:\/\//i.test(value)) return value
+  const resolvedBase = baseUrl || documentBaseUrl({}, sourceUrl)
+  const base = value.startsWith('/') ? resolvedBase : `${resolvedBase.replace(/\/?$/, '/')}`
+  return new URL(value, base).toString()
+}
+
 function endpointEntries(document, sourceUrl, limit) {
   const entries = []
+  const baseUrl = documentBaseUrl(document, sourceUrl)
 
   for (const [name, url] of Object.entries(document.x402Endpoints ?? {})) {
     if (typeof url === 'string' && url.startsWith('http')) {
@@ -109,6 +139,31 @@ function endpointEntries(document, sourceUrl, limit) {
     }
   }
 
+  if (Array.isArray(document.endpoints)) {
+    for (const endpoint of document.endpoints) {
+      const rawPath = endpoint?.url ?? endpoint?.endpoint ?? endpoint?.path
+      if (!rawPath) continue
+      entries.push({
+        name: endpoint.id ?? endpoint.name ?? String(rawPath).split('/').filter(Boolean).at(-1) ?? String(rawPath),
+        url: endpointUrl(rawPath, baseUrl, sourceUrl),
+        method: String(endpoint.method ?? 'POST').toUpperCase(),
+      })
+    }
+  }
+
+  if (Array.isArray(document.items)) {
+    for (const item of document.items) {
+      if (item?.type && item.type !== 'http') continue
+      const rawPath = item?.resource ?? item?.url ?? item?.endpoint ?? item?.path
+      if (!rawPath) continue
+      entries.push({
+        name: item.metadata?.name ?? item.id ?? item.name ?? String(rawPath).split('/').filter(Boolean).at(-1) ?? String(rawPath),
+        url: endpointUrl(rawPath, baseUrl, sourceUrl),
+        method: String(item.method ?? 'GET').toUpperCase(),
+      })
+    }
+  }
+
   if (document.openapi && document.paths && typeof document.paths === 'object') {
     const baseUrl = document.servers?.find(server => typeof server?.url === 'string')?.url
       ?? sourceUrl
@@ -173,6 +228,42 @@ function parseEncodedChallenge(value) {
   }
 }
 
+function parsePaymentAuthenticate(value) {
+  if (!value || !/^Payment\s+/i.test(value)) return null
+  const params = {}
+  const pattern = /([a-zA-Z][\w-]*)="([^"]*)"/g
+  let match = pattern.exec(value)
+
+  while (match) {
+    params[match[1]] = match[2]
+    match = pattern.exec(value)
+  }
+
+  const request = parseEncodedChallenge(params.request)
+  if (!request) return null
+
+  return {
+    protocol: 'mpp',
+    resource: { url: '' },
+    accepts: [{
+      scheme: 'mpp',
+      network: request.methodDetails?.network ?? params.method ?? '',
+      amount: request.amount ?? '',
+      asset: request.currency ?? '',
+      payTo: request.recipient ?? '',
+      resource: '',
+      maxTimeoutSeconds: '',
+      extra: {
+        description: request.description ?? '',
+        expires: params.expires ?? '',
+        id: params.id ?? '',
+        intent: params.intent ?? '',
+        method: params.method ?? '',
+      },
+    }],
+  }
+}
+
 async function fetchDocument(url) {
   const response = await fetch(url, {
     headers: {
@@ -205,9 +296,17 @@ async function probeEndpoint(entry) {
   const headerChallenge = parseEncodedChallenge(
     response.headers.get('payment-required') ?? response.headers.get('x-payment-required'),
   )
+  const paymentChallenge = parsePaymentAuthenticate(response.headers.get('www-authenticate'))
 
-  if (headerChallenge && !body.json?.accepts?.length) {
-    body.json = headerChallenge
+  if (!body.json?.accepts?.length) {
+    if (headerChallenge) {
+      body.json = headerChallenge
+    }
+    else if (paymentChallenge) {
+      paymentChallenge.resource.url = entry.url
+      paymentChallenge.accepts[0].resource = entry.url
+      body.json = paymentChallenge
+    }
   }
 
   return {
@@ -260,6 +359,7 @@ function challengeSummary(result) {
 
   return {
     status: result.status,
+    protocol: challenge?.protocol ?? (firstAccept.scheme === 'mpp' ? 'mpp' : 'x402'),
     resourceUrl,
     network: firstAccept.network ?? '',
     amount,
@@ -298,7 +398,7 @@ function findingList(documentResult, challengeResults, preflightResults, entries
   }
 
   if (entries.length === 0) {
-    findings.push('P1 - Document does not expose any manifest, OpenAPI, category, or resource endpoints for no-payment probes.')
+    findings.push('P1 - Document does not expose any manifest, OpenAPI, item, category, or resource endpoints for no-payment probes.')
   }
 
   for (const result of challengeResults) {
@@ -329,7 +429,7 @@ function findingList(documentResult, challengeResults, preflightResults, entries
 
   for (const result of preflightResults) {
     const allowed = result.headers['access-control-allow-headers'] ?? ''
-    if (!/x-payment/i.test(allowed)) {
+    if (allowed !== '*' && !/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'] ?? ''
@@ -353,7 +453,7 @@ 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 || '-'} |`
+    return `| ${result.name} | ${result.method ?? 'POST'} | ${result.status} | ${summary.protocol || '-'} | ${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'] ?? '-'} |`
@@ -370,7 +470,7 @@ function formatMarkdown(report) {
     '## Document',
     '',
     `- Status: ${report.document.status}`,
-    `- Type: ${document.openapi ? 'OpenAPI' : 'x402 manifest or JSON document'}`,
+    `- Type: ${report.directEndpoint ? 'direct endpoint' : (document.openapi ? 'OpenAPI' : 'x402 manifest or JSON document')}`,
     `- Agent: ${document.agent?.name ?? '-'}`,
     `- Wallet: ${document.agent?.wallet ?? '-'}`,
     `- Facilitator: ${document.facilitator ?? '-'}`,
@@ -380,9 +480,9 @@ function formatMarkdown(report) {
     '',
     '## No-Payment Challenge Map',
     '',
-    '| Endpoint | Method | HTTP | Price | Network | Resource URL |',
-    '| --- | --- | --- | --- | --- | --- |',
-    ...(challengeRows.length ? challengeRows : ['| - | - | - | - | - | - |']),
+    '| Endpoint | Method | HTTP | Protocol | Price | Network | Resource URL |',
+    '| --- | --- | --- | --- | --- | --- | --- |',
+    ...(challengeRows.length ? challengeRows : ['| - | - | - | - | - | - | - |']),
     '',
     '## Browser Preflight Map',
     '',
@@ -398,8 +498,18 @@ function formatMarkdown(report) {
 }
 
 async function runCheck(options) {
-  const document = await fetchDocument(options.url)
-  const entries = document.body.json ? endpointEntries(document.body.json, document.url, options.limit) : []
+  const document = options.endpoint
+    ? {
+        status: 200,
+        ok: true,
+        headers: {},
+        url: options.url,
+        body: { text: '{}', json: {} },
+      }
+    : await fetchDocument(options.url)
+  const entries = options.endpoint
+    ? [{ name: new URL(options.url).pathname.split('/').filter(Boolean).at(-1) ?? options.url, url: options.url, method: options.method || 'POST' }]
+    : (document.body.json ? endpointEntries(document.body.json, document.url, options.limit) : [])
   const origin = options.origin ?? new URL(document.url).origin
   const challenges = []
   const preflights = []
@@ -412,6 +522,7 @@ async function runCheck(options) {
   const report = {
     checkedAt: new Date().toISOString(),
     document,
+    directEndpoint: options.endpoint,
     entries,
     findings: [],
     origin,

package/package.json

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