Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

16.4 KB
Raw Blame
// Pure logic for the free x402 developer toolkit (echo / debug / verify-receipt).
//
// Kept I/O-free so every branch is unit-testable without a network or a live
// facilitator. The route handlers in api/x402/{echo,debug,verify-receipt}.js are
// thin wrappers that add CORS, rate limiting, and body parsing on top of these.
//
// Three capabilities:
//   • redactPaymentEnvelope() — decode an X-PAYMENT header and strip every
//     signature/secret down to a short prefix so echo can show a developer the
//     server's view of their payload WITHOUT leaking a reusable authorization.
//   • structuralVerdict()     — the rail's LOCAL verification (shape + signed
//     amount vs required + signed recipient vs payTo + builder-code echo). No
//     facilitator round-trip, no settlement — a fast, safe "would this pass our
//     own pre-facilitator checks?" verdict.
//   • diagnoseExchange()      — turn a failed 402 exchange (challenge / payment /
//     response, any subset) into a [{severity, field, problem, fix}] list keyed
//     to the real failure modes our rail produces.
//   • recomputeAttestation() / verifyAttestation() — recompute a three.ws
//     SHA-256 response attestation (fact-check style) and confirm/deny integrity.

import { createHash } from 'crypto';

import {
	decodePaymentHeader,
	decodeSignedAmount,
	decodeSignedRecipient,
	X402_VERSION,
	NETWORK_BASE_MAINNET,
	NETWORK_SOLANA_MAINNET,
} from '../x402-spec.js';

// Every field name whose value is a signature, private authorization, or other
// secret that must never be echoed back in full. Matched case-insensitively,
// substring — `signature`, `sig`, `authorization`, `secret`, `privateKey`, etc.
const SECRET_KEY_PATTERNS = [
	'signature',
	'sig',
	'secret',
	'privatekey',
	'private_key',
	'mnemonic',
	'seed',
	'password',
	'passphrase',
];

// How many leading characters of a redacted secret to keep, so a developer can
// still eyeball "yes that's my sig" without the value being replayable.
const REDACT_KEEP = 10;

function looksSecret(key) {
	const k = String(key).toLowerCase();
	return SECRET_KEY_PATTERNS.some((p) => k.includes(p));
}

// Replace a secret value with `<prefix>…(redacted, N chars)`. Non-string
// secrets (rare) collapse to a type marker so nothing sensitive survives.
function redactValue(value) {
	if (typeof value !== 'string') return '<redacted:non-string>';
	if (value.length <= REDACT_KEEP) return `${value}…(redacted)`;
	return `${value.slice(0, REDACT_KEEP)}…(redacted, ${value.length} chars)`;
}

// Deep-clone `obj`, redacting any value whose key looks like a secret. Also
// redacts long hex/base64 blobs living under an `authorization` object even when
// the key itself is innocuous (e.g. EIP-3009 `v`/`r`/`s` split signatures).
export function redactSecrets(obj, { inAuthorization = false } = {}) {
	if (Array.isArray(obj)) return obj.map((v) => redactSecrets(v, { inAuthorization }));
	if (obj && typeof obj === 'object') {
		const out = {};
		for (const [k, v] of Object.entries(obj)) {
			const childInAuth = inAuthorization || k.toLowerCase() === 'authorization';
			if (looksSecret(k)) {
				out[k] = redactValue(v);
			} else if (
				childInAuth &&
				typeof v === 'string' &&
				/^0x[0-9a-fA-F]{16,}$/.test(v)
			) {
				// A long 0x blob inside the signed authorization is signature
				// material regardless of its field name — redact it too.
				out[k] = redactValue(v);
			} else if (v && typeof v === 'object') {
				out[k] = redactSecrets(v, { inAuthorization: childInAuth });
			} else {
				out[k] = v;
			}
		}
		return out;
	}
	return obj;
}

