chati-dev 4.5.16 → 4.5.28

package/src/terminal/rail-readonly-workspace.js

@@ -0,0 +1,324 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, readlinkSync,
+  realpathSync, mkdirSync, mkdtempSync, rmSync, writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { sha256 } from '@chati/core';
+
+const CANONICAL_RAIL_MUTABLE_PATHS = new Set([
+  '.chati/v2/rail/journal.jsonl',
+  '.chati/v2/rail/journal.jsonl.checkpoint',
+  '.chati/v2/rail/journal.jsonl.lock',
+]);
+const CANONICAL_RAIL_CHECKPOINT_TEMP = /^\.chati\/v2\/rail\/journal\.jsonl\.checkpoint\.\d+\.[a-f0-9-]+\.tmp$/;
+const RAIL_READ_ONLY_WORKSPACE_TEST_HOOKS = Symbol.for('chati.rail.readonly-workspace-test-hooks');
+
+function runReadOnlyWorkspaceTestHook(name, detail) {
+  const hook = globalThis[RAIL_READ_ONLY_WORKSPACE_TEST_HOOKS]?.[name];
+  if (typeof hook === 'function') hook(detail);
+}
+
+function fail(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  error.details = details;
+  throw error;
+}
+
+function trustedGitEnvironment(source = process.env) {
+  const environment = Object.fromEntries(Object.entries(source).filter(([key]) => !key.startsWith('GIT_')));
+  return {
+    ...environment,
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
+    GIT_OPTIONAL_LOCKS: '0',
+    GIT_TERMINAL_PROMPT: '0',
+  };
+}
+
+function git(projectDir, args, options = {}) {
+  try {
+    return execFileSync('git', ['-C', projectDir, ...args], {
+      ...options,
+      env: trustedGitEnvironment(options.env || process.env),
+    });
+  } catch (error) {
+    return fail('RAIL_READ_ONLY_GIT_STATE_UNAVAILABLE', 'cannot capture the Git state required for a read-only RAIL action', { cause: error.message });
+  }
+}
+
+function portableRelative(projectDir, path) {
+  return relative(projectDir, path).split(sep).join('/');
+}
+
+function remainsInside(projectDir, path) {
+  const boundary = relative(projectDir, path);
+  return boundary === '' || (!boundary.startsWith(`..${sep}`) && boundary !== '..' && !isAbsolute(boundary));
+}
+
+function assertInternalSymlink(projectDir, path, target) {
+  const lexicalTarget = resolve(dirname(path), target);
+  if (!remainsInside(projectDir, lexicalTarget)) {
+    fail('RAIL_READ_ONLY_EXTERNAL_SYMLINK', 'read-only RAIL actions do not accept project symlinks that target external material', { path, target });
+  }
+  try {
+    const physicalTarget = realpathSync(path);
+    if (!remainsInside(projectDir, physicalTarget)) {
+      fail('RAIL_READ_ONLY_EXTERNAL_SYMLINK', 'read-only RAIL actions do not accept symlink chains that escape the project', { path, target });
+    }
+  } catch (error) {
+    if (error?.code?.startsWith?.('RAIL_')) throw error;
+    if (error?.code !== 'ENOENT') {
+      fail('RAIL_READ_ONLY_WORKSPACE_UNAVAILABLE', 'cannot resolve a project symlink for the read-only baseline', { path, cause: error.message });
+    }
+  }
+}
+
+function isCanonicalRailMutablePath(relativePath) {
+  return CANONICAL_RAIL_MUTABLE_PATHS.has(relativePath)
+    || CANONICAL_RAIL_CHECKPOINT_TEMP.test(relativePath);
+}
+
+function stableStat(stat) {
+  return {
+    dev: stat.dev,
+    ino: stat.ino,
+    mode: stat.mode,
+    nlink: stat.nlink,
+    size: stat.size,
+    mtime_ms: stat.mtimeMs,
+    ctime_ms: stat.ctimeMs,
+  };
+}
+
+function sameFileState(left, right) {
+  return sha256(stableStat(left)) === sha256(stableStat(right));
+}
+
+function hashRegularFile(path, initialStat) {
+  const hash = createHash('sha256');
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    const opened = fstatSync(descriptor);
+    if (!opened.isFile() || !sameFileState(opened, initialStat)) {
+      fail('RAIL_READ_ONLY_WORKSPACE_UNSTABLE', 'project file changed while the read-only baseline was captured', { path });
+    }
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    for (;;) {
+      const bytes = readSync(descriptor, buffer, 0, buffer.length, null);
+      if (bytes === 0) break;
+      hash.update(buffer.subarray(0, bytes));
+    }
+    const finished = fstatSync(descriptor);
+    if (!sameFileState(opened, finished)) {
+      fail('RAIL_READ_ONLY_WORKSPACE_UNSTABLE', 'project file changed while it was hashed', { path });
+    }
+  } catch (error) {
+    if (error?.code?.startsWith?.('RAIL_')) throw error;
+    fail('RAIL_READ_ONLY_WORKSPACE_UNAVAILABLE', 'cannot safely hash project material for a read-only RAIL action', { path, cause: error.message });
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+  return hash.digest('hex');
+}
+
+function filesystemManifest(projectDir) {
+  const entries = [];
+  const visit = (directory) => {
+    let names;
+    try { names = readdirSync(directory).sort(); }
+    catch (error) {
+      fail('RAIL_READ_ONLY_WORKSPACE_UNAVAILABLE', 'cannot enumerate project material for a read-only RAIL action', { path: directory, cause: error.message });
+    }
+    for (const name of names) {
+      const path = join(directory, name);
+      const relativePath = portableRelative(projectDir, path);
+      if (isCanonicalRailMutablePath(relativePath)) continue;
+      let stat;
+      try { stat = lstatSync(path); }
+      catch (error) {
+        fail('RAIL_READ_ONLY_WORKSPACE_UNSTABLE', 'project material changed while the read-only baseline was enumerated', { path, cause: error.message });
+      }
+      if (stat.isDirectory()) {
+        entries.push({ path: relativePath, type: 'directory', mode: stat.mode });
+        visit(path);
+      } else if (stat.isFile()) {
+        entries.push({ path: relativePath, type: 'file', ...stableStat(stat), digest: hashRegularFile(path, stat) });
+      } else if (stat.isSymbolicLink()) {
+        const target = readlinkSync(path);
+        assertInternalSymlink(projectDir, path, target);
+        entries.push({ path: relativePath, type: 'symlink', mode: stat.mode, target });
+      } else {
+        fail('RAIL_READ_ONLY_SPECIAL_FILE', 'read-only RAIL actions do not accept sockets, FIFOs or device nodes in the project tree', { path: relativePath });
+      }
+    }
+  };
+  visit(projectDir);
+  return entries;
+}
+
+export function captureRailReadOnlyWorkspace({ projectDir } = {}) {
+  const root = resolve(projectDir);
+  const head = git(root, ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+  const manifest = filesystemManifest(root);
+  return Object.freeze({
+    schema_version: 2,
+    project_dir: root,
+    head,
+    filesystem_entry_count: manifest.length,
+    filesystem_digest: sha256(manifest),
+  });
+}
+
+export function assertRailReadOnlyWorkspaceUnchanged({ projectDir, before, label } = {}) {
+  const after = captureRailReadOnlyWorkspace({ projectDir });
+  if (sha256(after) !== sha256(before)) {
+    fail('RAIL_READ_ONLY_WORKSPACE_MUTATED', `${label || 'RAIL read-only action'} changed the project worktree`, { before, after });
+  }
+  return after;
+}
+
+function captureCommitSubject(subjectDir, resultCommitRef, baseCommitRef) {
+  const manifest = filesystemManifest(subjectDir);
+  return Object.freeze({
+    schema_version: 3,
+    base_commit_ref: baseCommitRef,
+    result_commit_ref: resultCommitRef,
+    filesystem_entry_count: manifest.length,
+    filesystem_digest: sha256(manifest),
+  });
+}
+
+function resolveExactCommit(projectDir, commitRef, code, label) {
+  if (!/^[a-f0-9]{40,64}$/.test(commitRef || '')) {
+    fail(code, `read-only RAIL workspace requires a full lowercase ${label} commit id`);
+  }
+  const resolved = git(projectDir, ['rev-parse', '--verify', `${commitRef}^{commit}`], { encoding: 'utf8' }).trim();
+  if (resolved !== commitRef) fail(code, `read-only RAIL workspace resolved a different ${label} commit`);
+  return resolved;
+}
+
+function materializeReviewDelta({ projectDir, baseCommitRef, resultCommitRef, subjectDir }) {
+  const patch = git(projectDir, [
+    'diff', '--no-ext-diff', '--binary', '--full-index', baseCommitRef, resultCommitRef,
+  ], { encoding: null });
+  // git archive intentionally respects export-ignore. The immutable patch is
+  // materialized beside the archive so a reviewer can still inspect every
+  // committed change, including generated metadata omitted from the archive.
+  writeFileSync(join(subjectDir, 'CHATI_RAIL_REVIEW.diff'), patch, { mode: 0o400 });
+}
+
+function openPinnedSubjectDirectory(subjectDir) {
+  let descriptor;
+  try {
+    const before = lstatSync(subjectDir);
+    if (!before.isDirectory() || before.isSymbolicLink()) {
+      fail('RAIL_READ_ONLY_WORKSPACE_UNSAFE', 'review subject directory must be a real directory');
+    }
+    descriptor = openSync(subjectDir, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+    const opened = fstatSync(descriptor);
+    if (!opened.isDirectory() || opened.dev !== before.dev || opened.ino !== before.ino) {
+      fail('RAIL_READ_ONLY_WORKSPACE_UNSAFE', 'review subject directory changed before archive extraction');
+    }
+    return Object.freeze({ descriptor, identity: { dev: opened.dev, ino: opened.ino } });
+  } catch (error) {
+    if (descriptor !== undefined) closeSync(descriptor);
+    if (error?.code?.startsWith?.('RAIL_')) throw error;
+    return fail('RAIL_READ_ONLY_WORKSPACE_UNSAFE', 'review subject directory cannot be opened without following links', { cause: error.message });
+  }
+}
+
+function extractArchiveIntoPinnedSubject(archivePath, subjectDir) {
+  const pinned = openPinnedSubjectDirectory(subjectDir);
+  try {
+    if (process.platform === 'linux') {
+      // The child receives the pinned directory as fd 3, so tar never resolves
+      // the mutable subject pathname after the security check.
+      execFileSync('tar', ['-xf', archivePath, '-C', '/proc/self/fd/3', '--no-same-owner', '--no-same-permissions'], {
+        env: { ...process.env, TAR_OPTIONS: '' },
+        stdio: ['ignore', 'ignore', 'pipe', pinned.descriptor],
+      });
+      return;
+    }
+    const current = lstatSync(subjectDir);
+    if (!current.isDirectory() || current.isSymbolicLink()
+      || current.dev !== pinned.identity.dev || current.ino !== pinned.identity.ino) {
+      fail('RAIL_READ_ONLY_WORKSPACE_UNSAFE', 'review subject directory changed before archive extraction');
+    }
+    execFileSync('tar', ['-xf', archivePath, '-C', subjectDir, '--no-same-owner', '--no-same-permissions'], {
+      env: { ...process.env, TAR_OPTIONS: '' }, stdio: 'ignore',
+    });
+  } finally {
+    closeSync(pinned.descriptor);
+  }
+}
+
+/** Materialize exactly one immutable Git commit without linking its .git dir. */
+export function createRailReadOnlyCommitWorkspace({ projectDir, baseCommitRef, resultCommitRef } = {}) {
+  const canonicalProject = realpathSync(resolve(projectDir));
+  const resolvedBase = resolveExactCommit(canonicalProject, baseCommitRef, 'RAIL_REVIEW_BASE_COMMIT_INVALID', 'base');
+  const resolvedCommit = resolveExactCommit(canonicalProject, resultCommitRef, 'RAIL_REVIEW_RESULT_COMMIT_INVALID', 'result');
+  const root = mkdtempSync(join(tmpdir(), 'chati-rail-review-subject-'));
+  const rootStat = lstatSync(root);
+  const rootIdentity = {
+    dev: rootStat.dev,
+    ino: rootStat.ino,
+    uid: rootStat.uid,
+    gid: rootStat.gid,
+  };
+  const subjectDir = join(root, 'subject');
+  const archivePath = join(root, 'subject.tar');
+  try {
+    mkdirSync(subjectDir, { mode: 0o700 });
+    runReadOnlyWorkspaceTestHook('afterSubjectDirectoryCreate', { root, subjectDir });
+    git(canonicalProject, ['archive', '--format=tar', '--output', archivePath, resultCommitRef], { stdio: 'ignore' });
+    extractArchiveIntoPinnedSubject(archivePath, subjectDir);
+    rmSync(archivePath);
+    materializeReviewDelta({
+      projectDir: canonicalProject, baseCommitRef: resolvedBase, resultCommitRef: resolvedCommit, subjectDir,
+    });
+    const baseline = captureCommitSubject(subjectDir, resolvedCommit, resolvedBase);
+    return Object.freeze({
+      schema_version: 1,
+      root,
+      root_identity: Object.freeze(rootIdentity),
+      subject_dir: subjectDir,
+      canonical_project_dir: canonicalProject,
+      base_commit_ref: resolvedBase,
+      result_commit_ref: resultCommitRef,
+      baseline,
+    });
+  } catch (error) {
+    try { rmSync(root, { recursive: true, force: true }); } catch { /* best-effort cleanup of our private temp */ }
+    if (error?.code?.startsWith?.('RAIL_')) throw error;
+    return fail('RAIL_READ_ONLY_WORKSPACE_UNAVAILABLE', 'cannot materialize the immutable review commit', { cause: error.message });
+  }
+}
+
+export function assertRailReadOnlyCommitWorkspaceUnchanged({ workspace, label } = {}) {
+  const after = captureCommitSubject(workspace.subject_dir, workspace.result_commit_ref, workspace.base_commit_ref);
+  if (sha256(after) !== sha256(workspace.baseline)) {
+    fail('RAIL_READ_ONLY_WORKSPACE_MUTATED', `${label || 'RAIL read-only action'} changed the immutable commit workspace`, {
+      before: workspace.baseline, after,
+    });
+  }
+  return after;
+}
+
+export function cleanupRailReadOnlyCommitWorkspace(workspace) {
+  if (!workspace?.root || !workspace?.root_identity) return false;
+  let current;
+  try { current = lstatSync(workspace.root); }
+  catch (error) { if (error?.code === 'ENOENT') return true; throw error; }
+  if (!current.isDirectory() || current.isSymbolicLink()
+    || current.dev !== workspace.root_identity.dev || current.ino !== workspace.root_identity.ino
+    || current.uid !== workspace.root_identity.uid || current.gid !== workspace.root_identity.gid) {
+    fail('RAIL_READ_ONLY_WORKSPACE_CLEANUP_UNSAFE', 'immutable review workspace root changed before cleanup');
+  }
+  rmSync(workspace.root, { recursive: true });
+  return true;
+}