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.

77.8 KB
Raw Blame
// x402 protocol, facilitator-mediated micropayments.
// Spec: https://x402.org / https://github.com/coinbase/x402
//
// This module implements the *standard* x402 wire flow used by agentic.market,
// x402scan, and Coinbase's Bazaar. v2 wire format (April 2026 spec):
//
//   {
//     "x402Version": 2,
//     "error": "X-PAYMENT header is required",
//     "resource": { "url": "...", "description": "...", "mimeType": "application/json" },
//     "accepts": [
//       { "scheme": "exact", "network": "eip155:8453", "amount": "1000",
//         "asset": "0x...", "payTo": "0x...", "maxTimeoutSeconds": 60, "extra": {...} }
//     ],
//     "extensions": { "bazaar": { info: { input, output }, schema } }
//   }
//
// In addition to the body, the same envelope is emitted base64-encoded as the
// `payment-required` HTTP response header, required by agentic.market's
// Bazaar validator, which reads the header on its discovery probe.
//
// Networks use CAIP-2 IDs in v2: `eip155:<chainId>` for EVM, `solana:<genesis-prefix>`
// for Solana. The legacy `api/_lib/x402.js` is the unrelated Pump.fun agent-skill flow.
//
// Server flow on a paid resource:
//   1. No X-PAYMENT header → 402 with the body shape above.
//   2. Client retries with X-PAYMENT (base64-encoded PaymentPayload).
//   3. Server POSTs facilitator /verify with { x402Version, paymentPayload, paymentRequirements }
//      → { isValid, invalidReason?, payer? }
//   4. If isValid, do the work.
//   5. Server POSTs facilitator /settle (same body) → { success, transaction, network, payer }
//      Server attaches a base64 settlement object as `X-PAYMENT-RESPONSE` on the success reply.
//
// Settle has THREE outcomes, not two (Solana facilitators, 2026-09-17): success,
// failure, and `{ success:false, errorReason:'settlement_pending', transaction }`
// (broadcast, outcome not yet known). settlePayment retries a pending settle once
// and, if it is still unresolved, records it for the reconcile cron and returns
// `status:'pending'` so the buyer gets the good they paid for and the settlement
// hash to watch, instead of a 502 their own wallet history contradicts.

import { createHash } from 'crypto';

import { createCdpAuthHeaders } from '@coinbase/x402';
import {
	EIP2612_GAS_SPONSORING,
	ERC20_APPROVAL_GAS_SPONSORING,
	OFFER_RECEIPT,
	declareEip2612GasSponsoringExtension,
	declareErc20ApprovalGasSponsoringExtension,
} from '@x402/extensions';

import { env } from './env.js';
import { X402Error } from './x402-errors.js';
import { confirmSolanaPayment, signedSolanaMints } from './x402-solana-confirm.js';
import {
	NETWORK_SOLANA_MAINNET,
	NETWORK_SOLANA_DEVNET,
	isSolanaNetwork,
} from './x402/solana-networks.js';
import {
	PAYMENT_EVENT_TOPIC as BSC_PAYMENT_EVENT_TOPIC,
	settleDirectPayment,
	verifyDirectPayment,
} from './x402-bsc-direct.js';
import {
	BUILDER_CODE,
	declareBuilderCodeExtension,
	verifyClientEcho as verifyBuilderCodeEcho,
} from './x402-builder-code.js';
import { buildOffersExtension } from './x402/offer-receipt-server.js';
import { offerReceiptDeclaration } from './x402-offer-receipt.js';
import {
	NETWORK_XLAYER_MAINNET,
	okxXLayerAccept,
	settleOkxXLayerPayment,
	verifyOkxXLayerPayment,
	xlayerSettleable,
} from './x402-xlayer-okx.js';
import {
	resolveSolanaFacilitator,
	selfFacilitatorEnabled,
	selfFacilitatorUrl,
} from './x402/ring-config.js';
import {
	SETTLEMENT_PENDING_REASON,
	recordResourcePending,
} from './x402/pending-settlements.js';
// Safe to import here: self-facilitator.js pulls in env + the Solana connection
// only, never this module, so there is no cycle.
import { sponsorKnownBelowFloor } from './x402/self-facilitator.js';
import { isUptoRequirement, settleUptoClaim, uptoEnabled, verifyUpto } from './x402/upto.js';

export { X402Error };
// Re-export both gas-sponsoring declarators together so callers building 402
// bodies don't have to mix imports between this module and @x402/extensions.
// build402Body advertises both extensions as a pair when a Permit2 accept is
// present, and the public surface should match.
export { declareEip2612GasSponsoringExtension, declareErc20ApprovalGasSponsoringExtension };
export { BUILDER_CODE, declareBuilderCodeExtension };
// Protocol constant, re-exported so a caller handling a pending settle does not
// have to reach into the storage module for the wire string.
export { SETTLEMENT_PENDING_REASON };

export const X402_VERSION = 2;

// Extension keys we advertise alongside the bazaar discovery entry. Both
// gas-sponsoring extensions are non-binding hints to clients: when a
// requirement opts into the Permit2 asset-transfer method, the facilitator
// (CDP's x402ExactPermit2Proxy) lets the payer skip broadcasting the Permit2
// approval themselves. EIP-2612 sponsorship is the preferred path for tokens
// that implement EIP-2612 (Base USDC v2 does, the facilitator submits the
// off-chain permit via settleWithPermit). ERC-20 approval sponsorship is the
// universal fallback for any other ERC-20: the client signs (but does not
// broadcast) a raw approve(Permit2, MaxUint256) tx and the facilitator
// broadcasts it atomically before settling. Legacy clients stay on the
// EIP-3009 accept entry (offered first) and ignore both extensions.
export const EIP2612_EXTENSION_KEY = EIP2612_GAS_SPONSORING.key;
export const ERC20_APPROVAL_EXTENSION_KEY = ERC20_APPROVAL_GAS_SPONSORING.key;

// CAIP-2 network IDs as advertised by Coinbase x402 facilitators (PayAI, CDP).
// Solana mainnet's CAIP-2 namespace uses the truncated genesis-block hash.
export const NETWORK_BASE_MAINNET = 'eip155:8453';
export const NETWORK_BASE_SEPOLIA = 'eip155:84532';
export const NETWORK_ARBITRUM_MAINNET = 'eip155:42161';
export const NETWORK_BSC_MAINNET = 'eip155:56';
export { NETWORK_XLAYER_MAINNET };
// Solana ids come from x402/solana-networks.js, the one definition the whole
// rail shares (see isSolanaNetwork above).
export { NETWORK_SOLANA_MAINNET, NETWORK_SOLANA_DEVNET };

// Networks the CDP facilitator settles when credentials are configured.
// Confirmed against the live /supported probe, CDP advertises exact for Base
// and Arbitrum but NOT Optimism, so Optimism is deliberately absent: no accept
// entry routes there, and listing it only made /api/x402-status report 503.
const CDP_EVM_NETWORKS = new Set([
	NETWORK_BASE_MAINNET,
	NETWORK_BASE_SEPOLIA,
	NETWORK_ARBITRUM_MAINNET,
]);

// Networks that settle via on-chain pay(bytes32) calls rather than a
// facilitator (see x402-bsc-direct.js). The accept entry uses scheme='direct'
// and the client is responsible for broadcasting the tx + paying gas.
const DIRECT_NETWORKS = new Set([NETWORK_BSC_MAINNET]);

// Take a Base/Arbitrum/etc. EIP-3009 accept entry and return a sibling that
// asks the client to use the Permit2 asset-transfer method instead. The
// `assetTransferMethod` field is what @x402/evm's ExactEvmScheme keys on; with
// `supportsEip2612: true` set, the scheme will sign an EIP-2612 permit when
// its Permit2 allowance is insufficient and stuff it into the payment payload
// extensions for the facilitator to submit.
//
// Returns null when:
//   1. The source accept is not an EVM `exact` entry (BSC direct + Solana).
//   2. CDP credentials are missing, Permit2 settlement is a CDP-only path
//      (PayAI's facilitator only advertises `exact` with EIP-3009). Emitting
//      a Permit2 sibling we can't actually settle would mislead clients into
//      signing a typed-data we'd then reject at /verify time.
export function permit2VariantOf(accept) {
	if (!accept || accept.scheme !== 'exact') return null;
	if (typeof accept.network !== 'string' || !accept.network.startsWith('eip155:')) return null;
	if (!env.CDP_API_KEY_ID || !env.CDP_API_KEY_SECRET) return null;
	return {
		...accept,
		extra: {
			...(accept.extra || {}),
			assetTransferMethod: 'permit2',
			supportsEip2612: true,
		},
	};
}

// Emit an EIP-3009 accept followed by its Permit2 sibling. EIP-3009 stays
// first so the browser modal in public/x402.js (which only implements
// transferWithAuthorization) keeps selecting it; @x402/* SDK clients can pick
// the Permit2 entry to get gasless Permit2 onboarding via EIP-2612 sponsorship.
function pushEvmAccepts(out, accept) {
	out.push(accept);
	const sibling = permit2VariantOf(accept);
	if (sibling) out.push(sibling);
}