// Decode an X-PAYMENT header and return a redacted view of the envelope plus the
// fields a developer needs to debug: version, scheme, network, and the located
// signed amount/recipient. Throws on a structurally invalid header (base64 / JSON
// / not-an-object) — the caller maps that to a 400 with the thrown message.
export function redactPaymentEnvelope(paymentHeader) {
	const payload = decodePaymentHeader(paymentHeader); // throws X402Error on bad shape
	const signedAmount = decodeSignedAmount(payload);
	const signedRecipient = decodeSignedRecipient(payload);
	return {
		x402Version: payload.x402Version ?? null,
		scheme: payload.scheme ?? payload.accepted?.scheme ?? null,
		network: payload.network ?? payload.accepted?.network ?? null,
		signedAmount: signedAmount === null ? null : signedAmount.toString(),
		signedRecipient,
		envelope: redactSecrets(payload),
	};
}

// The rail's LOCAL pre-facilitator verdict for a decoded payment against a single
// requirement (accept entry). Mirrors the defense-in-depth checks verifyPayment()
// runs before ever calling the facilitator, but performs no network I/O and never
// settles. Returns { valid, checks[], reason? }.
//
// `requirement` is one accepts[] entry ({ scheme, network, amount, payTo, ... }).
// When omitted, only the envelope-shape checks run (amount/recipient are reported
// as "no requirement to compare against").
export function structuralVerdict(payload, requirement) {
	const checks = [];
	const fail = (field, detail) => checks.push({ field, pass: false, detail });
	const pass = (field, detail) => checks.push({ field, pass: true, detail });

	// Shape.
	if (!payload || typeof payload !== 'object') {
		return { valid: false, checks: [{ field: 'payload', pass: false, detail: 'not an object' }], reason: 'payload is not an object' };
	}
	if (payload.x402Version === X402_VERSION) pass('x402Version', `is ${X402_VERSION}`);
	else fail('x402Version', `expected ${X402_VERSION}, got ${payload.x402Version ?? 'undefined'}`);

	const scheme = payload.scheme ?? payload.accepted?.scheme;
	if (scheme) pass('scheme', String(scheme));
	else fail('scheme', 'missing scheme (top-level or accepted.scheme)');

	const network = payload.network ?? payload.accepted?.network;
	if (network) pass('network', String(network));
	else fail('network', 'missing network');

	// Amount: the signed amount must be ≥ the required amount (underpayment guard).
	const signedAmount = decodeSignedAmount(payload);
	if (requirement && requirement.amount != null) {
		if (signedAmount === null) {
			pass('amount', 'signed amount not locally decodable (Solana SPL / opaque) — facilitator-trusted');
		} else {
			let required = null;
			try {
				required = BigInt(requirement.amount);
			} catch {
				fail('amount', `requirement.amount "${requirement.amount}" is not an integer string`);
			}
			if (required !== null) {
				if (signedAmount >= required) pass('amount', `signed ${signedAmount} ≥ required ${required}`);
				else fail('amount', `signed ${signedAmount} < required ${required} (underpayment)`);
			}
		}
	} else if (signedAmount !== null) {
		pass('amount', `signed ${signedAmount} (no requirement supplied to compare)`);
	}

	// Recipient: the signed `to` must equal the requirement's payTo.
	const signedRecipient = decodeSignedRecipient(payload);
	if (requirement && requirement.payTo) {
		if (signedRecipient === null) {
			pass('payTo', 'signed recipient not locally decodable — facilitator-trusted');
		} else if (signedRecipient === String(requirement.payTo).toLowerCase()) {
			pass('payTo', 'signed recipient matches requirement.payTo');
		} else {
			fail('payTo', `signed recipient ${signedRecipient} ≠ requirement.payTo ${String(requirement.payTo).toLowerCase()}`);
		}
	}

	const failed = checks.filter((c) => !c.pass);
	return {
		valid: failed.length === 0,
		checks,
		...(failed.length ? { reason: failed.map((c) => `${c.field}: ${c.detail}`).join('; ') } : {}),
	};
}

// Known networks our rail settles on, for the debugger's network sanity check.
const KNOWN_NETWORKS = new Set([
	NETWORK_BASE_MAINNET,
	NETWORK_SOLANA_MAINNET,
	'eip155:42161',
	'eip155:56',
	'eip155:196',
]);

// Common shorthand a developer might send instead of the CAIP-2 id our accepts[]
// advertise — flagged with the canonical form as the fix.
const NETWORK_ALIASES = {
	base: NETWORK_BASE_MAINNET,
	'base-mainnet': NETWORK_BASE_MAINNET,
	solana: NETWORK_SOLANA_MAINNET,
	'solana-mainnet': NETWORK_SOLANA_MAINNET,
	arbitrum: 'eip155:42161',
	bsc: 'eip155:56',
	xlayer: 'eip155:196',
};

