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
// GET /cdn/<key> — first-party CDN for R2 bucket objects (avatars, thumbnails,
// forge GLBs). Routed via vercel.json: `/cdn/(.*)` → `/api/cdn-object?key=$1`.
//
// Why this exists: the bucket's public `*.r2.dev` dev domain is rate-limited by
// Cloudflare and not meant for production traffic — gallery pages loading dozens
// of thumbnails got throttled mid-burst, surfacing as `failed to load img /
// model-viewer` client errors. Streaming through the authenticated S3 endpoint
// sidesteps that limit entirely, and Vercel's CDN absorbs repeat reads via
// `s-maxage`, so each object is fetched from R2 roughly once per region per day.
//
// Exposure parity: the bucket is already fully readable through the public
// r2.dev domain, so serving the same namespace here grants read access to
// nothing new. What it DOES change is the origin the bytes arrive on: r2.dev is
// a foreign origin, three.ws is where the session cookie and the wallet live.
// So every response here is pinned to "data, never a document": the type comes
// from the server-chosen extension rather than the stored header, anything not
// safe to render inline is sent as an attachment, and `sandbox` puts whatever
// does render into an opaque origin. See `isInlineSafe` below.
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
import { GetObjectCommand } from '@aws-sdk/client-s3';
import { cors, error, wrap } from './_lib/http.js';
import { r2, isStorageInfrastructureError, publicUrlOrNull } from './_lib/r2.js';
import { fetchUpstream } from './_lib/upstream-fetch.js';
import { env } from './_lib/env.js';
// A flat #e2e2e2 64x64 PNG, served in place of a 502 when the whole storage
// product is down (both the signed read and the public-domain fallback fail
// the same way, which a per-credential failover cannot route around).
const PLACEHOLDER_PNG = Buffer.from(
'iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAATElEQVR42u3PMQ0AAAwDoPqXWSWVsHsJOCB9LgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIClwEaOGJ3yOGdeQAAAABJRU5ErkJggg==',
'base64',
);
// Object keys are caller-controlled path input — keep them boring. UUID-based
// keys, slashes, dots-in-filenames only; no traversal, no control chars.
const KEY_RE = /^[\w!*'().@-]+(?:\/[\w!*'().@-]+)*(?:\.[\w-]+)?$/;
const MAX_KEY_LENGTH = 512;
const CONTENT_TYPES = {
png: 'image/png',
jpg: 'image/jpeg',
jpeg: 'image/jpeg',
webp: 'image/webp',
gif: 'image/gif',
svg: 'image/svg+xml',
glb: 'model/gltf-binary',
gltf: 'model/gltf+json',
usdz: 'model/vnd.usdz+zip',
bin: 'application/octet-stream',
json: 'application/json',
mp3: 'audio/mpeg',
wav: 'audio/wav',
mp4: 'video/mp4',
webm: 'video/webm',
};
// Types a browser may render inline from the app origin. SVG is deliberately
// absent: an SVG document executes script, and one served inline from three.ws
// would run with three.ws's cookies. It still renders through <img>/<image>,
// which ignore content-disposition and never run script.
const INLINE_SAFE = new Set([
'image/png',
'image/jpeg',
'image/webp',
'image/gif',
'image/avif',
'model/gltf-binary',
'model/gltf+json',
'model/vnd.usdz+zip',
'audio/mpeg',
'audio/wav',
'audio/ogg',
'video/mp4',
'video/webm',
'application/json',
'application/octet-stream',
]);
export function isInlineSafe(type) {
return INLINE_SAFE.has(String(type).split(';')[0].trim().toLowerCase());
}
export function contentTypeFor(key, stored) {
const ext = key.split('.').pop()?.toLowerCase();
const byExt = CONTENT_TYPES[ext];
// The extension wins over the stored header. Every write path picks the
// extension server-side from an allowlisted type, whereas a stored
// Content-Type can be copied verbatim from an upstream provider's response
// (copyToBucket in _lib/forge-store.js). Preferring the header, as this used
// to, let a remote `text/html` decide what three.ws serves.
if (byExt) return byExt;
if (stored && isInlineSafe(stored)) return stored;
return 'application/octet-stream';
}
function cacheControlFor(key) {
// Thumbnails are regenerated under the same key, so let browsers revalidate
// hourly. Content keys (u/…, forge outputs) embed random segments and are
// write-once in practice — cache long everywhere.
return key.startsWith('thumb/')
? 'public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800'
: 'public, max-age=86400, s-maxage=2592000, stale-while-revalidate=604800';
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,HEAD,OPTIONS', origins: '*' })) return;
if (req.method !== 'GET' && req.method !== 'HEAD') {
res.setHeader('allow', 'GET, HEAD, OPTIONS');
return error(res, 405, 'method_not_allowed', 'GET or HEAD only');
}
const raw = req.query?.key;
const key = typeof raw === 'string' ? raw : '';
if (!key || key.length > MAX_KEY_LENGTH || key.includes('..') || !KEY_RE.test(key)) {
return error(res, 400, 'invalid_key', 'malformed object key');
}
const ifNoneMatch = req.headers['if-none-match'];
const range = req.headers.range;
try {
const obj = await r2.send(
new GetObjectCommand({
Bucket: env.S3_BUCKET,
Key: key,
IfNoneMatch: ifNoneMatch,
Range: range,
}),
);
const type = contentTypeFor(key, obj.ContentType);
res.statusCode = range && obj.ContentRange ? 206 : 200;
res.setHeader('content-type', type);
// A bucket object is data. `sandbox` drops anything that does reach a
// top-level navigation into an opaque origin, so it can neither script
// against three.ws nor read its storage; CORP stays permissive because the
// CORS policy above is `*` and embeds depend on it.
res.setHeader('content-security-policy', "default-src 'none'; sandbox");
res.setHeader('cross-origin-resource-policy', 'cross-origin');
if (!isInlineSafe(type)) res.setHeader('content-disposition', 'attachment');
res.setHeader('cache-control', cacheControlFor(key));
res.setHeader('accept-ranges', 'bytes');
if (obj.ETag) res.setHeader('etag', obj.ETag);
if (obj.ContentLength != null) res.setHeader('content-length', String(obj.ContentLength));
if (obj.ContentRange) res.setHeader('content-range', obj.ContentRange);
if (req.method === 'HEAD') {
obj.Body?.destroy?.();
return res.end();
}
obj.Body.pipe(res);
obj.Body.on('error', (err) => {
console.error('[cdn-object] stream error:', key, err?.message);
try {
res.destroy(err);
} catch {}
});
} catch (err) {
const status = err?.$metadata?.httpStatusCode;
if (status === 304) {
res.statusCode = 304;
res.setHeader('cache-control', cacheControlFor(key));
if (ifNoneMatch) res.setHeader('etag', ifNoneMatch);
return res.end();
}
const code = err?.Code || err?.name;
if (code === 'NoSuchKey' || code === 'NotFound' || status === 404) {
return error(res, 404, 'not_found', 'object not found');
}
if (code === 'InvalidRange' || status === 416) {
return error(res, 416, 'invalid_range', 'requested range not satisfiable');
}
// The signed read itself is broken: the credentials are rejected, or the
// endpoint is unreachable, which says nothing about the object. The same
// bytes are readable, unauthenticated, on the bucket's public domain, so
// serve them from there instead of 502ing every avatar, thumbnail and GLB
// on the site. On 2026-09-07 a rejected R2 secret took the signed read
// down and this route answered `upstream_error` for every object it
// serves; the public domain was serving those same keys with a 200
// throughout.
//
// STREAM the bytes, never redirect to them. This rung shipped as a 302 and
// that quietly broke a second contract while fixing the first: r2.dev sends
// no access-control-allow-origin at all, and a browser re-runs the CORS
// check on a redirect's target, so the wildcard grant set at the top of
// this handler is discarded the moment the hop is followed. Measured on
// 2026-09-09 from a foreign origin, every /cdn read threw "Failed to fetch"
// while the same URL curled 200, which is how the model-viewer stages on
// /spatial-mcp went dark. Streaming keeps the response on three.ws, so the
// CORS and CORP headers, the server-chosen content type and the attachment
// rule below all survive the degraded path unchanged. api/avatars/[id]/
// [action].js takes the same route for the same reason.
//
// It also stops the failover defeating its own purpose: a redirect points
// every browser straight at the rate-limited public domain this route was
// built to dodge, whereas a proxied read is absorbed by our own edge cache.
// That cache stays short (60s) rather than no-store, so a burst of gallery
// thumbnails costs r2.dev one fetch instead of one per viewer, and traffic
// still returns to the signed path within a minute of the credential being
// healthy again.
const isInfraFault = isStorageInfrastructureError(err);
const fallback = isInfraFault ? publicUrlOrNull(key) : null;
if (fallback) {
console.error('[cdn-object] signed read failed, streaming public bucket domain:', key, err?.message);
try {
const upstream = await fetchUpstream(
fallback,
{ headers: range ? { range } : {} },
{
name: 'r2:public-object',
timeoutMs: 20_000,
attempts: 2,
// A 404 on the public domain is the object genuinely being
// absent, not an outage: the signed error never got far
// enough to say so. Let it through and answer 404, so a
// caller that treats a missing thumbnail as an empty state
// is not handed a 502 it will retry forever.
okWhen: (r) => r.ok || r.status === 404,
},
);
if (upstream.status === 404) {
upstream.body?.cancel?.();
return error(res, 404, 'not_found', 'object not found');
}
const type = contentTypeFor(key, upstream.headers.get('content-type'));
res.statusCode = upstream.status === 206 ? 206 : 200;
res.setHeader('content-type', type);
res.setHeader('content-security-policy', "default-src 'none'; sandbox");
res.setHeader('cross-origin-resource-policy', 'cross-origin');
if (!isInlineSafe(type)) res.setHeader('content-disposition', 'attachment');
res.setHeader('accept-ranges', 'bytes');
res.setHeader('cache-control', 'public, max-age=60, s-maxage=60');
const len = upstream.headers.get('content-length');
if (len) res.setHeader('content-length', len);
const contentRange = upstream.headers.get('content-range');
if (contentRange) res.setHeader('content-range', contentRange);
const etag = upstream.headers.get('etag');
if (etag) res.setHeader('etag', etag);
if (req.method === 'HEAD') {
upstream.body?.cancel?.();
return res.end();
}
await pipeline(Readable.fromWeb(upstream.body), res);
return;
} catch (fallbackErr) {
console.error('[cdn-object] public bucket domain failed too:', key, fallbackErr?.message);
if (res.headersSent) return res.destroy(fallbackErr);
// Nothing is on the wire yet, so the 502 below still gets to
// answer, but only once the object's own length and range come
// back off: error() refuses to touch a committed response and
// never clears headers, so a leftover content-length would pin the
// JSON body to the object's byte count and hang the client waiting
// for megabytes that are never coming.
res.removeHeader('content-length');
res.removeHeader('content-range');
res.removeHeader('etag');
}
}
console.error('[cdn-object] r2 fetch failed:', key, err?.message);
// Both lanes point at the same disabled storage product (an R2 account-wide
// outage, not a credential rejection the public domain can route around).
// An image key can at least avoid a broken-image icon; a model key cannot
// be stood in for by a flat PNG, so it still falls through to the 502.
if (isInfraFault && contentTypeFor(key, null).startsWith('image/')) {
res.removeHeader('content-length');
res.removeHeader('content-range');
res.removeHeader('etag');
res.statusCode = 200;
res.setHeader('content-type', 'image/png');
res.setHeader('cross-origin-resource-policy', 'cross-origin');
res.setHeader('cache-control', 'public, max-age=30, s-maxage=30');
if (req.method === 'HEAD') return res.end();
return res.end(PLACEHOLDER_PNG);
}
return error(res, 502, 'upstream_error', 'failed to fetch object');
}
});