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.

12.3 KB
Raw Blame
/**
 * IPFS / Arweave URI resolver.
 *
 * Translates decentralised storage URIs into HTTPS gateway URLs
 * so the Three.js loader can fetch them normally.
 *
 *   ipfs://QmXyz...        → https://ipfs.filebase.io/ipfs/QmXyz...
 *   ipfs://bafkreiXyz...   → https://ipfs.filebase.io/ipfs/bafkreiXyz...
 *   ar://txId               → https://arweave.net/txId
 */

// Only gateways that serve subresource and fetch() reads with open CORS. The
// first entry is what an ipfs:// URI renders through, so it is the fastest one
// measured (Filebase and 4everland answer in ~150ms; Pinata's public gateway
// works but takes 4 to 7s). Every host below was dropped because it stopped
// serving, and normalizeGatewayURL() rewrites URLs still pointing at one:
//   - cf-ipfs.com, cloudflare-ipfs.com: Cloudflare retired both (Aug 2024), DNS fails.
//   - flk-ipfs.xyz: DNS fails.
//   - ipfs.io, dweb.link, w3s.link, nftstorage.link: since Oct 2026 they answer
//     every non-navigation request with 429/403 "switching to a service worker
//     gateway only" (gatewaychanges.ipfs.io), so <img>, fetch() and texture
//     loads against them all fail. pump.fun metadata still hands out ipfs.io URLs.
export const IPFS_GATEWAYS = [
	'https://ipfs.filebase.io/ipfs/',
	'https://4everland.io/ipfs/',
	'https://gateway.pinata.cloud/ipfs/',
];

const AR_GATEWAY = 'https://arweave.net/';

// Per-gateway budget. Public gateways routinely accept a connection and then
// never answer; without a deadline the first such host holds the whole chain.
const GATEWAY_TIMEOUT_MS = 8_000;

// Gateways that no longer serve reads (see IPFS_GATEWAYS above). Any HTTPS URL
// on one of these is rewritten onto a working gateway, keeping /ipfs/<cid>/path.
const DEAD_GATEWAY_HOST_RE =
	/^https?:\/\/(?:cf-ipfs\.com|cloudflare-ipfs\.com|flk-ipfs\.xyz|ipfs\.io|dweb\.link|w3s\.link|nftstorage\.link)\/ipfs\/(.+)$/i;

/**
 * Returns true when the URL uses a decentralised storage scheme.
 * @param {string} url
 * @returns {boolean}
 */
export function isDecentralizedURI(url) {
	return /^(ipfs|ar):\/\//i.test(url);
}

/**
 * Repair full HTTPS gateway URLs that point at a retired gateway host.
 * Leaves every other URL (including live gateways) untouched.
 *
 * @param {string} url
 * @param {number} [gatewayIndex=0]  Which working gateway to route to.
 * @returns {string}
 */
export function normalizeGatewayURL(url, gatewayIndex = 0) {
	if (!url) return url;
	const dead = url.match(DEAD_GATEWAY_HOST_RE);
	if (dead) {
		const gw = IPFS_GATEWAYS[gatewayIndex % IPFS_GATEWAYS.length];
		return gw + dead[1];
	}
	return url;
}

/**
 * Resolve an ipfs:// or ar:// URI to an HTTPS gateway URL.
 * For regular URLs the input is returned unchanged, except that URLs pointing
 * at a retired gateway host are rewritten onto a working gateway.
 *
 * @param {string} uri
 * @param {number} [gatewayIndex=0]  Which IPFS gateway to use (for fallback).
 * @returns {string}
 */
export function resolveURI(uri, gatewayIndex = 0) {
	if (!uri) return uri;

	// ipfs://CID  or  ipfs://CID/path
	const ipfsMatch = uri.match(/^ipfs:\/\/(.+)$/i);
	if (ipfsMatch) {
		const gw = IPFS_GATEWAYS[gatewayIndex % IPFS_GATEWAYS.length];
		return gw + ipfsMatch[1];
	}

	// ar://txId
	const arMatch = uri.match(/^ar:\/\/(.+)$/i);
	if (arMatch) {
		return AR_GATEWAY + arMatch[1];
	}

	return normalizeGatewayURL(uri, gatewayIndex);
}