// One v2 PaymentRequirements entry per supported network. Base mainnet first
//, agentic.market's validator inspects the first entry for its supported-network
// check, and Base is the most broadly recognized option in the Bazaar.
//
// In v2, `resource` / `description` / `mimeType` are top-level on the 402 body
// (not per-accepts), and the price field is `amount` (not `maxAmountRequired`).
// `amount` (optional) overrides the per-call price advertised in every accept
// entry. The MCP server passes the per-tool price derived from priceFor() so the
// 402 challenge advertises exactly what the settle path will charge for the
// called tool, instead of a single flat X402_MAX_AMOUNT_REQUIRED. Falls back to
// the flat env default when omitted (non-MCP paid endpoints, free-tool probes).
export function paymentRequirements(resourceUrl, { amount } = {}) {
	const common = {
		scheme: 'exact',
		amount: amount != null ? String(amount) : env.X402_MAX_AMOUNT_REQUIRED,
		maxTimeoutSeconds: 60,
		...(resourceUrl ? { resource: resourceUrl } : {}),
	};
	const out = [];
	// Solana-first platform default: the Solana accept leads so first-accept
	// clients and the payment modal settle on Solana unless the caller picks
	// another network explicitly. Base/BSC follow as alternatives.
	// Sponsoring the buyer's Solana fee is a convenience, not a precondition for
	// being paid. When we settle in-house and the sponsor cannot co-sign (no key
	// loaded, or the wallet under its SOL floor), advertise the accept WITHOUT a
	// feePayer: the buyer signs as their own fee payer and the facilitator only
	// broadcasts. Mirrors the same fallback in x402-paid-endpoint.js, so the 17
	// hand-rolled paid endpoints on this builder keep receiving on an empty
	// sponsor wallet instead of going dark with it.
	const selfPayOnly = solanaSelfPayOnly();
	if (env.X402_PAY_TO_SOLANA && (solanaSettleable() || selfPayOnly)) {
		out.push({
			...common,
			network: NETWORK_SOLANA_MAINNET,
			payTo: env.X402_PAY_TO_SOLANA,
			asset: env.X402_ASSET_MINT_SOLANA,
			// PayAI's Solana facilitator requires clients to build the SPL transfer
			// with this account as fee payer; without it, /verify rejects with
			// `missing_fee_payer`. Omitted only in self-pay mode, which the guard
			// above restricts to the self-routed facilitator for exactly that reason.
			extra: {
				name: 'USDC',
				decimals: 6,
				...(selfPayOnly ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }),
			},
		});
		// $THREE alongside USDC on the same Solana rail (opt-in via
		// X402_ACCEPT_THREE_SOLANA, see env.js). Pushed AFTER the USDC entry so
		// clients that pick the first Solana accept keep settling USDC; the modal
		// surfaces both as a token chooser. Same fee-payer co-sign path, the
		// checkout server transfers any SPL mint, so no extra wiring is needed.
		if (env.X402_ACCEPT_THREE_SOLANA && (env.X402_FEE_PAYER_SOLANA || selfPayOnly)) {
			out.push({
				...common,
				...(env.X402_THREE_AMOUNT_SOLANA ? { amount: String(env.X402_THREE_AMOUNT_SOLANA) } : {}),
				network: NETWORK_SOLANA_MAINNET,
				payTo: env.X402_PAY_TO_SOLANA,
				asset: env.THREE_TOKEN_MINT,
				extra: {
					name: 'THREE',
					decimals: env.THREE_TOKEN_DECIMALS,
					...(selfPayOnly ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }),
				},
			});
		}
	}
	if (env.X402_PAY_TO_BASE) {
		pushEvmAccepts(out, {
			...common,
			network: NETWORK_BASE_MAINNET,
			payTo: env.X402_PAY_TO_BASE,
			asset: env.X402_ASSET_ADDRESS_BASE,
			// `name` MUST match the on-chain EIP-712 domain. Base USDC's domain
			// name is "USD Coin" (not "USDC"); using "USDC" here makes the
			// facilitator recompute the wrong domain hash → invalid signature.
			extra: { name: 'USD Coin', version: '2', decimals: 6 },
		});
	}
	if (env.X402_PAY_TO_BSC) {
		// BSC uses the contract-mediated "direct" scheme, see x402-bsc-direct.js
		// for the wire flow. Clients call ThreeWSPayments.pay(ref) themselves and
		// hand back the resulting tx hash via the X-PAYMENT header.
		out.push({
			...common,
			scheme: 'direct',
			network: NETWORK_BSC_MAINNET,
			payTo: env.X402_PAY_TO_BSC,
			asset: env.X402_ASSET_ADDRESS_BSC,
			extra: {
				name: 'Binance-Peg USD Coin',
				decimals: 6,
				contract: env.X402_PAY_TO_BSC,
				method: 'pay(bytes32)',
				eventTopic: BSC_PAYMENT_EVENT_TOPIC,
			},
		});
	}
	// OKX Agent Payments Protocol rail, USD₮0 on X Layer (eip155:196), per
	// specs/okx-agent-payments.md. Advertised only when settlement is actually
	// possible (OKX facilitator creds or the direct-redemption relayer key).
	// USD₮0 shares USDC's 6-decimal atomic scale, so per-tool amounts carry
	// over unchanged.
	if (xlayerSettleable()) {
		out.push(okxXLayerAccept(resourceUrl, common.amount));
	}
	return out;
}

// Lazy CDP auth-headers factory. createCdpAuthHeaders() returns an async fn that,
// when invoked, returns { verify, settle, supported, list } header maps, each
// including a Correlation-Context tag and (when keys are set) a per-operation
// signed JWT in Authorization. We instantiate once per process; the inner fn
// re-signs on every call (JWTs are short-lived).
let cdpHeadersFactoryCache = null;
function getCdpHeadersFactory() {
	if (!cdpHeadersFactoryCache) {
		cdpHeadersFactoryCache = createCdpAuthHeaders(env.CDP_API_KEY_ID, env.CDP_API_KEY_SECRET);
	}
	return cdpHeadersFactoryCache;
}

// Exported for the resolution-matrix tests; internal callers (callFacilitator,
// verifyPayment, settlePayment, probeFacilitators) all route through here, so
// this is the single seam that decides who settles each network.
export function facilitatorFor(network) {
	if (isSolanaNetwork(network)) {
		// Solana resolution (see x402/ring-config.js): an explicit
		// X402_FACILITATOR_URL_SOLANA always wins; otherwise
		// X402_SELF_FACILITATOR_ENABLED=true defaults to our own
		// /api/x402-facilitator, and only a disabled self-facilitator falls back
		// to the external default (PayAI). `self` marks in-house routing for the
		// status probes.
		const solana = resolveSolanaFacilitator();
		return { url: solana.url, token: env.X402_FACILITATOR_TOKEN_SOLANA, self: solana.self };
	}
	// BSC settles via on-chain pay(), no facilitator needed. The {direct:true}
	// marker tells verifyPayment/settlePayment to bypass HTTP entirely and call
	// the local verifier in x402-bsc-direct.js.
	if (DIRECT_NETWORKS.has(network) || network === 'bsc') {
		return { direct: true };
	}
	// X Layer settles via the OKX Agent Payments Protocol rail, the official
	// OKX facilitator when credentialed, direct EIP-3009 redemption otherwise.
	// The {okxXLayer:true} marker routes to x402-xlayer-okx.js.
	if (network === NETWORK_XLAYER_MAINNET || network === 'xlayer') {
		return { okxXLayer: true };
	}
	// EVM mainnets supported by Coinbase CDP. When CDP keys are set, route all
	// of them through CDP (required for CDP Bazaar / agentic.market, only
	// endpoints whose first verify+settle is processed by CDP get cataloged).
	// Base mainnet falls back to X402_FACILITATOR_URL_BASE (PayAI by default)
	// when CDP keys are absent; other EVM chains require CDP.
	if (CDP_EVM_NETWORKS.has(network) || network === 'base') {
		if (env.CDP_API_KEY_ID && env.CDP_API_KEY_SECRET) {
			return { url: env.X402_CDP_FACILITATOR_URL, cdp: true };
		}
		if (
			network === NETWORK_BASE_MAINNET ||
			network === NETWORK_BASE_SEPOLIA ||
			network === 'base'
		) {
			return { url: env.X402_FACILITATOR_URL_BASE, token: env.X402_FACILITATOR_TOKEN_BASE };
		}
		throw new X402Error(
			'facilitator_unconfigured',
			`network ${network} requires CDP credentials (set CDP_API_KEY_ID + CDP_API_KEY_SECRET)`,
			500,
		);
	}
	throw new X402Error('unsupported_network', `unsupported network: ${network}`, 400);
}

// Is Base (eip155:8453) actually settleable right now? Base routes to CDP when
// CDP creds are set, otherwise to X402_FACILITATOR_URL_BASE. Treat Base as
// settleable ONLY when we can trust it will verify+settle:
//
//   1. CDP credentials are configured, Base routes to Coinbase's facilitator, a
//      known-good, platform-trusted path.
//   2. The operator has EXPLICITLY opted in via X402_ADVERTISE_BASE=true.
//
// A bare X402_FACILITATOR_URL_BASE being SET is deliberately NOT enough. Prod had
// it pointed at a facilitator host that answers every /verify with `404 Application
// not found`, so a Base accept was advertised (buyers pick it first), the buyer
// paid, verification 404'd, and they got a 502. A URL string is not proof the
// endpoint behind it works; only CDP or a deliberate operator opt-in is. Self-heals
// the moment either is set. Solana is unaffected: it settles via whatever
// facilitatorFor resolves (self-hosted when X402_SELF_FACILITATOR_ENABLED=true,
// external PayAI otherwise).
export function baseSettleable() {
	if (env.CDP_API_KEY_ID && env.CDP_API_KEY_SECRET) return true;
	return env.X402_ADVERTISE_BASE === true;
}

// Is Solana (the in-house ring rail) actually settleable right now? The Solana
// mirror of baseSettleable(): never advertise a Solana accept the facilitator
// will reject AFTER the buyer has paid. Solana settlement routes via
// resolveSolanaFacilitator():
//
//   • EXTERNAL facilitator (PayAI, or an explicit non-self URL), it holds its
//     own sponsor key and co-signs; we trust that path, so the accept settles.
//   • Our SELF-hosted facilitator, settle co-signs sponsor-mode payments with
//     X402_FEE_PAYER_SECRET_BASE58 (api/_lib/x402/self-facilitator.js). Without
//     that secret loaded, EVERY sponsor-mode settle throws
//     `sponsor_key_unconfigured` and the buyer eats a 502 AFTER submitting a
//     signed payment, the exact production failure this gate closes (80× 502 on
//     /api/x402/dance-tip, crypto-intel, three-intel in the 2026-07-03 export).
//     So self-routing is settleable only when the co-signing secret is present.
//
// The 402 challenge already requires X402_FEE_PAYER_SOLANA (the advertised
// sponsor PUBKEY); this adds the matching requirement that we can actually SIGN
// for it. Self-heals the instant the secret is set, no redeploy needed.
export function solanaSettleable() {
	const route = resolveSolanaFacilitator();
	if (!route.self) return true; // external facilitator co-signs with its own key
	// SELF-PAY (X402_RING_SELF_PAY): the buyer signs its own 1-signature fee and the
	// self-facilitator only BROADCASTS the already-signed tx, no sponsor key is
	// used (settleRingPayment's `if (!selfPay)` branch skips loadFeePayerKeypair).
	// So self-routing is settleable when self-pay is on, even with no sponsor
	// secret. Sponsor mode still requires the co-signing secret.
	if (String(process.env.X402_RING_SELF_PAY || '').toLowerCase() === 'true') return true;
	return !!String(process.env.X402_FEE_PAYER_SECRET_BASE58 || '').trim();
}

