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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Same-origin image proxy with IPFS multi-gateway fallback.
//
// Token art on /pump-visualizer (and any 3D surface that textures remote
// images) is loaded by Three.js with `crossOrigin = 'anonymous'`. The public
// IPFS gateways and metadata hosts these images live on (ipfs.io, arweave,
// per-launch CDNs) frequently answer browser requests with no
// `Access-Control-Allow-Origin` header, or get blocked by the browser's Opaque
// Response Blocking (ORB), so the texture fails and the console fills with CORS
// / ERR_BLOCKED_BY_ORB errors, one per token.
//
// Routing the image through this same-origin endpoint removes the cross-origin
// problem entirely: the browser only ever talks to three.ws. Server-side we:
// 1. Fetch the upstream image through the SSRF-hardened fetcher (scheme
// allowlist, our-side DNS + private-IP blocklist, connection pinning,
// per-redirect re-validation, byte cap, timeout). See api/_lib/ssrf.js.
// 2. If the source is an IPFS URL that fails, retry across alternate public
// gateways so one slow gateway never blanks the art.
// 3. If `?url=` turns out to address a token *metadata* document rather than an
// image (roughly half of pump.fun art is stored this way: feeds keep both
// kinds in a single `image_uri` column, indistinguishable without fetching),
// follow its `.image` field exactly one hop to the real artwork. Callers that
// already know they hold a metadata URI can say so explicitly with `?meta=`.
// 4. On total failure, serve a deterministic, on-brand SVG placeholder inline
// (200, permissive CORS) so the loader ALWAYS receives a valid image and
// never logs an error. The placeholder is generated here, same-origin, no
// external dependency that could itself be down, and is unique per seed:
// an abstract gradient "gem" that reads as token art rather than a generic
// "broken image" tile.
// 5. `?fallback=none` opts out of step 4 and answers 204 No Content instead.
// Token art wants the gem; a surface that already designs its own "no
// logo" state (the neutral disc on every DeFi table) does not, and would
// rather paint that disc than a gem that belongs to a different visual
// language. 204 rather than 404 because a withdrawn upstream icon is an
// ordinary outcome, not an error: the browser logs nothing for a 204, and
// the <img> still fires `error` with no bytes, so the caller's designed
// fallback runs exactly as it always did.
//
// Responses are immutable and CDN-cached: a given upstream URL yields the same
// bytes forever, so we cache hard at the edge and the proxy is hit once per art.
import { wrap, cors, method, error, rateLimited } from './_lib/http.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { fetchModel } from './_lib/fetch-model.js';
import { IPFS_GATEWAYS } from './_lib/ipfs-gateways.js';
// `?w=<px>` resizes a raster upstream to at most that width and re-encodes it
// as WebP. Gallery surfaces (the Forge showcase, the marketplace grid) paint
// full-resolution renders (a 1 MB PNG per card was normal on /forge) into
// 200-300 px boxes; served through here at the box's size they are ~20-40 KB.
// Widths snap to a fixed ladder so a gallery cannot mint an unbounded set of
// variants at the edge, and the result inherits the immutable cache below:
// the same upstream URL at the same width is the same bytes forever.
const RESIZE_WIDTHS = [64, 96, 128, 192, 256, 320, 480, 640, 960];
const RESIZE_MAX_INPUT_PIXELS = 64_000_000;
const RESIZE_WEBP_QUALITY = 82;
const RESIZABLE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/avif', 'image/tiff']);
function requestedWidth(raw) {
const n = Number.parseInt(raw ?? '', 10);
if (!Number.isFinite(n) || n <= 0) return 0;
return RESIZE_WIDTHS.find((w) => w >= n) ?? RESIZE_WIDTHS[RESIZE_WIDTHS.length - 1];
}
// Returns { bytes, contentType } for the delivered image: the resized WebP when
// the request asked for a width and the upstream is a raster we can decode, the
// untouched upstream bytes otherwise (SVG/GIF, an undecodable file, or a
// resizer failure all fall back to the original so the loader still gets a 200).
async function deliverable(image, width) {
const contentType = String(image.contentType || '').split(';')[0].trim().toLowerCase();
if (!width || !RESIZABLE_TYPES.has(contentType)) return { bytes: image.bytes, contentType: image.contentType };
try {
const sharp = (await import('sharp')).default;
const bytes = await sharp(Buffer.from(image.bytes), { limitInputPixels: RESIZE_MAX_INPUT_PIXELS })
.rotate()
.resize({ width, withoutEnlargement: true })
.webp({ quality: RESIZE_WEBP_QUALITY })
.toBuffer();
return { bytes, contentType: 'image/webp' };
} catch {
return { bytes: image.bytes, contentType: image.contentType };
}
}
const MAX_BYTES = 8 * 1024 * 1024; // 8 MB: generous for token art, bounded for abuse
// Per-gateway attempt cap. Each candidate fetch (DNS + connect + body) is bounded
// by this via the SSRF fetcher's own AbortController. Because the candidates are
// raced CONCURRENTLY (below), the whole resolution finishes in roughly one
// attempt's time, not the sum, so one stalled gateway never stacks toward the
// function's 30s kill, which is what produced the mass-504 storm.
const TIMEOUT_MS = 9_000;
// Token launch metadata (pump.fun et al.) is a small JSON doc whose `image`
// field is the real art. Resolving it server-side lets the browser load token
// images same-origin without the per-host CORS failures that a client-side
// `fetch(metadataUri)` hits. Kept short: the JSON is tiny.
const META_TIMEOUT_MS = 5_000;
// Overall budget for ALL upstream work combined: metadata resolution AND every
// gateway attempt. The function's Vercel maxDuration is 30s; trying 4 IPFS
// gateways at 10s each can reach 40s, and a slow metadata fetch (5s) layered on
// top of a 24s gateway budget reaches 29s + teardown and gets the invocation
// killed BEFORE the placeholder redirect below ever runs, defeating the
// "always hand back a valid 200" contract. A single deadline anchored at handler
// start, capped well under 30s, keeps meta + gateways + the placeholder response
// inside the hard kill no matter how the time is split between the two phases.
const TOTAL_BUDGET_MS = 25_000;
// Headroom reserved below the deadline so there is always time to compose and
// flush the placeholder SVG (or the real image) after the last upstream attempt.
const RESPONSE_HEADROOM_MS = 1_000;
// Pull the `<cid>/<path?>` portion out of any recognised IPFS URL form so we can
// re-point it at a different gateway. Returns null for non-IPFS URLs.
function ipfsPath(rawUrl) {
if (rawUrl.startsWith('ipfs://')) return rawUrl.slice('ipfs://'.length).replace(/^ipfs\//, '');
const m = rawUrl.match(/\/ipfs\/(.+)$/);
return m ? m[1] : null;
}
// Build the ordered list of candidate URLs to try for one logical image. The
// gateways are the shared server-side list (api/_lib/ipfs-gateways.js), so a
// gateway that stops serving is dropped in one place; api/_lib/ipfs-pin.js
// records why each retired host is absent.
function candidates(rawUrl) {
const path = ipfsPath(rawUrl);
if (path) return IPFS_GATEWAYS.map((g) => g + path);
// Non-IPFS: a single source (already an https CDN / arweave / data: link).
return [rawUrl.startsWith('ipfs://') ? IPFS_GATEWAYS[0] + rawUrl.slice(7) : rawUrl];
}
// Race every candidate gateway concurrently and resolve with the FIRST one that
// returns a usable payload. Resolves to null when all candidates fail, OR when the
// shared `budgetMs` elapses, whichever comes first, so a stalled gateway can
// never pin the invocation toward the 30s wall. The losing fetches are each
// independently time-boxed by `perAttemptMs` (the SSRF fetcher aborts them), so
// they cannot outlive the request in any meaningful way. This concurrency is the
// fix for the sequential ipfs.io stall storm: total wall time is now ~one attempt,
// not the sum of all four.
//
// A "usable payload" is an image, OR, when `acceptJson` is set, a JSON document.
// Roughly half the token art on pump.fun surfaces is addressed by its *metadata*
// URI rather than its image URI: the CID resolves to a small JSON doc whose
// `image` field holds the real art. Callers hand us that URI in `?url=` because
// upstream feeds store both kinds in one `image_uri` column and the two are
// indistinguishable without fetching. Detecting the JSON here, instead of
// discarding it as "valid response but not an image", lets one `?url=` call
// resolve either form. Returns { kind: 'image' | 'json', ... }.
function raceCandidates(urls, perAttemptMs, budgetMs, acceptJson) {
if (!urls.length || budgetMs < 250) return Promise.resolve(null);
return new Promise((resolve) => {
let settled = false;
let pending = urls.length;
const finish = (payload) => {
if (settled) return;
settled = true;
clearTimeout(timer);
resolve(payload);
};
const timer = setTimeout(() => finish(null), budgetMs);
for (const url of urls) {
fetchModel(url, { maxBytes: MAX_BYTES, timeoutMs: Math.min(perAttemptMs, budgetMs) })
.then((result) => {
const ct = result?.contentType || '';
if (ct.startsWith('image/')) return finish({ kind: 'image', ...result });
if (acceptJson && ct.includes('json')) {
// Metadata doc. Parse here: we already hold the bytes, so following
// it costs no extra gateway round-trip for the document itself.
try {
const data = JSON.parse(new TextDecoder().decode(result.bytes));
return finish({ kind: 'json', data });
} catch {
/* malformed: fall through and let the other candidates settle */
}
}
if (--pending === 0) finish(null); // valid response, but nothing we can use
})
.catch(() => {
// SSRF refusal, timeout, gateway 5xx: this candidate is out. Only
// give up once every candidate has settled.
if (--pending === 0) finish(null);
});
}
});
}
// Deterministic, dependency-free placeholder art. The same seed always renders
// the same image, so a given token's fallback is stable across loads and the
// edge cache stays warm. Derives a two-tone palette + accent from a hash of the
// seed and composes a soft gradient backdrop, a faceted "gem" glyph, and a
// monogram, on-brand for three.ws and clearly intentional, not a 404 tile.
function hashSeed(str) {
let h = 2166136261 >>> 0; // FNV-1a
for (let i = 0; i < str.length; i++) {
h ^= str.charCodeAt(i);
h = Math.imul(h, 16777619);
}
return h >>> 0;
}
function monogram(seed) {
const m = String(seed).match(/[A-Za-z0-9]/);
return (m ? m[0] : '◆').toUpperCase();
}
function placeholderSvg(seed) {
const s = String(seed || 'token');
const h = hashSeed(s);
const hue = h % 360; // primary hue
const hue2 = (hue + 38 + ((h >> 9) % 50)) % 360; // analogous accent
const rot = (h >> 3) % 360; // gem rotation for per-seed variety
const ch = monogram(s);
// Two deep, saturated stops keep contrast high enough for a white monogram.
const c1 = `hsl(${hue} 64% 16%)`;
const c2 = `hsl(${hue2} 58% 9%)`;
const glow = `hsl(${hue} 80% 60%)`;
const accent = `hsl(${hue2} 85% 66%)`;
return `<svg xmlns="http://www.w3.org/2000/svg" width="400" height="400" viewBox="0 0 400 400" role="img" aria-label="placeholder artwork">
<defs>
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="${c1}"/>
<stop offset="1" stop-color="${c2}"/>
</linearGradient>
<radialGradient id="glow" cx="0.5" cy="0.42" r="0.65">
<stop offset="0" stop-color="${glow}" stop-opacity="0.45"/>
<stop offset="1" stop-color="${glow}" stop-opacity="0"/>
</radialGradient>
<linearGradient id="facet" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="${accent}" stop-opacity="0.95"/>
<stop offset="1" stop-color="${glow}" stop-opacity="0.55"/>
</linearGradient>
</defs>
<rect width="400" height="400" fill="url(#bg)"/>
<rect width="400" height="400" fill="url(#glow)"/>
<g transform="rotate(${rot} 200 188)" opacity="0.9">
<polygon points="200,96 268,150 242,236 158,236 132,150" fill="url(#facet)"/>
<polygon points="200,96 268,150 200,188" fill="#ffffff" fill-opacity="0.16"/>
<polygon points="200,96 132,150 200,188" fill="#000000" fill-opacity="0.12"/>
<polygon points="200,188 242,236 158,236" fill="#000000" fill-opacity="0.18"/>
<polyline points="132,150 200,188 268,150" fill="none" stroke="#ffffff" stroke-opacity="0.25" stroke-width="1.5"/>
</g>
<text x="200" y="188" text-anchor="middle" dominant-baseline="central"
font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="84" font-weight="700"
fill="#ffffff" fill-opacity="0.92" style="paint-order:stroke">${ch}</text>
<text x="200" y="312" text-anchor="middle"
font-family="'Inter','Segoe UI',system-ui,sans-serif" font-size="15" font-weight="600"
letter-spacing="3" fill="#ffffff" fill-opacity="0.42">THREE.WS</text>
</svg>`;
}
// Pull the artwork URL out of a token metadata document. The metadata is
// creator-controlled, so we accept only a non-empty string and reject data: URLs.
// We never serve attacker-supplied inline content from our own origin. The URL
// itself is still validated by the SSRF fetcher before anything is requested.
// Returns null on anything unusable, so callers fall through to the placeholder.
function imageFromMetaDoc(data) {
if (!data || typeof data !== 'object') return null;
const candidate = data.image || data.image_url || data.imageUrl || data.imageUri || null;
if (typeof candidate !== 'string') return null;
const trimmed = candidate.trim();
if (!trimmed || /^data:/i.test(trimmed)) return null;
return trimmed;
}
// Resolve a token's artwork URL from its metadata JSON document. Backs the
// explicit `?meta=` parameter; the `?url=` path reaches the same place via
// raceCandidates()'s JSON detection. The document is raced across every
// gateway exactly like art is, because a metadata URI pinned to one gateway
// host (pump.fun hands out ipfs.io) dies with that host otherwise.
async function resolveImageFromMeta(metaUri, budgetMs) {
const doc = await raceCandidates(candidates(metaUri), META_TIMEOUT_MS, budgetMs, true);
return doc?.kind === 'json' ? imageFromMetaDoc(doc.data) : null;
}
// Whatever this endpoint returns is a remote party's bytes served from the
// three.ws origin. Token art is routinely SVG, and an SVG opened as a top-level
// document runs its own <script> under this origin, so `?url=` pointed at a
// hostile SVG was script execution on three.ws. As an <img> or a texture the
// bytes render exactly as before; opened directly, `sandbox` puts the document
// in an opaque origin with scripts disabled.
const PROXIED_CSP = "default-src 'none'; img-src data:; style-src 'unsafe-inline'; sandbox";
export default wrap(async function handler(req, res) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: false })) return;
if (!method(req, res, ['GET'])) return;
res.setHeader('content-security-policy', PROXIED_CSP);
const ip = clientIp(req);
const rl = await limits.imgProxyIp(ip);
if (!rl.success) return rateLimited(res, rl, 'too many image requests');
const url = new URL(req.url, 'http://x');
const directUrl = url.searchParams.get('url');
const metaUri = url.searchParams.get('meta');
const seed = url.searchParams.get('seed') || directUrl || metaUri || '';
const width = requestedWidth(url.searchParams.get('w'));
// Callers that paint their own "no image" state ask for 204 instead of the
// placeholder art; anything else (including an absent param) keeps the gem.
const placeholderOff = url.searchParams.get('fallback') === 'none';
// Accept one of: ?url=<image>, ?meta=<metadata-json>, or ?seed=<x> (placeholder
// only). Callers streaming launch feeds pass `meta` so the real artwork is
// resolved server-side; a missing image still yields the branded placeholder.
if (!directUrl && !metaUri && !seed) {
return error(res, 400, 'missing_url', 'one of url, meta, or seed is required');
}
// data: URIs are not proxyable targets: redirecting to attacker-supplied
// data: content is an open-redirect/content-injection vector. Reject.
if (directUrl && /^data:/i.test(directUrl.trim())) {
return error(
res,
400,
'invalid_url',
'data: URIs cannot be proxied. Pass an http(s) or ipfs URL',
);
}
// One hard deadline for ALL upstream work: metadata resolution and every
// gateway attempt draw from the same budget so their combined spend can never
// exceed it and trip the function's 30s kill before we serve the placeholder.
const deadline = Date.now() + TOTAL_BUDGET_MS - RESPONSE_HEADROOM_MS;
// Resolve the artwork URL: an explicit ?url wins; otherwise read it from the
// token metadata document server-side. A null result simply falls through to
// the placeholder below: the loader always receives a valid image. The meta
// fetch is capped at whatever is left of the shared budget (never more than
// META_TIMEOUT_MS) so a hung metadata host can't consume the gateway budget.
let target = directUrl;
if (!target && metaUri) {
const metaBudget = Math.min(META_TIMEOUT_MS, deadline - Date.now());
if (metaBudget > 250) target = await resolveImageFromMeta(metaUri, metaBudget);
}
// Race all candidate gateways concurrently inside whatever is left of the shared
// budget. The first valid image wins; if every gateway fails (or the budget
// runs out) we fall through to the placeholder below, always within the 30s wall.
//
// A `?url=` that turns out to address a metadata document (not art) is followed
// exactly one hop to the image it names. `acceptJson` is off on that second race
// so a doc pointing at another doc terminates instead of chaining. When `?meta=`
// was used the document is already resolved above, so JSON is not expected there.
let payload = await raceCandidates(
target ? candidates(target) : [],
TIMEOUT_MS,
deadline - Date.now(),
Boolean(directUrl),
);
if (payload?.kind === 'json') {
const nested = imageFromMetaDoc(payload.data);
payload = nested
? await raceCandidates(candidates(nested), TIMEOUT_MS, deadline - Date.now(), false)
: null;
}
const image = payload?.kind === 'image' ? payload : null;
if (!image) {
// Every source failed. Hand back a valid, CORS-clean placeholder inline so
// the texture/image loader resolves with a 200 instead of logging an error.
// Served same-origin (no external dependency to fail) and cached, but for a
// shorter window than real art so a transiently-down source can recover.
if (placeholderOff) {
// `?fallback=none`: the caller draws its own empty state, so send no
// body at all. Cached on the same short window as the placeholder, for
// the same reason: a source that comes back should be picked up soon.
res.statusCode = 204;
res.setHeader('access-control-allow-origin', '*');
res.setHeader('cache-control', 'public, max-age=300, s-maxage=3600');
res.end();
return;
}
res.statusCode = 200;
res.setHeader('content-type', 'image/svg+xml; charset=utf-8');
res.setHeader('access-control-allow-origin', '*');
res.setHeader('cache-control', 'public, max-age=300, s-maxage=3600');
res.end(placeholderSvg(seed));
return;
}
const out = await deliverable(image, width);
res.statusCode = 200;
res.setHeader('content-type', out.contentType);
res.setHeader('access-control-allow-origin', '*');
// Immutable: a given upstream URL is content-addressed (IPFS) or a fixed CDN
// asset, so the bytes never change. Cache hard at the browser and the edge.
res.setHeader('cache-control', 'public, max-age=86400, s-maxage=604800, immutable');
res.end(Buffer.from(out.bytes));
});