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.

45.9 KB
Raw Blame
// @ts-check
// HTTP helpers for Vercel Node handlers. Keeps handlers small + consistent.

import { webcrypto } from 'node:crypto';
import { env } from './env.js';
import { captureException } from './sentry.js';
import { sendOpsAlert } from './alerts.js';
import { instrument as zauthInstrument, drain as zauthDrain } from './zauth.js';
import { isDbUnavailableError, isDbCapacityError, isStoragePressured } from './db.js';
import { isStorageInfrastructureError } from './r2.js';
import { redactUrlSecrets } from './scrub-secrets.js';
import { provenanceHeaders, withProvenance } from './brownout/provenance.js';
import { CHAOS_HEADER, CHAOS_STATUS_HEADER, chaosDecision, withChaos } from './brownout/chaos.js';

// Secure-by-default caching: emit `no-store` UNLESS the handler already set a
// Cache-Control header (e.g. `res.setHeader('cache-control', 'public, s-maxage=…')`
// on a public read) or passes one via `headers`. Previously this unconditionally
// forced `no-store`, silently overriding any cache header a handler set just
// before calling json()/text() — so public reads like /u/:username were never
// CDN-cacheable. Error responses must NEVER be cached, so error()/serverError()/
// validationError() pass an explicit `cache-control: no-store` in `headers`,
// which wins via the loop below regardless of what the success path set.
function applyCacheControl(res, headers) {
	const fromArg = Object.keys(headers).some((k) => k.toLowerCase() === 'cache-control');
	// `getHeader` is always present on a real Node ServerResponse; guard so a
	// minimal mock without it still gets the secure default rather than throwing.
	const alreadySet = typeof res.getHeader === 'function' && res.getHeader('cache-control');
	if (!fromArg && !alreadySet) {
		res.setHeader('cache-control', 'no-store');
	}
}

export function json(res, status, body, headers = {}) {
	// Once the response is committed (a handler already streamed/wrote a head, or
	// an error path fires after a success path), setting headers again throws
	// ERR_HTTP_HEADERS_SENT and crashes the invocation. The first response stands;
	// a second send is always a bug whose only safe outcome is a no-op. Guard here
	// so this can never escalate a benign double-send into an unhandled 500.
	if (res.headersSent || res.writableEnded) {
		if (!res.writableEnded) res.end();
		return;
	}
	res.statusCode = status;
	res.setHeader('content-type', 'application/json; charset=utf-8');
	applyCacheControl(res, headers);
	res.setHeader('x-content-type-options', 'nosniff');
	res.setHeader('x-frame-options', 'DENY');
	res.setHeader('referrer-policy', 'strict-origin-when-cross-origin');
	for (const [k, v] of Object.entries(headers)) res.setHeader(k, v);
	res.end(JSON.stringify(body));
}

export function text(res, status, body, headers = {}) {
	res.statusCode = status;
	res.setHeader('content-type', 'text/plain; charset=utf-8');
	applyCacheControl(res, headers);
	res.setHeader('x-content-type-options', 'nosniff');
	res.setHeader('x-frame-options', 'DENY');
	res.setHeader('referrer-policy', 'strict-origin-when-cross-origin');
	for (const [k, v] of Object.entries(headers)) res.setHeader(k, v);
	res.end(body);
}

export function redirect(res, location, status = 302) {
	res.statusCode = status;
	res.setHeader('location', location);
	res.setHeader('cache-control', 'no-store');
	res.end();
}

export function error(res, status, code, message, extra = {}) {
	// Error responses must never be cached, even on a handler that set a permissive
	// Cache-Control on its success path before hitting this error branch.
	return json(res, status, { error: code, error_description: message, ...extra }, { 'cache-control': 'no-store' });
}

// Query params that can carry a credential, a wallet secret, an email, or a
// user's real-world position. These must never reach a log line, Sentry event,
// or ops alert — all off-box sinks — so they are stripped from any request URL
// we log. Keys are compared after normalizing away case and `_`/`-` separators
// (see isSensitiveQueryKey), so `api-key`, `api_key`, and `apiKey` all collapse
// to one entry here and a new casing variant can't slip a secret through.
const SENSITIVE_QUERY_KEYS = new Set([
	// precise geolocation
	'lat', 'lng', 'latitude', 'longitude', 'll', 'coords', 'coord',
	'originlat', 'originlng', 'geo', 'location', 'position',
	// bearer / session credentials
	'token', 'devicetoken', 'accesstoken', 'refreshtoken', 'idtoken',
	'authorization', 'auth', 'bearer', 'session', 'sessionid', 'sid',
	'password', 'passwd', 'pwd', 'pin', 'otp',
	// free-studio install token (api/_mcp-studio/install-token.js): a stolen one
	// spends its owner's generation budget
	'install',
	// API keys / signing secrets
	'apikey', 'key', 'accesskey', 'secret', 'clientsecret', 'signature', 'sig',
	// wallet secrets
	'privatekey', 'secretkey', 'mnemonic', 'seed', 'seedphrase', 'keypair',
	// PII
	'email',
]);

// Normalize a query key to its case/separator-insensitive form before matching,
// so `deviceToken`, `device_token`, and `device-token` are one key.
function isSensitiveQueryKey(key) {
	return SENSITIVE_QUERY_KEYS.has(key.toLowerCase().replace(/[_-]/g, ''));
}

