Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.6 KB
Raw Blame
/**
 * Git invocation for directories gbrain does not trust (a user-chosen checkout,
 * a candidate clone): the repository's own configuration must not run code or
 * reach the network. Every call scrubs `GIT_*` from the environment, ignores
 * system and global config, and disables fsmonitor, hooks, the untracked
 * cache, submodule recursion, protocols, credential helpers and automatic
 * maintenance. Arguments are an argv array, never a shell string. Callers
 * bound time and output (`company-brain/revision.ts` streams with its own
 * caps; `hardenedGitSync` takes a timeout and a byte cap).
 *
 * Git has no switch that turns off `filter.<driver>.clean|process` or
 * `diff.<driver>.textconv` from the repository's config, and porcelain such as
 * `status`, `diff`, `show` or `add` runs them whenever it converts working-tree
 * bytes. So only plumbing that never converts content is allowed
 * (`assertHardenedGitArgs`, wave 12 W4.3), and `hardenedPathDirty` answers
 * "is this file changed from HEAD" without `git status`.
 */
import { execFile, spawn, spawnSync } from './spawn.ts';
import { promisify } from 'node:util';
import { lstatSync } from 'node:fs';
import { once } from 'node:events';
import type { Writable } from 'node:stream';
import { join } from 'node:path';
import { envSafeDirectories, gitChildEnv, safeDirectoryEnv } from './git-env.ts';

export const HARDENED_GIT_ARGS: readonly string[] = ['--no-pager', '--no-optional-locks', '--no-replace-objects',
  '-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', '-c', 'core.untrackedCache=false',
  '-c', 'submodule.recurse=false', '-c', 'protocol.allow=never', '-c', 'credential.helper=',
  '-c', 'maintenance.auto=false', '-c', 'gc.auto=0'];

/**
 * GST-2331: what a managed-sync Git read that runs under `gitChildEnv` adds to it beside `HARDENED_GIT_ARGS`. In a partial
 * clone, Git fetches an object the repository lacks from the clone's remote; `GIT_NO_LAZY_FETCH=1` (Git 2.45+) reports the
 * object missing instead. On any Git, an empty `GIT_ALLOW_PROTOCOL` allows no transport and
 * overrides every `protocol.allow` and `protocol.<name>.allow` setting (an inherited allowlist or a per-protocol config
 * would otherwise beat the args' `protocol.allow=never`), so the read fails and nothing is fetched.
 */
export const NO_LAZY_FETCH_ENV: NodeJS.ProcessEnv = { GIT_NO_LAZY_FETCH: '1', GIT_ALLOW_PROTOCOL: '' };
let lazyFetchOff = true;

/** Test seam: `false` leaves `GIT_NO_LAZY_FETCH` (never the empty `GIT_ALLOW_PROTOCOL`) out of every hardened and managed-sync read, as a git older than 2.45 ignores it; returns the restore. */
export function __setNoLazyFetchForTests(value: boolean): () => void {
  const previous = lazyFetchOff;
  lazyFetchOff = value;
  return () => { lazyFetchOff = previous; };
}

/** `NO_LAZY_FETCH_ENV` as the test seam above leaves it, for a read under `gitChildEnv`. */
export const noLazyFetchEnv = (): NodeJS.ProcessEnv => lazyFetchOff ? NO_LAZY_FETCH_ENV : { ...NO_LAZY_FETCH_ENV, GIT_NO_LAZY_FETCH: undefined };

const OPERATOR_CONFIG_TTL_MS = 30_000;
let operatorConfig: { key: string; at: number; values: string[] } | null = null;

/**
 * #7584: the `safe.directory` entries in the operator's system and global Git config, in Git's order, read from `/` so no
 * repository's config takes part. Re-read every 30 s, so a running server picks up an edit without a restart.
 */
function operatorConfigSafeDirectories(): string[] {
  const key = operatorConfigKey();
  const known = freshOperatorConfig(key);
  if (known) return known;
  const run = spawnSync('git', OPERATOR_CONFIG_ARGS, { ...operatorConfigOptions(), env: { ...gitChildEnv(), LC_ALL: 'C' }, stdio: ['ignore', 'pipe', 'ignore'] });
  return rememberOperatorConfig(key, run.status === 0 ? run.stdout : null);
}

/** GBRA-133: the same read without blocking, for `hardenedGitStream`, so an asynchronous Git read spawns no synchronous Git. */
async function operatorConfigSafeDirectoriesAsync(): Promise<string[]> {
  const key = operatorConfigKey();
  const known = freshOperatorConfig(key);
  if (known) return known;
  const stdout = await promisify(execFile)('git', OPERATOR_CONFIG_ARGS, { ...operatorConfigOptions(), env: { ...gitChildEnv(), LC_ALL: 'C' }, encoding: 'buffer' }).then(run => run.stdout, () => null);
  return rememberOperatorConfig(key, stdout);
}

