x402-surface-check 0.2.14 → 0.2.16

package/README.md

@@ -16,7 +16,9 @@ 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 query/path examples and JSON request-body examples for safer no-payment probes
+- 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 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
 - MPP `WWW-Authenticate: Payment` and x402 V2 `WWW-Authenticate: X402 requirements=...` challenges
@@ -26,7 +28,7 @@ npx --yes x402-surface-check --endpoint --method POST https://x402.rpc.ankr.com/
 - 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 the requesting origin and `X-PAYMENT`
+- Browser CORS allowance for the requesting origin and `X-PAYMENT`, including the actual 402 challenge response
 - 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

package/bin/x402-surface-check.mjs

@@ -132,6 +132,12 @@ function endpointUrl(rawPath, baseUrl, sourceUrl) {
   return new URL(value, base).toString()
 }
 
+function openApiServerBaseUrl(document, sourceUrl) {
+  const rawUrl = document.servers?.find(server => typeof server?.url === 'string')?.url
+  if (!rawUrl) return documentBaseUrl(document, sourceUrl)
+  return endpointUrl(rawUrl, documentBaseUrl(document, sourceUrl), sourceUrl)
+}
+
 function linkedDiscoveryUrl(document, sourceUrl) {
   const rawUrl = document?.discovery_url
     ?? document?.discoveryUrl
@@ -151,21 +157,48 @@ function operationExpectedPrice(operation) {
   return numeric === null ? null : numeric
 }
 
-function exampleValue(schemaOrParameter) {
+function resolveLocalRef(ref, document) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) return undefined
+  return ref
+    .slice(2)
+    .split('/')
+    .map(part => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+    .reduce((value, part) => value?.[part], document)
+}
+
+function resolveSchema(schema, document, seen = new Set()) {
+  if (!schema || typeof schema !== 'object') return schema
+  if (!schema.$ref) return schema
+  if (seen.has(schema.$ref)) return schema
+  const resolved = resolveLocalRef(schema.$ref, document)
+  if (!resolved) return schema
+  seen.add(schema.$ref)
+  return resolveSchema(resolved, document, seen)
+}
+
+function exampleValue(schemaOrParameter, document) {
   if (!schemaOrParameter || typeof schemaOrParameter !== 'object') return undefined
-  const schema = schemaOrParameter.schema ?? schemaOrParameter
+  const schema = resolveSchema(schemaOrParameter.schema ?? schemaOrParameter, document)
   const value = schemaOrParameter.example
+    ?? schema.const
     ?? schema.example
     ?? schema.default
     ?? (Array.isArray(schema.enum) ? schema.enum[0] : undefined)
   if (value !== undefined) return value
-  if (schema.type === 'string') return ''
-  if (schema.type === 'number' || schema.type === 'integer') return 0
+  if (schema.type === 'string') {
+    if (schema.format === 'uri') return 'https://example.com'
+    if (schema.format === 'date-time') return '2026-01-01T00:00:00.000Z'
+    if (schema.format === 'date') return '2026-01-01'
+    if (Number(schema.minLength) > 0) return 'example'
+    return ''
+  }
+  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
   return undefined
 }
 
-function mediaExample(media) {
+function mediaExample(media, document) {
   if (!media || typeof media !== 'object') return undefined
   if (media.example !== undefined) return media.example
   const examples = media.examples && typeof media.examples === 'object'
@@ -175,7 +208,7 @@ function mediaExample(media) {
   if (firstExample?.value !== undefined) return firstExample.value
   if (firstExample?.externalValue) return undefined
 
-  const schema = media.schema
+  const schema = resolveSchema(media.schema, document)
   if (!schema || typeof schema !== 'object' || schema.type !== 'object') return undefined
   const body = {}
   const properties = schema.properties && typeof schema.properties === 'object'
@@ -185,29 +218,35 @@ function mediaExample(media) {
 
   for (const [name, property] of Object.entries(properties)) {
     if (!required.has(name)) continue
-    const value = exampleValue(property)
+    const value = exampleValue(property, document)
     if (value !== undefined) body[name] = value
   }
 
   return Object.keys(body).length ? body : undefined
 }
 
-function operationRequestBody(operation) {
+function operationRequestBody(operation, document) {
   const content = operation?.requestBody?.content
   if (!content || typeof content !== 'object') return undefined
   const media = content['application/json']
     ?? content['application/*+json']
     ?? Object.entries(content).find(([type]) => /json/i.test(type))?.[1]
-  return mediaExample(media)
+  return mediaExample(media, document)
+}
+
+function operationPaymentSignal(operation) {
+  if (operation?.['x-payment-info'] || operation?.['x-payment'] || operation?.['x-x402'] || operation?.payment) return 2
+  if (operation?.responses && Object.hasOwn(operation.responses, '402')) return 1
+  return 0
 }
 
-function openApiProbeUrl(path, operation, baseUrl) {
+function openApiProbeUrl(path, operation, baseUrl, document) {
   const parameters = Array.isArray(operation?.parameters) ? operation.parameters : []
   let resolvedPath = path
   const searchParams = new URLSearchParams()
 
   for (const parameter of parameters) {
-    const value = exampleValue(parameter)
+    const value = exampleValue(parameter, document)
     if (value === undefined || value === '') continue
     if (parameter.in === 'path') {
       resolvedPath = resolvedPath.replaceAll(`{${parameter.name}}`, encodeURIComponent(String(value)))
@@ -217,7 +256,9 @@ function openApiProbeUrl(path, operation, baseUrl) {
     }
   }
 
-  const url = path.startsWith('http') ? new URL(resolvedPath) : new URL(resolvedPath, baseUrl)
+  const url = /^https?:\/\//i.test(String(resolvedPath))
+    ? new URL(resolvedPath)
+    : new URL(String(resolvedPath).replace(/^\/+/, ''), `${baseUrl.replace(/\/?$/, '/')}`)
   for (const [name, value] of searchParams.entries()) {
     url.searchParams.set(name, value)
   }
@@ -273,24 +314,29 @@ function endpointEntries(document, sourceUrl, limit) {
   }
 
   if (document.openapi && document.paths && typeof document.paths === 'object') {
-    const baseUrl = document.servers?.find(server => typeof server?.url === 'string')?.url
-      ?? sourceUrl
+    const baseUrl = openApiServerBaseUrl(document, sourceUrl)
+    const openApiEntries = []
 
     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 = openApiProbeUrl(path, operation, baseUrl)
-        entries.push({
+        const url = openApiProbeUrl(path, operation, baseUrl, document)
+        openApiEntries.push({
           name: operation.operationId ?? `${method.toUpperCase()} ${path}`,
           url,
           method: method.toUpperCase(),
           expectedPriceUsd: operationExpectedPrice(operation),
-          requestBody: operationRequestBody(operation),
+          requestBody: operationRequestBody(operation, document),
+          paymentSignal: operationPaymentSignal(operation),
         })
       }
     }
+
+    entries.push(...openApiEntries
+      .sort((a, b) => b.paymentSignal - a.paymentSignal)
+      .map(({ paymentSignal, ...entry }) => entry))
   }
 
   for (const resource of document.resources ?? []) {
@@ -428,7 +474,7 @@ async function fetchDocument(url) {
   }
 }
 
-async function probeEndpoint(entry) {
+async function probeEndpoint(entry, origin) {
   const method = entry.method ?? 'POST'
   const response = await fetch(entry.url, {
     method,
@@ -436,6 +482,7 @@ async function probeEndpoint(entry) {
       'user-agent': `x402-surface-check/${packageJson.version}`,
       accept: 'application/json',
       'content-type': 'application/json',
+      ...(origin ? { origin } : {}),
     },
     body: method === 'GET' || method === 'HEAD'
       ? undefined
@@ -656,6 +703,9 @@ function findingList(documentResult, challengeResults, preflightResults, entries
       continue
     }
 
+    if (!result.headers?.['access-control-allow-origin']) {
+      findings.push(`P1 - ${result.name} 402 challenge response does not allow the requesting origin; browser agents cannot read the payment requirements even if preflight succeeds.`)
+    }
     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}.`)
     }
@@ -796,7 +846,7 @@ async function runCheck(options) {
   const preflights = []
 
   for (const entry of entries) {
-    challenges.push(await probeEndpoint(entry))
+    challenges.push(await probeEndpoint(entry, origin))
     preflights.push(await probePreflight(entry, origin))
   }
 

package/package.json

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