// Reduce a request URL to a log-safe form: keep the path and any benign params,
// but redact values that reveal a location or a credential. A geolocated read
// such as /api/irl/pins?lat=…&lng=…&deviceToken=… would otherwise spill the
// caller's exact position AND their device token into console / Sentry / Telegram
// on any 5xx — so every place req.url flows to a log sink routes through here.
export function redactUrl(rawUrl) {
	const url = String(rawUrl ?? '');
	const qIdx = url.indexOf('?');
	if (qIdx < 0) return url;
	const path = url.slice(0, qIdx);
	let params;
	try {
		params = new URLSearchParams(url.slice(qIdx + 1));
	} catch {
		// Unparseable query → don't risk logging the raw (possibly sensitive) tail.
		return `${path}?REDACTED`;
	}
	let touched = false;
	for (const key of [...params.keys()]) {
		if (isSensitiveQueryKey(key)) {
			params.set(key, 'REDACTED');
			touched = true;
		}
	}
	if (!touched) return url;
	const qs = params.toString();
	return qs ? `${path}?${qs}` : path;
}

// Distinguish a real top-level browser navigation from a programmatic API / agent
// call. Browsers stamp `Sec-Fetch-Mode: navigate` ONLY on top-level navigations;
// fetch()/XHR send cors|same-origin|no-cors. Clients without Sec-Fetch headers
// fall back to an Accept that prefers HTML. Used so a human who hits a 5xx is
// sent to the branded /500 page (carrying their support ref) while every API /
// agent caller keeps receiving the JSON error envelope it expects.
export function wantsHtmlNavigation(req) {
	const m = req?.method || 'GET';
	if (m !== 'GET' && m !== 'HEAD') return false;
	const mode = req?.headers?.['sec-fetch-mode'];
	if (mode) return mode === 'navigate';
	const accept = String(req?.headers?.['accept'] || '');
	return accept.includes('text/html');
}

// Build the /500 redirect target for a browser navigation that 5xx'd: the ref so
// the page can show + copy it, and the original (redacted) path so "Try again"
// retries the request that actually failed. redactUrl() keeps geo / tokens out of
// this URL too, since it ends up in the address bar and any referrer log.
function serverErrorPageLocation(ref, req) {
	const from = redactUrl(req?.url || '/').slice(0, 512);
	// Target the static file directly (public/500.html → /500.html is always
	// served by Vercel) so the error page never depends on a rewrite rule. The
	// `/500` clean URL also works for direct links, but the redirect can't rely
	// on it being configured.
	return `/500.html?ref=${encodeURIComponent(ref)}&from=${encodeURIComponent(from)}`;
}

// Short, URL-safe correlation id for tying a sanitized 5xx response back to the
// full server-side log line. Not security-sensitive — just needs to be unique.
function correlationId() {
	const b = new Uint8Array(8);
	/** @type {Crypto} */ (globalThis.crypto || webcrypto).getRandomValues(b);
	return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
}

// Throttle the log line for a database-unavailable outage to one per scope per
// minute (per warm lambda instance). A missing/rotated DATABASE_URL makes every
// DB-backed read reject, so without this a single misconfiguration produced
// thousands of identical `[api] unhandled` error lines + Sentry events in a few
// minutes — drowning real faults. The outage is already surfaced once via the
// deduped `db:unavailable` ops alert; here we only need a breadcrumb, at warn.
const _dbDownLoggedAt = new Map();
function logDbUnavailableOnce(scope, msg) {
	const now = Date.now();
	const last = _dbDownLoggedAt.get(scope) || 0;
	if (now - last < 60_000) return;
	_dbDownLoggedAt.set(scope, now);
	// Bound the map so a high-cardinality scope set (many distinct URLs) can't
	// grow it unbounded across a long-lived warm instance.
	if (_dbDownLoggedAt.size > 256) _dbDownLoggedAt.clear();
	console.warn(`[api] database unavailable — degrading ${scope}: ${msg}`);
}

// Log + capture + alert a server fault under a fresh correlation id WITHOUT
// writing a response, and return the ref. The body-writing helpers below build
// on this, but it's also the seam for handlers that must answer in a non-JSON
// content type (RSS/XML, sitemap text, JSON-RPC, MCP) and so can't call
// serverError(): they catch internally, call this to land the same log line +
// Sentry event + deduped ops alert, then echo `ref` in their own envelope. That
// keeps acceptance criterion #1 — every 5xx gets a ref/capture/alert — true for
// boundaries that never reach wrap(). `context` is merged into the Sentry extra
// (callers redact URLs via redactUrl() before passing them here).
export function reportServerError(err, { code = 'internal_error', status = 500, context = {} } = {}) {
	const ref = correlationId();
	// Mask URL-embedded credentials before the message reaches ANY sink (console,
	// Sentry, ops alert). Solana web3.js and fetch put the full request URL in
	// their network errors, so an on-chain failure would otherwise print the keyed
	// RPC endpoint (HELIUS_API_KEY) into logs. Applied here, at the single shared
	// sink, so every handler is covered rather than each remembering to redact.
	const rawDetail = err?.message || String(err ?? 'unknown error');
	const detail = redactUrlSecrets(rawDetail);
	// Whether anything was actually masked. Compared against the RAW string, not
	// against err.message, so an Error with an empty message (which falls back to
	// String(err)) is not misread as "redacted" and needlessly replaced below.
	const redacted = detail !== rawDetail;
	// A DB outage is infrastructure, not a code fault: throttle the log, skip the
	// Sentry capture, and collapse to the single shared `db:unavailable` alert so a
	// missing DATABASE_URL degrades quietly instead of flooding error tracking.
	const dbFull = isDbCapacityError(err);
	if (isDbUnavailableError(err) || dbFull) {
		logDbUnavailableOnce(code, detail);
		try {
			sendOpsAlert(dbFull ? 'database at storage cap — retention needed' : 'database unavailable', `${detail}\nref ${ref}`, {
				signature: dbFull ? 'db:capacity' : 'db:unavailable',
			});
		} catch { /* alerts best-effort */ }
		return ref;
	}
	// Object storage (R2/S3) outage: same class of fault, own deduped alert.
	if (isStorageInfrastructureError(err)) {
		logDbUnavailableOnce(code, `object storage unavailable: ${detail}`);
		try {
			sendOpsAlert('object storage unavailable', `${detail}\nref ${ref}`, { signature: 'storage:unavailable' });
		} catch { /* alerts best-effort */ }
		return ref;
	}
	console.error(`[server-error ${ref}] ${code} (${status}): ${detail}`);
	try {
		// Capture the original Error (preserving its stack + class) only when its
		// message carried no credential; otherwise send a redacted stand-in that
		// keeps the stack but not the key.
		let captured;
		if (err instanceof Error && !redacted) {
			captured = err; // nothing was masked, so send the original untouched
		} else {
			captured = new Error(detail);
			// A stack's first line repeats the message, so redact it too rather than
			// closing the front door and leaving the stack open.
			if (err instanceof Error && err.stack) captured.stack = redactUrlSecrets(err.stack);
		}
		captureException(captured, { ref, code, status, ...context });
		// Fire-and-forget like captureException; deduped per error class+message
		// (ref excluded from the signature so each occurrence doesn't re-alert).
		sendOpsAlert(`${status} ${code}`, `${detail}\nref ${ref}`, {
			signature: `server:${code}:${status}:${detail}`,
		});
	} catch {
		/* sentry/alerts best-effort; never mask the original failure */
	}
	return ref;
}

