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
// Real glTF/GLB fetching and structural parsing, with no dependencies.
//
// Two jobs live here, and both are the paid tool's actual product:
// 1. fetchModel(): an SSRF-guarded, size-capped, timeout-bounded HTTPS fetch.
// 2. inspectModel(): parse the container (GLB binary or .gltf JSON) and report
// what is inside it, plus optimization findings a caller can act on.
//
// The parser reads the glTF JSON chunk only. That is enough for every structural
// count, keeps the memory profile flat on large models, and never executes or
// trusts model content.
import { lookup } from 'node:dns/promises';
import { isIP } from 'node:net';
const GLB_MAGIC = 0x46546c67; // "glTF" little-endian
const CHUNK_JSON = 0x4e4f534a; // "JSON"
const CHUNK_BIN = 0x004e4942; // "BIN\0"
export const MAX_BYTES = 32 * 1024 * 1024;
export const FETCH_TIMEOUT_MS = 20_000;
/** Errors this module throws carry a stable `code` so tools can map them to clean responses. */
export class ModelError extends Error {
constructor(code, message) {
super(message);
this.name = 'ModelError';
this.code = code;
}
}
function isPrivateAddress(address, family) {
if (family === 6) {
const a = address.toLowerCase();
if (a === '::1' || a === '::') return true;
if (a.startsWith('fc') || a.startsWith('fd')) return true; // unique local
if (a.startsWith('fe80')) return true; // link local
// IPv4-mapped IPv6, e.g. ::ffff:10.0.0.1
const mapped = a.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
if (mapped) return isPrivateAddress(mapped[1], 4);
return false;
}
const [a, b] = address.split('.').map(Number);
if (a === 10 || a === 127 || a === 0) return true;
if (a === 169 && b === 254) return true;
if (a === 172 && b >= 16 && b <= 31) return true;
if (a === 192 && b === 168) return true;
if (a === 100 && b >= 64 && b <= 127) return true; // carrier-grade NAT
return false;
}
/**
* Reject anything that is not a public HTTPS origin before a single byte moves.
* A paid endpoint that fetches arbitrary URLs is an internal-network probe unless
* it does exactly this.
*/
export async function assertPublicHttpsUrl(rawUrl) {
let url;
try {
url = new URL(rawUrl);
} catch {
throw new ModelError('invalid_url', `Not a valid URL: ${rawUrl}`);
}
if (url.protocol !== 'https:') {
throw new ModelError('insecure_url', 'Only https:// model URLs are accepted.');
}
const host = url.hostname.replace(/^\[|\]$/g, '');
const literalFamily = isIP(host);
if (literalFamily) {
if (isPrivateAddress(host, literalFamily)) {
throw new ModelError('blocked_host', 'That address is not publicly routable.');
}
return url;
}
const records = await lookup(host, { all: true, verbatim: true });
if (!records.length) throw new ModelError('dns_failed', `Could not resolve ${host}.`);
for (const record of records) {
if (isPrivateAddress(record.address, record.family)) {
throw new ModelError('blocked_host', `${host} resolves to a private address.`);
}
}
return url;
}
/** Fetch a model with a hard byte ceiling, so a hostile URL cannot exhaust memory. */
export async function fetchModel(rawUrl, { maxBytes = MAX_BYTES, timeoutMs = FETCH_TIMEOUT_MS } = {}) {
const url = await assertPublicHttpsUrl(rawUrl);
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetch(url, {
signal: controller.signal,
redirect: 'error',
headers: { accept: 'model/gltf-binary, model/gltf+json, application/octet-stream, */*' },
});
if (!res.ok) {
throw new ModelError('fetch_failed', `Model host answered ${res.status}.`);
}
const declared = Number(res.headers.get('content-length') || 0);
if (declared > maxBytes) {
throw new ModelError('too_large', `Model is ${declared} bytes; the ceiling is ${maxBytes}.`);
}
const buffer = Buffer.from(await res.arrayBuffer());
if (buffer.byteLength > maxBytes) {
throw new ModelError('too_large', `Model is ${buffer.byteLength} bytes; the ceiling is ${maxBytes}.`);
}
return buffer;
} catch (err) {
if (err instanceof ModelError) throw err;
if (err?.name === 'AbortError') {
throw new ModelError('timeout', `Model fetch exceeded ${timeoutMs}ms.`);
}
throw new ModelError('fetch_failed', err?.message || 'Model fetch failed.');
} finally {
clearTimeout(timer);
}
}
/** Pull the glTF JSON document out of a GLB container, or parse a .gltf directly. */
export function readGltfDocument(buffer) {
if (buffer.byteLength >= 12 && buffer.readUInt32LE(0) === GLB_MAGIC) {
const version = buffer.readUInt32LE(4);
if (version !== 2) {
throw new ModelError('unsupported_version', `GLB container version ${version} is not supported (expected 2).`);
}
let offset = 12;
let json = null;
let binBytes = 0;
while (offset + 8 <= buffer.byteLength) {
const chunkLength = buffer.readUInt32LE(offset);
const chunkType = buffer.readUInt32LE(offset + 4);
const start = offset + 8;
const end = start + chunkLength;
if (end > buffer.byteLength) {
throw new ModelError('corrupt', 'GLB chunk runs past the end of the file.');
}
if (chunkType === CHUNK_JSON) json = buffer.subarray(start, end).toString('utf8');
else if (chunkType === CHUNK_BIN) binBytes = chunkLength;
offset = end + ((4 - (chunkLength % 4)) % 4);
}
if (!json) throw new ModelError('corrupt', 'GLB container has no JSON chunk.');
return { document: parseJson(json), container: 'glb', binBytes };
}
return { document: parseJson(buffer.toString('utf8')), container: 'gltf', binBytes: 0 };
}
function parseJson(text) {
try {
return JSON.parse(text);
} catch {
throw new ModelError('corrupt', 'Model JSON could not be parsed.');
}
}
const count = (value) => (Array.isArray(value) ? value.length : 0);
/** Sum every primitive across every mesh: the number that actually predicts draw calls. */
function primitiveStats(document) {
let primitives = 0;
let indexed = 0;
let modes = new Set();
for (const mesh of document.meshes || []) {
for (const primitive of mesh.primitives || []) {
primitives += 1;
if (primitive.indices !== undefined) indexed += 1;
modes.add(primitive.mode ?? 4);
}
}
return { primitives, indexed, modes: [...modes].sort((a, b) => a - b) };
}
/** Vertex and triangle totals, read from accessor counts rather than estimated. */
function geometryStats(document) {
const accessors = document.accessors || [];
let vertices = 0;
let triangles = 0;
for (const mesh of document.meshes || []) {
for (const primitive of mesh.primitives || []) {
const position = primitive.attributes?.POSITION;
if (position !== undefined && accessors[position]) vertices += accessors[position].count || 0;
const mode = primitive.mode ?? 4;
if (mode !== 4) continue;
if (primitive.indices !== undefined && accessors[primitive.indices]) {
triangles += Math.floor((accessors[primitive.indices].count || 0) / 3);
} else if (position !== undefined && accessors[position]) {
triangles += Math.floor((accessors[position].count || 0) / 3);
}
}
}
return { vertices, triangles };
}
/** Textures that ship as raw pixels inside the container, the usual size culprit. */
function imageStats(document) {
let embedded = 0;
let external = 0;
let dataUri = 0;
for (const image of document.images || []) {
if (image.bufferView !== undefined) embedded += 1;
else if (typeof image.uri === 'string' && image.uri.startsWith('data:')) dataUri += 1;
else if (image.uri) external += 1;
}
return { embedded, external, dataUri };
}
function morphTargetCount(document) {
let targets = 0;
for (const mesh of document.meshes || []) {
for (const primitive of mesh.primitives || []) {
targets += count(primitive.targets);
}
}
return targets;
}
/**
* Turn the raw counts into findings worth paying for: each one names the problem,
* the evidence, and the fix.
*/
function findings(stats) {
const out = [];
if (stats.geometry.triangles > 250_000) {
out.push({
severity: 'high',
issue: 'Very high triangle count',
detail: `${stats.geometry.triangles.toLocaleString()} triangles will stall low-end GPUs and mobile browsers.`,
fix: 'Decimate the mesh or ship an LOD chain. Target 150k triangles or fewer for web delivery.',
});
}
if (stats.images.embedded + stats.images.dataUri > 0 && stats.sizeBytes > 12 * 1024 * 1024) {
out.push({
severity: 'high',
issue: 'Large file with embedded textures',
detail: `${(stats.sizeBytes / 1024 / 1024).toFixed(1)} MB with ${stats.images.embedded + stats.images.dataUri} embedded image(s).`,
fix: 'Compress textures to KTX2/Basis and enable Draco or Meshopt geometry compression.',
});
}
if (!stats.extensionsUsed.some((e) => e.includes('draco') || e.includes('meshopt') || e.includes('EXT_meshopt'))) {
out.push({
severity: stats.sizeBytes > 4 * 1024 * 1024 ? 'medium' : 'low',
issue: 'No geometry compression',
detail: 'The model declares neither KHR_draco_mesh_compression nor EXT_meshopt_compression.',
fix: 'Run gltf-transform with meshopt compression. Typical saving is 40 to 70 percent of the geometry payload.',
});
}
if (stats.primitives.primitives > 0 && stats.primitives.indexed < stats.primitives.primitives) {
out.push({
severity: 'medium',
issue: 'Unindexed primitives',
detail: `${stats.primitives.primitives - stats.primitives.indexed} of ${stats.primitives.primitives} primitives ship without an index buffer.`,
fix: 'Weld and index the geometry. Unindexed triangle soup wastes both bandwidth and vertex cache.',
});
}
if (stats.materials > 24) {
out.push({
severity: 'medium',
issue: 'High material count',
detail: `${stats.materials} materials means at least ${stats.materials} draw calls per frame.`,
fix: 'Atlas the textures and merge materials that differ only by base color.',
});
}
if (stats.animations === 0 && stats.skins > 0) {
out.push({
severity: 'low',
issue: 'Skinned mesh with no animation',
detail: 'The model carries a skeleton but ships no animation clips.',
fix: 'Retarget a clip onto the rig, or drop the skin if the model is meant to be static.',
});
}
if (!out.length) {
out.push({
severity: 'none',
issue: 'No structural problems found',
detail: 'Counts, compression, and indexing all look healthy for web delivery.',
fix: 'Ship it.',
});
}
return out;
}
/** The paid tool's whole product: a structural report plus actionable findings. */
export function inspectModel(buffer, { sourceUrl } = {}) {
const { document, container, binBytes } = readGltfDocument(buffer);
const stats = {
source: sourceUrl || null,
container,
sizeBytes: buffer.byteLength,
binaryChunkBytes: binBytes,
generator: document.asset?.generator || null,
gltfVersion: document.asset?.version || null,
scenes: count(document.scenes),
nodes: count(document.nodes),
meshes: count(document.meshes),
materials: count(document.materials),
textures: count(document.textures),
images: imageStats(document),
samplers: count(document.samplers),
animations: count(document.animations),
skins: count(document.skins),
cameras: count(document.cameras),
morphTargets: morphTargetCount(document),
primitives: primitiveStats(document),
geometry: geometryStats(document),
extensionsUsed: document.extensionsUsed || [],
extensionsRequired: document.extensionsRequired || [],
};
return { ...stats, findings: findings(stats) };
}