// True when Solana must be advertised WITHOUT extra.feePayer: we settle in-house
// and the sponsor cannot co-sign (none configured, no key loaded, or the wallet
// is under its SOL floor). The buyer then signs as its own fee payer and the
// facilitator only broadcasts. Every Solana accept builder must consult this;
// advertising a sponsor the facilitator refuses at the floor gate makes buyers
// sign payments that can never settle.
export function solanaSelfPayOnly() {
	return (
		resolveSolanaFacilitator().self &&
		(!env.X402_FEE_PAYER_SOLANA || !solanaSettleable() || sponsorKnownBelowFloor())
	);
}

// Shared exact-scheme requirements builder for the hand-rolled x402 endpoints that
// call send402()/verifyPayment() directly instead of going through paidEndpoint().
// Emits the platform-standard accept set for a USDC price:
//
//   1. Solana first, the always-on, self-hosted settle rail (first-accept clients
//      and wallet modals settle here).
//   2. Base second, but ONLY when baseSettleable() (CDP creds or explicit opt-in)
//      AND the Base pay-to/asset are configured. A dead or unconfigured Base
//      facilitator is never advertised as a rail that 402s the buyer and then 502s
//      at /verify. With CDP set, permit2VariantOf appends the gasless Permit2
//      sibling right after the Base accept.
//
// Replaces five byte-for-byte copies of this logic (model-check, mint-to-mesh,
// vanity, vanity-verifiable, mint-to-mesh-batch) and matches the Solana-first ordering
// the discovery catalog (wk.js) already advertises, so live 402 and catalog agree.
export function buildExactRequirements(resourceUrl, amount = env.X402_MAX_AMOUNT_REQUIRED) {
	const amt = String(amount);
	const out = [];
	const selfPayOnly = solanaSelfPayOnly();
	if (
		env.X402_PAY_TO_SOLANA &&
		env.X402_ASSET_MINT_SOLANA &&
		(solanaSettleable() || selfPayOnly) &&
		(env.X402_FEE_PAYER_SOLANA || selfPayOnly)
	) {
		out.push({
			scheme: 'exact',
			network: NETWORK_SOLANA_MAINNET,
			amount: amt,
			payTo: env.X402_PAY_TO_SOLANA,
			asset: env.X402_ASSET_MINT_SOLANA,
			maxTimeoutSeconds: 60,
			resource: resourceUrl,
			extra: {
				name: 'USDC',
				decimals: 6,
				...(selfPayOnly ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }),
			},
		});
	}
	if (baseSettleable() && env.X402_PAY_TO_BASE && env.X402_ASSET_ADDRESS_BASE) {
		const eip3009 = {
			scheme: 'exact',
			network: NETWORK_BASE_MAINNET,
			amount: amt,
			payTo: env.X402_PAY_TO_BASE,
			asset: env.X402_ASSET_ADDRESS_BASE,
			maxTimeoutSeconds: 60,
			resource: resourceUrl,
			extra: { name: 'USD Coin', version: '2', decimals: 6 },
		};
		out.push(eip3009);
		const permit2 = permit2VariantOf(eip3009);
		if (permit2) out.push(permit2);
	}
	return out;
}

// Operations the CDP SDK pre-builds headers for; map our internal path to the SDK key.
const CDP_OP_FOR_PATH = { '/verify': 'verify', '/settle': 'settle', '/supported': 'supported' };

// Return { Authorization?, Correlation-Context? } for a facilitator call. For CDP
// we ask the SDK for per-operation headers (it adds telemetry + signed JWT);
// for bearer-token facilitators (PayAI self-hosted) we return a static Bearer.
// Wraps any SDK/JWT-signing error as an X402Error so the caller can map to 5xx
// cleanly instead of leaking a raw stack.
async function authHeadersFor(config, path) {
	if (config.cdp) {
		try {
			const factory = getCdpHeadersFactory();
			const all = await factory();
			const op = CDP_OP_FOR_PATH[path];
			return (op && all[op]) || {};
		} catch (err) {
			throw new X402Error(
				'facilitator_auth_failed',
				`CDP auth header generation failed: ${err.message}`,
				500,
			);
		}
	}
	return config.token ? { Authorization: `Bearer ${config.token}` } : {};
}

export function decodePaymentHeader(header) {
	if (!header) throw new X402Error('payment_required', 'X-PAYMENT header required', 402);
	let json;
	try {
		json = Buffer.from(String(header), 'base64').toString('utf8');
	} catch (err) {
		throw new X402Error(
			'invalid_payment',
			`X-PAYMENT base64 decode failed: ${err.message}`,
			400,
		);
	}
	let payload;
	try {
		payload = JSON.parse(json);
	} catch (err) {
		throw new X402Error('invalid_payment', `X-PAYMENT JSON parse failed: ${err.message}`, 400);
	}
	if (!payload || typeof payload !== 'object') {
		throw new X402Error('invalid_payment', 'X-PAYMENT must decode to a JSON object', 400);
	}
	return payload;
}

function hostOf(url) {
	try {
		return new URL(url).host;
	} catch {
		return url;
	}
}

// Facilitator HTTP timeout. Defaults to 15s; tunable via env so chains/
// networks with congested settlement (e.g. Solana under load) don't fail
// settle for legitimate payments. Caller-supplied per-call override wins
// when present so we can keep verify quick and give settle a longer leash.
const FACILITATOR_TIMEOUT_MS_DEFAULT = (() => {
	const raw = Number(env.X402_FACILITATOR_TIMEOUT_MS);
	if (Number.isFinite(raw) && raw >= 1_000 && raw <= 120_000) return raw;
	return 15_000;
})();

// Upstream statuses that signal a transient facilitator / payment-network
// hiccup (gateway down, settlement service overloaded) rather than a rejected
// payment. A 4xx, including 402 (payment required), 409 (idempotency
// conflict), and 400-with-isValid:false, is a definitive answer and is never
// retried.
const TRANSIENT_FACILITATOR_STATUS = new Set([502, 503, 504]);

function summarizeUpstream(data, text) {
	// CDP surfaces the reason under `errorMessage`; PayAI under `error`/`message`.
	return String(
		data.error ||
			data.message ||
			data.errorMessage ||
			data.invalidReason ||
			text.slice(0, 200) ||
			'',
	).slice(0, 300);
}

async function callFacilitator(
	network,
	path,
	body,
	{ timeoutMs, idempotencyKey, retries = 1 } = {},
) {
	const config = facilitatorFor(network);
	const url = `${config.url}${path}`;
	const host = hostOf(config.url);
	const headers = {
		'content-type': 'application/json',
		accept: 'application/json',
		...(await authHeadersFor(config, path)),
	};
	if (idempotencyKey) {
		// Both casing variants appear in the wild (PayAI uses `Idempotency-Key`,
		// some Cloudflare-fronted facilitators normalize to lowercase). Send both
		// for maximum compatibility, fetch headers are case-insensitive on the
		// wire so this is just a Node-level convenience.
		headers['Idempotency-Key'] = idempotencyKey;
	}
	// Retries are only safe for idempotent calls: /verify mutates no state, and
	// /settle carries the deterministic Idempotency-Key from buildIdempotencyKey
	// so a re-sent settle is de-duplicated by the facilitator instead of paying
	// twice. A settle without a key (legacy callers) gets a single attempt, we
	// won't risk a double-spend to recover from a blip.
	const retryable = path === '/verify' || Boolean(idempotencyKey);
	const serializedBody = JSON.stringify(body);

	let attempt = 0;
	for (;;) {
		let res;
		try {
			res = await fetch(url, {
				method: 'POST',
				headers,
				body: serializedBody,
				signal: AbortSignal.timeout(timeoutMs || FACILITATOR_TIMEOUT_MS_DEFAULT),
			});
		} catch (err) {
			// Network failure / timeout, transient. Retry once for idempotent
			// calls before giving up.
			if (retryable && attempt < retries) {
				attempt += 1;
				console.warn(
					`[x402] facilitator ${path} unreachable (host=${host}, network=${network}): ${err.message}, retry ${attempt}/${retries} in 500ms`,
				);
				await new Promise((r) => setTimeout(r, 500));
				continue;
			}
			// Server logs keep the host for diagnosis; user-facing X402Error message
			// omits it so we don't leak internal facilitator topology to clients.
			console.warn(
				`[x402] facilitator ${path} unreachable (host=${host}, network=${network}): ${err.message}`,
			);
			throw new X402Error(
				'facilitator_unreachable',
				`facilitator ${path} (network=${network}) fetch failed: ${err.message}`,
				502,
			);
		}
		const text = await res.text();
		let data = {};
		if (text) {
			try {
				data = JSON.parse(text);
			} catch {
				console.warn(
					`[x402] facilitator ${path} non-JSON (host=${host}, network=${network}, status=${res.status})`,
				);
				throw new X402Error(
					'facilitator_bad_response',
					`facilitator ${path} (network=${network}) returned non-JSON (status ${res.status})`,
					502,
				);
			}
		}
		if (!res.ok) {
			// PayAI returns 400 with { isValid: false } for invalid payments,
			// pass through so verifyPayment can emit a clean 402 to the caller.
			if (path === '/verify' && data.isValid === false) return data;
			const detail = summarizeUpstream(data, text);
			// A 400 from /verify means the facilitator rejected the *payment
			// payload itself* (malformed X-PAYMENT header, wrong scheme, etc.),
			// that's a client error, not an upstream outage. CDP signals it with
			// an `errorMessage` and no `isValid` field, so the PayAI passthrough
			// above misses it and we'd otherwise 502. Normalize to an
			// invalid-payment result so verifyPayment emits a clean 402 and the
			// caller is re-prompted to pay, instead of seeing a server error.
			if (path === '/verify' && res.status === 400) {
				console.warn(
					`[x402] facilitator /verify rejected payload (host=${host}, network=${network}): ${detail}`,
				);
				return {
					isValid: false,
					invalidReason: detail || 'payment payload rejected by facilitator',
				};
			}
			// Transient upstream 5xx, the payment network or settlement service
			// blinked. Retry once for idempotent calls; the Idempotency-Key keeps
			// a re-sent settle from double-paying.
			if (retryable && TRANSIENT_FACILITATOR_STATUS.has(res.status) && attempt < retries) {
				attempt += 1;
				console.warn(
					`[x402] facilitator ${path} ${res.status} (host=${host}, network=${network}): ${detail}, retry ${attempt}/${retries} in 500ms`,
				);
				await new Promise((r) => setTimeout(r, 500));
				continue;
			}
			console.warn(
				`[x402] facilitator ${path} ${res.status} (host=${host}, network=${network}): ${detail}`,
			);
			throw new X402Error(
				'facilitator_error',
				`facilitator ${path} (network=${network}) ${res.status}: ${detail}`,
				502,
			);
		}
		return data;
	}
}

