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.

15.8 KB
Raw Blame
// Shared vocabulary for guard proofs: the sandbox, the fixture applier, and the
// verdict model. scripts/prove-guards.mjs drives it, scripts/audit-guards.mjs
// validates the declarations against it, and tests/audit-guards.test.js
// exercises it against a synthetic registry without touching the real
// repository.
//
// A "proof" answers a question the guard registry could not: does this guard
// still catch the thing it claims to catch? A registry entry is a claim. A
// proof is evidence. The difference matters because a guard can rot into a
// no-op (a renamed directory it no longer scans, a regex that stopped matching,
// an exclusion list that grew until it excluded everything) and still exit 0
// forever, which reads exactly like success.
//
// Every proof is TWO-SIDED, and that is the whole point:
//
//   control    the sandbox is arranged so the guard MUST pass (exit 0)
//   violation  one surgical mutation is applied and the guard MUST fail,
//              with a failure message that names the right reason
//
// A one-sided proof is worthless. "The guard exited non-zero" also happens when
// the sandbox is broken, when a dependency is missing, or when an unrelated
// pre-existing violation is sitting in the tree. Requiring exit 0 first pins
// the guard to a known-clean baseline, so the non-zero exit afterwards is
// attributable to the mutation and nothing else. Requiring the output to
// contain an expected fragment closes the last hole: a guard that fails for the
// wrong reason is not a working guard.

import { spawnSync } from 'node:child_process';
import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import path from 'node:path';

/** Verdicts a proof run can produce, worst first. Order is the report order. */
export const VERDICTS = {
	CONTROL_FAILED: 'control-failed',
	NOT_CAUGHT: 'not-caught',
	WRONG_REASON: 'wrong-reason',
	PROVEN: 'proven',
	DECLARED_LIVE: 'declared-live',
};

/** Verdicts that mean the guard is not demonstrably working. */
export const FAILING_VERDICTS = new Set([
	VERDICTS.CONTROL_FAILED,
	VERDICTS.NOT_CAUGHT,
	VERDICTS.WRONG_REASON,
]);

/**
 * Normalize a declared proof into the shape the runner executes.
 * Throws on a malformed declaration so the auditor can report it precisely.
 */
export function normalizeProof(guard) {
	const proof = guard.proof;
	if (!proof || typeof proof !== 'object') {
		throw new Error(`guard "${guard.id}" has no proof block`);
	}
	if (proof.kind === 'live') {
		if (!proof.reason || typeof proof.reason !== 'string') {
			throw new Error(`guard "${guard.id}" declares kind:"live" without a reason`);
		}
		return { kind: 'live', reason: proof.reason };
	}
	if (!proof.summary || typeof proof.summary !== 'string') {
		throw new Error(`guard "${guard.id}" proof needs a summary`);
	}
	const violation = proof.violation;
	if (!violation || typeof violation !== 'object') {
		throw new Error(`guard "${guard.id}" proof needs a violation block`);
	}
	const writes = violation.write ?? {};
	const appends = violation.append ?? {};
	const deletes = violation.delete ?? [];
	const links = violation.link ?? {};
	const jsonOps = violation.json ?? [];
	if (!Array.isArray(deletes)) {
		throw new Error(`guard "${guard.id}" violation.delete must be an array`);
	}
	if (!Array.isArray(jsonOps)) {
		throw new Error(`guard "${guard.id}" violation.json must be an array`);
	}
	const mutations =
		Object.keys(writes).length +
		Object.keys(appends).length +
		Object.keys(links).length +
		deletes.length +
		jsonOps.length;
	if (!mutations) throw new Error(`guard "${guard.id}" violation mutates nothing`);
	for (const op of jsonOps) {
		if (!op || typeof op.file !== 'string' || typeof op.pointer !== 'string') {
			throw new Error(`guard "${guard.id}" json op needs file + pointer`);
		}
		const kinds = ['insert', 'set', 'removeWhere'].filter((k) => k in op);
		if (kinds.length !== 1) {
			throw new Error(`guard "${guard.id}" json op needs exactly one of insert/set/removeWhere`);
		}
		// Pointers are dot paths (`results.0.tag`), not RFC 6901 slash pointers.
		// A slash pointer does not fail: `set` splits it on `.`, finds one segment,
		// and writes a junk top-level key named `/results/0/tag` that the guard
		// never reads. The proof then reports NOT CAUGHT and reads as a rotted
		// guard rather than as a typo in its own declaration.
		if (op.pointer.includes('/')) {
			throw new Error(
				`guard "${guard.id}" json op pointer "${op.pointer}" is a slash path; ` +
					`pointers are dot paths, so write "${op.pointer.replace(/^\/+/, '').replace(/\//g, '.')}"`,
			);
		}
	}
	if (!proof.expect || typeof proof.expect !== 'string') {
		throw new Error(`guard "${guard.id}" proof needs an expect fragment`);
	}
	return {
		kind: 'mutation',
		summary: proof.summary,
		setup: proof.setup ?? {},
		stage: proof.stage === true,
		violation: { write: writes, append: appends, delete: deletes, link: links, json: jsonOps },
		expect: proof.expect,
	};
}

