Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

15.7 KB
Raw Blame
import { spawn } from 'node:child_process';
import { existsSync, readlinkSync } from 'node:fs';
import { posix } from 'node:path';
import { fileURLToPath } from 'node:url';
import { isolatedWorkerUrls } from './worker-urls';
import type { RenderGlbOptions, RenderResult } from '../render';
import {
  EvaluatorSubprocessError,
  type EvaluatorProcessLaunch,
  type EvaluatorSubprocessControls,
  renderGLBViaProcessLaunch,
  sanitizedEvaluatorEnv,
} from './subprocess';

const DEFAULT_RUNTIME_ROOT = '/app';
const DEFAULT_BWRAP_PATH = '/usr/local/bin/bwrap';
const DEFAULT_SETPRIV_PATH = '/usr/bin/setpriv';
const DEFAULT_PRLIMIT_PATH = '/usr/bin/prlimit';
const DEFAULT_NODE_PATH = '/usr/local/bin/node';
const ENV_PATH = '/usr/bin/env';
const READINESS_VERSION = 'kiln.evaluator.isolation-readiness.v1';
const TRANSPORT_VERSION = 'kiln.evaluator.isolation-transport.v1';
const TRANSPORT_STDOUT_MARKER = 'kiln-evaluator-transport-boot-v1\n';
const PROBE_DEADLINE_MS = 8_000;
const MAX_READINESS_PROTOCOL_BYTES = 16 * 1024;
const MAX_TRANSPORT_STDOUT_BYTES = 256;
const READINESS_FAILURE_CODES = [
  'wrapper-launch',
  'fd3-transport',
  'loader-probe-boot',
  'invariant-namespace',
  'invariant-environment',
  'invariant-filesystem',
  'invariant-network',
  'invariant-generated-policy',
  'deadline',
] as const;
const READINESS_CHECKS = [
  'user-namespace',
  'no-new-privileges',
  'capabilities-empty',
  'environment-exact',
  'product-filesystem-denied',
  'host-filesystem-denied',
  'runtime-filesystem-read-only',
  'network-namespace-empty',
  'metadata-and-local-network-denied',
  'generated-capabilities-denied',
] as const;

export interface IsolatedEvaluatorHost {
  platform?: NodeJS.Platform;
  runtimeRoot?: string;
  bwrapPath?: string;
  setprivPath?: string;
  prlimitPath?: string;
  nodePath?: string;
  pathExists?: (path: string) => boolean;
}

export interface IsolatedEvaluatorControls extends EvaluatorSubprocessControls {
  host?: IsolatedEvaluatorHost;
}

export interface EvaluatorIsolationReadiness {
  version: typeof READINESS_VERSION;
  mode: 'isolated';
  checks: readonly string[];
}

interface EvaluatorIsolationReadinessFailure {
  version: typeof READINESS_VERSION;
  mode: 'isolated';
  failure: EvaluatorIsolationProbeFailureCode;
}

interface EvaluatorIsolationTransport {
  version: typeof TRANSPORT_VERSION;
  transport: 'fd3';
}

export type EvaluatorIsolationReadinessFailureCode = (typeof READINESS_FAILURE_CODES)[number];
type EvaluatorIsolationProbeFailureCode = Extract<
  EvaluatorIsolationReadinessFailureCode,
  | 'loader-probe-boot'
  | 'invariant-namespace'
  | 'invariant-environment'
  | 'invariant-filesystem'
  | 'invariant-network'
  | 'invariant-generated-policy'
>;

export class EvaluatorIsolationReadinessError extends EvaluatorSubprocessError {
  readonly readinessCode: EvaluatorIsolationReadinessFailureCode;

  constructor(readinessCode: EvaluatorIsolationReadinessFailureCode) {
    super('ISOLATION_UNAVAILABLE', 'Isolated evaluator readiness check failed.');
    this.name = 'EvaluatorIsolationReadinessError';
    this.readinessCode = readinessCode;
  }
}

export function isolationReadinessFailureCode(
  error: unknown,
): EvaluatorIsolationReadinessFailureCode | undefined {
  if (!(error instanceof EvaluatorIsolationReadinessError)) return undefined;
  return READINESS_FAILURE_CODES.includes(error.readinessCode) ? error.readinessCode : undefined;
}

function isolationUnavailable(): never {
  throw new EvaluatorSubprocessError('ISOLATION_UNAVAILABLE', 'Isolated evaluator is unavailable.');
}

function requiredAbsolutePath(value: string): string {
  if (!posix.isAbsolute(value) || posix.normalize(value) !== value) isolationUnavailable();
  return value;
}