// Emit a 5xx WITHOUT leaking internal error detail to the client. The real
// message (which may carry RPC URLs, wallet addresses, or stack-derived text)
// is logged + captured server-side under a correlation id the caller can quote
// to support; the client only sees a generic description + the ref.
export function serverError(res, status, code, err, extra = {}) {
	// Coerce a DB outage OR a storage-cap failure to 503 + Retry-After regardless of
	// the caller's status, so boundaries that catch internally (sitemap, deployments)
	// advertise "retry shortly" to clients and CDNs exactly like wrap() does, instead
	// of a hard 500.
	if (isDbUnavailableError(err) || isDbCapacityError(err)) {
		const ref = reportServerError(err, { code, status: 503 });
		if (typeof res.setHeader === 'function') res.setHeader('retry-after', '30');
		return json(res, 503, {
			error: 'service_unavailable',
			error_description: 'database temporarily unavailable, retry shortly',
			ref,
			...extra,
		}, { 'cache-control': 'no-store' });
	}
	if (isStorageInfrastructureError(err)) {
		const ref = reportServerError(err, { code, status: 503 });
		if (typeof res.setHeader === 'function') res.setHeader('retry-after', '30');
		return json(res, 503, {
			error: 'service_unavailable',
			error_description: 'object storage temporarily unavailable, retry shortly',
			ref,
			...extra,
		}, { 'cache-control': 'no-store' });
	}
	const ref = reportServerError(err, { code, status });
	return json(res, status, {
		error: code,
		error_description: `internal error, quote ref ${ref} to support`,
		ref,
		...extra,
	}, { 'cache-control': 'no-store' });
}

// Dispatch: client-fault (4xx) keep their descriptive message; server-fault
// (5xx) are sanitized via serverError. Use this in catch blocks where the
// status is derived from `err.status` and may be either class.
export function respondError(res, status, code, err, extra = {}) {
	if (status < 500) {
		return error(res, status, code, err?.message || code, extra);
	}
	return serverError(res, status, code, err, extra);
}

// Advertise the limiter budget on the response using the conventional
// `RateLimit-*` headers (the shape GitHub/Stripe and the IETF
// draft-ietf-httpapi-ratelimit-headers converge on). `result` is the object
// returned by api/_lib/rate-limit.js limiters: { success, limit, remaining,
// reset } where `reset` is an absolute epoch-ms timestamp. Returns the
// seconds-until-reset so callers can reuse it for Retry-After.
export function setRateLimitHeaders(res, result) {
	if (!result) return 0;
	const now = Date.now();
	const resetSec = Math.max(0, Math.ceil(((result.reset ?? now) - now) / 1000));
	if (Number.isFinite(result.limit)) res.setHeader('ratelimit-limit', String(result.limit));
	if (Number.isFinite(result.remaining)) {
		res.setHeader('ratelimit-remaining', String(Math.max(0, result.remaining)));
	}
	res.setHeader('ratelimit-reset', String(resetSec));
	return resetSec;
}

// Standard 429 response. Given a limiter result, set the RateLimit-* budget
// headers plus Retry-After (RFC 9110 §10.2.3) so well-behaved clients — and the
// paying agents this platform is built for — back off by the exact window
// instead of hammering or giving up blind. `retry_after` is mirrored into the
// JSON body for clients that read the envelope rather than headers.
export function rateLimited(res, result, message = 'too many requests', extra = {}) {
	const retryAfter = Math.max(1, setRateLimitHeaders(res, result));
	res.setHeader('retry-after', String(retryAfter));
	// Surface the limiter's own `reason` (set by api/_lib/rate-limit.js) so clients
	// can tell a genuine quota hit from a degraded/unavailable limiter — e.g. a
	// Redis outage fails critical buckets closed with `rate_limiter_unavailable`,
	// which a client should present as "temporarily unavailable, retrying" rather
	// than "you've hit your limit".
	const reason = result?.reason;
	return error(res, 429, 'rate_limited', message, {
		retry_after: retryAfter,
		...(reason ? { reason } : {}),
		...extra,
	});
}

// Response shape used for zod validation errors so clients can render
// field-level feedback. Mirrors RFC 9457-style problem details (lite).
export function validationError(res, err) {
	return json(res, err.status || 400, {
		error: err.code || 'validation_error',
		error_description: err.message || 'invalid input',
		issues: err.issues || [],
	}, { 'cache-control': 'no-store' });
}

export async function readJson(req, limit = 1_000_000) {
	const ct = req.headers['content-type'] || '';
	if (!ct.includes('application/json')) {
		throw Object.assign(new Error('content-type must be application/json'), { status: 415 });
	}
	return readBody(req, limit).then((buf) => {
		try {
			return JSON.parse(buf.toString('utf8'));
		} catch {
			throw Object.assign(new Error('invalid JSON'), { status: 400 });
		}
	});
}