/** Every sandbox path a proof reads or writes, for snapshot and restore. */
export function touchedPaths(proof) {
	if (proof.kind === 'live') return [];
	return [
		...Object.keys(proof.setup),
		...Object.keys(proof.violation.write),
		...Object.keys(proof.violation.append),
		...Object.keys(proof.violation.link),
		...proof.violation.json.map((op) => op.file),
		...proof.violation.delete,
	];
}

/** Capture the current bytes of each path (null when absent). */
export function snapshot(root, paths) {
	const saved = new Map();
	for (const rel of paths) {
		if (saved.has(rel)) continue;
		const abs = path.join(root, rel);
		// lstat, not existsSync: a proof may replace a path with a symlink, and
		// following it would snapshot the target's bytes and then restore them
		// over the link's location.
		let stat = null;
		try {
			stat = lstatSync(abs);
		} catch {
			stat = null;
		}
		saved.set(rel, stat?.isFile() ? readFileSync(abs) : null);
	}
	return saved;
}

/** Put every captured path back exactly as it was. */
export function restore(root, saved) {
	for (const [rel, bytes] of saved) {
		const abs = path.join(root, rel);
		if (bytes === null) {
			rmSync(abs, { force: true });
		} else {
			mkdirSync(path.dirname(abs), { recursive: true });
			writeFileSync(abs, bytes);
		}
	}
}

/**
 * Render a fixture body.
 *
 * Two escapes exist because the alternative is a fixture that rots:
 *   {{pkg.version}}  the repo's current version. check-dist compares
 *                    dist/agent-3d/versions.json against package.json, so a
 *                    hardcoded version would make the proof fail on the next
 *                    release rather than when the guard breaks.
 *   { fill: n }      n bytes of filler. Two guards assert a minimum artifact
 *                    size, and a megabyte of literal text does not belong in a
 *                    registry a human reads.
 */
export function renderFixture(body, context = {}) {
	if (body && typeof body === 'object' && Number.isInteger(body.fill)) {
		return Buffer.alloc(body.fill, body.byte ?? 'x');
	}
	return String(body).replace(/\{\{pkg\.version\}\}/g, context.pkgVersion ?? '0.0.0');
}

/** Write a file, creating parent directories. */
export function writeInto(root, rel, contents, context) {
	const abs = path.join(root, rel);
	mkdirSync(path.dirname(abs), { recursive: true });
	writeFileSync(abs, renderFixture(contents, context));
}

/** Apply a set of files verbatim. */
export function applyFiles(root, files, context) {
	for (const [rel, contents] of Object.entries(files)) writeInto(root, rel, contents, context);
}

/**
 * Resolve a dot-path pointer inside a parsed JSON document.
 * `routes`, `sections.2.pages` — numeric segments index arrays.
 */
export function resolvePointer(doc, pointer) {
	let node = doc;
	for (const segment of pointer.split('.').filter(Boolean)) {
		if (node == null) return undefined;
		node = node[/^\d+$/.test(segment) ? Number(segment) : segment];
	}
	return node;
}

/** Shallow "every listed key matches" predicate, for removeWhere. */
function matchesWhere(candidate, where) {
	if (!candidate || typeof candidate !== 'object') return false;
	return Object.entries(where).every(([k, v]) => candidate[k] === v);
}