// Probe `/supported` on each configured facilitator and report whether the
// scheme/network pairs we advertise are actually supported. Used by
// /api/x402-status to surface misconfigurations before a paying client hits them.
//
// When CDP credentials are configured we probe every CDP-supported EVM network,
// not just Base, `wk.js` advertises Arbitrum acceptance for /api/x402/model-check
// and `permit2VariantOf` emits Permit2 siblings on any EVM `exact` accept, so
// the status surface needs to confirm the facilitator supports each of those
// networks. Without CDP creds, Base is the only EVM we can actually settle.
export async function probeFacilitators() {
	const evmNetworks =
		env.CDP_API_KEY_ID && env.CDP_API_KEY_SECRET
			? [...CDP_EVM_NETWORKS].filter((n) => n !== NETWORK_BASE_SEPOLIA)
			: [NETWORK_BASE_MAINNET];
	const targets = [
		...evmNetworks.map((network) => ({ network, ...facilitatorFor(network) })),
		{ network: NETWORK_SOLANA_MAINNET, ...facilitatorFor(NETWORK_SOLANA_MAINNET) },
	];
	// The self-hosted facilitator is probed whenever its flag is on, even when
	// an explicit external URL wins the routing, and reported as a distinct
	// entry, so a mis-enveloped deploy shows the self facilitator's health right
	// next to wherever settlement actually routes.
	if (selfFacilitatorEnabled()) {
		const selfUrl = selfFacilitatorUrl();
		const alreadyTargeted = targets.some(
			(t) => t.network === NETWORK_SOLANA_MAINNET && t.url === selfUrl,
		);
		if (!alreadyTargeted) {
			targets.push({
				network: NETWORK_SOLANA_MAINNET,
				url: selfUrl,
				token: env.X402_FACILITATOR_TOKEN_SOLANA,
				self: true,
			});
		}
	}
	const seen = new Map();
	const results = [];
	for (const t of targets) {
		if (!t.url) {
			results.push({
				network: t.network,
				self: Boolean(t.self),
				ok: false,
				reason: 'no facilitator URL configured',
			});
			continue;
		}
		let entry = seen.get(t.url);
		if (!entry) {
			entry = (async () => {
				try {
					const probeUrl = `${t.url}/supported`;
					const headers = {
						accept: 'application/json',
						...(await authHeadersFor(t, '/supported')),
					};
					const res = await fetch(probeUrl, {
						headers,
						signal: AbortSignal.timeout(10_000),
					});
					if (!res.ok) return { error: `status ${res.status}` };
					const json = await res.json();
					return { kinds: Array.isArray(json?.kinds) ? json.kinds : [] };
				} catch (err) {
					return { error: err.message };
				}
			})();
			seen.set(t.url, entry);
		}
		const data = await entry;
		if (data.error) {
			results.push({
				network: t.network,
				self: Boolean(t.self),
				url: t.url,
				ok: false,
				reason: `/supported probe failed: ${data.error}`,
			});
			continue;
		}
		const matching = data.kinds.filter(
			(k) =>
				k.scheme === 'exact' &&
				k.network === t.network &&
				(k.x402Version ?? 1) === X402_VERSION,
		);
		const supports = matching.length > 0;
		// Aggregate the extension keys the facilitator advertises for this
		// scheme/network. Each /supported `kind` carries an `extensions: string[]`
		// list (see @x402/core server schema). We surface whether each gas-
		// sponsoring extension is present so /api/x402-status can flag silently-
		// degraded setups where we advertise an extension but the facilitator
		// won't actually settle it.
		const advertisedExtensions = new Set();
		for (const k of matching) {
			if (Array.isArray(k.extensions)) {
				for (const ext of k.extensions) advertisedExtensions.add(ext);
			}
		}
		results.push({
			network: t.network,
			self: Boolean(t.self),
			url: t.url,
			ok: supports,
			reason: supports
				? `facilitator advertises exact/${t.network}`
				: `facilitator does NOT advertise scheme=exact network=${t.network} (configure X402_FACILITATOR_URL_${t.network.toUpperCase()} to a facilitator that does)`,
			extensions: [...advertisedExtensions],
			supportsEip2612GasSponsoring: advertisedExtensions.has(EIP2612_EXTENSION_KEY),
			supportsErc20ApprovalGasSponsoring: advertisedExtensions.has(
				ERC20_APPROVAL_EXTENSION_KEY,
			),
		});
	}
	return results;
}

// Inspect the payload to determine which asset-transfer method the client
// signed with. EIP-3009 transferWithAuthorization payloads carry
// `payload.authorization`; Permit2 PermitWitnessTransferFrom payloads carry
// `payload.permit2Authorization`. Returns null if the structure is unknown
// (e.g. Solana SPL transfer, BSC direct), in which case the caller falls back
// to the first matching network entry.
function detectAssetTransferMethod(paymentPayload) {
	const inner = paymentPayload?.payload;
	if (!inner || typeof inner !== 'object') return null;
	if (inner.permit2Authorization) return 'permit2';
	if (inner.authorization) return 'eip3009';
	return null;
}

// True for accepts[] entries that exist only to advertise an authentication
// alternative (USE-21 auth-hints): zero-amount placeholders flagged with
// `extra.authRequired`. They are redeemed by presenting the matching auth
// header (Authorization / SIGN-IN-WITH-X) BEFORE the payment dance, never by
// an X-PAYMENT header. verifyPayment must exclude them from requirement
// matching so the invariant is enforced structurally rather than relying on
// the real entries happening to sort first: otherwise a crafted payload (e.g.
// a Base payment against a Solana-only paid route that still advertises a
// Base auth-hint entry) could select the amount="0" requirement and obtain
// the resource for a zero-value settlement.
function isAuthHintAccept(requirement) {
	if (!requirement || typeof requirement !== 'object') return false;
	if (requirement.extra?.authRequired != null) return true;
	return String(requirement.amount) === '0';
}

// Assets are compared exactly on Solana (base58 is case-sensitive) and
// case-insensitively on EVM, where clients send checksummed or lowercased hex.
function sameAsset(a, b) {
	if (!a || !b) return false;
	const x = String(a);
	const y = String(b);
	return x.startsWith('0x') && y.startsWith('0x') ? x.toLowerCase() === y.toLowerCase() : x === y;
}

// Match the decoded payload to one of the offered requirements. The match is
// by (network, assetTransferMethod, asset). The method matters because we
// publish two accept entries per EVM network (EIP-3009 first, Permit2 sibling
// second) and the facilitator's /verify call has to receive the same `extra`
// block the client signed against. The asset matters because a resource can
// quote several tokens on one network (USDC and $THREE on Solana): matching by
// network alone judged every $THREE payment against the USDC entry, so the
// facilitator looked for a USDC recipient account in a $THREE transaction and
// refused it, and no buyer could ever pay in the second token.
//
// The asset comes from the payload's echoed `accepted` entry (x402 v2) when it
// is there. A Solana payload without one is read from the signed transaction
// itself. Only when neither names an asset does the first network match win.
function selectRequirement(paymentPayload, allRequirements) {
	// OKX-dialect payloads (PAYMENT-SIGNATURE header) carry the chosen entry as
	// `accepted` instead of top-level scheme/network, see x402-xlayer-okx.js.
	const network =
		paymentPayload?.network ||
		paymentPayload?.accepted?.network ||
		paymentPayload?.paymentRequirements?.network;
	const method = detectAssetTransferMethod(paymentPayload);
	const matchesMethod = (r) => {
		if (!method) return true;
		const reqMethod = r.extra?.assetTransferMethod || 'eip3009';
		return reqMethod === method;
	};
	if (network) {
		let candidates = allRequirements.filter((r) => r.network === network && matchesMethod(r));
		// A payload that names its scheme only matches offers of that scheme, so an
		// `upto` authorization is never read against the sibling `exact` offer for
		// the same network and asset (and vice versa).
		const payloadScheme = paymentPayload?.accepted?.scheme || paymentPayload?.scheme;
		if (payloadScheme && candidates.some((r) => r.scheme === payloadScheme)) {
			candidates = candidates.filter((r) => r.scheme === payloadScheme);
		}
		if (!candidates.length)
			throw new X402Error(
				'unsupported_network',
				`payment network "${network}" (assetTransferMethod="${method || 'unknown'}") is not offered`,
				402,
			);
		const echoedAsset = paymentPayload?.accepted?.asset || paymentPayload?.paymentRequirements?.asset;
		if (echoedAsset) {
			const found = candidates.find((r) => sameAsset(r.asset, echoedAsset));
			if (!found)
				throw new X402Error(
					'unsupported_asset',
					`payment asset "${echoedAsset}" is not offered on ${network}; offered: ${candidates.map((r) => r.asset).join(', ')}`,
					402,
				);
			return found;
		}
		if (candidates.length > 1 && isSolanaNetwork(network)) {
			const signedMints = signedSolanaMints(paymentPayload);
			const found = candidates.find((r) => signedMints.includes(r.asset));
			if (found) return found;
		}
		return candidates[0];
	}
	if (method) {
		const found = allRequirements.find(matchesMethod);
		if (found) return found;
	}
	return allRequirements[0];
}