function requiredRuntimeRoot(value: string): string {
  const root = requiredAbsolutePath(value);
  if (root !== DEFAULT_RUNTIME_ROOT) isolationUnavailable();
  return root;
}

function workerInsideRuntime(workerPath: string, runtimeRoot: string): string {
  const normalized = requiredAbsolutePath(workerPath);
  const packageRoot = posix.join(runtimeRoot, 'node_modules') + posix.sep;
  if (!normalized.startsWith(packageRoot)) isolationUnavailable();
  return normalized;
}

function runtimeMounts(runtimeRoot: string, pathExists: (path: string) => boolean): string[] {
  const mounts = ['/usr', '/lib', '/lib64', posix.join(runtimeRoot, 'node_modules')];
  const existing = mounts.filter((path) => pathExists(path));
  if (!existing.includes('/usr') || !existing.includes(posix.join(runtimeRoot, 'node_modules'))) {
    isolationUnavailable();
  }
  return existing;
}

/**
 * Build the Linux process boundary; each hosting environment must qualify it.
 * The outer image runs as a non-root user. setpriv clears inheritable/ambient
 * capabilities and locks no-new-privs before bubblewrap creates fresh user,
 * PID, network, mount, IPC, UTS, and cgroup namespaces. bubblewrap drops the
 * bounding/effective sets after entering its user namespace, where that drop
 * is valid for the non-root caller. Only the language runtime and installed
 * dependency tree are mounted read-only; scratch is tmpfs.
 */
function isolatedEvaluatorLaunchWithLoader(
  workerPath: string,
  host: IsolatedEvaluatorHost = {},
  loader: 'tsx' | 'module' = 'tsx',
): EvaluatorProcessLaunch {
  const platform = host.platform ?? process.platform;
  if (platform !== 'linux') isolationUnavailable();
  const runtimeRoot = requiredRuntimeRoot(host.runtimeRoot ?? DEFAULT_RUNTIME_ROOT);
  const pathExists = host.pathExists ?? existsSync;
  const bwrapPath = requiredAbsolutePath(host.bwrapPath ?? DEFAULT_BWRAP_PATH);
  const setprivPath = requiredAbsolutePath(host.setprivPath ?? DEFAULT_SETPRIV_PATH);
  const prlimitPath = requiredAbsolutePath(host.prlimitPath ?? DEFAULT_PRLIMIT_PATH);
  const nodePath = requiredAbsolutePath(host.nodePath ?? DEFAULT_NODE_PATH);
  for (const executable of [bwrapPath, setprivPath, prlimitPath, nodePath, ENV_PATH]) {
    if (!pathExists(executable)) isolationUnavailable();
  }
  const resolvedWorkerPath = workerInsideRuntime(workerPath, runtimeRoot);
  if (!pathExists(resolvedWorkerPath)) isolationUnavailable();

  const bwrapArgs = [
    '--unshare-all',
    // --unshare-all only tries a user namespace; --disable-userns requires it.
    '--unshare-user',
    '--die-with-parent',
    '--new-session',
    '--disable-userns',
    '--cap-drop',
    'ALL',
    '--clearenv',
    '--setenv',
    'NODE_ENV',
    'production',
    '--setenv',
    'NO_COLOR',
    '1',
    '--proc',
    '/proc',
    '--dev',
    '/dev',
    '--tmpfs',
    '/tmp',
    '--dir',
    runtimeRoot,
    '--dir',
    posix.join(runtimeRoot, 'node_modules'),
  ];
  for (const mount of runtimeMounts(runtimeRoot, pathExists)) {
    bwrapArgs.push('--ro-bind', mount, mount);
  }
  // Remove the legacy mutation accessor. Throw mode breaks the Khronos
  // validator's feature detection before any GLB can be validated.
  const nodeArgs = [nodePath, '--max-old-space-size=512', '--disable-proto=delete'];
  if (loader === 'tsx') nodeArgs.push('--import', 'tsx');
  nodeArgs.push(resolvedWorkerPath);
  bwrapArgs.push(
    '--chdir',
    runtimeRoot,
    // Bubblewrap passes inherited fds to the command. The spawn caller supplies
    // only stdio and the fd3 protocol pipe; no descriptor-preservation flag exists.
    '--',
    prlimitPath,
    '--cpu=65:65',
    '--as=6442450944:6442450944',
    '--fsize=100663296:100663296',
    '--nofile=64:64',
    '--nproc=64:64',
    '--',
    // Bubblewrap adds PWD after --clearenv. Clear the final worker environment
    // again instead of weakening the exact two-variable readiness invariant.
    ENV_PATH,
    '-i',
    'NODE_ENV=production',
    'NO_COLOR=1',
    ...nodeArgs,
  );

  return {
    command: setprivPath,
    args: [
      '--no-new-privs',
      '--inh-caps=-all',
      '--ambient-caps=-all',
      '--',
      bwrapPath,
      ...bwrapArgs,
    ],
    // The wrapper receives no product/provider environment. bubblewrap clears
    // even this two-key environment before creating the worker environment.
    env: sanitizedEvaluatorEnv({}),
    detached: true,
  };
}