/**
 * Edit a JSON file in place.
 *
 * Some guards can only be violated by changing a large committed registry
 * (vercel.json, a golden fixture, a server manifest). Pasting the whole file
 * into a fixture would make the proof unreadable and would rot the moment the
 * real file changed, so proofs describe the edit instead of the result.
 */
export function applyJsonOp(root, op) {
	const abs = path.join(root, op.file);
	const doc = JSON.parse(readFileSync(abs, 'utf8'));
	if ('set' in op) {
		const segments = op.pointer.split('.').filter(Boolean);
		const leaf = segments.pop();
		const parent = segments.length ? resolvePointer(doc, segments.join('.')) : doc;
		if (parent == null) throw new Error(`json op: ${op.file} has no ${op.pointer}`);
		parent[/^\d+$/.test(leaf) ? Number(leaf) : leaf] = op.set;
	} else {
		const target = resolvePointer(doc, op.pointer);
		if (!Array.isArray(target)) throw new Error(`json op: ${op.file}#${op.pointer} is not an array`);
		if ('insert' in op) {
			target.splice(Number.isInteger(op.at) ? op.at : 0, 0, op.insert);
		} else {
			const index = target.findIndex((entry) => matchesWhere(entry, op.removeWhere));
			if (index === -1) throw new Error(`json op: nothing in ${op.file}#${op.pointer} matches ${JSON.stringify(op.removeWhere)}`);
			target.splice(index, 1);
		}
	}
	writeFileSync(abs, `${JSON.stringify(doc, null, '\t')}\n`);
}

/** Apply the violation: writes, appends, JSON edits, symlinks, then deletes. */
export function applyViolation(root, violation, context) {
	applyFiles(root, violation.write, context);
	for (const [rel, tail] of Object.entries(violation.append)) {
		const abs = path.join(root, rel);
		const head = existsSync(abs) ? readFileSync(abs, 'utf8') : '';
		writeInto(root, rel, head + tail, context);
	}
	for (const op of violation.json) applyJsonOp(root, op);
	for (const [rel, target] of Object.entries(violation.link)) {
		const abs = path.join(root, rel);
		mkdirSync(path.dirname(abs), { recursive: true });
		rmSync(abs, { force: true });
		symlinkSync(target, abs);
	}
	for (const rel of violation.delete) rmSync(path.join(root, rel), { force: true, recursive: true });
}

/**
 * Run a guard's command inside the sandbox.
 * The command is the literal package.json script, so a proof exercises exactly
 * what the gate runs and never a paraphrase of it.
 */
export function runGuard(command, cwd, timeoutMs = 180_000) {
	const started = process.hrtime.bigint();
	const res = spawnSync('sh', ['-c', command], {
		cwd,
		encoding: 'utf8',
		timeout: timeoutMs,
		maxBuffer: 32 * 1024 * 1024,
		env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0', GUARD_PROOF_SANDBOX: '1' },
	});
	const ms = Number(process.hrtime.bigint() - started) / 1e6;
	const output = `${res.stdout ?? ''}${res.stderr ?? ''}`;
	return {
		code: res.status === null ? 124 : res.status,
		output,
		timedOut: res.status === null,
		ms: Math.round(ms),
	};
}

/** Trim guard output to the lines that carry the verdict. */
export function excerpt(output, limit = 6) {
	const lines = output
		.split('\n')
		.map((l) => l.replace(/\s+$/, ''))
		.filter((l) => l.trim().length);
	if (lines.length <= limit) return lines.join('\n');
	return `${lines.slice(0, limit).join('\n')}\n... ${lines.length - limit} more line(s)`;
}

/**
 * Execute one proof against a prepared sandbox and return its verdict.
 * Pure with respect to the sandbox: whatever it touched is restored on the way
 * out, so proofs run back to back in a single checkout without contaminating
 * each other.
 */
/**
 * Stage the sandbox worktree.
 *
 * Two guards read the git INDEX rather than the filesystem (`git grep` over
 * tracked files; `git ls-files -s` for committed symlinks), so an unstaged
 * fixture is invisible to them and the proof would report NOT CAUGHT for a
 * guard that works perfectly. Staging is opt-in per proof for that reason.
 */