// Extract the signed amount from a v2 PaymentPayload, regardless of scheme.
// Returns a BigInt in the asset's atomic units (USDC → 6-decimal micros).
// Returns null when the payload's amount can't be located without trusting
// the facilitator, Solana SPL transfers carry the amount inside an opaque
// serialized transaction we won't parse client-side, so we leave that check
// to the facilitator + the on-chain confirmation. Returning null means
// "facilitator-trusted amount"; returning a BigInt means "we just verified
// the signed amount equals or exceeds the requirement".
//
// Defense-in-depth: a compromised facilitator could otherwise verify a
// payment for a smaller amount than the requirement and we'd happily
// deliver the resource. Per the audit, this is the underpayment vector.
export function decodeSignedAmount(paymentPayload) {
	const inner = paymentPayload?.payload;
	if (!inner || typeof inner !== 'object') return null;
	// EIP-3009 transferWithAuthorization, `authorization.value` is the
	// EIP-712 typed-data field clients sign. uint256 string in atomic units.
	if (inner.authorization && typeof inner.authorization === 'object') {
		const v = inner.authorization.value;
		if (typeof v === 'string' || typeof v === 'number' || typeof v === 'bigint') {
			try {
				return BigInt(v);
			} catch {
				return null;
			}
		}
	}
	// Permit2 PermitWitnessTransferFrom, `permitted.amount` is what the user
	// authorizes. @x402/evm exposes the structured permit object pre-broadcast.
	if (inner.permit2Authorization && typeof inner.permit2Authorization === 'object') {
		const permitted = inner.permit2Authorization?.permit?.permitted;
		const v = permitted?.amount;
		if (typeof v === 'string' || typeof v === 'number' || typeof v === 'bigint') {
			try {
				return BigInt(v);
			} catch {
				return null;
			}
		}
		// Some clients flatten to `permit2Authorization.amount`.
		const flat = inner.permit2Authorization.amount;
		if (typeof flat === 'string' || typeof flat === 'number' || typeof flat === 'bigint') {
			try {
				return BigInt(flat);
			} catch {
				return null;
			}
		}
	}
	return null;
}

// Extract the recipient the payer actually signed over, so we can confirm the
// funds are bound to OUR `requirement.payTo` and not an attacker address the
// facilitator might (if compromised/buggy) accept. Returns a lowercase hex
// string, or null when the recipient can't be located without trusting the
// facilitator (e.g. Solana SPL transfers).
//
// Defense-in-depth: the EIP-712 signature commits to `to`, so a payment whose
// signed recipient differs from the offered payTo is invalid regardless of
// what /verify returns.
export function decodeSignedRecipient(paymentPayload) {
	const inner = paymentPayload?.payload;
	if (!inner || typeof inner !== 'object') return null;
	// EIP-3009 transferWithAuthorization, `authorization.to` is signed.
	if (inner.authorization && typeof inner.authorization === 'object') {
		const to = inner.authorization.to;
		if (typeof to === 'string' && to) return to.toLowerCase();
	}
	// Permit2, the spend recipient travels in the witness/transfer details.
	// Clients shape this a few ways; check the known locations and bail out
	// (null = facilitator-trusted) rather than guess when none are present.
	if (inner.permit2Authorization && typeof inner.permit2Authorization === 'object') {
		const p2 = inner.permit2Authorization;
		const candidate = p2.transferDetails?.to ?? p2.witness?.to ?? p2.spender ?? p2.to;
		if (typeof candidate === 'string' && candidate) return candidate.toLowerCase();
	}
	return null;
}

// Build a deterministic idempotency key per (verified-payment-payload, requirement).
// Idempotent retries of /settle (timeouts, transient 5xx) will hash to the same
// key and let the facilitator de-duplicate, preventing double-settlement. Hashing
// the full payload+requirement means two distinct payments by the same payer
// generate distinct keys.
function buildIdempotencyKey({ paymentPayload, requirement }) {
	const material = JSON.stringify({
		// Order matters for deterministic hashing, stringify the fields in a
		// fixed shape rather than the raw payload (which has insertion-order
		// dependence in some clients).
		network: requirement?.network,
		payTo: requirement?.payTo,
		asset: requirement?.asset,
		amount: requirement?.amount,
		scheme: requirement?.scheme,
		payload: paymentPayload,
	});
	return createHash('sha256').update(material).digest('hex').slice(0, 32);
}

// Verify a base64 X-PAYMENT header against the offered requirements.
// Returns { paymentPayload, requirement, payer, directVerified? } on success.
// For direct-scheme networks (BSC), the on-chain verification result is stashed
// on `directVerified` so settlePayment can synthesise a response without
// re-hitting the RPC.
//
// `builderCode` is the extension block we declared on the 402 challenge,
// when present, we reject any payment whose `extensions[BUILDER_CODE].a`
// does not exactly echo the declared app code (anti-tamper). Built so the
// resource server enforces the echo invariant the spec normally puts on the
// facilitator, important because not every facilitator implements it yet,
// and the on-chain calldata suffix needs trustworthy `a` to be useful.
//
// When the caller doesn't pass `builderCode`, we derive it from
// X402_BUILDER_CODE_APP so the raw-verifyPayment routes (model-check,
// mint-to-mesh, mint-to-mesh-batch, mcp/auth) get echo enforcement symmetric
// with build402Body's auto-declaration. Pass `builderCode: null`
// explicitly to opt out (e.g. test harnesses).
// CDP's /verify and /settle validate the forwarded paymentPayload against a
// strict envelope schema. Clients speaking the PAYMENT-SIGNATURE dialect
// (@x402/fetch v2, OKX) echo unsigned listing copy into the payload,
// `resource` and `extensions` blocks copied verbatim from our own 402 body,
// and CDP rejects the whole payment when that echo trips its validator
// ("'paymentPayload' is invalid: must match one of [x402V2PaymentPayload,
// x402V1PaymentPayload]"). That let per-endpoint listing copy break payment
// settlement (14 endpoints deterministically failed while 31 passed, split
// purely by echoed content). None of the echoed fields are signed, the
// EIP-712 / SPL signature covers `payload` only, and none are needed to
// verify or settle, so for CDP we forward the minimal envelope it always
// accepts. Non-CDP facilitators (PayAI, the self-facilitator) keep the
// original payload untouched.
function minimalPaymentPayloadForCdp(paymentPayload) {
	if (!paymentPayload || typeof paymentPayload !== 'object') return paymentPayload;
	const out = {};
	if (paymentPayload.x402Version !== undefined) out.x402Version = paymentPayload.x402Version;
	if (paymentPayload.scheme !== undefined) out.scheme = paymentPayload.scheme;
	if (paymentPayload.network !== undefined) out.network = paymentPayload.network;
	if (paymentPayload.accepted !== undefined) out.accepted = paymentPayload.accepted;
	out.payload = paymentPayload.payload;
	return out;
}

// `upto` is verified in-process by the official @x402/svm upto facilitator: it
// checks the signed channel-open transaction (deposit equals the cap, our payee,
// our fee payer) and rejects a buyer-supplied voucher. The deposit itself is
// broadcast by the paid endpoint BEFORE the handler runs (settleUptoDeposit);
// the claim of the measured amount happens in settlePayment below.
async function verifyUptoPayment({ paymentPayload, requirement }) {
	if (!uptoEnabled()) {
		throw new X402Error('unsupported_scheme', 'the upto scheme is not enabled on this deployment', 402);
	}
	let result;
	try {
		result = await verifyUpto({ paymentPayload, requirement });
	} catch (err) {
		throw new X402Error('verify_failed', `upto verify failed: ${err?.message || err}`, 502);
	}
	if (!result?.isValid) {
		throw new X402Error(
			'invalid_payment',
			`upto payment rejected: ${result?.invalidReason || 'invalid'}${result?.invalidMessage ? ` (${result.invalidMessage})` : ''}`,
			402,
		);
	}
	return {
		paymentPayload,
		requirement,
		payer: result.payer || null,
		upto: { capRequirement: requirement, depositSettled: false },
	};
}

