chati-dev 4.5.28 → 4.5.29

package/src/terminal/darwin-browser-application.js

@@ -0,0 +1,116 @@
+/** Trusted application/proxy lifetime, not an evidence issuer. Application
+ * stdout is never an ownership, readiness or completion message. */
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { sha256 } from '@chati/core';
+import { validateBrowserObservationPlan } from '@chati/planning';
+import { prepareDarwinBrowserApplicationLaunch, assertDarwinSealedLaunch, disposeDarwinSealedLaunch } from './darwin-execution.js';
+import { createVerifiedBrowserProxy } from './browser-endpoint-proxy.js';
+import { createDarwinVerificationBinding } from './verification-process-facts.js';
+
+function error(code) { return Object.assign(new Error(code), { code }); }
+
+export async function startDarwinBrowserApplication(input) {
+  if (!input || Object.keys(input).sort().join(',') !== 'observerDirectory,plan,workingDir'
+    || typeof input.workingDir !== 'string' || !isAbsolute(input.workingDir)
+    || typeof input.observerDirectory !== 'string' || !isAbsolute(input.observerDirectory)) throw error('BROWSER_APPLICATION_CONFIGURATION_INVALID');
+  const plan = structuredClone(validateBrowserObservationPlan(input.plan));
+  if (plan.application.listener_transport !== 'darwin_prebound_tcp_v1') throw error('BROWSER_APPLICATION_LISTENER_TRANSPORT_REQUIRED');
+  const workingDir = realpathSync(input.workingDir);
+  const context = Object.freeze({ authority_kind: 'verification_check', invocation_id: randomUUID(),
+    launch_nonce: randomUUID(), executable_binding_digest: sha256(plan.application.executable_binding) });
+  let launch; let proxy; let child; let ready; let timer; let escalation; let drainTimer;
+  let setupError; let spawnError; let inputError = null; let outputBytes = 0;
+  let timedOut = false; let outputLimitExceeded = false; let requestedStop = false; let finalizing = false;
+  let resolveFinished;
+  const finished = new Promise(resolve => { resolveFinished = resolve; });
+  function terminate(signal = 'SIGTERM') {
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+    // Signal only our unreaped helper. Its native owner/reaper handles the
+    // admitted application, not a fresh caller-side PID/group lookup.
+    try { child.kill(signal); } catch (failure) { spawnError ??= failure; }
+    if (!escalation) escalation = setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+    }, 2000);
+  }
+  async function finalize(exitCode, signal, failure) {
+    if (finalizing) return;
+    finalizing = true;
+    clearTimeout(timer); clearTimeout(escalation); clearTimeout(drainTimer);
+    failure ??= setupError ?? spawnError;
+    let completion; let binding;
+    try {
+      await proxy?.close();
+      if (!failure) {
+        completion = launch.supervisorChannels.readCompletion(exitCode);
+        assertDarwinSealedLaunch(launch);
+        binding = createDarwinVerificationBinding({ context, helperSha256: launch.helperSha256,
+          policyDigest: launch.policyDigest, ready, completion, workingDir,
+          executableBinding: plan.application.executable_binding, args: plan.application.args, stdin: plan.application.stdin });
+      }
+    } catch (caught) { failure ??= caught; }
+    try { disposeDarwinSealedLaunch(launch); } catch (caught) { failure ??= caught; }
+    // EOF callbacks on different descriptors have no ordering guarantee.
+    // Report closure after our own explicit revocation, not before cleanup.
+    const proof = launch.browserProofChannels.summary();
+    resolveFinished(Object.freeze({ containment_kind: 'darwin_scoped_process_group_v1',
+      process_tree_stopped: false, process_group_stopped: Boolean(completion), detached_descendants: 'unknown',
+      exit_code: exitCode, signal, timed_out: timedOut, output_limit_exceeded: outputLimitExceeded,
+      input_error: inputError, discarded_output_bytes: outputBytes, requested_stop: requestedStop,
+      error_code: failure ? failure.code || 'BROWSER_APPLICATION_COMPLETION_INVALID' : null,
+      listener_transport: plan.application.listener_transport,
+      executable_binding: Object.freeze(plan.application.executable_binding),
+      stdin_sha256: createHash('sha256').update(plan.application.stdin).digest('hex'),
+      containment_digest: sha256({ role: 'browser-application', helper_sha256: launch.helperSha256,
+        policy_digest: launch.policyDigest, native_nonce: context.launch_nonce }),
+      darwin_verification_binding: binding ?? null, endpoint_proof: proof, proxy: proxy.facts() }));
+  }
+  try {
+    launch = prepareDarwinBrowserApplicationLaunch({ binding: plan.application.executable_binding,
+      projectDir: workingDir, args: plan.application.args, authorityContext: context,
+      applicationPort: plan.application.port, listenerTransport: plan.application.listener_transport, observerDirectory: input.observerDirectory });
+    proxy = await createVerifiedBrowserProxy({ hostname: plan.hostname, applicationPort: plan.application.port,
+      timeoutMs: plan.timeout_ms, verifyPeer: tuple => launch.browserProofChannels.verifyPeer(tuple) });
+    assertDarwinSealedLaunch(launch);
+    child = spawn(launch.command, launch.args, { cwd: '/', detached: true,
+      env: { PATH: '/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', TZ: 'UTC',
+        HOME: launch.temporaryDirectory, TMPDIR: launch.temporaryDirectory,
+        PORT: String(plan.application.port), HOST: '127.0.0.1', CHATI_APPLICATION_LISTENER_FD: '11' },
+      stdio: ['pipe', 'pipe', 'pipe', 'ignore', launch.projectDescriptor,
+        ...launch.supervisorChannels.inheritedDescriptors, ...launch.browserProofChannels.inheritedDescriptors, launch.browserListenerDescriptor] });
+    for (const stream of ['stdout', 'stderr']) child[stream].on('data', bytes => {
+      outputBytes += bytes.length;
+      if (outputBytes > 2 * 1024 * 1024 && !outputLimitExceeded) { outputLimitExceeded = true; terminate(); }
+    });
+    child.once('error', failure => { spawnError = failure; });
+    child.stdin.on('error', failure => { inputError = failure.code || failure.name; });
+    child.once('exit', (code, signal) => {
+      clearTimeout(timer); clearTimeout(escalation);
+      drainTimer = setTimeout(() => {
+        child.stdout.destroy(); child.stderr.destroy(); child.stdin.destroy();
+        void finalize(code, signal, error('BROWSER_APPLICATION_OUTPUT_NOT_CLOSED'));
+      }, 2000);
+    });
+    child.once('close', (code, signal) => { void finalize(code, signal); });
+    timer = setTimeout(() => { timedOut = true; terminate(); }, plan.timeout_ms);
+    launch.browserProofChannels.afterSpawn();
+    ready = launch.supervisorChannels.readReady(child.pid, launch.verifiedCdhash);
+    assertDarwinSealedLaunch(launch);
+    launch.supervisorChannels.authorize();
+    child.stdin.end(plan.application.stdin);
+    return Object.freeze({ proxyUrl: proxy.serverUrl, proxyPort: proxy.port, finished,
+      // Caller closes the browser first, then the proxy/application, and consumes
+      // private completion. No recursion through app-mutated TMP or subject.
+      async stop() { requestedStop = true; terminate(); await proxy.close(); return finished; } });
+  } catch (failure) {
+    setupError = failure;
+    if (child) { terminate('SIGKILL'); await finished; }
+    else {
+      await proxy?.close();
+      if (launch) disposeDarwinSealedLaunch(launch);
+    }
+    throw failure;
+  }
+}