export async function readForm(req, limit = 1_000_000) {
	const buf = await readBody(req, limit);
	return Object.fromEntries(new URLSearchParams(buf.toString('utf8')));
}

export function readBody(req, limit) {
	// The Cloud Run server (server/index.mjs) pre-parses JSON / urlencoded / text /
	// octet-stream bodies through Express body-parser middleware ahead of every
	// handler, fully draining the raw request stream in the process, and stores the
	// result on req.body. If we then attach 'data'/'end' listeners to that same
	// (already-ended) stream below, they never fire — the promise hangs forever.
	// This was a live production incident: every JSON POST handler using readJson
	// (MCP tools/call, /api/forge, etc.) deadlocked with zero response. When
	// req.body is already populated, reconstruct the equivalent raw bytes from it
	// instead of touching the stream. Vercel serverless, local dev, and mcp-server
	// never set req.body ahead of time, so the raw-stream path below is unchanged
	// there — this only short-circuits when a prior middleware already consumed
	// the stream for us.
	if (Buffer.isBuffer(req.rawBody)) {
		// express.json()/urlencoded()'s `verify` hook (server/index.mjs) captured the
		// exact bytes pre-parse — prefer this over req.body so anything depending on
		// byte-for-byte fidelity (HMAC signature checks) still works.
		if (req.rawBody.length > limit) {
			return Promise.reject(Object.assign(new Error('payload too large'), { status: 413 }));
		}
		return Promise.resolve(req.rawBody);
	}
	if (req.body !== undefined) {
		const ct = req.headers['content-type'] || '';
		let buf;
		if (Buffer.isBuffer(req.body)) buf = req.body;
		else if (typeof req.body === 'string') buf = Buffer.from(req.body, 'utf8');
		else if (ct.includes('application/x-www-form-urlencoded')) {
			buf = Buffer.from(new URLSearchParams(req.body).toString(), 'utf8');
		} else buf = Buffer.from(JSON.stringify(req.body ?? {}), 'utf8');
		if (buf.length > limit) {
			return Promise.reject(Object.assign(new Error('payload too large'), { status: 413 }));
		}
		return Promise.resolve(buf);
	}
	// Neither req.rawBody nor req.body was populated by a prior middleware. If the
	// stream was already *consumed* by someone who then threw the bytes away (a
	// body-parser that drained it without capturing rawBody/body, a proxy layer in
	// some deployment), attaching 'data'/'end' listeners now is too late: those
	// events already fired and Node's Readable never re-emits 'end' for a listener
	// added after the stream closed. Resolving empty here (rather than hanging
	// forever on events that can never fire) turns a silent request timeout into a
	// normal "empty/invalid body" response the caller can see and retry.
	//
	// The signal for that is `readableEnded`, NOT `req.complete`. They mean
	// different things and conflating them broke every raw-body upload in
	// production: `req.complete` goes true once Node has *received* the whole
	// message off the socket, whether or not anyone read it, and Cloud Run's
	// frontend buffers the entire request before invoking the container. So a
	// perfectly readable, fully-buffered body arrived with complete === true and
	// was discarded unread, which is why POST /api/3d/inspect answered `empty_body`
	// to a real GLB upload. `readableEnded` only goes true after 'end' has actually
	// been emitted to a consumer, which is precisely the drained-stream case.
	// A destroyed stream can never emit 'end' either, so it short-circuits too.
	if (req.readableEnded || req.destroyed) return Promise.resolve(Buffer.alloc(0));
	return new Promise((resolve, reject) => {
		const chunks = [];
		let total = 0;
		let settled = false;
		// Defense in depth for the same hazard when the stream looks readable at
		// the time we start listening but never delivers 'data'/'end' for some
		// other reason (a stalled proxy, a client that never sends the promised
		// body). Without this, such a request pins a Cloud Run concurrency slot
		// for the full request timeout instead of failing fast with a diagnosable
		// error.
		const timeoutMs = Number(process.env.READ_BODY_TIMEOUT_MS) || 15_000;
		const timer = setTimeout(() => {
			if (settled) return;
			settled = true;
			reject(Object.assign(new Error('timed out reading request body'), { status: 408 }));
		}, timeoutMs);
		if (typeof timer.unref === 'function') timer.unref();
		const finish = (fn, arg) => {
			if (settled) return;
			settled = true;
			clearTimeout(timer);
			fn(arg);
		};
		req.on('data', (c) => {
			total += c.length;
			if (total > limit) {
				// Stop consuming, but leave the socket alive: destroying it here
				// resets the connection before the handler can write its 413, so
				// the caller sees an opaque "connection closed" instead of the
				// error that tells them their upload was too big. Unpipe + pause
				// is what raw-body does for the same reason; Node tears the
				// connection down after the response, once there is one to send.
				req.unpipe?.();
				req.pause?.();
				finish(reject, Object.assign(new Error('payload too large'), { status: 413 }));
				return;
			}
			chunks.push(c);
		});
		req.on('end', () => finish(resolve, Buffer.concat(chunks)));
		req.on('error', (err) => finish(reject, err));
	});
}

// ibm.com and any subdomain (any depth), https only. Used by the default
// allowlist so the IBM partnership embeds reach the shared three.ws APIs.
const IBM_ORIGIN = /^https:\/\/([a-z0-9-]+\.)*ibm\.com$/i;