// Diagnose a failed x402 exchange. `input` may carry any subset of
// { challenge, payment, response }. Returns a flat list of findings ordered
// most-severe first: [{ severity: 'error'|'warning'|'info', field, problem, fix }].
export function diagnoseExchange(input = {}) {
	const findings = [];
	const add = (severity, field, problem, fix) => findings.push({ severity, field, problem, fix });

	const { challenge, payment, response } = input || {};

	if (challenge === undefined && payment === undefined && response === undefined) {
		add('error', 'input', 'no challenge, payment, or response supplied', 'POST at least one of { challenge, payment, response } — the 402 body, your X-PAYMENT payload (decoded), and/or the server response you got back.');
		return { findings, ok: false };
	}

	// ── Challenge (the 402 body the server sent) ────────────────────────────
	let accepts = null;
	if (challenge !== undefined) {
		if (!challenge || typeof challenge !== 'object') {
			add('error', 'challenge', 'challenge is not a JSON object', 'Paste the parsed 402 response body, e.g. { x402Version, accepts: [...] }.');
		} else {
			if (challenge.x402Version !== undefined && challenge.x402Version !== X402_VERSION) {
				add('warning', 'challenge.x402Version', `challenge advertises x402Version ${challenge.x402Version}; this server speaks ${X402_VERSION}`, `Send x402Version: ${X402_VERSION} in your payment payload.`);
			}
			accepts = challenge.accepts || challenge.requirements || null;
			if (!Array.isArray(accepts) || accepts.length === 0) {
				add('error', 'challenge.accepts', 'challenge has no accepts[] array', 'A valid 402 body carries accepts[] (v2) or requirements[] (legacy) with at least one payment option.');
			} else {
				for (let i = 0; i < accepts.length; i++) {
					const a = accepts[i];
					if (a?.amount != null && !/^\d+$/.test(String(a.amount))) {
						add('error', `challenge.accepts[${i}].amount`, `amount "${a.amount}" is not an integer atomic-units string`, 'amount is in the asset\'s smallest unit as a string (USDC 6-decimals → "10000" = $0.01), never a decimal like "0.01".');
					}
				}
			}
		}
	}

	// ── Payment (the decoded X-PAYMENT payload the caller signed) ───────────
	if (payment !== undefined) {
		if (!payment || typeof payment !== 'object') {
			add('error', 'payment', 'payment is not a JSON object', 'Base64-decode your X-PAYMENT header and paste the resulting JSON here (or POST the raw header to /api/x402/echo).');
		} else {
			if (payment.x402Version !== undefined && payment.x402Version !== X402_VERSION) {
				add('error', 'payment.x402Version', `payment declares x402Version ${payment.x402Version}; server requires ${X402_VERSION}`, `Set x402Version: ${X402_VERSION}.`);
			} else if (payment.x402Version === undefined) {
				add('warning', 'payment.x402Version', 'payment payload omits x402Version', `Include x402Version: ${X402_VERSION}.`);
			}
			const net = payment.network ?? payment.accepted?.network;
			if (net) {
				const alias = NETWORK_ALIASES[String(net).toLowerCase()];
				if (alias && alias !== net) {
					add('error', 'payment.network', `network "${net}" is a shorthand, not the CAIP-2 id the rail matches on`, `Use "${alias}".`);
				} else if (!KNOWN_NETWORKS.has(net) && !alias) {
					add('warning', 'payment.network', `network "${net}" is not one this server advertises`, 'Copy the exact network string from an accepts[] entry in the 402 challenge.');
				}
				// Cross-check against the challenge's offered networks.
				if (Array.isArray(accepts) && accepts.length) {
					const offered = accepts.map((a) => a.network).filter(Boolean);
					if (offered.length && !offered.includes(net)) {
						add('error', 'payment.network', `you signed for "${net}" but the challenge only offers [${offered.join(', ')}]`, 'Pick one of the offered networks and re-sign against that accepts[] entry.');
					}
				}
			} else {
				add('error', 'payment.network', 'payment payload has no network', 'Set network to the CAIP-2 id from the accepts[] entry you chose.');
			}

			// Amount vs the matching accept.
			const signed = decodeSignedAmount(payment);
			if (signed !== null && Array.isArray(accepts) && accepts.length) {
				const match = accepts.find((a) => a.network === (payment.network ?? payment.accepted?.network)) || accepts[0];
				if (match?.amount != null && /^\d+$/.test(String(match.amount))) {
					const required = BigInt(match.amount);
					if (signed < required) {
						add('error', 'payment.authorization.value', `signed amount ${signed} is below the required ${required}`, 'Sign an authorization for at least the amount in the accepts[] entry (atomic units).');
					}
				}
			}
			// Decimal-vs-atomic footgun: an authorization value that looks like a
			// human decimal ("0.01") never parses as atomic units.
			const rawVal = payment?.payload?.authorization?.value;
			if (typeof rawVal === 'string' && rawVal.includes('.')) {
				add('error', 'payment.authorization.value', `value "${rawVal}" contains a decimal point`, 'Authorization value is atomic units as an integer string ("10000"), not a decimal token amount.');
			}
		}
	}

	// ── Response (the server's error the caller got back) ───────────────────
	if (response !== undefined && response && typeof response === 'object') {
		const code = response.error || response.code;
		const known = {
			payment_required: 'No X-PAYMENT header was sent (or it was empty). Attach your base64 payment payload as the X-PAYMENT header and retry.',
			invalid_payment: 'The payload was structurally valid but failed a check — usually underpayment, wrong payTo, or a malformed authorization. Run /api/x402/echo on your header to see the decoded amount/recipient.',
			unsupported_network: 'The network in your payload is not one this resource offers. Use a network from the challenge accepts[].',
			builder_code_tampered: 'The builder-code extension in your payload does not echo the one the challenge declared. Do not modify extensions[]; pass them through verbatim.',
		};
		if (code && known[code]) {
			add('info', 'response.error', `server returned "${code}"`, known[code]);
		} else if (code) {
			add('info', 'response.error', `server returned "${code}"`, 'See docs/x402 for the full error catalog.');
		}
	}

	// Order: error → warning → info.
	const rank = { error: 0, warning: 1, info: 2 };
	findings.sort((a, b) => rank[a.severity] - rank[b.severity]);
	return { findings, ok: findings.every((f) => f.severity !== 'error') };
}