// Schemes an <img src> or a Three.js TextureLoader can actually render. Every
// image URL this module hands out is attacker-reachable: it arrives from a
// `?image=` deep link, a third-party token feed, or a peer's join options. A
// scheme outside this set is never art. It is either an attempt at a script
// sink (javascript:, vbscript:), a local-resource probe (file:, about:), or an
// HTML document dressed as an image (data:text/html), so the only correct
// answer is to drop it, not to pass it through to whoever asked.
const SAFE_IMAGE_SCHEMES = new Set(['http', 'https', 'ipfs', 'ar', 'blob']);
// Longest source URL worth proxying. Real IPFS/Arweave/CDN art sits well under
// 300 characters; a multi-kilobyte value is either junk or an attempt to make
// us issue an oversized upstream request, and the proxy would reject it anyway.
const MAX_SOURCE_URL = 2048;

// Characters that never appear unencoded in a real image path, and that are
// exactly the ones a crafted value uses to break out of the syntax it lands in:
// quotes and parentheses close a CSS url(), a semicolon starts a new declaration,
// angle brackets open a tag, whitespace and backslash split the token. A
// scheme-less value carrying any of them is not art someone forgot to encode, it
// is a payload, and handing it to an image sink costs a doomed request and a
// console error even when the escaping downstream holds.
const CSS_HTML_UNSAFE = /["'()<>;\\\s]/;

/**
 * True when a URL is safe to hand to an <img>/TextureLoader as an image source.
 * Relative and site-absolute paths qualify as long as they still look like paths;
 * `data:` only when it declares an image media type.
 *
 * @param {string} url
 * @returns {boolean}
 */
export function isSafeImageURL(url) {
	if (typeof url !== 'string') return false;
	const s = url.trim();
	if (!s) return false;
	// Control characters exist here only to smuggle a scheme past a parser
	// ("java\tscript:alert(1)" is a live URL in some engines). Refuse outright.
	if (/[\u0000-\u001f\u007f]/.test(s)) return false;
	const scheme = s.match(/^([a-z][a-z0-9+.\-]*):/i)?.[1]?.toLowerCase();
	if (!scheme) return !CSS_HTML_UNSAFE.test(s); // relative or site-absolute path
	if (scheme === 'data') return /^data:image\/[a-z0-9.+\-]+[,;]/i.test(s);
	if (!SAFE_IMAGE_SCHEMES.has(scheme)) return false;
	// blob: is an opaque single token; the rest are real URLs whose path is subject
	// to the same no-breakout-characters rule as a relative path.
	return scheme === 'blob' || !CSS_HTML_UNSAFE.test(s);
}

/**
 * Route an external image URL through the same-origin /api/img proxy.
 *
 * Third-party token-art hosts (per-launch CDNs, IPFS/Arweave gateways) fail in
 * browsers for reasons we can't fix client-side: missing CORS headers, ORB
 * blocking, retired hosts, and TLS interception on filtered networks. The
 * proxy fetches server-side with multi-gateway IPFS retry and always answers
 * with a valid image (deterministic placeholder on total failure), so the
 * loader never errors. Same-origin, relative, data:image and blob: URLs pass
 * through untouched; the proxy only earns its keep cross-origin.
 *
 * Anything that is not a renderable image source (javascript:, data:text/html,
 * file:, an over-long URL) resolves to '' so callers fall through to their own
 * "no art" branch instead of pushing a hostile value into an image sink.
 *
 * `width` asks the proxy for a copy no wider than that many pixels, re-encoded
 * as WebP (it snaps up to a fixed ladder, so a caller cannot mint unbounded
 * edge variants). Token art is stored at whatever size its creator uploaded:
 * four coins in the /play world pulled 2.7 MB of full-size PNGs for textures
 * that are a few hundred pixels on screen. Pass the size the art is actually
 * used at; leave it off to get the original bytes.
 *
 * `fallback: 'none'` asks the proxy for 204 No Content instead of the gem when
 * every source fails. Use it wherever the surface already designs its own "no
 * image" state (the neutral logo disc on the DeFi tables): the browser logs
 * nothing for a 204, and the <img> still fires `error`, so the designed state
 * renders and the console stays clean. Leave it off for token art, which wants
 * the placeholder.
 *
 * @param {string} url          Image URL (https://, ipfs:// or ar:// accepted).
 * @param {string} [seed]       Stable placeholder seed (e.g. the token mint).
 * @param {{ width?: number, fallback?: 'art'|'none' }} [opts]
 * @returns {string}
 */
export function proxiedImageURL(url, seed = '', { width = 0, fallback = 'art' } = {}) {
	if (typeof url !== 'string' || !url) return '';
	// Protocol-relative art still deserves the proxy's CORS and gateway retry,
	// so give it the scheme the page is already on before anything else looks
	// at it. Site-absolute ('/x.png') is untouched; only '//host/x.png' matches.
	const raw = /^\/\/[^/]/.test(url.trim()) ? 'https:' + url.trim() : url.trim();
	if (!isSafeImageURL(raw)) return '';
	if (!/^(https?|ipfs|ar):/i.test(raw)) return raw;
	if (typeof location !== 'undefined' && raw.startsWith(location.origin + '/')) return raw;
	if (raw.length > MAX_SOURCE_URL) return '';
	const q = new URLSearchParams({ url: resolveURI(raw) });
	if (seed) q.set('seed', seed);
	if (width > 0) q.set('w', String(Math.round(width)));
	if (fallback === 'none') q.set('fallback', 'none');
	return `/api/img?${q.toString()}`;
}

/**
 * Route an external model URL through the same-origin /api/glb proxy.
 *
 * Generated models live on the public asset bucket, whose CORS policy is an
 * origin allowlist naming the production site. Every other origin that loads a
 * GLB in a browser (a partner embed, a notebook on localhost, a Codespaces
 * preview, a local audit run) gets no `access-control-allow-origin` header back
 * and the fetch dies inside model-viewer as "Failed to fetch", with nothing on
 * the page able to recover it. `/api/glb` reads the same public object
 * server-side through the SSRF-hardened fetcher and answers with open CORS and
 * an immutable cache header, so the model loads from anywhere and repeat views
 * cost one upstream read.
 *
 * Same-origin, relative, data: and blob: URLs are handed back untouched: the
 * proxy only earns its keep cross-origin. ipfs:// and ar:// resolve to a gateway
 * URL first, so a model pinned on decentralised storage proxies like any other.
 * Anything that is not a safe URL for an asset sink resolves to '' so callers
 * fall through to their own "no model" branch.
 *
 * @param {string} url  Model URL (https://, ipfs:// or ar:// accepted).
 * @returns {string}
 */
export function proxiedModelURL(url) {
	if (typeof url !== 'string' || !url) return '';
	const raw = /^\/\/[^/]/.test(url.trim()) ? 'https:' + url.trim() : url.trim();
	if (!isSafeImageURL(raw)) return '';
	if (!/^(https?|ipfs|ar):/i.test(raw)) return raw;
	if (raw.length > MAX_SOURCE_URL) return '';
	const resolved = resolveURI(raw);
	if (typeof location !== 'undefined' && resolved.startsWith(location.origin + '/')) return resolved;
	return `/api/glb?src=${encodeURIComponent(resolved)}`;
}

// Pull the CID (plus any path) back out of a URL that already names a gateway,
// so content whose gateway was baked in upstream can still be rotated. Matches
// the /ipfs/<cid>[/path] form every gateway in the list serves.
const GATEWAY_URL_RE = /^https?:\/\/[^/]+\/ipfs\/(.+)$/i;

/**
 * Every HTTPS URL that can serve one piece of decentralised content, in
 * preference order. An `ipfs://` URI expands to one URL per gateway; so does a
 * URL that already points at a gateway (its CID is re-extracted), which is what
 * makes content whose gateway was chosen upstream recoverable. Anything else
 * (a plain CDN URL, `ar://`) yields the single normalised URL, so callers can
 * loop over the result unconditionally.
 *
 * @param {string} uri
 * @returns {string[]}
 */
export function uriCandidates(uri) {
	if (!uri) return [];
	const ipfsMatch = String(uri).match(/^ipfs:\/\/(.+)$/i);
	const cid = ipfsMatch ? ipfsMatch[1] : (String(uri).match(GATEWAY_URL_RE) || [])[1];
	if (cid) {
		const first = resolveURI(uri, 0);
		const all = IPFS_GATEWAYS.map((gw) => gw + cid);
		// Keep whatever the caller (or an upstream resolver) already chose at the
		// head of the list: it is the one most likely to be warm in a CDN.
		return [first, ...all.filter((u) => u !== first)];
	}
	const single = resolveURI(uri, 0);
	return single ? [single] : [];
}

/**
 * Try to fetch from the primary gateway; on failure, cycle through fallbacks.
 *
 * @param {string} ipfsURI  An ipfs:// URI, or any URL uriCandidates understands.
 * @returns {Promise<Response>}
 */
export async function fetchWithFallback(ipfsURI) {
	let lastError;
	for (const url of uriCandidates(ipfsURI)) {
		try {
			// Bounded per gateway: a black-holing gateway used to block the whole
			// chain behind it, which made the fallback list decorative.
			const res = await fetch(url, { signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS) });
			if (res.ok) return res;
			lastError = new Error(`${url} responded ${res.status}`);
		} catch (err) {
			lastError = err;
		}
	}
	throw lastError || new Error('All IPFS gateways failed for ' + ipfsURI);
}