package/src/terminal/darwin-browser-observer.js

@@ -0,0 +1,57 @@
+/** Host-owned composition. Application and observer have separate sandboxes;
+ * only this host process owns the endpoint proof and proxy. */
+import { mkdtempSync, realpathSync, rmdirSync } from 'node:fs';
+import { request } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { startDarwinBrowserApplication } from './darwin-browser-application.js';
+import { runIsolatedDarwinBrowserObserver } from './spawner.js';
+import { readDarwinBrowserRendezvousNamespace } from './browser-runtime.js';
+import { darwinBrowserObserverInvocation } from './browser-process-facts.js';
+
+function fail(code) { throw Object.assign(new Error(code), { code }); }
+function ready(handle, plan) {
+  return new Promise(resolve => {
+    const probe = request({ hostname: '127.0.0.1', port: handle.proxyPort, method: 'GET',
+      path: `http://${plan.hostname}:${plan.application.port}${plan.ready_path}`,
+      headers: { host: `${plan.hostname}:${plan.application.port}` }, timeout: 2200 }, response => {
+      const ok = response.statusCode >= 200 && response.statusCode < 400;
+      response.destroy(); resolve(ok);
+    });
+    probe.on('timeout', () => probe.destroy()); probe.on('error', () => resolve(false)); probe.end();
+  });
+}
+
+export async function runDarwinBrowserObservation({ workingDir, runtimeDirectory, browserFile, nodeBinding, plan }) {
+  const observerDir = mkdtempSync(join(realpathSync(tmpdir()), 'chati-browser-observer-subject-'));
+  const applicationLifetime = new AbortController();
+  let app; let appFacts; let facts; let invocation; let baseBundleId; let failure;
+  try {
+    baseBundleId = readDarwinBrowserRendezvousNamespace(join(runtimeDirectory, 'chromium', browserFile));
+    app = await startDarwinBrowserApplication({ workingDir, observerDirectory: runtimeDirectory, plan });
+    void app.finished.then(() => applicationLifetime.abort());
+    const deadline = performance.now() + Math.min(30000, plan.timeout_ms);
+    while (!await ready(app, plan)) {
+      if (applicationLifetime.signal.aborted) fail('BROWSER_APPLICATION_EXITED');
+      if (performance.now() >= deadline) fail('BROWSER_APPLICATION_NOT_READY');
+      await delay(25);
+    }
+    invocation = darwinBrowserObserverInvocation({ workingDir: observerDir, runtimeDirectory, browserFile,
+      proxyPort: app.proxyPort, nodeBinding, plan });
+    facts = await runIsolatedDarwinBrowserObserver({ ...invocation, observerDirectory: runtimeDirectory,
+      applicationProject: workingDir, proxyPort: app.proxyPort, baseBundleId, applicationSignal: applicationLifetime.signal });
+    if (applicationLifetime.signal.aborted) fail('BROWSER_APPLICATION_EXITED');
+  } catch (error) { failure = error; }
+  finally {
+    try { if (app) appFacts = await app.stop(); } catch (error) { failure ??= error; }
+    // Unknown detached descendants do not justify traversing a mutable tree.
+    try { rmdirSync(observerDir); } catch (error) { if (error.code !== 'ENOTEMPTY') failure ??= error; }
+  }
+  if (failure) throw failure;
+  // base_bundle_id names Chromium's BaseBundleID rendezvous namespace. A flat
+  // headless shell does not acquire fictitious application bundle metadata.
+  return { facts, invocation, binding: { schema_version: 1, runtime_directory: runtimeDirectory,
+    observer_working_dir: observerDir, browser_file: browserFile, proxy_port: app.proxyPort,
+    base_bundle_id: baseBundleId, application: appFacts } };
+}