const OPERATOR_CONFIG_ARGS = ['config', '--includes', '--show-scope', '-z', '--get-all', 'safe.directory'];
const operatorConfigOptions = () => ({ cwd: '/', timeout: 10_000, maxBuffer: 1024 * 1024, killSignal: 'SIGKILL' as const });
const operatorConfigKey = () => ['HOME', 'XDG_CONFIG_HOME', 'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_NOSYSTEM', 'PATH'].map(name => process.env[name] ?? '').join('\0');
const freshOperatorConfig = (key: string) => operatorConfig?.key === key && Date.now() - operatorConfig.at < OPERATOR_CONFIG_TTL_MS ? operatorConfig.values : null;

/** Git's `-z --show-scope` output (null when the read failed) as the system and global entries, cached under `key`. */
function rememberOperatorConfig(key: string, stdout: Buffer | null): string[] {
  const fields = stdout ? stdout.toString('utf8').split('\0') : [];
  const values: string[] = [];
  for (let i = 0; i + 1 < fields.length; i += 2) if (fields[i] === 'system' || fields[i] === 'global') values.push(fields[i + 1]!);
  operatorConfig = { key, at: Date.now(), values };
  return values;
}

export function __resetOperatorGitConfigForTests(): void { operatorConfig = null; }

/**
 * System and global config stay off and every `GIT_*` variable is dropped, except the operator's `safe.directory` entries
 * (system, global, then environment, as Git orders them), carried as environment config (#7584). They relax only Git's
 * ownership check for a repository owned by another user, which the operator allowed for their own `git` too. GST-2331: an
 * empty `GIT_ALLOW_PROTOCOL` allows no transport whatever the repository's `protocol.<name>.allow` says, so a read in a
 * partial clone fetches nothing even on a Git that ignores `GIT_NO_LAZY_FETCH`.
 */
export function hardenedGitEnvironment(operatorSafeDirectories: string[] = operatorConfigSafeDirectories()): NodeJS.ProcessEnv {
  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
  return { ...env, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_OPTIONAL_LOCKS: '0',
    ...(lazyFetchOff ? { GIT_NO_LAZY_FETCH: '1' } : {}), GIT_ALLOW_PROTOCOL: '', GIT_NO_REPLACE_OBJECTS: '1', GIT_TERMINAL_PROMPT: '0', GIT_LFS_SKIP_SMUDGE: '1', LC_ALL: 'C',
    ...safeDirectoryEnv([...operatorSafeDirectories, ...envSafeDirectories()]) };
}

export type HardenedGitResult = { ok: true; stdout: Buffer } | { ok: false; reason: 'exit' | 'timeout' | 'too_large' | 'unavailable'; status?: number; stderr?: string };

/**
 * GBRA-217: the one `git log` gbrain runs in an untrusted checkout, the reason-trailer read (`reason-trailers.ts`). A
 * name-only listing of the first-parent line with no renames compares tree entries only, so no filter, textconv or
 * external diff runs; signatures are not verified (no gpg). Every option is required, so no other `log` passes.
 */
export const REASON_LOG_OPTIONS: readonly string[] = ['-z', '--first-parent', '--diff-merges=first-parent', '--root', '--name-only', '--no-renames', '--no-relative',
  '--no-ext-diff', '--no-textconv', '--no-show-signature', '--format=%x00%H%x00%(trailers:key=gbrain-reason,valueonly,unfold)'];

/**
 * The second `git log` gbrain runs in an untrusted checkout, the direction-evidence history read (persistence/git-gap.ts
 * `readPathHistory`): a raw listing (modes and full blob ids, no patch) of every commit, merges against their first
 * parent, with no renames, so only tree entries are compared and no filter, textconv or external diff runs. Every option
 * is required.
 */
export const HISTORY_LOG_OPTIONS: readonly string[] = ['-z', '--raw', '--no-abbrev', '--full-history', '--root', '--diff-merges=first-parent', '--no-renames', '--no-relative',
  '--no-ext-diff', '--no-textconv', '--no-show-signature', '--format=%x1e%H%x1f%ct'];
/** Each `log` shape allowed: its options exactly, all of them. */
const LOG_SHAPES: ReadonlyArray<readonly string[]> = [REASON_LOG_OPTIONS, HISTORY_LOG_OPTIONS];