// IBM publishes the partnership page through its Seismic CMS (live.ibm.com /
// ibm.seismic.com), and Seismic *executes* embedded HTML from its content
// gateway origin — e.g. https://gateway-prod-ibm-us-east-otter.seismic.com —
// NOT from *.ibm.com. So the real embedding origin for the IBM x402 demo is a
// *.seismic.com host, and IBM_ORIGIN alone never matches it. Allow Seismic-served
// origins (any depth) over https too, so the free Forge (/api/forge), the Solana
// RPC proxy (/api/solana-rpc) and other default-allowlist endpoints work when the
// page runs inside Seismic. Anchored to the exact host so look-alikes like
// seismic.com.evil.example can't match.
const SEISMIC_ORIGIN = /^https:\/\/([a-z0-9-]+\.)*seismic\.com$/i;

// Add fields to the response's `Vary` header without dropping what is already
// there. `res.setHeader('vary', …)` REPLACES, so a handler that varies on Cookie
// would otherwise erase the `vary: origin` cors() just set (and vice versa), and
// a shared cache would then serve one origin's CORS headers to another. Use this
// on any public-cacheable read whose body changes with a request header.
export function varyOn(res, ...fields) {
	const current = String(res.getHeader?.('vary') || '')
		.split(',')
		.map((f) => f.trim())
		.filter(Boolean);
	const seen = new Set(current.map((f) => f.toLowerCase()));
	for (const field of fields) {
		if (!seen.has(field.toLowerCase())) {
			seen.add(field.toLowerCase());
			current.push(field);
		}
	}
	res.setHeader('vary', current.join(', '));
}

export function cors(
	req,
	res,
	{ origins = null, methods = 'GET,POST,OPTIONS', credentials = false, payments = true } = {},
) {
	const origin = req.headers.origin;
	if (origins === '*') {
		res.setHeader('access-control-allow-origin', '*');
	} else if (origin && isAllowedOrigin(origin, origins)) {
		res.setHeader('access-control-allow-origin', origin);
		res.setHeader('vary', 'origin');
		if (credentials) res.setHeader('access-control-allow-credentials', 'true');
	}
	res.setHeader('access-control-allow-methods', methods);
	// `payments: false` is for the surfaces we present as having no payment
	// capability at all (the free ChatGPT connector and the endpoints its widget
	// touches). Advertising a payment request header and exposing a
	// PAYMENT-REQUIRED response header on one of those is a claim a reviewer can
	// read straight off the network tab, and it contradicts the rest of the
	// surface. The default stays `true`, so every metered caller is unchanged.
	res.setHeader(
		'access-control-allow-headers',
		payments
			? 'authorization, content-type, mcp-session-id, mcp-protocol-version, x-payment, payment-signature, x-payment-rail, x-ap2-mandate, x-ap2-cart, x-a2a-extensions, idempotency-key, x-irl-device, x-irl-fix, x-forge-client, x-agent-id, x-forge-seed'
			: 'authorization, content-type, mcp-session-id, mcp-protocol-version, idempotency-key, x-irl-device, x-irl-fix, x-forge-client, x-agent-id, x-forge-seed',
	);
	// x402: clients (drop-in modal, x402-fetch) must read these to drive the
	// 402-pay-retry flow and surface settlement receipts. Without `expose`,
	// cross-origin readers only see CORS-safelisted response headers.
	res.setHeader(
		'access-control-expose-headers',
		payments ? 'PAYMENT-REQUIRED, PAYMENT-RESPONSE, Payment-Receipt, WWW-Authenticate, x-a2a-extensions, x-payment-response, x-payment-network, x-payment-tx, link' : 'link',
	);
	res.setHeader('access-control-max-age', '86400');
	if (req.method === 'OPTIONS') {
		res.statusCode = 204;
		res.end();
		return true;
	}
	return false;
}

// CORS for a read that the <agent-3d> embed makes from somebody else's website.
//
// The default allowlist is right for our own pages and wrong for an embed: the whole
// point of the embed is that it runs on origins we have never heard of, so those
// reads were blocked and logged a CORS error in every host site's console. A request
// that carries no cookie and no authorization header can only ever see the public
// answer, so it is safe to open to any origin. Anything authenticated keeps the
// strict allowlist and its credentials.
export function embedReadCors(req, res, { methods = 'GET,OPTIONS', authedMethods = methods } = {}) {
	const wanted = req.method === 'OPTIONS' ? String(req.headers['access-control-request-method'] || 'GET').toUpperCase() : req.method;
	const anonymous = !req.headers.cookie && !req.headers.authorization;
	const asksForAuth = /\bauthorization\b/i.test(String(req.headers['access-control-request-headers'] || ''));
	if (wanted === 'GET' && anonymous && !asksForAuth) return cors(req, res, { origins: '*', methods });
	return cors(req, res, { methods: authedMethods, credentials: true });
}

function isAllowedOrigin(origin, allowed) {
	if (!allowed) {
		if (origin === env.APP_ORIGIN) return true;
		if (origin === 'https://x402scan.com') return true;
		if (origin === 'https://agentic.market') return true;
		if (origin === 'https://www.agentic.market') return true;
		// IBM partnership: allow ibm.com and every subdomain (any depth) over
		// https, so the partnership page's embeds and the shared three.ws APIs
		// (forge, etc.) work when served from *.ibm.com. Anchored to the exact
		// host so look-alikes like ibm.com.evil.example or notibm.com don't match.
		if (IBM_ORIGIN.test(origin)) return true;
		// …and from the Seismic CMS gateway IBM actually embeds it through.
		if (SEISMIC_ORIGIN.test(origin)) return true;
		if (
			process.env.NODE_ENV !== 'production' &&
			/^https?:\/\/localhost(:\d+)?$/.test(origin)
		) {
			return true;
		}
		return false;
	}
	return allowed.some((pat) => (typeof pat === 'string' ? origin === pat : pat.test(origin)));
}