export function isolatedEvaluatorLaunch(
  workerPath: string,
  host: IsolatedEvaluatorHost = {},
): EvaluatorProcessLaunch {
  return isolatedEvaluatorLaunchWithLoader(
    workerPath,
    host,
    /\.tsx?$/.test(workerPath) ? 'tsx' : 'module',
  );
}

export async function renderGLBViaIsolatedEvaluator(
  code: string,
  options: RenderGlbOptions = {},
  controls: IsolatedEvaluatorControls = {},
): Promise<RenderResult> {
  const workerPath = fileURLToPath(isolatedWorkerUrls(import.meta.url).worker);
  const launch = isolatedEvaluatorLaunch(workerPath, controls.host);
  const { host: _, ...processControls } = controls;
  return renderGLBViaProcessLaunch(code, options, processControls, launch);
}

export function decodeEvaluatorIsolationReadiness(
  value: unknown,
): EvaluatorIsolationReadiness | EvaluatorIsolationReadinessFailure {
  if (typeof value !== 'object' || value === null || Array.isArray(value)) isolationUnavailable();
  const record = value as Record<string, unknown>;
  if (
    Object.keys(record).sort().join(',') === 'failure,mode,version' &&
    record.version === READINESS_VERSION &&
    record.mode === 'isolated' &&
    [
      'loader-probe-boot',
      'invariant-namespace',
      'invariant-environment',
      'invariant-filesystem',
      'invariant-network',
      'invariant-generated-policy',
    ].includes(String(record.failure))
  ) {
    return record as unknown as EvaluatorIsolationReadinessFailure;
  }
  if (
    Object.keys(record).sort().join(',') !== 'checks,mode,version' ||
    record.version !== READINESS_VERSION ||
    record.mode !== 'isolated' ||
    !Array.isArray(record.checks) ||
    record.checks.length !== READINESS_CHECKS.length ||
    record.checks.join(',') !== READINESS_CHECKS.join(',')
  ) {
    isolationUnavailable();
  }
  return record as unknown as EvaluatorIsolationReadiness;
}

export function decodeEvaluatorIsolationTransport(value: unknown): EvaluatorIsolationTransport {
  if (
    typeof value !== 'object' ||
    value === null ||
    Array.isArray(value) ||
    Object.keys(value).sort().join(',') !== 'transport,version'
  ) {
    isolationUnavailable();
  }
  const record = value as Record<string, unknown>;
  if (record.version !== TRANSPORT_VERSION || record.transport !== 'fd3') isolationUnavailable();
  return record as unknown as EvaluatorIsolationTransport;
}

function terminateReadinessChild(child: ReturnType<typeof spawn>): void {
  try {
    if (child.pid) process.kill(-child.pid, 'SIGKILL');
  } catch {}
}

