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.

17.4 KB
Raw Blame
// @ts-check
// api/_lib/x402/preflight.js
//
// x402 Preflight: a signed, time-bounded statement that an endpoint can
// actually take your money and finish the job.
//
// The problem it exists for
// -------------------------
// x402 tells a client WHAT a resource costs. It says nothing about whether the
// server is currently able to SETTLE what it charges. Those are different
// questions with the same happy path and completely different failure modes,
// and the gap between them is paid for by the buyer:
//
//   1. client GETs a paid route, receives 402 with a price and accepts
//   2. client signs a transfer and retries with X-PAYMENT
//   3. server cannot settle (its fee sponsor is empty, its facilitator is down,
//      its RPC is over quota) and answers 502
//
// The client burned a signature, a blockhash and a round trip on a service that
// could not have completed at step 1. Worse, in the sponsored-fee model the
// buyer's own funds are fine: the thing that is broken belongs to the SELLER,
// and the buyer has no way to see it. On 2026-08-28 three.ws was that seller for
// three hours. 95 payment attempts, 0 settled, every one of them predictable
// from state the server already had.
//
// Preflight closes that gap the way CORS preflight closes its own: one cheap,
// cacheable request BEFORE the expensive one, answered from state the server
// already computes.
//
// Why it is signed, and why that is the interesting part
// -----------------------------------------------------
// An unsigned health endpoint is a courtesy. A signed, time-bounded, replay-
// resistant one is EVIDENCE. Three properties follow, and none of them are
// available from a plain status page:
//
//   ATTRIBUTABLE   A client that paid after reading `payable: true` holds a
//                  statement signed by the seller's own attester key saying the
//                  seller believed it could settle, at a stated instant. In a
//                  marketplace of autonomous agents transacting with strangers,
//                  that is the difference between "it broke" and "you said it
//                  would work". Disputes stop being he-said-she-said.
//   UNREPLAYABLE   Every attestation carries `expires_at` and verification
//                  REJECTS an expired one. A seller cannot serve a cached
//                  healthy attestation through an outage, and an attacker who
//                  captures one cannot replay it later.
//   RELAYABLE      Because it verifies offline against a public key, a registry,
//                  an index or a peer can cache and forward attestations without
//                  becoming trusted. Discovery services can rank by measured
//                  settleability instead of by self-description.
//
// Honesty rules the format enforces
// ---------------------------------
//  * `payable` is a THREE-valued field: true, false, or unknown. A server that
//    cannot determine its own state must say `unknown`, never `true`. Every
//    code path here fails to `unknown`, so a crashed sensor degrades to "I do
//    not know" rather than to a lie.
//  * Every rate carries the window and the sample size it was measured over. A
//    rate without its window is a rumour; `confidence` is derived from the
//    sample, so a 100% settle rate over 3 attempts cannot masquerade as proof.
//  * `alternates` names the other networks on the same origin that ARE payable,
//    so a client whose preferred rail is down can re-route in the same round
//    trip instead of discovering the outage one failed payment at a time.
//  * `retry_after` is advisory back-off, so a fleet of agents meeting an
//    unpayable seller backs off instead of synchronising into a retry storm.
//
// This module is deliberately pure: no DB, no fetch, no chain, no clock except
// what the caller injects. The I/O that feeds it lives in api/x402/preflight.js,
// and the same verify() below is what runs inside the browser SDK and the CLI.
//
// Spec: specs/x402-preflight.md

import { createHash } from 'node:crypto';
import { ed25519 } from '@noble/curves/ed25519.js';
import bs58 from 'bs58';

/** Body profile emitted by this module. Bump on a breaking body change. */
export const PREFLIGHT_SPEC = 'x402-preflight/1';

/**
 * Envelope version, and the domain separator mixed into the signed bytes.
 * Domain separation is what stops a preflight signature from ever being
 * replayable as an agent-manifest signature or any other three.ws statement
 * signed by the same attester identity.
 */
export const PREFLIGHT_ENVELOPE_VERSION = 'threews.x402.preflight.v1';

/** Default validity. Short enough that a stale copy cannot outlive an incident. */
export const PREFLIGHT_TTL_SECONDS = 60;

/** Hard ceiling on requested TTL: an hour-long assurance is not an assurance. */
export const PREFLIGHT_MAX_TTL_SECONDS = 300;

/**
 * Machine-readable reasons an endpoint is not payable. Clients switch on these,
 * so they are part of the wire contract: add, never repurpose.
 *
 * `sponsor_below_floor` is the one that produced this whole module. It means the
 * SELLER's fee wallet cannot pay network fees, so nothing the buyer does can
 * make the payment settle.
 */