export async function verifyPayment({ paymentHeader, requirements, builderCode }) {
	const all = Array.isArray(requirements) ? requirements : [requirements];
	// Auth-hint placeholder entries (amount="0" / extra.authRequired) are never
	// payable via X-PAYMENT, drop them before matching so the zero-amount
	// bypass can't be reached regardless of accepts[] ordering. The auth-hint
	// redemption path never calls verifyPayment (it short-circuits on the auth
	// header in x402-paid-endpoint.js), so this filter only ever removes
	// entries an X-PAYMENT was forbidden from matching in the first place.
	const payable = all.filter((r) => !isAuthHintAccept(r));
	if (!payable.length) {
		throw new X402Error(
			'invalid_payment',
			'this resource has no payable accepts[] entries, use the advertised authentication method instead of X-PAYMENT',
			402,
		);
	}
	const paymentPayload = decodePaymentHeader(paymentHeader);
	const requirement = selectRequirement(paymentPayload, payable);
	if (isUptoRequirement(requirement)) {
		return verifyUptoPayment({ paymentPayload, requirement });
	}
	const effectiveBuilderCode =
		builderCode === undefined && env.X402_BUILDER_CODE_APP
			? declareBuilderCodeExtension({ a: env.X402_BUILDER_CODE_APP })
			: builderCode;
	if (effectiveBuilderCode) {
		const payloadBuilder = paymentPayload?.extensions?.[BUILDER_CODE];
		const echo = verifyBuilderCodeEcho({
			required: effectiveBuilderCode,
			payload: payloadBuilder,
		});
		if (!echo.ok) {
			throw new X402Error('builder_code_tampered', echo.reason, 402);
		}
	}
	// Defense-in-depth amount check. For EVM (EIP-3009 + Permit2) the signed
	// amount is inside the payload; reject under-payment before we even ask
	// the facilitator. For Solana SPL (amount inside an opaque serialized tx)
	// we still rely on the facilitator + on-chain confirmation.
	const signedAmount = decodeSignedAmount(paymentPayload);
	if (signedAmount !== null) {
		let required;
		try {
			required = BigInt(requirement.amount);
		} catch {
			throw new X402Error(
				'invalid_requirement',
				`requirement.amount must parse as BigInt, got "${requirement.amount}"`,
				500,
			);
		}
		if (signedAmount < required) {
			throw new X402Error(
				'invalid_payment',
				`signed payment amount ${signedAmount.toString()} is below required ${required.toString()}`,
				402,
			);
		}
	}
	// Defense-in-depth recipient check. The EIP-712 signature commits to the
	// recipient, so confirm the payer signed funds to OUR payTo, a compromised
	// facilitator can't redirect a wrong-recipient authorization past us. Null
	// (Solana SPL / unknown shape) falls through to facilitator trust.
	const signedRecipient = decodeSignedRecipient(paymentPayload);
	if (signedRecipient !== null && requirement.payTo) {
		if (signedRecipient !== String(requirement.payTo).toLowerCase()) {
			throw new X402Error(
				'invalid_payment',
				`signed payment recipient ${signedRecipient} does not match required payTo ${requirement.payTo}`,
				402,
			);
		}
	}
	const config = facilitatorFor(requirement.network);
	if (config.direct) {
		const directVerified = await verifyDirectPayment({ paymentPayload, requirement });
		return {
			paymentPayload,
			requirement,
			payer: directVerified.payer,
			directVerified,
		};
	}
	if (config.okxXLayer) {
		const okxVerified = await verifyOkxXLayerPayment({ paymentPayload, requirement });
		return {
			paymentPayload,
			requirement,
			payer: okxVerified.payer,
			okxVerified,
		};
	}
	const result = await callFacilitator(requirement.network, '/verify', {
		x402Version: X402_VERSION,
		paymentPayload: config.cdp ? minimalPaymentPayloadForCdp(paymentPayload) : paymentPayload,
		paymentRequirements: requirement,
	});
	if (!result.isValid) {
		throw new X402Error(
			'invalid_payment',
			`payment rejected: ${result.invalidReason || 'unknown reason'}`,
			402,
		);
	}
	// Facilitator response cross-check. When it echoes network/asset (most do),
	// confirm they match the requirement we sent, a compromised or buggy
	// facilitator could otherwise verify a payment intended for chain A as if
	// it were chain B. Missing echoed fields don't fail (older facilitators).
	if (result.network && result.network !== requirement.network) {
		throw new X402Error(
			'facilitator_bad_response',
			`facilitator /verify network mismatch: requested ${requirement.network}, got ${result.network}`,
			502,
		);
	}
	if (
		result.asset &&
		requirement.asset &&
		String(result.asset).toLowerCase() !== String(requirement.asset).toLowerCase()
	) {
		throw new X402Error(
			'facilitator_bad_response',
			`facilitator /verify asset mismatch: requested ${requirement.asset}, got ${result.asset}`,
			502,
		);
	}
	// Solana defense-in-depth: the amount/recipient live inside the opaque
	// serialized transaction, so the facilitator was historically the only
	// guard. Statically decode the signed SPL transfer and reject if it pays
	// us less than required (or to the wrong ATA/mint), symmetric with the
	// EVM signed-amount/recipient checks above. Undecodable payloads stay
	// facilitator-trusted (inconclusive) so a parsing quirk never blocks a
	// valid payment.
	if (isSolanaNetwork(requirement.network)) {
		const confirm = confirmSolanaPayment({ paymentPayload, requirement });
		if (confirm.confirmed === false) {
			throw new X402Error('invalid_payment', confirm.reason, 402);
		}
	}
	return { paymentPayload, requirement, payer: result.payer || null };
}

// Settle the verified payment on-chain via the matching facilitator.
// For direct-scheme networks (BSC), the user already broadcast the tx during
// verifyPayment, settle just synthesises the response shape callers expect.
//
// Two call shapes supported:
//   1. settlePayment({ verified })   ← preferred. `verified` is the object
//      verifyPayment returned. Payer-binding is enforced.
//   2. settlePayment({ paymentPayload, requirement, directVerified })
//      ← legacy. Payer-binding cannot be enforced (no `verified.payer`
//      anchor). Kept so external/older callers don't break, but new code
//      should pass `verified`.
// Is this settle response the non-terminal `settlement_pending` outcome?
//
// Both halves are required. The reason alone is not enough: without a broadcast
// signature there is nothing for a retry to reconcile against, so a bare
// `settlement_pending` with no transaction is treated as an ordinary failure
// rather than something to wait on. Matches @x402/core's
// isRetryableSettlementPendingResult.
export function isSettlementPending(result) {
	return (
		!!result &&
		result.success === false &&
		result.errorReason === SETTLEMENT_PENDING_REASON &&
		!!result.transaction
	);
}

// Claim the measured charge on the escrowed channel and shape the facilitator
// SettleResponse like every other settle: success, transaction, network, payer.
async function settleUptoClaimResponse({ verified }) {
	const { capRequirement } = verified.upto;
	let res;
	try {
		res = await settleUptoClaim({
			paymentPayload: verified.paymentPayload,
			requirement: capRequirement,
			amountAtomics: verified.requirement.amount,
		});
	} catch (err) {
		throw new X402Error('settle_failed', `upto claim failed: ${err?.message || err}`, err?.status || 502);
	}
	if (!res?.success) {
		throw new X402Error(
			'settle_failed',
			`upto claim rejected: ${res?.errorReason || 'unknown'}${res?.errorMessage ? ` (${res.errorMessage})` : ''}`,
			502,
		);
	}
	return {
		success: true,
		transaction: res.transaction,
		network: res.network || verified.requirement.network,
		payer: res.payer || verified.payer || null,
		scheme: 'upto',
		amount: verified.requirement.amount,
	};
}

export async function settlePayment(args) {
	const verified = args?.verified || null;
	const paymentPayload = verified?.paymentPayload || args?.paymentPayload;
	const requirement = verified?.requirement || args?.requirement;
	const directVerified = verified?.directVerified || args?.directVerified;
	const verifiedPayer = verified?.payer || args?.verifiedPayer || null;

	if (!requirement) {
		throw new X402Error(
			'settle_failed',
			'settlePayment requires `verified` or `requirement`',
			500,
		);
	}

	// `upto`: settle the CLAIM for the measured amount (requirement.amount has
	// already been lowered from the cap to the charge by the paid endpoint).
	if (verified?.upto) {
		return settleUptoClaimResponse({ verified });
	}

	const config = facilitatorFor(requirement.network);
	if (config.direct) {
		if (!directVerified) {
			throw new X402Error(
				'settle_failed',
				'direct-scheme settle requires the verify step to run first',
				500,
			);
		}
		return settleDirectPayment({ verified: directVerified, requirement });
	}
	if (config.okxXLayer) {
		const okxVerified = verified?.okxVerified || args?.okxVerified;
		if (!okxVerified) {
			throw new X402Error(
				'settle_failed',
				'X Layer settle requires the verify step to run first',
				500,
			);
		}
		return settleOkxXLayerPayment({ verified: okxVerified, requirement, paymentPayload });
	}
	const idempotencyKey = buildIdempotencyKey({ paymentPayload, requirement });
	const settleBody = {
		x402Version: X402_VERSION,
		paymentPayload: config.cdp ? minimalPaymentPayloadForCdp(paymentPayload) : paymentPayload,
		paymentRequirements: requirement,
	};
	let result = await callFacilitator(requirement.network, '/settle', settleBody, {
		idempotencyKey,
	});

	// `settlement_pending`: the facilitator broadcast a transaction and cannot yet
	// say whether it landed. Retry EXACTLY ONCE with the identical body and the
	// same idempotency key, which is what lets the facilitator recognize the retry
	// and reconcile against the signature it already broadcast instead of sending
	// a second transaction. One retry, never a loop: bounded waiting belongs to
	// the facilitator's own confirmation window, and this call is inside a buyer's
	// open HTTP request. Mirrors @x402/core's settleWithPendingRetry.
	if (isSettlementPending(result)) {
		result = await callFacilitator(requirement.network, '/settle', settleBody, {
			idempotencyKey,
		});
	}

	// Still unresolved after the retry. Reporting failure here is the exact bug
	// the pending state exists to remove: the buyer's transaction is on the wire
	// and very likely lands, so a 502 would tell someone who IS being charged
	// that they were not, and leave the work they paid for undelivered.
	//
	// Instead: record the signature, answer pending, and let the caller deliver.
	// The reconcile cron (/api/cron/x402-settlement-reconcile) confirms the
	// signature afterwards and closes the books. The record is the precondition,
	// not a nicety: delivering against a pending settlement we cannot reconcile
	// later would be an unaccountable giveaway, so an unrecordable pending stays
	// a hard failure.
	if (isSettlementPending(result)) {
		const recorded = await recordResourcePending({
			key: idempotencyKey,
			signature: result.transaction,
			meta: {
				network: requirement.network,
				payer: result.payer || verifiedPayer || null,
				payTo: requirement.payTo,
				mint: requirement.asset,
				amountAtomic: requirement.amount ? Number(requirement.amount) : null,
				resourceUrl: requirement.resource || null,
				idempotencyKey,
			},
		});
		if (!recorded) {
			throw new X402Error(
				'settle_failed',
				`settle unresolved: the facilitator broadcast ${result.transaction} but its outcome is unknown and the pending record could not be stored, so it cannot be reconciled later. Retry the payment.`,
				502,
			);
		}
		return {
			success: true,
			status: 'pending',
			pending: true,
			transaction: result.transaction,
			network: result.network || requirement.network,
			payer: result.payer || verifiedPayer || null,
		};
	}

	if (!result.success) {
		const reason = result.errorReason || 'unknown reason';
		// A sponsor/fee wallet under its SOL floor is transient operator capacity,
		// not a broken endpoint: it self-heals the moment treasury-topup (or the
		// operator) refunds the wallet. Answering 502 here made every trust
		// monitor, buyer, and internal pipeline read a funding gap as an outage
		// (tens of thousands of 502 settle_failed rows during the July 2026 dry
		// spells). 503 + the retryable code tells callers to back off and retry;
		// genuinely unexplained settle failures stay 502.
		// `fee_wallet_cannot_cover_settle` is the same class: the wallet clears the
		// floor but not by this settle's own cost (an ATA-create for a mint the
		// recipient has never held carries ~0.00204 SOL of rent). Same cure, a
		// top-up, so it must not read as a broken endpoint either.
		if (/^(fee_wallet_below_floor|fee_wallet_cannot_cover_settle|sponsor_sol_floor|sol_floor)/.test(reason)) {
			throw new X402Error(
				'settlement_unavailable',
				`settlement temporarily unavailable: ${reason} (sponsor wallet below its SOL floor; retry after it is refunded)`,
				503,
			);
		}
		// The wallet fee governor's refusal is the same class of answer for the same
		// reason: nothing is broken, the platform is deliberately pacing its own SOL
		// burn and the budget refills (at the UTC reset, or the moment the fee wallet
		// is topped up). It was the one deliberate throttle the branch above missed,
		// and at volume it IS the platform's error rate: 15,619 of the 20,030
		// `http_502` rows the autonomous loop recorded in the 48h to 2026-08-06 were
		// this refusal wearing a server-fault status code. Same treatment: 503 +
		// retryable code, so buyers back off instead of reading a funding cap as an
		// outage. Genuinely unexplained settle failures still stay 502.
		// Self-pay: the BUYER's wallet cannot cover the Solana network fee. Nothing
		// is wrong on our side and no top-up of ours will help, so this must not
		// wear the "we are refunding our wallet, retry later" message. It is a
		// 402: the buyer adds a little SOL and pays again.
		if (/^buyer_cannot_cover_fee/.test(reason)) {
			throw new X402Error(
				'insufficient_fee_balance',
				'your wallet does not have enough SOL to cover the Solana network fee for this payment; ' +
					`add a small amount of SOL and try again (${reason})`,
				402,
			);
		}
		if (/^fee_runway_exhausted/.test(reason)) {
			throw new X402Error(
				'settlement_unavailable',
				`settlement paced: ${reason} (fee wallet spent today's SOL fee budget; retry after it refills)`,
				503,
			);
		}
		throw new X402Error('settle_failed', `settle failed: ${reason}`, 502);
	}
	// Defense-in-depth: a compromised facilitator could return success for
	// settlement on a different chain or to a different recipient. Cross-check
	// the network/payer it claims against the requirement we sent and the
	// payer we verified earlier. Missing echoed fields are tolerated for
	// backward-compat with older facilitator implementations.
	if (result.network && result.network !== requirement.network) {
		throw new X402Error(
			'facilitator_bad_response',
			`facilitator /settle network mismatch: requested ${requirement.network}, got ${result.network}`,
			502,
		);
	}
	if (
		verifiedPayer &&
		result.payer &&
		String(result.payer).toLowerCase() !== String(verifiedPayer).toLowerCase()
	) {
		throw new X402Error(
			'facilitator_bad_response',
			`facilitator /settle payer mismatch: verified ${verifiedPayer}, settled ${result.payer}`,
			502,
		);
	}
	return result;
}