// Attach the request's data provenance to the response, and honour a chaos
// directive if this request carries a valid one.
//
// This sits in wrap() because wrap() is the one seam every handler already goes
// through: putting it here means a new endpoint reports its provenance without
// its author doing anything, which is the only way a guarantee like this stays
// true across hundreds of handlers. Headers are written just before the body
// goes out; a response already streaming keeps whatever it had, since headers
// cannot be added after the fact and a throw here must never cost a caller a
// working answer.
function attachProvenance(res) {
	try {
		if (res.headersSent || typeof res.setHeader !== 'function') return;
		const headers = provenanceHeaders();
		if (!headers) return;
		res.setHeader('x-brownout', headers.summary);
		if (headers.trace) res.setHeader('x-brownout-trace', headers.trace);
		// Browsers cannot read a response header unless it is exposed, and the
		// whole point of this is that a client can tell a degraded answer from a
		// live one.
		const exposed = res.getHeader('access-control-expose-headers');
		const want = headers.trace ? 'x-brownout, x-brownout-trace' : 'x-brownout';
		res.setHeader('access-control-expose-headers', exposed ? `${exposed}, ${want}` : want);
	} catch {
		/* provenance is telemetry: it never breaks a response */
	}
}

// Wrap async handlers so uncaught errors return a consistent JSON envelope.
export function wrap(handler) {
	return async (req, res, ...rest) => {
		const monitored = zauthInstrument(req, res);
		const chaos = chaosDecision(req);
		if (req?.headers?.[CHAOS_HEADER] && typeof res.setHeader === 'function') {
			// Always answer the question the caller asked, including when the answer
			// is no. A prover that believes it broke an upstream and did not would
			// record a green proof for a fallback nothing exercised, which is worse
			// than a red one.
			try {
				res.setHeader(CHAOS_STATUS_HEADER, chaos.allowed ? `applied;faults=${chaos.faults.size}` : `refused;reason=${chaos.reason}`);
			} catch { /* header write is best-effort */ }
		}
		const run = () => withProvenance(() => withChaos(chaos.faults, async () => {
		try {
			await handler(req, res, ...rest);
		} catch (err) {
			const dbDown = isDbUnavailableError(err);
			// Storage-cap failures (SQLSTATE 53100) are, like a connectivity outage, an
			// infrastructure condition rather than a code bug — reads still work, writes
			// fail until retention frees space — so they take the same graceful, throttled,
			// no-Sentry path, just with a distinct alert so ops knows to reclaim space
			// (api/cron/db-retention.js) rather than chase a phantom bug.
			const dbFull = !dbDown && isDbCapacityError(err);
			const dbDegraded = dbDown || dbFull;
			// A missing env var (api/_lib/env.js `req()`) is a deployment-configuration
			// gap, not a code bug: the endpoint is down until the operator sets the
			// secret. Surface it as 503 not_configured with a deduped alert naming the
			// exact var — instead of one generic "unhandled 5xx" + Sentry event per hit
			// (the July 2026 siwe/siws nonce incident: JWT_SECRET unset → hundreds of
			// anonymous 500s that never said which var was missing).
			const missingEnv = !dbDegraded && /^Missing required env var: /.test(err?.message || '');
			// An object-storage (R2/S3) fault is infrastructure too. Deliberate
			// author-written errors (`expose`) and 4xx throws keep their own contract
			// even when their text happens to match the storage pattern ("unauthorized").
			const storageDown = !dbDegraded && !missingEnv && !err?.expose && !(err?.status && err.status < 500)
				&& isStorageInfrastructureError(err);
			const status = dbDegraded || missingEnv || storageDown ? 503 : (err.status || 500);
			if (status >= 500) {
				const ref = correlationId();
				if (dbDegraded) {
					// During a DB outage/cap EVERY endpoint that doesn't catch internally lands
					// here. A missing/rotated DATABASE_URL or a full branch would otherwise emit
					// one `[api] unhandled` error line + one Sentry event per request — thousands
					// in minutes. It's infrastructure, not a code bug: throttle the log, skip
					// the Sentry capture, and fire only the single shared deduped alert.
					logDbUnavailableOnce(`${req.method} ${redactUrl(req.url)}`, err?.message || String(err));
					sendOpsAlert(dbFull ? 'database at storage cap — retention needed' : 'database unavailable', `${err?.message || String(err)}\nref ${ref}`, {
						signature: dbFull ? 'db:capacity' : 'db:unavailable',
					});
				} else if (storageDown) {
					// Every route that writes to R2 without its own try/catch lands here
					// during a bucket outage: throttle the log, skip Sentry, one deduped alert.
					logDbUnavailableOnce(`${req.method} ${redactUrl(req.url)}`, `object storage unavailable: ${err?.message || String(err)}`);
					sendOpsAlert('object storage unavailable', `${err?.message || String(err)}\nref ${ref}`, {
						signature: 'storage:unavailable',
					});
				} else if (missingEnv) {
					// One concise line + one deduped alert per (route, var) — the fix is
					// always the same: set the named var in the deployment env.
					console.error(`[api] ${err.message} [ref ${ref}] — set it in the deployment env (${req.method} ${redactUrl(req.url)})`);
					sendOpsAlert(`endpoint not configured: ${req.method} ${redactUrl(req.url)}`, `${err.message}\nSet the var in the Vercel env and redeploy.\nref ${ref}`, {
						signature: `not-configured:${redactUrl(req.url)}:${err.message}`,
					});
				} else {
					// Redact coordinates / device tokens so a 5xx on a geolocated read never
					// spills the caller's position or credential to an off-box sink.
					console.error(`[api] unhandled [ref ${ref}]`, err);
					captureException(err, { ref, url: redactUrl(req.url), method: req.method });
					sendOpsAlert(`unhandled 5xx in ${req.method} ${redactUrl(req.url)}`, `${err?.message || String(err)}\nref ${ref}`, {
						signature: `unhandled:${redactUrl(req.url)}:${err?.message}`,
					});
				}
				// Never echo a raw upstream message in a 5xx body — Solana/web3.js
				// network errors embed the keyed RPC URL (…helius-rpc.com/?api-key=…),
				// so err.message would leak HELIUS_API_KEY to the client. Hand back a
				// sanitized envelope keyed to the same ref we just logged.
				if (!res.headersSent && !res.writableEnded) {
					if (dbDegraded || storageDown) {
						// 503 with Retry-After so clients and CDNs know to back off.
						res.setHeader('retry-after', '30');
					}
					if (wantsHtmlNavigation(req)) {
						// A human navigated into this 5xx — send them to the branded
						// error page with their ref instead of a raw JSON blob. API and
						// agent callers (no `Sec-Fetch-Mode: navigate`) keep the envelope.
						redirect(res, serverErrorPageLocation(ref, req), 303);
					} else if (missingEnv) {
						// Don't name the missing var to the client — which secrets are
						// unset is operator information; the ref ties it to the log line.
						json(res, status, {
							error: 'not_configured',
							error_description: `this endpoint is not configured on this deployment — quote ref ${ref} to support`,
							ref,
						}, { 'cache-control': 'no-store' });
					} else if (!dbDegraded && err.expose && err.code) {
						// An author-written contract error: the endpoint deliberately threw
						// this status, code, and message (gateway `fail()`, or an explicit
						// `Object.assign(new Error(...), { status, code, expose: true })`).
						// These are documented parts of the endpoint's contract and are what
						// a caller needs to react correctly, so a `503 upstream_unavailable`
						// must not collapse into a generic internal_error. The `expose`
						// marker is the whole gate: an error that merely bubbled up never
						// carries it, so the redaction below still covers every leak case.
						json(res, status, {
							error: err.code,
							error_description: err.message || `error, quote ref ${ref} to support`,
							ref,
						}, { 'cache-control': 'no-store' });
					} else {
						// `err.code` is NOT safe to echo here, for the same reason the
						// message above is redacted: on a 5xx it carries internal
						// implementation detail the caller has no business seeing. A
						// Postgres failure puts the raw SQLSTATE in it (a missing table
						// answered `42P01`, naming the storage engine and the fault), and
						// a Node socket failure puts ECONNREFUSED / ENOTFOUND there,
						// mapping our internal topology. 4xx keeps its code below, where
						// it is a deliberate, documented part of each endpoint's contract.
						json(res, status, {
							error: dbDegraded || storageDown ? 'service_unavailable' : 'internal_error',
							error_description: dbDegraded
								? 'database temporarily unavailable, retry shortly'
								: storageDown
								? 'object storage temporarily unavailable, retry shortly'
								: `internal error, quote ref ${ref} to support`,
							ref,
						}, { 'cache-control': 'no-store' });
					}
				}
			} else if (!res.headersSent && !res.writableEnded) {
				if (err.code === 'validation_error' && Array.isArray(err.issues)) {
					validationError(res, err);
				} else {
					error(res, status, err.code || 'bad_request', err.message || 'error');
				}
			}
		}
		}));
		// The provenance header has to be written while the ledger is still in
		// scope AND before the body is flushed, so the res.end path is patched for
		// the duration of the handler rather than read afterwards. Every helper in
		// this module funnels through res.end, so one seam covers json(), error()
		// and a hand-rolled stream alike.
		const originalEnd = typeof res.end === 'function' ? res.end.bind(res) : null;
		if (originalEnd) {
			res.end = (...args) => {
				attachProvenance(res);
				res.end = originalEnd;
				return originalEnd(...args);
			};
		}
		try {
			await run();
		} finally {
			if (originalEnd) res.end = originalEnd;
		}
		// Keep the lambda alive briefly so the zauth SDK's in-flight POST to
		// back.zauthx402.com can finish. Cost: ~250ms of post-response runtime
		// on monitored requests only. The user has already received the response.
		if (monitored) await zauthDrain();
	};
}