export function stageSandbox(root) {
	spawnSync('git', ['add', '-A'], { cwd: root, stdio: 'ignore' });
}

/** Drop everything staging added, back to the sandbox baseline commit. */
export function unstageSandbox(root) {
	spawnSync('git', ['reset', '--quiet'], { cwd: root, stdio: 'ignore' });
}

export function proveGuard(guard, proof, sandbox, options = {}) {
	const { run = runGuard, stage = stageSandbox, unstage = unstageSandbox, context = {} } = options;
	if (proof.kind === 'live') {
		return {
			id: guard.id,
			verdict: VERDICTS.DECLARED_LIVE,
			reason: proof.reason,
			ms: 0,
		};
	}

	const saved = snapshot(sandbox, touchedPaths(proof));
	try {
		applyFiles(sandbox, proof.setup, context);
		const control = run(guard.command, sandbox);

		// A red baseline is not automatically a broken proof. Some guards are
		// failing on the tree right now for reasons that have nothing to do with
		// the fixture (a long tail of stub hrefs, a doc link someone else broke),
		// and refusing to prove them would mean the guards most likely to be
		// ignored are also the ones nobody verifies.
		//
		// So a red baseline downgrades the proof to a DIFFERENTIAL one, which is
		// still sound: the expected fragment must be ABSENT before the mutation
		// and PRESENT after it. That attributes the new finding to the fixture
		// just as tightly as a clean baseline does. What it cannot do is hide the
		// red: `baseline: "red"` rides along on the result and the runner reports
		// it, because a guard that fails on its own repository is its own defect.
		const baseline = control.code === 0 ? 'clean' : 'red';
		if (baseline === 'red' && control.output.includes(proof.expect)) {
			return {
				id: guard.id,
				verdict: VERDICTS.CONTROL_FAILED,
				summary: proof.summary,
				baseline,
				controlCode: control.code,
				output: excerpt(control.output),
				ms: control.ms,
				note: `the tree already produces "${proof.expect}" before the fixture is applied, so nothing can be attributed to it`,
			};
		}

		applyViolation(sandbox, proof.violation, context);
		if (proof.stage) stage(sandbox);
		const violated = run(guard.command, sandbox);
		const ms = control.ms + violated.ms;
		if (violated.code === 0) {
			return {
				id: guard.id,
				verdict: VERDICTS.NOT_CAUGHT,
				summary: proof.summary,
				baseline,
				controlCode: control.code,
				violationCode: 0,
				output: excerpt(violated.output),
				ms,
			};
		}
		if (!violated.output.includes(proof.expect)) {
			return {
				id: guard.id,
				verdict: VERDICTS.WRONG_REASON,
				summary: proof.summary,
				baseline,
				expect: proof.expect,
				controlCode: control.code,
				violationCode: violated.code,
				output: excerpt(violated.output),
				ms,
			};
		}
		return {
			id: guard.id,
			verdict: VERDICTS.PROVEN,
			summary: proof.summary,
			baseline,
			controlCode: control.code,
			violationCode: violated.code,
			evidence: firstMatchingLine(violated.output, proof.expect),
			ms,
		};
	} catch (err) {
		// A fixture that cannot even be applied (its target file was deleted, its
		// pointer resolves to nothing) is a broken DECLARATION, not a broken
		// guard. It must surface as a failing verdict rather than an uncaught
		// throw, because a throw here aborts the entire run and silently skips
		// every guard after this one, which already happened once when a proof
		// kept editing public/event.json after the tree retired that file.
		return {
			id: guard.id,
			verdict: VERDICTS.CONTROL_FAILED,
			summary: proof.summary,
			output: String(err?.message ?? err),
			ms: 0,
			note: 'the proof fixture could not be applied, so the guard was never exercised; fix this proof in data/guards.json',
		};
	} finally {
		if (proof.stage) unstage(sandbox);
		restore(sandbox, saved);
	}
}

/** The single output line that carries the expected fragment. */
export function firstMatchingLine(output, fragment) {
	for (const line of output.split('\n')) {
		if (line.includes(fragment)) return line.trim().slice(0, 240);
	}
	return '';
}