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.

6.1 KB
Raw Blame
// @ts-check
// GET /api/cron/garment-catalog-audit — daily integrity sweep of the public
// wardrobe catalog.
//
// The catalog (gs://three-ws-garments/garments/catalog.json) is living
// production data fed by the garment forge and consumed by every closet
// client. It can rot silently: an object deleted or overwritten, a bucket
// policy change breaking anonymous reads, a truncated upload. This cron
// verifies, for every entry:
//
//   1. structural validity (spec/slot/region/license/hash-shape — the same
//      contract src/garment-catalog.js enforces client-side),
//   2. the GLB and thumbnail are anonymously reachable (HEAD),
//   3. the GLB bytes still hash to model.sha256 (full check on a rotating
//      subset per run, so a 100-entry catalog stays inside cron budget while
//      every entry gets re-hashed within a few days).
//
// Failures are logged through reportServerError, which the production triage
// sweep (npm run triage:gcp) already classifies — no new alert channel.
// The heavyweight geometric audit (bind + walk-gait deviation) stays in
// `npm run audit:garments`, run on demand after seeding or placement changes.

import { error, json, method, reportServerError, wrapCron } from '../_lib/http.js';
import { requireCron } from '../_lib/cron-auth.js';

const CATALOG_URL = 'https://storage.googleapis.com/three-ws-garments/garments/catalog.json';
const SPEC_URI = 'https://three.ws/specs/garment-manifest-v1';
// This sweep makes one request per catalog entry (a reachability HEAD) plus a
// full GLB download for each entry in the rotating re-hash subset, so an
// unbounded stall on any single object would hold the whole audit open to Cloud
// Run's 900s request timeout, well past Cloud Scheduler's 320s attempt deadline.
// A HEAD against GCS is a metadata round trip; a GLB download moves real bytes,
// so it gets the longer ceiling.
const HEAD_TIMEOUT_MS = 15_000;
const CATALOG_TIMEOUT_MS = 20_000;
const DOWNLOAD_TIMEOUT_MS = 60_000;
const SLOTS = new Set([
	'top', 'bottom', 'footwear', 'outerwear', 'hair', 'headwear', 'glasses', 'accessory',
]);
const REGIONS = new Set([
	'torso', 'upperArms', 'lowerArms', 'hands',
	'hips', 'upperLegs', 'lowerLegs', 'feet', 'neck', 'scalp',
]);
const LICENSES = new Set([
	'CC0-1.0', 'CC-BY-4.0', 'MIT', 'Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause',
]);
const SHA256_RE = /^[0-9a-f]{64}$/;
// Full-hash this many entries per run, rotating by day-of-year so the whole
// catalog is re-verified every few days without ever fetching every GLB.
const HASH_SAMPLE = 5;

function structuralErrors(m) {
	const errs = [];
	if (m?.spec !== SPEC_URI) errs.push('unknown spec');
	if (!SLOTS.has(m?.slot)) errs.push(`unknown slot "${m?.slot}"`);
	if (!Array.isArray(m?.occludes) || m.occludes.some((r) => !REGIONS.has(r))) {
		errs.push('bad occludes');
	}
	if (!LICENSES.has(m?.license)) errs.push(`license "${m?.license}"`);
	if (!SHA256_RE.test(m?.model?.sha256 || '')) errs.push('malformed sha256');
	if (!/^https:\/\//.test(m?.model?.uri || '')) errs.push('non-https model.uri');
	return errs;
}

async function head(url) {
	const res = await fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(HEAD_TIMEOUT_MS) }).catch(() => null);
	return res?.ok ? null : `HEAD ${url} -> ${res ? res.status : 'unreachable'}`;
}

async function sha256Of(url) {
	const res = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) }).catch(() => null);
	if (!res?.ok) return null;
	// The timeout covers the body stream too, so a download that stalls partway
	// rejects here rather than at the fetch. Fall back to the same null this
	// function already returns for an unreachable object: "not hashed this run",
	// which the caller skips. A slow object must not be reported as sha256 drift,
	// and must not fail the audit for the entries that did verify.
	const buf = await res.arrayBuffer().catch(() => null);
	if (!buf) return null;
	const digest = await crypto.subtle.digest('SHA-256', buf);
	return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
}

export default wrapCron(async (req, res) => {
	if (!method(req, res, ['GET'])) return;
	if (!requireCron(req, res)) return;

	const catRes = await fetch(CATALOG_URL, { signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS) }).catch(() => null);
	if (!catRes?.ok) {
		reportServerError(new Error(`garment catalog unreachable (${catRes?.status ?? 'network'})`), {
			code: 'garment_catalog_unreachable',
			context: { url: CATALOG_URL },
		});
		return error(res, 502, 'catalog_unreachable', `catalog fetch ${catRes?.status ?? 'failed'}`);
	}
	const catalog = await catRes.json().catch(() => null);
	if (!Array.isArray(catalog)) {
		reportServerError(new Error('garment catalog is not a JSON array'), {
			code: 'garment_catalog_malformed',
		});
		return error(res, 502, 'catalog_malformed', 'catalog is not a JSON array');
	}

	const failures = [];
	for (const m of catalog) {
		const label = `${m?.slot}/${m?.id}`;
		const errs = structuralErrors(m);
		if (errs.length) {
			failures.push({ id: label, errors: errs });
			continue;
		}
		const reach = (await Promise.all([
			head(m.model.uri),
			m.preview?.thumbnail ? head(m.preview.thumbnail) : null,
		])).filter(Boolean);
		if (reach.length) failures.push({ id: label, errors: reach });
	}

	// Rotating full-hash sample: day-of-year picks the window.
	const day = Math.floor(Date.now() / 86_400_000);
	const clean = catalog.filter((m) => !failures.some((f) => f.id === `${m?.slot}/${m?.id}`));
	const hashed = [];
	for (let i = 0; i < Math.min(HASH_SAMPLE, clean.length); i++) {
		const m = clean[(day * HASH_SAMPLE + i) % clean.length];
		const sha = await sha256Of(m.model.uri);
		hashed.push(`${m.slot}/${m.id}`);
		if (sha && sha !== m.model.sha256) {
			failures.push({ id: `${m.slot}/${m.id}`, errors: ['sha256 drift: stored bytes no longer match the manifest'] });
		}
	}

	for (const f of failures) {
		reportServerError(new Error(`garment catalog entry broken: ${f.id}: ${f.errors.join('; ')}`), {
			code: 'garment_catalog_entry_broken',
			context: f,
		});
	}

	return json(res, 200, {
		ok: failures.length === 0,
		entries: catalog.length,
		hashed,
		failures,
	});
});