// Wrap cron handlers with DB-unavailability awareness.
//
// When the database is unreachable (wrong credentials, connection refused, etc.)
// every cron invocation would otherwise bubble a NeonDbError to wrap(), which
// logs `[api] unhandled` and fires a sendOpsAlert per invocation — turning a
// single misconfigured DATABASE_URL into a sustained ops-alert storm. wrapCron
// intercepts DB-unavailable errors before they reach wrap(), logs a single warn,
// and returns 200 { ok: false, reason: 'db_unavailable' } so Vercel doesn't
// count the cron as a hard failure. Non-DB errors re-throw to wrap() so genuine
// bugs still surface through normal alerting.
//
// `requireWriteCapacity` opts a write-heavy cron into a storage-pressure preflight:
// when the branch is at its project-size cap, running a full tick only fails per-row
// (53100) and floods the logs, so the tick is skipped with 200 { ok: true, skipped }
// and a single warn instead. The probe is a READ (works at the cap); db-retention
// then reclaims space and the next tick resumes (see isStoragePressured). This is the
// proactive complement to the reactive catch below — it stops crons that swallow
// their own write errors (the pump-intel firehose) from storming the logs at the cap.
//
// `maxDurationMs` gives the cron a real time budget. Before the 2026-07-07 Cloud Run
// migration, the `maxDuration` a handler exported was Vercel-enforced; nothing ever
// replaced that enforcement, so a hang anywhere inside a handler ran unbounded until
// Cloud Run's own 900s ingress timeout killed the connection with no cron name, no
// elapsed time, and no heartbeat write. Defaults to 120000 (the most common declared
// `maxDuration` value) when the caller does not pass one.
// The most common declared `maxDuration` value across api/cron/*.js today, and
// what a cron gets for free when it declares none of its own.
export const DEFAULT_CRON_MAX_DURATION_MS = 120_000;