// `extensions` is the extension envelope returned with the success body
// (e.g. `{ "offer-receipt": { info: { receipt: ... }, schema: ... } }` per the
// Offer & Receipt extension §5.1). Callers leave it undefined when no
// extensions are configured for the route.
export function encodePaymentResponseHeader(settleResult, extensions) {
	const body = {
		success: true,
		transaction: settleResult.transaction,
		network: settleResult.network,
		payer: settleResult.payer,
		// SettleResponse extras the OKX Agent Payments Protocol receipt carries
		// (specs/okx-agent-payments.md §1.4): `status` ("success"/"pending",
		// pending buyers poll /settle/status), `amount` in atomic units. Other
		// rails' facilitators don't return them; absent stays absent.
		...(settleResult.status ? { status: settleResult.status } : {}),
		...(settleResult.amount ? { amount: settleResult.amount } : {}),
	};
	if (extensions && Object.keys(extensions).length > 0) {
		body.extensions = extensions;
	}
	return Buffer.from(JSON.stringify(body), 'utf8').toString('base64');
}

// Long-form description used for the top-level `resource.description` and
// (lightly trimmed) for the bazaar extension. Stays in one place so the 402
// challenge, the /.well-known/x402.json discovery file, and any operator
// dashboards stay in sync.
export const RESOURCE_DESCRIPTION =
	'three.ws MCP, Streamable HTTP transport (MCP 2025-06-18) exposing 3D avatar viewer, glTF/GLB model validation/inspection/optimization, and Solana agent data as JSON-RPC 2.0 tool calls. Pay-per-call in USDC on Base mainnet (eip155:8453) or Solana mainnet. ≤256 tools/call output, ≤32-message JSON-RPC batches. Operated by three.ws.';

// Build the bazaar.schema *meta-schema*, the JSON Schema that validates the
// `{input, output}` shape of the extension itself, NOT the endpoint's response
// body. The user's response-body schema gets nested at
// `schema.properties.output.properties.example`. Matches the reference
// @x402/extensions/bazaar createDiscoveryExtension output exactly; deviating
// from it causes agentic.market's parser to reject the endpoint with
// "v2 discovery extension validation failed" even when all surface-level
// checks (Transport, Payment Requirements, Bazaar Extension) pass.
export function buildBazaarSchema({
	method,
	queryParamsSchema,
	bodyType,
	bodySchema,
	outputSchema,
}) {
	const upperMethod = String(method || 'GET').toUpperCase();
	const isBodyMethod = ['POST', 'PUT', 'PATCH'].includes(upperMethod);
	const inputProperties = {
		type: { type: 'string', const: 'http' },
		method: {
			type: 'string',
			enum: isBodyMethod ? ['POST', 'PUT', 'PATCH'] : ['GET', 'HEAD', 'DELETE'],
		},
	};
	const inputRequired = ['type', 'method'];
	if (isBodyMethod) {
		inputProperties.bodyType = { type: 'string', enum: ['json', 'form-data', 'text'] };
		inputProperties.body =
			bodySchema && typeof bodySchema === 'object' ? bodySchema : { type: 'object' };
		inputRequired.push('bodyType', 'body');
	} else if (queryParamsSchema && typeof queryParamsSchema === 'object') {
		inputProperties.queryParams = { type: 'object', ...queryParamsSchema };
	}
	const schema = {
		$schema: 'https://json-schema.org/draft/2020-12/schema',
		type: 'object',
		properties: {
			input: {
				type: 'object',
				properties: inputProperties,
				required: inputRequired,
				additionalProperties: false,
			},
		},
		required: ['input'],
	};
	if (outputSchema && typeof outputSchema === 'object') {
		schema.properties.output = {
			type: 'object',
			properties: {
				type: { type: 'string' },
				example: { type: 'object', ...outputSchema },
			},
			required: ['type'],
		};
	}
	return schema;
}

// Bazaar discovery extension, shape required by agentic.market's validator.
// `info.input.{type,method,body|queryParams|pathParams}` describes how to call
// the resource; `info.output.{type,example}` shows what comes back; top-level
// `schema` is the meta-schema built by `buildBazaarSchema` above.
//
// This is the v2 `declareDiscoveryExtension` shape. The flat
// `{method,input,inputSchema,output:{example,schema}}` shape v1 used is no
// longer indexed by the CDP Bazaar.
export function bazaarExtension() {
	// The sample body is what a buyer replays after settling the 402, so the URL
	// in it has to be a model that actually resolves. example.com/model.glb made
	// the documented first call fail on a DNS-shaped error that reads like a
	// broken endpoint; this is the same GLB the agent card advertises for
	// validate_model, served from our own origin.
	const exampleBody = {
		jsonrpc: '2.0',
		id: 1,
		method: 'tools/call',
		params: {
			name: 'validate_model',
			arguments: { url: 'https://three.ws/avatars/cesium-man.glb' },
		},
	};
	const exampleResponse = {
		jsonrpc: '2.0',
		id: 1,
		result: {
			content: [
				{ type: 'text', text: '{"ok":true,"warnings":[],"meta":{"vertices":12345}}' },
			],
		},
	};
	const requestBodySchema = {
		$schema: 'https://json-schema.org/draft/2020-12/schema',
		type: 'object',
		required: ['jsonrpc', 'method'],
		properties: {
			jsonrpc: { type: 'string', const: '2.0' },
			id: { type: ['string', 'number'] },
			method: {
				type: 'string',
				enum: ['initialize', 'tools/list', 'tools/call', 'ping'],
				description: 'MCP JSON-RPC method.',
			},
			params: {
				type: 'object',
				description:
					'For tools/call: { name, arguments }. Tool names include validate_model, inspect_model, optimize_model, search_public_avatars, register_agent, solana_agent_reputation, and others, see tools/list.',
			},
		},
	};
	const responseBodySchema = {
		$schema: 'https://json-schema.org/draft/2020-12/schema',
		type: 'object',
		properties: {
			jsonrpc: { type: 'string', const: '2.0' },
			id: { type: ['string', 'number'] },
			result: {
				type: 'object',
				properties: {
					content: {
						type: 'array',
						items: {
							type: 'object',
							required: ['type', 'text'],
							properties: {
								type: { type: 'string', enum: ['text'] },
								text: { type: 'string' },
							},
						},
					},
				},
			},
			error: {
				type: 'object',
				properties: {
					code: { type: 'number' },
					message: { type: 'string' },
				},
			},
		},
	};
	return {
		discoverable: true,
		info: {
			input: {
				type: 'http',
				method: 'POST',
				body: exampleBody,
				bodyType: 'json',
			},
			output: {
				type: 'json',
				example: exampleResponse,
			},
		},
		schema: buildBazaarSchema({
			method: 'POST',
			bodyType: 'json',
			bodySchema: requestBodySchema,
			outputSchema: responseBodySchema,
		}),
	};
}

// True when any offered requirement asks the client to use the Permit2
// asset-transfer method. When so, we automatically advertise BOTH gas-
// sponsoring extensions at the top level, the facilitator (CDP's
// x402ExactPermit2Proxy) submits the approval atomically with settlement so
// the payer never broadcasts the approval tx themselves. EIP-2612 is the
// preferred path for tokens that implement it (Base USDC v2 does);
// ERC-20 approval is the universal fallback that works with any ERC-20.
// permit2VariantOf already gates Permit2 emission on CDP creds being
// present, so by the time any accept reaches this check, the facilitator
// can honor both extensions.
function hasPermit2Accept(accepts) {
	const list = Array.isArray(accepts) ? accepts : [accepts];
	return list.some((a) => a?.extra?.assetTransferMethod === 'permit2');
}