// Recompute a three.ws fact-check style attestation from the response fields it
// commits to. The scheme (api/x402/fact-check.js) is:
//   "sha256:" + sha256(JSON.stringify({ verdict, confidence, claim, sources: [urls] }))
// Returns the recomputed "sha256:<hex>" string.
export function recomputeAttestation(result) {
	const sources = Array.isArray(result?.sources)
		? result.sources.map((s) => (typeof s === 'string' ? s : s?.url)).filter(Boolean)
		: [];
	return (
		'sha256:' +
		createHash('sha256')
			.update(
				JSON.stringify({
					verdict: result?.verdict,
					confidence: result?.confidence,
					claim: result?.claim,
					sources,
				}),
			)
			.digest('hex')
	);
}

// Confirm/deny a claimed attestation against the result it was computed over.
// Returns { verified, scheme, recomputed, claimed, mismatchReason? }.
export function verifyAttestation(result) {
	const claimed = result?.attestation;
	if (typeof claimed !== 'string' || !claimed.startsWith('sha256:')) {
		return {
			verified: false,
			scheme: 'sha256',
			recomputed: null,
			claimed: claimed ?? null,
			mismatchReason: 'no sha256: attestation string present on the object',
		};
	}
	// Everything the scheme hashes must be present, else "verified: true" would be
	// vacuous (hashing undefineds).
	const missing = ['verdict', 'confidence', 'claim', 'sources'].filter(
		(k) => result[k] === undefined || result[k] === null,
	);
	if (missing.length) {
		return {
			verified: false,
			scheme: 'sha256',
			recomputed: null,
			claimed,
			mismatchReason: `cannot recompute — the attested fields are missing: ${missing.join(', ')}`,
		};
	}
	const recomputed = recomputeAttestation(result);
	return {
		verified: recomputed === claimed,
		scheme: 'sha256',
		recomputed,
		claimed,
		...(recomputed === claimed ? {} : { mismatchReason: 'recomputed digest does not match the attested one — the object was altered after signing' }),
	};
}