async function assertIsolationTransport(launch: EvaluatorProcessLaunch): Promise<void> {
  return await new Promise<void>((resolve, reject) => {
    const child = spawn(launch.command, launch.args, {
      env: launch.env,
      windowsHide: true,
      detached: true,
      stdio: ['ignore', 'pipe', 'ignore', 'pipe'],
    });
    const stdoutChunks: Buffer[] = [];
    const protocolChunks: Buffer[] = [];
    let stdoutBytes = 0;
    let protocolBytes = 0;
    let settled = false;
    const fail = (readinessCode: EvaluatorIsolationReadinessFailureCode) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      reject(new EvaluatorIsolationReadinessError(readinessCode));
    };
    const timer = setTimeout(() => {
      terminateReadinessChild(child);
      fail('deadline');
    }, PROBE_DEADLINE_MS);
    child.stdout?.on('data', (chunk: Buffer) => {
      stdoutBytes += chunk.byteLength;
      if (stdoutBytes > MAX_TRANSPORT_STDOUT_BYTES) {
        terminateReadinessChild(child);
        fail('wrapper-launch');
        return;
      }
      stdoutChunks.push(Buffer.from(chunk));
    });
    const protocol = child.stdio[3];
    if (!protocol) {
      terminateReadinessChild(child);
      fail('fd3-transport');
      return;
    }
    protocol.on('data', (chunk: Buffer) => {
      protocolBytes += chunk.byteLength;
      if (protocolBytes > MAX_READINESS_PROTOCOL_BYTES) {
        terminateReadinessChild(child);
        fail('fd3-transport');
        return;
      }
      protocolChunks.push(Buffer.from(chunk));
    });
    child.once('error', () => fail('wrapper-launch'));
    child.once('close', (code) => {
      if (settled) return;
      const stdout = Buffer.concat(stdoutChunks).toString('utf8');
      if (stdout !== TRANSPORT_STDOUT_MARKER) return fail('wrapper-launch');
      if (code !== 0 || protocolChunks.length === 0) return fail('fd3-transport');
      try {
        decodeEvaluatorIsolationTransport(
          JSON.parse(Buffer.concat(protocolChunks).toString('utf8')),
        );
        settled = true;
        clearTimeout(timer);
        resolve();
      } catch {
        fail('fd3-transport');
      }
    });
  });
}

async function runIsolationProbe(
  launch: EvaluatorProcessLaunch,
): Promise<EvaluatorIsolationReadiness> {
  return await new Promise<EvaluatorIsolationReadiness>((resolve, reject) => {
    const child = spawn(launch.command, launch.args, {
      env: launch.env,
      windowsHide: true,
      detached: true,
      stdio: ['ignore', 'ignore', 'ignore', 'pipe'],
    });
    const protocol = child.stdio[3];
    const chunks: Buffer[] = [];
    let bytes = 0;
    let settled = false;
    const fail = (readinessCode: EvaluatorIsolationReadinessFailureCode) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      reject(new EvaluatorIsolationReadinessError(readinessCode));
    };
    const timer = setTimeout(() => {
      terminateReadinessChild(child);
      fail('deadline');
    }, PROBE_DEADLINE_MS);
    if (!protocol) {
      terminateReadinessChild(child);
      fail('fd3-transport');
      return;
    }
    protocol.on('data', (chunk: Buffer) => {
      bytes += chunk.byteLength;
      if (bytes > MAX_READINESS_PROTOCOL_BYTES) {
        terminateReadinessChild(child);
        fail('loader-probe-boot');
        return;
      }
      chunks.push(Buffer.from(chunk));
    });
    child.once('error', () => fail('wrapper-launch'));
    child.once('close', (code) => {
      if (settled) return;
      if (chunks.length === 0) return fail('loader-probe-boot');
      try {
        const result = decodeEvaluatorIsolationReadiness(
          JSON.parse(Buffer.concat(chunks).toString('utf8')),
        );
        if ('failure' in result) return fail(result.failure);
        if (code !== 0) return fail('loader-probe-boot');
        settled = true;
        clearTimeout(timer);
        resolve(result);
      } catch {
        fail('loader-probe-boot');
      }
    });
  });
}

/** Fail-closed boot/readiness proof. Package presence alone is not accepted. */
export async function assertIsolatedEvaluatorReady(
  host: IsolatedEvaluatorHost = {},
): Promise<EvaluatorIsolationReadiness> {
  if (
    typeof process.getuid !== 'function' ||
    process.getuid() === 0 ||
    process.geteuid?.() !== process.getuid()
  ) {
    throw new EvaluatorIsolationReadinessError('invariant-namespace');
  }
  const workers = isolatedWorkerUrls(import.meta.url);
  const transportPath = fileURLToPath(workers.transport);
  const probePath = fileURLToPath(workers.probe);
  let transportLaunch: EvaluatorProcessLaunch;
  let probeLaunch: EvaluatorProcessLaunch;
  try {
    transportLaunch = isolatedEvaluatorLaunchWithLoader(transportPath, host, 'module');
    probeLaunch = isolatedEvaluatorLaunch(probePath, host);
    // Trusted parent evidence is passed as bounded probe arguments, never
    // through the source worker's environment or generated-source protocol.
    probeLaunch.args.push(
      '--kiln-host-uid',
      String(process.getuid()),
      '--kiln-host-userns',
      readlinkSync('/proc/self/ns/user'),
    );
  } catch {
    throw new EvaluatorIsolationReadinessError('wrapper-launch');
  }
  await assertIsolationTransport(transportLaunch);
  return await runIsolationProbe(probeLaunch);
}