// Build the v2 PaymentRequired body. Top-level `resource` carries url/description/
// mimeType (per v2 spec); per-accept entries no longer repeat them.
//
// `description`, `mimeType`, and `bazaar` are per-route, each paid endpoint
// wants its own catalog entry on agentic.market, not the MCP boilerplate.
// Callers may pass an `extensions` object to add or override entries (e.g. an
// endpoint that wants to declare a custom extension); when omitted we still
// emit `bazaar` plus, when any accept opts into Permit2, `eip2612GasSponsoring`.
// We also auto-declare the ERC-8021 `builder-code` extension when
// X402_BUILDER_CODE_APP is configured, so every paid endpoint contributes to
// on-chain attribution without having to opt in per-route.
// USE-13: `serviceName`, `tags`, `iconUrl` belong on the `resource` object
// per the Bazaar spec. Facilitators apply soft-drop validation so silently
// invalid fields are skipped, but we keep them within limits here too,
// printable-ASCII, ≤32 chars (serviceName/tag), ≤5 tags, absolute https URL.
export async function build402Body({
	resourceUrl,
	accepts,
	error = 'X-PAYMENT header is required',
	description = RESOURCE_DESCRIPTION,
	mimeType = 'application/json',
	bazaar = bazaarExtension(),
	extensions: extraExtensions,
	serviceName,
	tags,
	iconUrl,
}) {
	const extensions = { bazaar };
	if (hasPermit2Accept(accepts)) {
		Object.assign(
			extensions,
			declareEip2612GasSponsoringExtension(),
			declareErc20ApprovalGasSponsoringExtension(),
		);
	}
	if (env.X402_BUILDER_CODE_APP && !extraExtensions?.[BUILDER_CODE]) {
		extensions[BUILDER_CODE] = declareBuilderCodeExtension({
			a: env.X402_BUILDER_CODE_APP,
		});
	}
	// Sign one offer per accepts[] entry (when issuer is configured and the
	// caller hasn't already provided signed offers in extraExtensions). The
	// x402-paid-endpoint.js wrapper pre-signs and passes offers via
	// extraExtensions to avoid signing twice; hand-rolled callers (launchpad,
	// vanity, etc.) get offers here automatically. Signing failure is silently
	// absorbed, the protocol stays valid without the extension.
	if (!extraExtensions?.[OFFER_RECEIPT]) {
		try {
			const offersFragment = await buildOffersExtension(
				resourceUrl,
				Array.isArray(accepts) ? accepts : [accepts],
			);
			if (offersFragment) Object.assign(extensions, offersFragment);
		} catch (err) {
			console.error('[build402Body] buildOffersExtension failed:', err?.message || err);
		}
	}
	if (extraExtensions && typeof extraExtensions === 'object') {
		Object.assign(extensions, extraExtensions);
	}
	// Merge static capability declaration into the offer-receipt extension slot.
	// Declaration fields (includeTxHash, offerValiditySeconds) sit alongside the
	// per-request signed offers (info.offers) so crawlers see both at once. The
	// declaration spreads first so existing offer data is never overwritten.
	const decl = offerReceiptDeclaration();
	if (decl) {
		const existing = extensions[OFFER_RECEIPT];
		extensions[OFFER_RECEIPT] = existing
			? { ...decl[OFFER_RECEIPT], ...existing }
			: decl[OFFER_RECEIPT];
	}
	const resource = { url: resourceUrl, description, mimeType };
	if (typeof serviceName === 'string' && serviceName.length) {
		resource.serviceName = serviceName;
	}
	if (Array.isArray(tags) && tags.length) {
		resource.tags = tags.slice(0, 5);
	}
	if (typeof iconUrl === 'string' && iconUrl.length) {
		resource.iconUrl = iconUrl;
	}
	return {
		x402Version: X402_VERSION,
		error,
		resource,
		accepts: Array.isArray(accepts) ? accepts : [accepts],
		extensions,
	};
}

// Ceiling for the base64 PAYMENT-REQUIRED header mirror. Node's default
// http client limit is 16 KB for the ENTIRE header block, and x402scan's
// registration probe flags any response whose headers exceed 16 KB
// (HEADERS_OVERFLOW, "some clients will fail to parse this response").
// Endpoints with rich bazaar schemas + per-accept signed offers were
// emitting 11-17 KB headers, which the production LB then dropped entirely.
//
// The cap itself was then too close to the edge. On 2026-09-18 production
// delivered a 7,760-byte mirror (/api/x402/forge) but silently stripped an
// 8,192-byte one (/api/x402/pump-launch, which landed exactly on the old 8 KB
// cap), so that route answered 402 with no PAYMENT-REQUIRED header at all and
// marketplace validators failed it. 7 KB sits below every size observed to
// survive and leaves headroom for the other response headers to grow. The body
// always carries the complete challenge, so a smaller mirror loses nothing a
// client needs.
export const PAYMENT_REQUIRED_HEADER_MAX = 7 * 1024;

const isPlainRecord = (v) => v != null && typeof v === 'object' && !Array.isArray(v);

// Drop the human-facing `info` examples from a bazaar extension, keeping the
// machine-readable `schema` that discovery validators actually parse. Returns
// null when nothing worth advertising survives.
function bazaarWithoutInfo(bazaar) {
	if (!isPlainRecord(bazaar)) return null;
	const { info, ...rest } = bazaar;
	return isPlainRecord(rest.schema) ? rest : null;
}

// A structurally-valid but compact bazaar mirror for the header: it preserves
// the input (queryParams/body) and output presence that agent-discovery
// crawlers key on (agentcash's extractSchemas2 / x402scan's Bazaar probe read
// `schema.properties.input.properties.{body|queryParams}` and
// `schema.properties.output.properties.example`), but replaces the potentially
// large per-field JSON Schemas with `{ type: 'object' }`. The canonical JSON
// body still carries the full, detailed schema, this is only the size-capped
// header fallback for routes whose real schema is too big to mirror verbatim.
function compactDiscoveryBazaar(bazaar) {
	const schema = bazaar?.schema;
	const inputProps = schema?.properties?.input?.properties;
	if (!isPlainRecord(inputProps)) return null;
	const input = {
		type: inputProps.type ?? { type: 'string', const: 'http' },
		method: inputProps.method ?? { type: 'string' },
		...(isPlainRecord(inputProps.body)
			? { body: { type: 'object' } }
			: isPlainRecord(inputProps.queryParams)
				? { queryParams: { type: 'object' } }
				: {}),
	};
	const hasOutput = isPlainRecord(schema?.properties?.output);
	return {
		discoverable: bazaar.discoverable !== undefined ? bazaar.discoverable : true,
		schema: {
			...(schema.$schema ? { $schema: schema.$schema } : {}),
			type: 'object',
			properties: {
				input: {
					type: 'object',
					properties: input,
					...(Array.isArray(schema.properties.input.required)
						? { required: schema.properties.input.required }
						: {}),
					additionalProperties: false,
				},
				...(hasOutput
					? {
						output: {
							type: 'object',
							properties: {
								type: { type: 'string' },
								example: { type: 'object' },
							},
							required: ['type'],
						},
					}
					: {}),
			},
			...(Array.isArray(schema.required) ? { required: schema.required } : {}),
		},
	};
}

// The base64 header value mirroring a 402 envelope. When the full envelope
// fits the budget it ships verbatim. Otherwise we shed the heavy
// payment-execution extensions (signed offers, gas-sponsoring hints, SIWX /
// auth-hints, builder-code) but KEEP the `bazaar` discovery extension, because
// agent-discovery crawlers (agentcash, x402scan's Bazaar) read the challenge
// from THIS header, not the JSON body, dropping bazaar makes every paid route
// look schema-less to them. We try, in order: full bazaar, bazaar without the
// `info` examples, then a compact bazaar with `{type:'object'}` field schemas,
// picking the first that fits, before falling back to the extension-less slim
// mirror, then null. Header-only payers still get everything needed to pay
// (accepts is always complete); the JSON body remains the canonical, complete
// envelope with the full detailed schemas per the v2 spec.
export function paymentRequiredHeaderValue(body) {
	const encode = (obj) => Buffer.from(JSON.stringify(obj), 'utf8').toString('base64');
	const full = encode(body);
	if (full.length <= PAYMENT_REQUIRED_HEADER_MAX) return full;

	const { x402Version, error, resource, accepts, extensions } = body;
	const slimBase = { x402Version, error, resource, accepts };
	const bazaar = extensions?.bazaar;
	if (isPlainRecord(bazaar)) {
		const candidates = [bazaar, bazaarWithoutInfo(bazaar), compactDiscoveryBazaar(bazaar)];
		for (const candidate of candidates) {
			if (!candidate) continue;
			const mirror = encode({ ...slimBase, extensions: { bazaar: candidate } });
			if (mirror.length <= PAYMENT_REQUIRED_HEADER_MAX) return mirror;
		}
	}

	const slim = encode(slimBase);
	return slim.length <= PAYMENT_REQUIRED_HEADER_MAX ? slim : null;
}

export async function send402(res, opts = {}) {
	res.statusCode = 402;
	res.setHeader('content-type', 'application/json; charset=utf-8');
	res.setHeader('cache-control', 'no-store');
	// v2 spec: the full envelope ({x402Version, error, resource, accepts,
	// extensions}) ships in the response body, that is the canonical read
	// for `@x402/fetch` and other SDK clients. The `PAYMENT-REQUIRED` header
	// carries a base64 mirror for header-only crawlers, capped by
	// paymentRequiredHeaderValue() so the total header block stays parseable
	// (oversized mirrors were silently dropped by the production LB and
	// flagged by x402scan's registration probe).
	const body = await build402Body(opts);
	const headerValue = paymentRequiredHeaderValue(body);
	if (headerValue) res.setHeader('PAYMENT-REQUIRED', headerValue);
	res.end(JSON.stringify(body));
}

// Resolve the canonical resource URL the client hit, so the facilitator can
// match the payer's signed payload against the same string we advertise.
//
// We always anchor on env.APP_ORIGIN (set via PUBLIC_APP_ORIGIN) rather than
// trusting `x-forwarded-host` / `host`. Trusting those headers lets a caller
// craft a 402 challenge that advertises an attacker-controlled `resource.url`,
// which agents may then call or display.
export function resolveResourceUrl(_req, path) {
	return `${env.APP_ORIGIN}${path}`;
}