/**
 * The exact options each allowed plumbing subcommand may take; anything not
 * listed here refuses.
 */
const ALLOWED_OPTIONS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
  ['rev-parse', new Set(['--show-toplevel', '--absolute-git-dir', '--git-common-dir', '--verify', '--quiet', '--show-object-format'])],
  ['ls-files', new Set(['-s', '--stage', '--eol', '-z', '--cached', '--others', '--exclude-standard'])],
  ['ls-tree', new Set(['-r', '-l', '-z', '--full-tree'])],
  ['cat-file', new Set(['--batch', '--batch-check'])],
  ['hash-object', new Set(['--no-filters', '--stdin-paths'])],
  ['check-attr', new Set(['-z', '--stdin'])],
  ['check-ignore', new Set(['-z', '--stdin'])],
  ['diff-index', new Set(['--cached', '--quiet'])],
  ['diff-tree', new Set(['-r', '-z', '--no-renames'])],
  ['log', new Set(LOG_SHAPES.flat())],
]);

/** Options a subcommand must carry, so its output stays raw and machine-readable. */
const REQUIRED_OPTIONS: ReadonlyMap<string, readonly string[]> = new Map([
  ['hash-object', ['--no-filters']],
  ['diff-index', ['--cached']],
  ['diff-tree', ['-r', '-z', '--no-renames']],
]);

/**
 * Refuses (throws) any Git invocation that could run a repository-configured
 * clean/process filter or textconv: only the allow-listed plumbing with its
 * exact options before `--`/`--end-of-options`, `hash-object` only under
 * `--no-filters`, `diff-index` only `--cached` and `diff-tree` only as
 * `-r -z --no-renames` (a raw listing: no patch, textconv or rename scoring).
 */
export function assertHardenedGitArgs(args: readonly string[]): void {
  const sub = args[0] ?? '';
  const allowed = ALLOWED_OPTIONS.get(sub);
  const end = args.findIndex(arg => arg === '--' || arg === '--end-of-options');
  const options = args.slice(1, end < 0 ? undefined : end).filter(arg => arg.startsWith('-'));
  const ok = allowed !== undefined && options.every(arg => allowed.has(arg))
    && (REQUIRED_OPTIONS.get(sub) ?? []).every(arg => options.includes(arg))
    && (sub !== 'log' || LOG_SHAPES.some(shape => shape.every(arg => options.includes(arg)) && options.every(arg => shape.includes(arg))));
  if (!ok) throw new Error(`hardened git refuses \`git ${args.slice(0, 2).join(' ')}\`: only filter-free plumbing may run in an untrusted checkout (see src/core/hardened-git.ts)`);
}

/**
 * Runs `git -C <root> <args>` synchronously under the hardening above, within `timeoutMs` and `maxBytes` of stdout. With
 * `stderr`, a nonzero exit carries Git's message, so a caller can tell one failure from another.
 */
export function hardenedGitSync(root: string, args: string[], limits: { timeoutMs: number; maxBytes: number; stderr?: boolean }): HardenedGitResult {
  assertHardenedGitArgs(args);
  const run = spawnSync('git', [...HARDENED_GIT_ARGS, '-C', root, ...args],
    { env: hardenedGitEnvironment(), stdio: ['ignore', 'pipe', limits.stderr ? 'pipe' : 'ignore'], timeout: limits.timeoutMs, maxBuffer: limits.maxBytes, killSignal: 'SIGKILL' });
  const code = (run.error as NodeJS.ErrnoException | undefined)?.code;
  if (code === 'ETIMEDOUT') return { ok: false, reason: 'timeout' };
  if (code === 'ENOBUFS') return { ok: false, reason: 'too_large' };
  if (run.error) return { ok: false, reason: 'unavailable' };
  if (run.status !== 0) return { ok: false, reason: 'exit', ...(run.status === null ? {} : { status: run.status }), ...(limits.stderr && run.stderr ? { stderr: run.stderr.toString('utf8') } : {}) };
  return { ok: true, stdout: run.stdout };
}

export type HardenedGitStreamResult = { ok: true; exitCode: 0; signal: null; bytes: number; endsWithNul: boolean }
  | { ok: false; reason: 'exit' | 'signal' | 'timeout' | 'too_large' | 'unavailable' | 'stalled'; status?: number; signal?: NodeJS.Signals };

/**
 * How long stdout may sit idle after Git exited while it is being read (not held by `onChunk`). Bun can lose the readiness
 * of a child's stdout that turns readable as the child exits (#7053: the one-shot poll fired and was never re-armed, the
 * output and EOF left unread), so `close` never comes; such a run fails as `stalled` instead of waiting forever.
 */
