Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
import { createHash } from 'node:crypto';
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { unzipSync } from 'fflate';
export const ASSET_BASE = 'https://assets.kilnstudio.tools/';
export const hashBytes = (bytes) => createHash('sha256').update(bytes).digest('hex');
export function assetPath(path) {
if (typeof path !== 'string' || !path || path.startsWith('/') || path.includes('\\') || path.includes(':') || path.split('/').some((part) => part === '..' || part === '.')) {
throw new Error(`Unsafe asset path: ${path}`);
}
return path;
}
export function verifyBytes(bytes, record, name = record.path) {
const actual = hashBytes(bytes);
if (actual !== record.sha256.replace(/^sha256:/, '') || bytes.length !== record.bytes) {
throw new Error(`SHA-256/size verification failed for ${name}: expected ${record.sha256} / ${record.bytes} bytes, received ${actual} / ${bytes.length} bytes`);
}
return bytes;
}
export async function fetchPinnedFile(record, { mirror = process.env.KILN_ASSET_MIRROR, cache, base = ASSET_BASE } = {}) {
const path = assetPath(record.path);
if (!cache) throw new Error('A local cache directory is required');
const target = join(cache, path);
try {
verifyBytes(await readFile(target), record, path);
return target;
} catch (error) {
if (error.code !== 'ENOENT') throw error;
}
let bytes;
if (mirror) {
try { bytes = await readFile(join(mirror, path)); }
catch (error) { throw new Error(`Required mirror asset is unavailable: ${path}. Check KILN_ASSET_MIRROR or set KILN_SITE_PACKS=0 for the pre-upload build.`, { cause: error }); }
} else {
try {
const response = await fetch(new URL(path, base), { signal: AbortSignal.timeout(30_000) });
if (!response.ok) throw new Error(`HTTP ${response.status}`);
bytes = Buffer.from(await response.arrayBuffer());
} catch (error) {
throw new Error(`Required public asset is unavailable: ${new URL(path, base)}. Set KILN_ASSET_MIRROR to a verified local mirror, or KILN_SITE_PACKS=0 before the R2 upload.`, { cause: error });
}
}
verifyBytes(bytes, record, path);
await mkdir(dirname(target), { recursive: true });
await writeFile(target, bytes);
return target;
}
/**
* Which seal an archive carries, from where it sits in the mirror: a saved revision's editable archive (the
* bridge's under `standalone/`, each vehicle's in an `editable/` directory) is sealed by its own revision
* `manifest.json`; every pack archive is sealed by a `delivery.json` inventory.
*/
export const archiveProfile = (path) => (path.startsWith('standalone/') || path.split('/').includes('editable') ? 'editable' : 'delivery');
/** Only data pinned by the outer manifest is accepted; every inner file is sealed too. */
export function verifyArchive(bytes, profile = 'delivery') {
const files = unzipSync(bytes);
for (const path of Object.keys(files)) assetPath(path);
const deliveryEnvelope = profile === 'editable' && files['delivery.json']
&& JSON.parse(new TextDecoder().decode(files['delivery.json'])).profile === 'editable';
const manifestPath = profile === 'editable' && !deliveryEnvelope
? Object.keys(files).find((path) => path.endsWith('/manifest.json'))
: 'delivery.json';
if (!manifestPath || !files[manifestPath]) throw new Error(`Archive lacks ${profile === 'editable' ? 'revision manifest.json' : 'delivery.json'}`);
const manifest = JSON.parse(new TextDecoder().decode(files[manifestPath]));
if (!manifest.files || typeof manifest.files !== 'object') throw new Error('Archive manifest has no file seals');
const prefix = profile === 'editable' && !deliveryEnvelope ? manifestPath.slice(0, -'manifest.json'.length) : '';
const sealed = new Set([manifestPath]);
for (const [relativePath, record] of Object.entries(manifest.files)) {
const path = `${prefix}${assetPath(relativePath)}`;
if (!files[path]) throw new Error(`Sealed archive member is missing: ${path}`);
verifyBytes(files[path], record, path);
sealed.add(path);
}
// Kiln's import format keeps a revision's saved-material closure beside its manifest, outside its file seals. It
// belongs there exactly when the manifest uses saved materials, and must hold every material the manifest pins.
const materials = (manifest.build?.dependencies ?? []).filter((item) => item?.kind === 'kiln.material.v1' || item?.kind === 'kiln.material.v2');
if (profile === 'editable' && !deliveryEnvelope && materials.length && files[`${prefix}materials.kiln.json`]) {
const closure = JSON.parse(new TextDecoder().decode(files[`${prefix}materials.kiln.json`]));
const held = new Set((closure.records ?? []).map((item) => `${item.manifest?.materialId}/${item.manifest?.revisionId}`));
for (const { manifest: pin } of materials) if (!held.has(`${pin.materialId}/${pin.revisionId}`)) throw new Error(`Material closure lacks ${pin.materialId}`);
sealed.add(`${prefix}materials.kiln.json`);
}
for (const path of Object.keys(files)) {
if (!path.endsWith('/') && !sealed.has(path)) throw new Error(`Unsealed archive member: ${path}`);
}
return { files, manifest, prefix };
}