x402check 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,135 @@
+# x402check
+
+Validate [x402](https://www.x402.org/) payment configurations. Works in Node, browsers, and edge runtimes — zero dependencies.
+
+**[x402check.com](https://www.x402check.com)** — try it in the browser
+
+## Install
+
+```
+npm i x402check
+```
+
+## Quick start
+
+```js
+import { validate } from 'x402check'
+
+const result = validate({
+  x402Version: 2,
+  accepts: [{
+    scheme: 'exact',
+    network: 'base',
+    payTo: '0x1234567890abcdef1234567890abcdef12345678',
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    amount: '10000',
+    maxTimeoutSeconds: 300
+  }]
+})
+
+result.valid      // true | false
+result.errors     // ValidationIssue[]
+result.warnings   // ValidationIssue[]
+result.normalized // canonical v2 config
+```
+
+## API
+
+### `validate(input, options?)`
+
+Validates a config object or JSON string. Returns errors, warnings, and a normalized v2 config.
+
+```js
+validate(configOrJson)
+validate(configOrJson, { strict: true }) // promotes warnings to errors
+```
+
+**Returns:** `ValidationResult`
+
+```ts
+{
+  valid: boolean
+  version: 'v2' | 'v1' | 'unknown'
+  errors: ValidationIssue[]
+  warnings: ValidationIssue[]
+  normalized: NormalizedConfig | null
+}
+```
+
+Each issue includes a machine-readable `code`, a `field` path, a human-readable `message`, and an optional `fix` suggestion.
+
+### `extractConfig(response)`
+
+Extracts an x402 config from an HTTP 402 response. Checks the JSON body first, then falls back to the `PAYMENT-REQUIRED` header (base64 or raw JSON).
+
+```js
+const res = await fetch(url)
+const { config, source, error } = extractConfig({
+  body: await res.json(),
+  headers: res.headers
+})
+// source: 'body' | 'header' | null
+```
+
+### `detect(input)`
+
+Returns the config format: `'v2'`, `'v1'`, or `'unknown'`.
+
+```js
+detect({ x402Version: 2, accepts: [...] }) // 'v2'
+```
+
+### `normalize(input)`
+
+Converts any supported config to canonical v2 shape. Returns `null` if the format is unrecognized.
+
+```js
+const v2Config = normalize(v1Config)
+```
+
+### Address validation
+
+```js
+import { validateAddress, validateEvmAddress, validateSolanaAddress } from 'x402check'
+
+validateAddress(addr, 'eip155:8453', 'payTo')   // dispatches by network
+validateEvmAddress(addr, 'payTo')                // EIP-55 checksum verification
+validateSolanaAddress(addr, 'payTo')             // base58, 32-byte decode check
+```
+
+### Network & asset registry
+
+```js
+import {
+  isKnownNetwork, getNetworkInfo, getCanonicalNetwork,
+  isKnownAsset, getAssetInfo, isValidCaip2
+} from 'x402check'
+
+isValidCaip2('eip155:8453')           // true
+getCanonicalNetwork('base')           // 'eip155:8453'
+getNetworkInfo('eip155:8453')         // { name: 'Base', type: 'evm', testnet: false }
+isKnownAsset('eip155:8453', '0x833…') // true
+getAssetInfo('eip155:8453', '0x833…') // { symbol: 'USDC', name: 'USD Coin', decimals: 6 }
+```
+
+## Supported formats
+
+| Format | `x402Version` | Status |
+|--------|---------------|--------|
+| v2     | `2`           | Recommended |
+| v1     | `1`           | Supported, auto-normalized to v2 |
+
+## Validation checks
+
+- Required fields (`scheme`, `network`, `amount`, `asset`, `payTo`)
+- Amount is a numeric string > 0
+- Network is valid [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md)
+- EVM addresses: `0x`-prefixed, 40 hex chars, EIP-55 checksum
+- Solana addresses: base58, decodes to 32 bytes
+- Known network and asset registry warnings
+- `maxTimeoutSeconds` is a positive integer (if present)
+- Resource URL format (if present)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -28,6 +28,12 @@ const ErrorCode = {
 	NO_EVM_CHECKSUM: "NO_EVM_CHECKSUM",
 	INVALID_SOLANA_ADDRESS: "INVALID_SOLANA_ADDRESS",
 	ADDRESS_NETWORK_MISMATCH: "ADDRESS_NETWORK_MISMATCH",
+	INVALID_BAZAAR_INFO: "INVALID_BAZAAR_INFO",
+	INVALID_BAZAAR_SCHEMA: "INVALID_BAZAAR_SCHEMA",
+	INVALID_BAZAAR_INFO_INPUT: "INVALID_BAZAAR_INFO_INPUT",
+	INVALID_OUTPUT_SCHEMA: "INVALID_OUTPUT_SCHEMA",
+	INVALID_OUTPUT_SCHEMA_INPUT: "INVALID_OUTPUT_SCHEMA_INPUT",
+	MISSING_INPUT_SCHEMA: "MISSING_INPUT_SCHEMA",
 	UNKNOWN_NETWORK: "UNKNOWN_NETWORK",
 	UNKNOWN_ASSET: "UNKNOWN_ASSET",
 	LEGACY_FORMAT: "LEGACY_FORMAT",
@@ -61,6 +67,12 @@ const ErrorMessages = {
 	NO_EVM_CHECKSUM: "EVM address is all-lowercase with no checksum protection",
 	INVALID_SOLANA_ADDRESS: "Invalid Solana address format",
 	ADDRESS_NETWORK_MISMATCH: "Address format does not match network type",
+	INVALID_BAZAAR_INFO: "extensions.bazaar.info must be an object with input and output",
+	INVALID_BAZAAR_SCHEMA: "extensions.bazaar.schema must be a valid JSON Schema object",
+	INVALID_BAZAAR_INFO_INPUT: "extensions.bazaar.info.input must include type and method",
+	INVALID_OUTPUT_SCHEMA: "accepts[i].outputSchema must be an object with input and output",
+	INVALID_OUTPUT_SCHEMA_INPUT: "accepts[i].outputSchema.input must include type and method",
+	MISSING_INPUT_SCHEMA: "No input schema found (no bazaar extension or outputSchema) -- consider adding one so agents know how to call your API",
 	UNKNOWN_NETWORK: "Network is not in the known registry -- config may still work but cannot be fully validated",
 	UNKNOWN_ASSET: "Asset is not in the known registry -- config may still work but cannot be fully validated",
 	LEGACY_FORMAT: "Config uses legacy flat format -- consider upgrading to x402 v2",
@@ -1724,6 +1736,146 @@ function validateLegacy(_config, detectedFormat, _originalInput) {
 	return issues;
 }
 
+//#endregion
+//#region src/validation/rules/extensions.ts
+/**
+* Check whether a value is a non-null plain object (not an array).
+*/
+function isObject(v) {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/**
+* Validate `extensions.bazaar` when present.
+*
+* Checks:
+* - bazaar is an object
+* - bazaar.info exists and is an object with input (type + method) and output
+* - bazaar.schema exists and looks like a JSON Schema object
+*
+* @returns Array of warning issues (empty when bazaar is absent or valid)
+*/
+function validateBazaar(config) {
+	const issues = [];
+	if (!config.extensions) return issues;
+	const bazaar = config.extensions["bazaar"];
+	if (bazaar === void 0) return issues;
+	if (!isObject(bazaar)) {
+		issues.push({
+			code: ErrorCode.INVALID_BAZAAR_INFO,
+			field: "extensions.bazaar",
+			message: "extensions.bazaar must be an object",
+			severity: "warning",
+			fix: "Set extensions.bazaar to an object with info and schema properties"
+		});
+		return issues;
+	}
+	const info = bazaar["info"];
+	if (!isObject(info)) issues.push({
+		code: ErrorCode.INVALID_BAZAAR_INFO,
+		field: "extensions.bazaar.info",
+		message: ErrorMessages.INVALID_BAZAAR_INFO,
+		severity: "warning",
+		fix: "Add an info object with input and output properties describing your API"
+	});
+	else {
+		const input = info["input"];
+		if (!isObject(input) || !input["type"] || !input["method"]) issues.push({
+			code: ErrorCode.INVALID_BAZAAR_INFO_INPUT,
+			field: "extensions.bazaar.info.input",
+			message: ErrorMessages.INVALID_BAZAAR_INFO_INPUT,
+			severity: "warning",
+			fix: "Add input.type (e.g. \"application/json\") and input.method (e.g. \"POST\")"
+		});
+		const output = info["output"];
+		if (!isObject(output)) issues.push({
+			code: ErrorCode.INVALID_BAZAAR_INFO,
+			field: "extensions.bazaar.info.output",
+			message: "extensions.bazaar.info.output must be an object",
+			severity: "warning",
+			fix: "Add an output object describing the API response format"
+		});
+	}
+	const schema = bazaar["schema"];
+	if (!isObject(schema) || !schema["type"] && !schema["$schema"] && !schema["properties"]) issues.push({
+		code: ErrorCode.INVALID_BAZAAR_SCHEMA,
+		field: "extensions.bazaar.schema",
+		message: ErrorMessages.INVALID_BAZAAR_SCHEMA,
+		severity: "warning",
+		fix: "Add a JSON Schema object with type, $schema, or properties"
+	});
+	return issues;
+}
+/**
+* Validate `accepts[].outputSchema` on the raw parsed input.
+*
+* Uses the raw parsed object because AcceptsEntry strips outputSchema during normalization.
+*
+* Checks per entry with outputSchema:
+* - outputSchema is an object
+* - outputSchema.input exists with type and method
+* - outputSchema.output exists and is an object
+*
+* @returns Array of warning issues
+*/
+function validateOutputSchema(parsed) {
+	const issues = [];
+	const accepts = parsed["accepts"];
+	if (!Array.isArray(accepts)) return issues;
+	for (let i = 0; i < accepts.length; i++) {
+		const entry = accepts[i];
+		if (!isObject(entry)) continue;
+		const outputSchema = entry["outputSchema"];
+		if (outputSchema === void 0) continue;
+		const fieldPath = `accepts[${i}].outputSchema`;
+		if (!isObject(outputSchema)) {
+			issues.push({
+				code: ErrorCode.INVALID_OUTPUT_SCHEMA,
+				field: fieldPath,
+				message: ErrorMessages.INVALID_OUTPUT_SCHEMA,
+				severity: "warning",
+				fix: "Set outputSchema to an object with input and output properties"
+			});
+			continue;
+		}
+		const input = outputSchema["input"];
+		if (!isObject(input) || !input["type"] || !input["method"]) issues.push({
+			code: ErrorCode.INVALID_OUTPUT_SCHEMA_INPUT,
+			field: `${fieldPath}.input`,
+			message: ErrorMessages.INVALID_OUTPUT_SCHEMA_INPUT,
+			severity: "warning",
+			fix: "Add input.type (e.g. \"application/json\") and input.method (e.g. \"POST\")"
+		});
+		const output = outputSchema["output"];
+		if (!isObject(output)) issues.push({
+			code: ErrorCode.INVALID_OUTPUT_SCHEMA,
+			field: `${fieldPath}.output`,
+			message: "accepts[i].outputSchema.output must be an object",
+			severity: "warning",
+			fix: "Add an output object describing the API response format"
+		});
+	}
+	return issues;
+}
+/**
+* Emit a warning when neither `extensions.bazaar` nor any `accepts[].outputSchema` is present.
+*
+* @returns Single-element array with MISSING_INPUT_SCHEMA warning, or empty array
+*/
+function validateMissingSchema(config, parsed) {
+	if (config.extensions && config.extensions["bazaar"] !== void 0) return [];
+	const accepts = parsed["accepts"];
+	if (Array.isArray(accepts)) {
+		for (const entry of accepts) if (isObject(entry) && entry["outputSchema"] !== void 0) return [];
+	}
+	return [{
+		code: ErrorCode.MISSING_INPUT_SCHEMA,
+		field: "extensions",
+		message: ErrorMessages.MISSING_INPUT_SCHEMA,
+		severity: "warning",
+		fix: "Add extensions.bazaar with info and schema to help agents discover your API -- see https://bazaar.x402.org"
+	}];
+}
+
 //#endregion
 //#region src/validation/orchestrator.ts
 /**
@@ -1808,6 +1960,9 @@ function runPipeline(input, options) {
 		else warnings.push(issue);
 	}
 	warnings.push(...validateLegacy(normalized, format, parsed));
+	warnings.push(...validateBazaar(normalized));
+	warnings.push(...validateOutputSchema(parsed));
+	warnings.push(...validateMissingSchema(normalized, parsed));
 	if (options?.strict === true) {
 		for (const warning of warnings) errors.push({
 			...warning,
@@ -1916,9 +2071,68 @@ function extractConfig(response) {
 	};
 }
 
+//#endregion
+//#region src/check.ts
+/**
+* Check an HTTP 402 response: extract config, validate, and enrich with registry data.
+*
+* Never throws. All failures are represented in the returned CheckResult.
+*
+* @param response - Response-like object with body and/or headers
+* @param options - Validation options (e.g. strict mode)
+* @returns Unified check result
+*/
+function check(response, options) {
+	const extraction = extractConfig(response);
+	if (!extraction.config) return {
+		extracted: false,
+		source: null,
+		extractionError: extraction.error,
+		valid: false,
+		version: "unknown",
+		errors: [],
+		warnings: [],
+		normalized: null,
+		summary: [],
+		raw: null
+	};
+	const validation = validate(extraction.config, options);
+	const summary = [];
+	const accepts = validation.normalized?.accepts ?? [];
+	for (let i = 0; i < accepts.length; i++) {
+		const entry = accepts[i];
+		const networkInfo = getNetworkInfo(entry.network);
+		const assetInfo = getAssetInfo(entry.network, entry.asset);
+		summary.push({
+			index: i,
+			network: entry.network,
+			networkName: networkInfo?.name ?? entry.network,
+			networkType: networkInfo?.type ?? null,
+			payTo: entry.payTo,
+			amount: entry.amount,
+			asset: entry.asset,
+			assetSymbol: assetInfo?.symbol ?? null,
+			assetDecimals: assetInfo?.decimals ?? null,
+			scheme: entry.scheme
+		});
+	}
+	return {
+		extracted: true,
+		source: extraction.source,
+		extractionError: null,
+		valid: validation.valid,
+		version: validation.version,
+		errors: validation.errors,
+		warnings: validation.warnings,
+		normalized: validation.normalized,
+		summary,
+		raw: extraction.config
+	};
+}
+
 //#endregion
 //#region src/index.ts
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 
 //#endregion
 exports.CAIP2_REGEX = CAIP2_REGEX;
@@ -1928,6 +2142,7 @@ exports.KNOWN_ASSETS = KNOWN_ASSETS;
 exports.KNOWN_NETWORKS = KNOWN_NETWORKS;
 exports.SIMPLE_NAME_TO_CAIP2 = SIMPLE_NAME_TO_CAIP2;
 exports.VERSION = VERSION;
+exports.check = check;
 exports.decodeBase58 = decodeBase58;
 exports.detect = detect;
 exports.extractConfig = extractConfig;