const EXITED_STDOUT_IDLE_MS = 5_000;
export type HardenedGitInput = string | Buffer | Iterable<Buffer | string> | AsyncIterable<Buffer | string>;

/**
 * Runs `git -C <root> <args>` asynchronously under the same hardening and
 * allow-list as `hardenedGitSync`, streaming stdout to `onChunk` (nothing is
 * buffered here) and feeding `stdin` with backpressure. The process is killed
 * with SIGKILL past `timeoutMs` or `maxBytes` of stdout. A throw from
 * `onChunk` or from a `stdin` iterable kills the process and rejects, so a
 * caller never mistakes a run cut short for a finished one. An `onChunk` that
 * returns a promise holds stdout until it settles (a large read yields to the
 * event loop between chunks); a rejection fails the run like a throw. The operator's `safe.directory` read it needs runs
 * asynchronously too (GBRA-133), so the whole read spawns no synchronous Git.
 */
export function hardenedGitStream(root: string, args: string[],
  opts: { stdin?: HardenedGitInput; timeoutMs: number; maxBytes?: number; onChunk?: (chunk: Buffer) => void | Promise<void> }): Promise<HardenedGitStreamResult> {
  try { assertHardenedGitArgs(args); } catch (error) { return Promise.reject(error); }
  // GBRA-133: not an async function and no callback below names `opts`, so no timer or listener closes over the caller's
  // options, and the chunk handler is dropped once the read settled. Before, an async function's parameters were captured by
  // every callback here: the exited-stdout idle timer kept the caller's `onChunk` (and through it the whole pass that read)
  // reachable for seconds after the read had ended.
  const { stdin, timeoutMs, maxBytes } = opts;
  let onChunk = opts.onChunk;
  return operatorConfigSafeDirectoriesAsync().then(operator => new Promise<HardenedGitStreamResult>((accept, reject) => {
    const child = spawn('git', [...HARDENED_GIT_ARGS, '-C', root, ...args],
      { env: hardenedGitEnvironment(operator), stdio: [stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'] });
    let bytes = 0;
    let last = -1;
    let stopped: 'timeout' | 'too_large' | undefined;
    let failure: { error: unknown } | undefined;
    let settled = false;
    let exited = false;
    let holding = false;
    let idle: ReturnType<typeof setTimeout> | undefined;
    const settle = (outcome: () => void): void => { if (settled) return; settled = true; onChunk = undefined; clearTimeout(timer); clearTimeout(idle); outcome(); };
    const fail = (error: unknown): void => { failure ??= { error }; child.kill('SIGKILL'); };
    const timer = setTimeout(() => { stopped ??= 'timeout'; child.kill('SIGKILL'); }, timeoutMs);
    const watchIdle = (): void => {
      clearTimeout(idle);
      if (exited && !holding) idle = setTimeout(() => settle(() => failure ? reject(failure.error) : accept({ ok: false, reason: stopped ?? 'stalled' })), EXITED_STDOUT_IDLE_MS);
    };
    child.stdout?.on('data', (chunk: Buffer) => {
      if (settled || stopped || failure) return;
      bytes += chunk.length;
      if (maxBytes !== undefined && bytes > maxBytes) { stopped = 'too_large'; child.kill('SIGKILL'); return; }
      last = chunk[chunk.length - 1] ?? last;
      let held: void | Promise<void>;
      try { held = onChunk?.(chunk); } catch (error) { fail(error); return; }
      if (held) { holding = true; child.stdout?.pause(); held.then(() => { holding = false; watchIdle(); child.stdout?.resume(); }, fail); }
      watchIdle();
    });
    child.on('exit', () => { exited = true; watchIdle(); });
    child.on('error', () => { if (child.pid === undefined) settle(() => accept({ ok: false, reason: 'unavailable' })); });
    child.on('close', (code: number | null, signal: NodeJS.Signals | null) => settle(() => {
      if (failure) reject(failure.error);
      else if (stopped) accept({ ok: false, reason: stopped });
      else if (signal) accept({ ok: false, reason: 'signal', signal });
      else if (code !== 0) accept({ ok: false, reason: 'exit', ...(code === null ? {} : { status: code }) });
      else accept({ ok: true, exitCode: 0, signal: null, bytes, endsWithNul: last === 0 });
    }));
    if (stdin !== undefined && child.stdin) void feedStdin(child.stdin, stdin, fail);
  }));
}

async function feedStdin(stdin: Writable, input: HardenedGitInput, fail: (error: unknown) => void): Promise<void> {
  stdin.on('error', () => {});
  if (typeof input === 'string' || Buffer.isBuffer(input)) { stdin.end(input); return; }
  try {
    for await (const piece of input) {
      if (stdin.destroyed) return;
      if (!stdin.write(piece)) await once(stdin, 'drain');
    }
    stdin.end();
  } catch (error) {
    if (stdin.destroyed) return;
    fail(error);
  }
}

/**
 * Splits a NUL-terminated record stream (`-z` output) into complete records
 * across chunk boundaries; bytes after the last NUL wait for the next chunk.
 */
export class NulRecordSplitter {
  private pending: Buffer[] = [];
  push(chunk: Buffer): Buffer[] {
    const records: Buffer[] = [];
    let start = 0;
    for (let end = chunk.indexOf(0); end >= 0; end = chunk.indexOf(0, start)) {
      const piece = chunk.subarray(start, end);
      records.push(this.pending.length === 0 ? piece : Buffer.concat([...this.pending, piece]));
      this.pending = [];
      start = end + 1;
    }
    if (start < chunk.length) this.pending.push(chunk.subarray(start));
    return records;
  }
  /** Whether every byte pushed so far belongs to a NUL-terminated record (true before any byte). */
  get atRecordBoundary(): boolean { return this.pending.length === 0; }
}

/**
 * The completeness rule for a `-z` read: Git exited 0, was not signalled,
 * and its output ended exactly at a NUL (an empty output is complete). Any
 * other read may be truncated and must not be trusted for absence.
 */
export function hardenedStreamComplete(result: HardenedGitStreamResult): boolean {
  return result.ok && (result.bytes === 0 || result.endsWithNul);
}

const PATH_LIMITS = { timeoutMs: 10_000, maxBytes: 1024 * 1024 };

/**
 * Whether `rel` (repository-relative, `/`-separated) differs from HEAD the
 * way `git status --porcelain -- <rel>` would report it, computed from
 * filter-free plumbing: untracked and not ignored, staged (index differs from
 * HEAD, or unborn HEAD), or working-tree bytes differ from the index blob.
 * `null` when Git cannot say without running repository code or reading
 * config: a conversion attribute (`filter`, `text`, `eol`,
 * `working-tree-encoding`), CRLF working-tree bytes (`core.autocrlf`), a
 * symlink or gitlink, an executable-bit-only difference (`core.filemode`), or
 * any Git failure.
 */
export function hardenedPathDirty(root: string, rel: string): boolean | null {
  const pathspec = `:(literal)${rel}`;
  const indexed = hardenedGitSync(root, ['ls-files', '-s', '--eol', '-z', '--', pathspec], PATH_LIMITS);
  if (!indexed.ok) return null;
  const entry = indexed.stdout.toString('utf8').split('\0')[0];
  if (!entry) {
    const untracked = hardenedGitSync(root, ['ls-files', '-z', '--others', '--exclude-standard', '--', pathspec], PATH_LIMITS);
    return untracked.ok ? untracked.stdout.length > 0 : null;
  }
  const [meta = '', eolInfo = ''] = entry.split('\t');
  const [mode, blob, stage] = meta.split(' ');
  const worktreeEol = eolInfo.trim().split(/\s+/)[1];
  if (!mode || !blob || !stage) return null;
  if (stage !== '0') return true;
  if (mode !== '100644' && mode !== '100755') return null;
  const head = hardenedGitSync(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], PATH_LIMITS);
  if (!head.ok) return head.reason === 'exit' && head.status === 1 ? true : null;
  const staged = hardenedGitSync(root, ['diff-index', '--cached', '--quiet', 'HEAD', '--', pathspec], PATH_LIMITS);
  if (!staged.ok) return staged.reason === 'exit' && staged.status === 1 ? true : null;
  const hashed = hardenedGitSync(root, ['hash-object', '--no-filters', '--', rel], PATH_LIMITS);
  if (!hashed.ok) return null;
  let executable: boolean;
  try { executable = (lstatSync(join(root, ...rel.split('/'))).mode & 0o111) !== 0; } catch { return null; }
  if (hashed.stdout.toString('utf8').trim() === blob) return executable === (mode === '100755') ? false : null;
  if (worktreeEol === 'w/crlf' || worktreeEol === 'w/mixed') return null;
  const attrs = hardenedGitSync(root, ['check-attr', '-z', 'filter', 'text', 'eol', 'working-tree-encoding', '--', rel], PATH_LIMITS);
  if (!attrs.ok) return null;
  const values = attrs.stdout.toString('utf8').split('\0').filter((_, i) => i % 3 === 2);
  return values.every(value => value === 'unspecified' || value === 'unset') ? true : null;
}