package/src/terminal/darwin-execution.js

@@ -0,0 +1,185 @@
+/** Sealed Darwin launch preparation. Receipt authority remains in the spawner. */
+import { spawnSync } from 'node:child_process';
+import { closeSync, constants, fstatSync, lstatSync, mkdtempSync, openSync, realpathSync, rmdirSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { createDarwinBrowserListenerSync, inspectDarwinBrowserListenerSync, createDarwinBrowserProofChannels, createDarwinSupervisorChannels, sha256 } from '@chati/core';
+import { installationAuthorityStateDirectory } from '../installer-v2/installation-authority.js';
+import { assertExecutableSnapshot, disposeExecutableSnapshot, prepareExecutableSnapshot, prepareRuntimeNativeHelperSnapshot } from './executable-snapshot.js';
+import { darwinAuthorityProfile, darwinBrowserApplicationProfile, darwinBrowserObserverProfile, darwinVerificationProfile } from './darwin-authority-policy.js';
+
+const RECORDS = new WeakMap();
+function fail(message) { throw Object.assign(new Error(message), { code: 'DARWIN_SEALED_EXECUTION_UNAVAILABLE' }); }
+function quote(path) {
+  if (typeof path !== 'string' || !isAbsolute(path)
+    || Array.from(path).some((character) => character.codePointAt(0) < 32 || character.codePointAt(0) === 127)) {
+    fail('sandbox paths must be absolute and contain no control characters');
+  }
+  return JSON.stringify(path);
+}
+export function darwinSealedPlanningProfile({ snapshotDirectory, authorityDirectory, promptDirectory, launcherPath, launcherDirectory }) {
+  // This preserves the existing non-authority Planning execution contract.
+  // The later authority-bearing backend requires its own scoped policy/receipt.
+  const protectedPaths = [snapshotDirectory, authorityDirectory, promptDirectory, launcherPath, launcherDirectory].filter(Boolean);
+  const ancestors = new Set();
+  for (const path of protectedPaths) {
+    quote(path);
+    for (let parent = dirname(path); ; parent = dirname(parent)) {
+      ancestors.add(parent);
+      if (parent === dirname(parent)) break;
+    }
+  }
+  return `(version 1) (allow default)\n(deny file-write* (subpath ${quote(snapshotDirectory)}))\n(deny file-read* file-write* (subpath ${quote(authorityDirectory)}))\n`
+    + (promptDirectory ? `(deny file-write* (subpath ${quote(promptDirectory)}))\n` : '')
+    + (launcherPath ? `(deny file-write* (literal ${quote(launcherPath)}))\n` : '')
+    + (launcherDirectory ? `(deny file-write* (subpath ${quote(launcherDirectory)}))\n` : '')
+    // A subpath rule alone does not stop renaming a writable ancestor and
+    // accessing the same image through its new, unprotected pathname.
+    + [...ancestors].map((path) => `(deny file-write* (literal ${quote(path)}))\n`).join('');
+}
+function projectIdentity(stat) { return { dev: stat.dev, ino: stat.ino, uid: stat.uid, mode: stat.mode }; }
+function matches(left, right) { return Object.keys(left).every((key) => left[key] === right[key]); }
+
+export function prepareDarwinSealedLaunch(options) { return prepareDarwinLaunch(options, false); }
+export function prepareDarwinAuthorityLaunch(options) { return prepareDarwinLaunch(options, true); }
+export function prepareDarwinBrowserApplicationLaunch({ applicationPort, listenerTransport, observerDirectory, ...options }) {
+  if (listenerTransport !== 'darwin_prebound_tcp_v1') fail('Darwin browser application requires an explicit prebound TCP plan');
+  return prepareDarwinLaunch({ ...options, verificationIsolation: true, hasPrompt: false }, true,
+    { applicationPort, observerDirectory });
+}
+export function prepareDarwinBrowserObserverLaunch({ proxyPort, observerDirectory, applicationProject, baseBundleId, ...options }) {
+  return prepareDarwinLaunch({ ...options, verificationIsolation: true, hasPrompt: false }, true, null,
+    { proxyPort, observerDirectory, applicationProject, baseBundleId });
+}
+
+function disposeTemporary(state) {
+  if (!state) return;
+  try {
+    if (!matches(state.identity, projectIdentity(fstatSync(state.descriptor)))
+      || !matches(state.identity, projectIdentity(lstatSync(state.path)))) fail('private runtime directory changed before cleanup');
+    // A detached descendant may outlive the observed group. Never recursively
+    // traverse its mutable temporary tree or turn group-empty into quiescence.
+    try { rmdirSync(state.path); } catch (error) { if (error.code !== 'ENOTEMPTY') throw error; }
+  } finally { closeSync(state.descriptor); }
+}
+
+function prepareDarwinLaunch({ binding, harnessId, projectDir, args, hasPrompt = false, promptDirectory, temporaryRoot,
+  authorityContext, stateDirectory, writeScopes, maskedReadPaths = [], councilToolIsolation = false, verificationIsolation = false,
+  subjectReadOnly = false }, authority, browserApplication = null, browserObserver = null) {
+  if (process.platform !== 'darwin') fail('Darwin sealed launch requires an actual macOS host');
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string' || arg.includes('\0'))) fail('provider arguments must be an array of strings');
+  const project = realpathSync(projectDir);
+  let snapshot;
+  let descriptor;
+  let helperSnapshot;
+  let channels;
+  let browserProof;
+  let browserListener;
+  let temporary;
+  try {
+    helperSnapshot = prepareRuntimeNativeHelperSnapshot('darwin-launcher', { projectDir: project, temporaryRoot });
+    const launcher = helperSnapshot.executablePath;
+    snapshot = prepareExecutableSnapshot(binding, { harnessId, projectDir: project, temporaryRoot, requireNativeImage: verificationIsolation });
+    descriptor = openSync(project, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    const identity = projectIdentity(fstatSync(descriptor));
+    if (!matches(identity, projectIdentity(lstatSync(project)))) fail('project changed before descriptor binding');
+    assertExecutableSnapshot(helperSnapshot);
+    const inspected = spawnSync(launcher, ['inspect', snapshot.executablePath], {
+      encoding: 'utf8', timeout: 10000, maxBuffer: 65536, cwd: '/',
+      env: { PATH: '/usr/bin:/bin' }, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (inspected.status !== 0 || inspected.error || inspected.signal) {
+      fail(`the staged image has no usable native code identity: ${inspected.stderr?.trim() || inspected.error?.code || inspected.status}`);
+    }
+    let information;
+    try { information = JSON.parse(inspected.stdout); } catch { fail('Darwin image inspection returned invalid output'); }
+    if (!information || typeof information !== 'object' || Array.isArray(information)
+      || Object.keys(information).sort().join(',') !== 'cdhash,schema_version'
+      || information.schema_version !== 1 || !/^[a-f0-9]{40}$/.test(information.cdhash)) fail('Darwin image inspection returned invalid identity');
+    let profile;
+    if (authority) {
+      channels = createDarwinSupervisorChannels(authorityContext);
+      if (browserApplication) {
+        browserProof = createDarwinBrowserProofChannels(channels.nonce);
+        const fd = createDarwinBrowserListenerSync(browserApplication.applicationPort);
+        browserListener = { fd, port: browserApplication.applicationPort };
+        browserListener.generation = inspectDarwinBrowserListenerSync(fd, browserListener.port);
+      }
+      const path = mkdtempSync(join(realpathSync(temporaryRoot ?? tmpdir()), 'chati-runtime-'));
+      const temporaryDescriptor = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+      temporary = { path, descriptor: temporaryDescriptor, identity: projectIdentity(fstatSync(temporaryDescriptor)) };
+      const profileInputs = { project,
+        temporaryDirectory: path, snapshotDirectory: snapshot.directory, launcherDirectory: helperSnapshot.directory,
+        launcherPath: launcher, executablePath: snapshot.executablePath,
+        supportingExecutablePaths: snapshot.supportingExecutables.map(entry => entry.executable_path),
+        authorityDirectory: installationAuthorityStateDirectory(), homeDirectory: realpathSync(homedir()),
+        promptDirectory: promptDirectory ? realpathSync(promptDirectory) : undefined,
+        writeScopes, maskedReadPaths, councilToolIsolation };
+      profile = browserApplication ? darwinBrowserApplicationProfile({ ...profileInputs,
+        applicationPort: browserApplication.applicationPort, observerDirectory: realpathSync(browserApplication.observerDirectory) })
+        : browserObserver ? darwinBrowserObserverProfile({ ...profileInputs, ...browserObserver,
+          observerDirectory: realpathSync(browserObserver.observerDirectory), applicationProject: realpathSync(browserObserver.applicationProject) })
+        : verificationIsolation ? darwinVerificationProfile({ ...profileInputs, subjectReadOnly })
+        : darwinAuthorityProfile({ ...profileInputs, stateDirectory: realpathSync(stateDirectory) });
+    } else {
+      profile = darwinSealedPlanningProfile({ snapshotDirectory: snapshot.directory,
+        authorityDirectory: installationAuthorityStateDirectory(), promptDirectory, launcherPath: launcher,
+        launcherDirectory: helperSnapshot.directory });
+    }
+    const record = Object.freeze({
+      command: '/usr/bin/sandbox-exec',
+      args: Object.freeze(['-p', profile, launcher, browserApplication ? 'launch-browser-prebound-admitted' : authority ? 'launch-admitted' : 'launch', information.cdhash, snapshot.executablePath,
+        hasPrompt ? '1' : '0', ...(channels ? [channels.nonce] : []), ...(browserListener ? [String(browserListener.port)] : []), '--', ...args]),
+      projectDescriptor: descriptor,
+      executableSnapshot: snapshot,
+      ...(authority ? { supervisorChannels: channels, verifiedCdhash: information.cdhash,
+        helperSha256: helperSnapshot.executableSha256, policyDigest: sha256(profile), temporaryDirectory: temporary.path } : {}),
+      ...(browserProof ? { browserProofChannels: browserProof, browserListenerDescriptor: browserListener.fd } : {}),
+      kind: authority ? 'darwin_scoped_process_group_v1' : 'darwin_sealed_planning_v1',
+    });
+    RECORDS.set(record, { descriptor, snapshot, project, identity, helperSnapshot, channels, browserProof, browserListener, temporary });
+    assertDarwinSealedLaunch(record);
+    return record;
+  } catch (error) {
+    if (browserListener) { try { closeSync(browserListener.fd); } catch (cleanupError) { error.listenerCleanupError = cleanupError; } }
+    if (browserProof) { try { browserProof.dispose(); } catch (cleanupError) { error.browserProofCleanupError = cleanupError; } }
+    if (channels) { try { channels.dispose(); } catch (cleanupError) { error.channelCleanupError = cleanupError; } }
+    if (temporary) { try { disposeTemporary(temporary); } catch (cleanupError) { error.temporaryCleanupError = cleanupError; } }
+    if (descriptor !== undefined) closeSync(descriptor);
+    if (snapshot) { try { disposeExecutableSnapshot(snapshot); } catch (cleanupError) { error.snapshotCleanupError = cleanupError; } }
+    if (helperSnapshot) { try { disposeExecutableSnapshot(helperSnapshot); } catch (cleanupError) { error.helperCleanupError = cleanupError; } }
+    throw error;
+  }
+}
+
+export function assertDarwinSealedLaunch(record) {
+  const state = RECORDS.get(record);
+  if (!state) fail('Darwin launch is unknown or disposed');
+  assertExecutableSnapshot(state.snapshot);
+  assertExecutableSnapshot(state.helperSnapshot);
+  if (state.browserListener && inspectDarwinBrowserListenerSync(state.browserListener.fd, state.browserListener.port) !== state.browserListener.generation) fail('prebound browser listener changed before Darwin launch');
+  if (!matches(state.identity, projectIdentity(fstatSync(state.descriptor)))
+    || !matches(state.identity, projectIdentity(lstatSync(state.project)))) fail('project directory changed before Darwin launch');
+  if (state.temporary && (!matches(state.temporary.identity, projectIdentity(fstatSync(state.temporary.descriptor)))
+    || !matches(state.temporary.identity, projectIdentity(lstatSync(state.temporary.path))))) fail('private runtime directory changed before Darwin launch');
+  return true;
+}
+
+export function disposeDarwinSealedLaunch(record) {
+  const state = RECORDS.get(record);
+  if (!state) return false;
+  RECORDS.delete(record);
+  closeSync(state.descriptor);
+  try {
+    if (state.browserListener) closeSync(state.browserListener.fd);
+  } finally {
+    try {
+      try { try { state.browserProof?.dispose(); } finally { state.channels?.dispose(); } }
+      finally { disposeTemporary(state.temporary); }
+    } finally {
+      try { disposeExecutableSnapshot(state.snapshot); }
+      finally { disposeExecutableSnapshot(state.helperSnapshot); }
+    }
+  }
+  return true;
+}

package/src/terminal/executable-snapshot.js

@@ -0,0 +1,202 @@
+/** Private executable copies, hashed while reading the sealed source descriptor. */
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, openSync,
+  readSync, realpathSync, rmdirSync, writeSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join, relative, sep } from 'node:path';
+import { directoryPathSync, lstatAtSync, mkdirAtSync, openAtSync, readDirectorySync, unlinkAtSync } from '@chati/core';
+import {
+  digestProviderExecutable, openPinnedProviderExecutable, openPinnedProviderSupportingExecutables,
+} from '../installer-v2/provider-executable.js';
+import { openAttestedRuntimeNativeHelper } from './runtime-native-helper.js';
+
+const RECORDS = new WeakMap();
+const HOOKS = Symbol.for('chati.terminal.security-test-hooks');
+const DIRECTORY_FLAGS = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+function failure(message) {
+  throw Object.assign(new Error(message), { code: 'PROVIDER_EXECUTABLE_SNAPSHOT_INVALID' });
+}
+function hook(name, value) { globalThis[HOOKS]?.[name]?.(value); }
+function inside(root, target) {
+  const part = relative(root, target);
+  return part === '' || (part !== '..' && !part.startsWith(`..${sep}`) && !isAbsolute(part));
+}
+function sameInode(left, right) { return left.dev === right.dev && left.ino === right.ino; }
+function sourceUnchanged(before, after) {
+  return ['dev', 'ino', 'mode', 'uid', 'gid', 'nlink', 'size', 'mtimeMs', 'ctimeMs']
+    .every((field) => before[field] === after[field]);
+}
+
+function copyPinnedImage(state, source) {
+  const name = basename(source.binding.executable_path);
+  if (state.entries.some((entry) => entry.name === name)) failure('snapshot executable basenames collide');
+  const before = fstatSync(source.descriptor);
+  const writer = openAtSync(state.directoryDescriptor, name,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NONBLOCK, 0o600);
+  const entry = { name, identity: fstatSync(writer), descriptor: undefined, digest: source.binding.executable_sha256 };
+  state.entries.push(entry);
+  try {
+    const hash = createHash('sha256');
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let position = 0;
+    while (position < before.size) {
+      const bytes = readSync(source.descriptor, buffer, 0, Math.min(buffer.length, before.size - position), position);
+      if (bytes === 0) failure('sealed executable changed during snapshot copy');
+      hash.update(buffer.subarray(0, bytes));
+      let written = 0;
+      while (written < bytes) {
+        const count = writeSync(writer, buffer, written, bytes - written, position + written);
+        if (count === 0) failure('snapshot write made no progress');
+        written += count;
+      }
+      position += bytes;
+      hook('afterExecutableSnapshotChunk', { sourceDescriptor: source.descriptor, position });
+    }
+    if (!sourceUnchanged(before, fstatSync(source.descriptor)) || hash.digest('hex') !== entry.digest) {
+      failure('snapshot bytes differ from the sealed installation binding');
+    }
+    fchmodSync(writer, 0o500);
+    fsyncSync(writer);
+    const completed = fstatSync(writer);
+    if (!sameInode(completed, entry.identity) || completed.nlink !== 1 || completed.size !== before.size) {
+      failure('snapshot image changed while being prepared');
+    }
+    entry.descriptor = openAtSync(state.directoryDescriptor, name, constants.O_RDONLY | constants.O_NONBLOCK);
+    entry.snapshot = digestProviderExecutable(entry.descriptor).snapshot;
+    if (!sameInode(entry.snapshot, completed) || entry.snapshot.nlink !== 1
+      || (entry.snapshot.mode & 0o777) !== 0o500) failure('snapshot image could not be pinned read-only');
+  } finally { closeSync(writer); }
+}
+
+function assertDirectory(state) {
+  const attached = lstatAtSync(state.parentDescriptor, state.name);
+  const pinned = fstatSync(state.directoryDescriptor);
+  if (!attached.isDirectory() || !sameInode(attached, state.identity)
+    || !sameInode(pinned, state.identity) || (pinned.mode & 0o777) !== 0o700
+    || pinned.uid !== process.geteuid() || directoryPathSync(state.directoryDescriptor) !== state.path) {
+    failure('private executable snapshot directory changed');
+  }
+}
+
+function cleanup(state) {
+  // Never recursive: unknown/replaced entries are retained, not deleted.
+  try {
+    assertDirectory(state);
+    for (const entry of state.entries) {
+      const current = lstatAtSync(state.directoryDescriptor, entry.name);
+      if (!current.isFile() || !sameInode(current, entry.identity) || current.nlink !== 1) {
+        failure('snapshot cleanup refused an unowned or multiply linked entry');
+      }
+    }
+    if (readDirectorySync(state.directoryDescriptor).some((name) => !state.entries.some((entry) => entry.name === name))) {
+      failure('snapshot cleanup refused unknown directory contents');
+    }
+    for (const entry of state.entries) unlinkAtSync(state.directoryDescriptor, entry.name);
+    fsyncSync(state.directoryDescriptor);
+    // rmdir can only remove an empty directory. No recursive path traversal.
+    assertDirectory(state);
+    rmdirSync(state.path);
+    fsyncSync(state.parentDescriptor);
+  } finally {
+    for (const entry of state.entries) if (entry.descriptor !== undefined) closeSync(entry.descriptor);
+    if (state.directoryDescriptor !== undefined) closeSync(state.directoryDescriptor);
+    if (state.parentDescriptor !== undefined) closeSync(state.parentDescriptor);
+  }
+  return true;
+}
+
+function preparePinnedSnapshot(sources, { projectDir, temporaryRoot = tmpdir() }) {
+  const project = realpathSync(projectDir);
+  const parent = realpathSync(temporaryRoot);
+  if (inside(project, parent)) failure('private executable snapshot must be outside the project');
+  let state;
+  let parentDescriptor;
+  try {
+    const parentStat = lstatSync(parent);
+    parentDescriptor = openSync(parent, DIRECTORY_FLAGS);
+    const pinnedParent = fstatSync(parentDescriptor);
+    if (!parentStat.isDirectory() || !sameInode(parentStat, pinnedParent)
+      || ((pinnedParent.mode & 0o022) !== 0 && (pinnedParent.mode & 0o1000) === 0)) {
+      failure('temporary snapshot parent is unsafe');
+    }
+    const name = `chati-executable-${randomUUID()}`;
+    hook('beforeExecutableSnapshotDirectoryCreate', { parent });
+    mkdirAtSync(parentDescriptor, name, { mode: 0o700 });
+    const directoryDescriptor = openAtSync(parentDescriptor, name, DIRECTORY_FLAGS);
+    state = { parentDescriptor, directoryDescriptor, name, entries: [],
+      path: directoryPathSync(directoryDescriptor), identity: fstatSync(directoryDescriptor) };
+    parentDescriptor = undefined;
+    assertDirectory(state);
+    if (inside(project, state.path)) failure('snapshot directory overlaps the project');
+    for (const source of sources) copyPinnedImage(state, source);
+    fsyncSync(directoryDescriptor);
+    fsyncSync(state.parentDescriptor);
+    const record = Object.freeze({
+      directory: state.path, directoryDescriptor,
+      executablePath: join(state.path, state.entries[0].name),
+      executableSha256: state.entries[0].digest,
+      supportingExecutables: Object.freeze(state.entries.slice(1).map((entry) => Object.freeze({
+        executable_path: join(state.path, entry.name), executable_sha256: entry.digest,
+      }))),
+    });
+    RECORDS.set(record, state);
+    assertExecutableSnapshot(record);
+    return record;
+  } catch (error) {
+    if (state) {
+      try { cleanup(state); } catch (cleanupError) { error.snapshotCleanupError = cleanupError; }
+    }
+    if (parentDescriptor !== undefined) closeSync(parentDescriptor);
+    throw error;
+  }
+}
+
+export function prepareExecutableSnapshot(binding, { harnessId, projectDir, temporaryRoot, requireNativeImage = false } = {}) {
+  const project = realpathSync(projectDir);
+  const sources = [];
+  try {
+    sources.push(openPinnedProviderExecutable(binding, { harnessId, projectDir: project, requireNativeImage }));
+    sources.push(...openPinnedProviderSupportingExecutables(binding, { harnessId, projectDir: project }));
+    for (const source of sources) {
+      if (realpathSync(source.binding.executable_path) !== source.binding.executable_path
+        || inside(project, source.binding.executable_path)) failure('snapshot source must be physically outside the project');
+    }
+    hook('afterExecutableSnapshotSourcesOpen', { sources });
+    return preparePinnedSnapshot(sources, { projectDir: project, temporaryRoot });
+  } finally { for (const source of sources) closeSync(source.descriptor); }
+}
+
+/** The only installed-project source accepted here is a publisher-attested
+ * runtime helper. The provider entrypoint above retains its outside-project
+ * restriction. Both paths copy/hash exactly the already opened source FD. */
+export function prepareRuntimeNativeHelperSnapshot(name, { projectDir, temporaryRoot } = {}) {
+  const source = openAttestedRuntimeNativeHelper(name);
+  try {
+    hook('afterRuntimeHelperSnapshotSourceOpen', { source });
+    return preparePinnedSnapshot([source], { projectDir, temporaryRoot });
+  } finally { closeSync(source.descriptor); }
+}
+
+export function assertExecutableSnapshot(record) {
+  const state = RECORDS.get(record);
+  if (!state) failure('snapshot is unknown or already disposed');
+  assertDirectory(state);
+  for (const entry of state.entries) {
+    const attached = lstatAtSync(state.directoryDescriptor, entry.name);
+    if (!sameInode(attached, entry.identity) || !attached.isFile() || attached.nlink !== 1) {
+      failure('snapshot executable entry changed');
+    }
+    const current = digestProviderExecutable(entry.descriptor, entry.snapshot);
+    if (current.sha256 !== entry.digest) failure('snapshot executable digest changed');
+  }
+  return true;
+}
+
+export function disposeExecutableSnapshot(record) {
+  const state = RECORDS.get(record);
+  if (!state) return false;
+  RECORDS.delete(record);
+  return cleanup(state);
+}

package/src/terminal/handoff-parser.js

@@ -25,6 +25,31 @@ const LEGACY_STATUS_ALIASES = {
   BLOCKED: 'needs_input',
 };
 
+/** Execution completion and the quality verdict are independent facts. */
+export function isPlanningQaOutcomeValid(outcome, threshold) {
+  return Boolean(outcome && Number.isFinite(outcome.score) && outcome.score >= 0 && outcome.score <= 100
+    && ['approved', 'needs_correction'].includes(outcome.gate_result)
+    && Number.isSafeInteger(outcome.blocking_count) && outcome.blocking_count >= 0
+    && (outcome.gate_result !== 'approved' || (outcome.score >= threshold && outcome.blocking_count === 0))
+    && (outcome.gate_result !== 'needs_correction' || outcome.score < threshold || outcome.blocking_count > 0));
+}
+
+export function normalizePlanningQaOutcome(handoff, threshold) {
+  const outcome = {
+    score: handoff?.score,
+    gate_result: handoff?.decisions?.gate_result,
+    blocking_count: Array.isArray(handoff?.blockers) ? handoff.blockers.length : null,
+  };
+  // Old agents sometimes emitted score100 for task completion and score0 in
+  // decisions. Never silently choose between competing quality scores.
+  const alternateScore = handoff?.decisions?.planning_score;
+  if (handoff?.status !== 'complete' || !isPlanningQaOutcomeValid(outcome, threshold)
+    || (alternateScore !== undefined && Number(alternateScore) !== outcome.score)) {
+    return { ok: false, code: 'QA_RESULT_INVALID', error: 'QA must return its planning quality score, an explicit approved/needs_correction verdict, and consistent blockers. Execution completion is not approval.' };
+  }
+  return { ok: true, outcome };
+}
+
 /**
  * Parse the <chati-handoff> block from agent stdout.
  *
@@ -33,7 +58,7 @@ const LEGACY_STATUS_ALIASES = {
  * @param {string} output - Full stdout from the agent process
  * @returns {{ found: boolean, handoff: object|null, rawOutput: string, valid: boolean, warnings: string[] }}
  */
-export function parseAgentOutput(output) {
+export function parseAgentOutput(output, { strict = false } = {}) {
   if (!output || typeof output !== 'string') {
     return { found: false, handoff: null, rawOutput: '', valid: false, warnings: ['No output provided'] };
   }
@@ -44,7 +69,28 @@ export function parseAgentOutput(output) {
   }
 
   const content = match[1].trim();
-  const handoff = parseHandoffFields(content);
+  let handoff;
+  if (strict) {
+    try {
+      if ([...output.matchAll(/<chati-handoff>([\s\S]*?)<\/chati-handoff>/g)].length !== 1) {
+        throw new Error('Exactly one terminal handoff is required.');
+      }
+      // Decisions that can approve a plan must come from unambiguous source
+      // bytes. The permissive legacy parser truncates numeric strings and
+      // overwrites duplicate fields, so it is not a fallback on this path.
+      const document = yaml.load(content, { schema: yaml.JSON_SCHEMA });
+      if (!document || typeof document !== 'object' || Array.isArray(document)) throw new Error('Handoff must be a YAML mapping.');
+      handoff = { ...parseHandoffFields(''), ...document };
+      if ((handoff.score !== null || handoff.status === 'complete')
+        && (!Number.isFinite(handoff.score) || handoff.score < 0 || handoff.score > 100)) {
+        throw new Error('Handoff score must be a finite number from 0 to 100.');
+      }
+    } catch (error) {
+      return { found: true, handoff: null, rawOutput: output, valid: false, warnings: [`Invalid strict handoff: ${error.message}`] };
+    }
+  } else {
+    handoff = parseHandoffFields(content);
+  }
   handoff.status = LEGACY_STATUS_ALIASES[handoff.status] || handoff.status;
 
   // Validate the parsed handoff