export function wrapCron(handler, { requireWriteCapacity = false, maxDurationMs } = {}) {
	const budgetMs = maxDurationMs ?? DEFAULT_CRON_MAX_DURATION_MS;
	return wrap(async (req, res, ...rest) => {
		// Derive cron name from the request URL for heartbeat tracking.
		const cronName = (req.url || '').replace(/^\/api\/cron\//, '').split('?')[0] || 'unknown';
		const t0 = Date.now();
		if (requireWriteCapacity) {
			let pressure = null;
			try { pressure = await isStoragePressured(); } catch { /* a probe fault must never stall a tick */ }
			if (pressure?.pressured) {
				console.warn(`[cron] ${cronName} skipped — db at storage cap (${pressure.sizeMb}MB ≥ ${pressure.highWaterMb}MB); retention will reclaim space`);
				// Heartbeat a healthy skip so uptime monitoring reads it as up, not stalled.
				import('./cache.js').then(({ cacheSet }) => {
					cacheSet(`cron:heartbeat:${cronName}`, { ok: true, skipped: 'db_at_storage_cap', t: t0, ms: Date.now() - t0 }, 7 * 24 * 60 * 60).catch(() => {});
				}).catch(() => {});
				if (!res.headersSent && !res.writableEnded) {
					json(res, 200, { ok: true, skipped: 'db_at_storage_cap', size_mb: pressure.sizeMb, high_water_mb: pressure.highWaterMb });
				}
				return;
			}
		}

		const writeHeartbeat = (beat) => {
			import('./cache.js').then(({ cacheSet }) => {
				cacheSet(`cron:heartbeat:${cronName}`, beat, 7 * 24 * 60 * 60).catch(() => {});
			}).catch(() => {});
		};

		// True once the budget timer below has already answered the request and
		// recorded the tick as timed out. Guards the handler's own (late) heartbeat
		// write from clobbering that record if it eventually finishes on its own.
		let timedOut = false;

		const runHandler = (async () => {
			try {
				await handler(req, res, ...rest);
				// A handler that reports its own failure as a 5xx (instead of throwing)
				// failed too; recording it as healthy hid a broken cron on the ops board.
				if (timedOut) return;
				const failed = res.statusCode >= 500;
				writeHeartbeat(failed
					? { ok: false, t: t0, ms: Date.now() - t0, err: `answered HTTP ${res.statusCode}` }
					: { ok: true, t: t0, ms: Date.now() - t0 });
			} catch (err) {
				if (!timedOut) {
					writeHeartbeat({ ok: false, t: t0, ms: Date.now() - t0, err: err?.message?.slice(0, 200) });
				}
				if (isDbUnavailableError(err) || isDbCapacityError(err)) {
					const full = isDbCapacityError(err);
					console.warn(`[cron] db ${full ? 'at storage cap' : 'unavailable'}, skipping tick:`, err.message);
					if (!res.headersSent && !res.writableEnded) {
						json(res, 200, { ok: false, reason: full ? 'db_full' : 'db_unavailable' });
					}
					return;
				}
				if (isStorageInfrastructureError(err) && !err?.expose && !(err?.status && err.status < 500)) {
					console.warn('[cron] object storage unavailable, skipping tick:', err.message);
					sendOpsAlert('object storage unavailable', `${err.message}\ncron tick skipped`, { signature: 'storage:unavailable' });
					if (!res.headersSent && !res.writableEnded) {
						json(res, 200, { ok: false, reason: 'storage_unavailable' });
					}
					return;
				}
				throw err;
			}
		})();

		let timer;
		const budget = new Promise((resolve) => {
			timer = setTimeout(() => {
				timedOut = true;
				if (!res.headersSent && !res.writableEnded) {
					writeHeartbeat({ ok: false, t: t0, ms: Date.now() - t0, timed_out: true });
					console.warn(`[cron] ${cronName} exceeded its ${budgetMs}ms budget, answering 503 before Cloud Run's own timeout kills the connection`);
					sendOpsAlert(`cron timeout: ${cronName}`, `exceeded its ${budgetMs}ms budget`, { signature: `cron:timeout:${cronName}` });
					json(res, 503, { ok: false, reason: 'cron_timeout', cron: cronName, budget_ms: budgetMs });
				}
				resolve();
			}, budgetMs);
			if (typeof timer.unref === 'function') timer.unref();
		});

		try {
			await Promise.race([runHandler, budget]);
		} finally {
			clearTimeout(timer);
			// Node cannot preempt arbitrary async work without an AbortSignal threaded
			// through every I/O call inside the handler, so the handler itself is never
			// cancelled when the budget wins the race. Swallow whatever it eventually
			// does (resolve or reject) so it can never try to write to the response this
			// request already ended, or crash the process with an unhandled rejection.
			runHandler.catch(() => {});
		}
	});
}

export function method(req, res, allowed) {
	const m = req.method || 'GET';
	// HEAD must be allowed wherever GET is allowed (RFC 9110 §9.3.2).
	// Treat an incoming HEAD as GET for the purposes of the allowlist check;
	// Node.js HTTP automatically strips the response body on HEAD responses.
	const effective = (m === 'HEAD' && allowed.includes('GET')) ? 'GET' : m;
	// …and normalize the request itself to GET so downstream dispatch that
	// branches on `req.method === 'GET'` (exact equality) actually runs for a
	// HEAD probe instead of falling through every branch and hanging the
	// invocation until the function's hard timeout → a 504. This is safe: Node's
	// ServerResponse captured the request method at construction (set
	// `_hasBody = false` for HEAD), so the body stays stripped no matter what we
	// set req.method to here.
	if (effective === 'GET' && m === 'HEAD') req.method = 'GET';
	if (!allowed.includes(effective)) {
		// Dedupe: a handler that already lists HEAD alongside GET would otherwise
		// advertise `Allow: GET, HEAD, HEAD`.
		const advertised = allowed.includes('GET') ? [...new Set([...allowed, 'HEAD'])] : allowed;
		res.setHeader('allow', advertised.join(', '));
		error(res, 405, 'method_not_allowed', `method ${m} not allowed`);
		return false;
	}
	return true;
}