export const PREFLIGHT_REASONS = Object.freeze([
	'ok',
	'sponsor_below_floor',
	'settlement_degraded',
	'facilitator_unreachable',
	'network_not_configured',
	'rail_unavailable',
	'unknown',
]);

const REASON_SET = new Set(PREFLIGHT_REASONS);

/**
 * Back-off hint per reason, in seconds. A dry sponsor needs a human with a
 * wallet, so the hint is minutes; a degraded rail usually clears itself, so the
 * hint is short enough to retry within the same task.
 */
const RETRY_AFTER = Object.freeze({
	sponsor_below_floor: 300,
	settlement_degraded: 60,
	facilitator_unreachable: 60,
	rail_unavailable: 60,
	network_not_configured: 3600,
	unknown: 30,
});

// Deterministic JSON: keys sorted recursively, undefined dropped. The signer and
// every verifier must hash byte-identical input regardless of property insertion
// order, so this is the one representation that may be hashed.
function canonicalize(value) {
	if (Array.isArray(value)) return `[${value.map(canonicalize).join(',')}]`;
	if (value && typeof value === 'object') {
		const keys = Object.keys(value)
			.filter((k) => value[k] !== undefined)
			.sort();
		return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(',')}}`;
	}
	return JSON.stringify(value === undefined ? null : value);
}

/** sha256 of a string as lowercase hex. */
export function sha256Hex(input) {
	return createHash('sha256').update(Buffer.from(String(input), 'utf8')).digest('hex');
}

/**
 * Statistical confidence in a measured rate, on 0..1.
 *
 * A settle rate is only as trustworthy as the sample behind it, and the failure
 * this guards against is real: a ring that settled 3 of 3 payments overnight
 * reports 100%, which reads identically to a proven rail. Confidence rises with
 * the sample and is capped below 1 because no finite sample proves the next
 * payment settles.
 *
 * Deliberately a simple saturating curve rather than a Wilson interval: the
 * number is a hint for routing, and a hint an operator can predict in their head
 * beats a statistically tighter one nobody can sanity-check.
 * @param {number} attempts
 * @returns {number} 0..0.99, two decimals
 */
export function sampleConfidence(attempts) {
	const n = Math.max(0, Math.floor(Number(attempts) || 0));
	if (n <= 0) return 0;
	// 20 attempts is the same threshold the settle sensor uses before it will
	// judge a window at all, and lands here at ~0.66.
	return Math.round(Math.min(0.99, n / (n + 10)) * 100) / 100;
}

/**
 * Decide one network's payability from the platform's own measurements.
 *
 * Every branch that cannot prove payability returns `unknown` rather than
 * guessing, and `payable: true` is only ever returned on positive evidence. That
 * asymmetry is the whole point: a buyer acting on this makes an irreversible
 * transfer, so the expensive mistake is a false `true`, never a false `unknown`.
 *
 * Pure. The caller supplies every input; nothing is read from the environment.
 *
 * @param {object} p
 * @param {boolean} p.configured        is this network wired up to accept at all
 * @param {boolean|null} [p.sponsorBelowFloor]  null when unmeasured
 * @param {'ok'|'degraded'|'down'|'unknown'|null} [p.settleStatus]
 * @param {number|null} [p.settleRate]  0..1, null when unmeasured
 * @param {number} [p.attempts]         sample behind settleRate
 * @param {number} [p.windowHours]
 * @param {boolean} [p.facilitatorReachable]
 * @returns {{ payable: boolean|'unknown', reason: string, retry_after: number|null,
 *   settle: { rate: number|null, attempts: number, window_hours: number|null, confidence: number } }}
 */
export function decideNetworkPayability({
	configured,
	sponsorBelowFloor = null,
	settleStatus = null,
	settleRate = null,
	attempts = 0,
	windowHours = null,
	facilitatorReachable = true,
}) {
	const settle = {
		rate: settleRate == null || !Number.isFinite(Number(settleRate)) ? null : Number(settleRate),
		attempts: Math.max(0, Math.floor(Number(attempts) || 0)),
		window_hours: windowHours == null ? null : Number(windowHours),
		confidence: sampleConfidence(attempts),
	};
	const out = (payable, reason) => ({
		payable,
		reason,
		retry_after: payable === true ? null : (RETRY_AFTER[reason] ?? RETRY_AFTER.unknown),
		settle,
	});

	if (!configured) return out(false, 'network_not_configured');
	// The seller's fee wallet is empty. Nothing the buyer does can fix this, which
	// is exactly why it has to be said BEFORE the buyer signs anything.
	if (sponsorBelowFloor === true) return out(false, 'sponsor_below_floor');
	if (!facilitatorReachable) return out('unknown', 'facilitator_unreachable');
	if (settleStatus === 'down') return out(false, 'settlement_degraded');
	if (settleStatus === 'degraded') return out(false, 'settlement_degraded');
	// Configured, nothing known to be broken, but nothing measured either: a
	// quiet rail is not a proven one.
	if (settleStatus === 'unknown' || settleStatus == null) return out('unknown', 'unknown');
	return out(true, 'ok');
}

/**
 * Assemble the report body. Networks are sorted by id so the canonical bytes do
 * not depend on the order the caller happened to gather them in.
 *
 * @param {object} p
 * @param {string} p.subject           origin the report speaks for
 * @param {Record<string, ReturnType<typeof decideNetworkPayability> & {asset?:string, pay_to?:string}>} p.networks
 * @param {string} [p.issuedAt]        ISO
 * @param {number} [p.ttlSeconds]
 * @param {object} [p.endpoint]        optional per-route detail
 * @returns {object}
 */
export function buildPreflightReport({ subject, networks, issuedAt, ttlSeconds, endpoint }) {
	if (!subject) throw new Error('buildPreflightReport: subject is required');
	const at = issuedAt || new Date().toISOString();
	const ttl = Math.min(
		PREFLIGHT_MAX_TTL_SECONDS,
		Math.max(1, Math.floor(Number(ttlSeconds) || PREFLIGHT_TTL_SECONDS)),
	);

	/** @type {Record<string, object>} */
	const sorted = {};
	for (const key of Object.keys(networks || {}).sort()) {
		const n = networks[key];
		sorted[key] = {
			payable: n.payable,
			reason: REASON_SET.has(n.reason) ? n.reason : 'unknown',
			retry_after: n.retry_after ?? null,
			settle: n.settle,
			...(n.asset ? { asset: n.asset } : {}),
			...(n.pay_to ? { pay_to: n.pay_to } : {}),
		};
	}

	// Alternates are computed here rather than left to the client so that every
	// consumer (SDK, CLI, a registry relaying the envelope) agrees on the same
	// fallback set, and so the set is inside the signature.
	const payableIds = Object.keys(sorted).filter((k) => sorted[k].payable === true);
	for (const key of Object.keys(sorted)) {
		sorted[key].alternates = payableIds.filter((k) => k !== key);
	}

	const body = {
		$schema: 'https://three.ws/schemas/x402-preflight/1.json',
		spec: PREFLIGHT_SPEC,
		subject: String(subject),
		issued_at: at,
		expires_at: new Date(new Date(at).getTime() + ttl * 1000).toISOString(),
		networks: sorted,
		payable_any: payableIds.length > 0,
	};
	if (endpoint) body.endpoint = endpoint;
	return body;
}

/** The exact bytes run through ed25519, domain-separated by envelope version. */
export function signingMessage(digest) {
	return Buffer.from(`${PREFLIGHT_ENVELOPE_VERSION}:${digest}`, 'utf8');
}

/** Digest over the report plus the issuer and instant it was signed at. */
export function reportDigest({ report, issuer, signedAt }) {
	return sha256Hex(canonicalize({ report, issuer, signedAt }));
}

/**
 * Sign a report with an ed25519 secret key (a Solana Keypair's 64-byte
 * secretKey, or a raw 32-byte seed). Pure crypto: no DB, no network.
 * @param {object} report from buildPreflightReport
 * @param {Uint8Array} secretKey
 * @param {{signedAt?: string}} [opts]
 * @returns {object} the signed envelope
 */
export function signPreflight(report, secretKey, { signedAt } = {}) {
	const seed = secretKey.slice(0, 32);
	const issuer = bs58.encode(ed25519.getPublicKey(seed));
	const at = signedAt || report.issued_at || new Date().toISOString();
	const digest = reportDigest({ report, issuer, signedAt: at });
	return {
		spec: PREFLIGHT_ENVELOPE_VERSION,
		report,
		issuer,
		signedAt: at,
		digest,
		algorithm: 'ed25519',
		signature: bs58.encode(ed25519.sign(signingMessage(digest), seed)),
	};
}

/**
 * Verify a signed envelope. Pure and offline: this is what an outside party runs
 * on bytes it fetched, and what the browser SDK runs before trusting a report.
 *
 * Expiry is checked as part of verification, not left to the caller. An expired
 * attestation is not a valid one that happens to be old: treating it as valid is
 * precisely the replay this format exists to prevent, and making it the caller's
 * job would mean every consumer has to remember. `clockSkewMs` allows for honest
 * clock drift between two machines without opening a replay window.
 *
 * @param {object} envelope
 * @param {{issuer?: string, now?: number, clockSkewMs?: number, subject?: string}} [expect]
 * @returns {{ valid: boolean, reason: string, issuer: string|null, digest: string|null, expired: boolean }}
 */
export function verifyPreflight(envelope, { issuer: expectedIssuer, now, clockSkewMs = 30_000, subject } = {}) {
	const fail = (reason, extra = {}) => ({
		valid: false,
		reason,
		issuer: envelope?.issuer || null,
		digest: null,
		expired: false,
		...extra,
	});

	if (!envelope || typeof envelope !== 'object' || !envelope.report) return fail('not_an_envelope');
	if (envelope.spec !== PREFLIGHT_ENVELOPE_VERSION) return fail('unsupported_envelope_version');
	if (envelope.algorithm && envelope.algorithm !== 'ed25519') return fail('unsupported_algorithm');
	if (!envelope.issuer || !envelope.signature || !envelope.signedAt) return fail('unsigned');
	if (envelope.report.spec !== PREFLIGHT_SPEC) return fail('unsupported_report_spec');

	const digest = reportDigest({
		report: envelope.report,
		issuer: envelope.issuer,
		signedAt: envelope.signedAt,
	});
	if (envelope.digest && String(envelope.digest).toLowerCase() !== digest) {
		return { ...fail('digest_mismatch'), digest };
	}
	if (expectedIssuer && expectedIssuer !== envelope.issuer) {
		return { ...fail('issuer_mismatch'), digest };
	}
	// A report is only about the origin it names. Without this check a valid
	// attestation for one seller could be presented as covering another.
	if (subject && normalizeOrigin(subject) !== normalizeOrigin(envelope.report.subject)) {
		return { ...fail('subject_mismatch'), digest };
	}

	let ok = false;
	try {
		ok = ed25519.verify(bs58.decode(envelope.signature), signingMessage(digest), bs58.decode(envelope.issuer));
	} catch {
		return { ...fail('malformed_signature'), digest };
	}
	if (!ok) return { ...fail('bad_signature'), digest };

	const at = typeof now === 'number' ? now : Date.now();
	const expiresAt = Date.parse(envelope.report.expires_at || '');
	if (!Number.isFinite(expiresAt)) return { ...fail('no_expiry'), digest };
	if (at - clockSkewMs > expiresAt) {
		return { valid: false, reason: 'expired', issuer: envelope.issuer, digest, expired: true };
	}
	// A report stamped in the future is either a broken clock or a forgery
	// attempt to extend an assurance window. Neither is safe to act on.
	const issuedAt = Date.parse(envelope.report.issued_at || '');
	if (Number.isFinite(issuedAt) && issuedAt - clockSkewMs > at) {
		return { ...fail('issued_in_future'), digest };
	}

	return { valid: true, reason: 'ok', issuer: envelope.issuer, digest, expired: false };
}

/** Compare origins without being defeated by a trailing slash or a case change. */
export function normalizeOrigin(value) {
	try {
		const u = new URL(String(value));
		return `${u.protocol}//${u.host}`.toLowerCase();
	} catch {
		return String(value || '').trim().replace(/\/+$/, '').toLowerCase();
	}
}

/**
 * Read one network's verdict out of a VERIFIED envelope.
 *
 * Takes the envelope rather than the report so a caller cannot skip
 * verification by reaching for the body directly, and returns `unknown` for a
 * network the report does not mention rather than treating silence as a no.
 * @param {object} envelope
 * @param {string} network e.g. 'solana:mainnet'
 * @returns {{ payable: boolean|'unknown', reason: string, retry_after: number|null, alternates: string[] }}
 */
export function networkVerdict(envelope, network) {
	const n = envelope?.report?.networks?.[network];
	if (!n) return { payable: 'unknown', reason: 'network_not_configured', retry_after: null, alternates: [] };
	return {
		payable: n.payable,
		reason: n.reason,
		retry_after: n.retry_after ?? null,
		alternates: Array.isArray(n.alternates) ? n.alternates : [],
	};
}