Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.3 KB
Raw Blame
/**
 * Shared symlink-safe path-confinement + dotfile-trust helpers.
 *
 * Consolidates the realpath-containment idiom that previously lived only in
 * `sources-ops.ts` (`isPathContained`) and `validateUploadPath`
 * (`operations.ts`), and adds `isTrustedDotfile` — the multi-user-host trust
 * gate for walk-up routing dotfiles (`.gbrain-source` / `.gbrain-mount`).
 *
 * Threat model (POSIX multi-user host): an attacker who can write into a
 * shared ancestor directory of the victim's CWD (`/tmp`, `/var/tmp`,
 * `/dev/shm`, shared NFS/SMB, CI runner volumes, container bind-mounts) can
 * plant a routing dotfile that silently retargets the victim's reads/writes
 * to the attacker's source/brain. The walk-up resolvers must therefore refuse
 * a dotfile they can't prove the victim (or root) owns. (#418/#419)
 *
 * Fail-closed: any stat/realpath error → not trusted / not contained. The one
 * documented exception is platforms without numeric uid (Windows), where the
 * multi-user-POSIX threat model does not apply and `isTrustedDotfile` trusts
 * by default so existing single-user setups keep working.
 */

import { realpathSync, existsSync, type Stats } from 'fs';
import { realpath as realpathAsync } from 'fs/promises';
import { resolve as resolvePath, relative, isAbsolute, dirname, basename, join, sep, posix } from 'path';

/**
 * Symlink-safe path confinement: realpath BOTH sides, then a separator-aware
 * prefix check. A plain `startsWith()` on un-resolved paths would let a
 * `parent/skills` symlink → `/etc` (or `$GBRAIN_HOME/clones/<id>` → `/etc`)
 * bypass the boundary; resolving first defeats that.
 *
 * Returns true iff `child` exists AND its realpath is `parent`'s realpath or a
 * real subtree of it. Returns false if either path is unresolvable (missing /
 * permission) or the resolved child escapes — fail-closed.
 */
export function isPathContained(child: string, parent: string): boolean {
  let resolvedChild: string;
  let resolvedParent: string;
  try {
    resolvedChild = realpathSync(child);
    resolvedParent = realpathSync(parent);
  } catch {
    return false; // missing / unresolvable path → not contained
  }
  return resolvedPrefixContained(resolvedChild, resolvedParent, sep);
}

/**
 * Pure separator-aware prefix check over ALREADY-RESOLVED paths — the exact
 * logic that regressed on Windows (#3643/#4103: a hardcoded '/' suffix made
 * every real backslash subdirectory fail the prefix test). Exported so the
 * win32 shapes (drive-letter roots, backslash subtrees, UNC shares) are
 * testable on POSIX CI, where realpathSync can never produce them
 * (gbrain#4103 review requirement — no Windows runner exists).
 */
export function resolvedPrefixContained(
  resolvedChild: string,
  resolvedParent: string,
  sepChar: string,
): boolean {
  // Append the OS separator so /foo doesn't match /foobar. `sep`, not a
  // hardcoded '/': realpathSync returns backslash paths on Windows, so a '/'
  // suffix would make the prefix test fail for every real subdirectory.
  const parentWithSep = resolvedParent.endsWith(sepChar) ? resolvedParent : resolvedParent + sepChar;
  return resolvedChild === resolvedParent || resolvedChild.startsWith(parentWithSep);
}

/**
 * True when a `path.relative(root, x)` result leaves `root`: it is exactly
 * `..`, starts with a `..` path component (`../` or `..` + the platform
 * separator), or is absolute (another drive on Windows). A bare
 * `startsWith('..')` is wrong: it also matches a legal first folder such as
 * `..drafts`, `..x` or `...`, which sits inside the root.
 *
 * Accepts both native and `/`-joined relative paths, because several callers
 * normalize to `/` before checking. `pathOps` lets tests pass `path.win32` to
 * check backslash and drive-letter shapes on POSIX CI. The empty string (the
 * root itself) is NOT an escape; callers keep their own policy for it.
 */
export function relativeEscapesRoot(
  rel: string,
  pathOps: { sep: string; isAbsolute(p: string): boolean } = { sep, isAbsolute },
): boolean {
  return rel === '..' || rel.startsWith('../') || rel.startsWith('..' + pathOps.sep) || pathOps.isAbsolute(rel);
}

/**
 * Trust gate for a walk-up routing dotfile, given its `lstatSync` Stats.
 *
 * The caller MUST pass an `lstatSync` result, never `statSync` — `lstat` does
 * not follow symlinks, so a planted symlink redirect is visible here as
 * `isSymbolicLink()` instead of being followed-then-trusted.
 *
 * Rejects three classes of untrusted file:
 *   1. symlinks — an attacker-planted redirect to a file they control;
 *   2. foreign-owned — `uid` is neither the caller's nor root's (an attacker
 *      can't `chown` a file to the victim, so foreign ownership means planted;
 *      root-owned is trusted — root is the system admin and can write anywhere
 *      regardless);
 *   3. world-writable (`mode & 0o002`) — anyone can clobber it later, even when
 *      ownership is currently legitimate.
 *
 * On platforms without `process.getuid` (Windows) returns true: the
 * multi-user-POSIX threat model does not apply and ownership is unknowable.
 */
export function isTrustedDotfile(stats: Stats): boolean {
  // No numeric uid (Windows) → can't verify ownership; threat model N/A.
  if (typeof process.getuid !== 'function') return true;
  // A symlink is an attacker redirect — never trust. (Requires an lstat Stats.)
  if (stats.isSymbolicLink()) return false;
  const myUid = process.getuid();
  // Foreign-owned (not me, not root) → planted. Root-owned is trusted.
  if (stats.uid !== myUid && stats.uid !== 0) return false;
  // World-writable → anyone can clobber it later, even when ownership is legit.
  if ((stats.mode & 0o002) !== 0) return false;
  return true;
}

/**
 * Resolve a path through symlinks, falling back to lexical `resolve()` when the
 * path doesn't exist (stale registration). Used by the registered-path prefix
 * matchers so a symlinked CWD can't create a false prefix match against a
 * registered `local_path` / mount path while still tolerating a registered path
 * that no longer exists on disk.
 */
export function realpathOrResolve(p: string): string {
  try {
    return realpathSync(p);
  } catch {
    return resolvePath(p);
  }
}

/**
 * Convert a Git Bash / MSYS / Cygwin drive path to native Windows form
 * (gbrain#2955): `/c/Users/x` and `/cygdrive/c/Users/x` → `C:\Users\x`.
 *
 * On Windows, a `sources add --path` run from Git Bash records an msys-style
 * `local_path`. Every later `path.win32.resolve(cwd, '/c/Users/x')` joins it
 * as `<cwd-drive>:\c\Users\x` — a phantom path that never exists — so
 * write-through / sync silently target a directory nothing ever created.
 *
 * Pure and platform-parameterized (defaults to `process.platform`) so the
 * win32 branch is unit-testable on POSIX CI, mirroring
 * `resolvedPrefixContained` above. On non-win32 platforms it is identity —
 * `/c/…` is a legitimate directory name there. Anything that doesn't match
 * the drive shape (native paths, UNC shares, relative paths, non-drive
 * absolutes) passes through unchanged.
 */
export function msysToNativePath(
  p: string,
  platform: NodeJS.Platform = process.platform,
): string {
  if (platform !== 'win32' || !p) return p;
  const m = /^\/(?:cygdrive\/)?([A-Za-z])(\/.*)?$/.exec(p);
  if (!m) return p;
  const drive = m[1]!.toUpperCase();
  const rest = (m[2] ?? '').replace(/\//g, '\\');
  return `${drive}:${rest || '\\'}`;
}

/** The platform the loaded `path` module resolves for: the stored-root verdict follows the module that resolves the root. */
const PATH_PLATFORM: NodeJS.Platform = sep === '\\' ? 'win32' : 'linux';

/**
 * #7646: is a stored root (`sources.local_path`, `sync.repo_path`) absolute on THIS host? The one predicate sync,
 * `config set`, write-through, `sources set-path --clear` and doctor share. On win32 only a drive path (`C:\\x`, or a
 * Git Bash `/c/x`, healed by `msysToNativePath`) or a UNC share counts: `path.win32.isAbsolute` also accepts the
 * root-relative `\\brain` and `/brain`, which resolve against whatever drive gbrain runs from. On POSIX it is
 * `path.posix.isAbsolute`, so a Windows drive path another host stored is not absolute here.
 */
export function isHostAbsolutePath(p: string, platform: NodeJS.Platform = PATH_PLATFORM): boolean {
  if (platform !== 'win32') return posix.isAbsolute(p);
  return /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/])/.test(msysToNativePath(p, platform));
}

/** #7646: a stored root absolute only on another operating system (a Windows drive or UNC path on POSIX, a POSIX path on win32). */
export function isForeignAbsolutePath(p: string, platform: NodeJS.Platform = PATH_PLATFORM): boolean {
  if (isHostAbsolutePath(p, platform)) return false;
  return platform === 'win32' ? posix.isAbsolute(p) && !/^[\\/]{2}/.test(p) : isHostAbsolutePath(p, 'win32');
}

/**
 * Async twin of `realpathOrResolve` — same fallback contract, but backed by
 * `fs.promises.realpath` instead of `realpathSync`. Exists so a caller
 * resolving N independent paths (e.g. every registered source's local_path)
 * can `Promise.all` them and let a slow/interrupted filesystem stall on ONE
 * path without serializing behind the others: `realpathSync` blocks the
 * event loop for its full duration no matter how many `Promise.all`-wrapped
 * calls surround it (#4091-class root-cause), so parallelizing the SYNC
 * function would still take sum-of-durations, not max-of-durations. Use this
 * version whenever more than one path is being resolved together.
 *
 * The lexical fallback below is the same shape as the sync version above
 * (unflagged there only because semgrep's diff-scoped CI scan doesn't
 * re-flag pre-existing lines): `p` is never raw untrusted input at this
 * call site — a registered source's local_path or the CLI's own cwd — and
 * this is the fallback for a path that already failed to realpath
 * (ENOENT/stale registration). The security boundary is the caller's
 * realpath-both-sides prefix/containment check afterward, not this
 * resolve() call.
 */
export async function realpathOrResolveAsync(p: string): Promise<string> {
  try {
    return await realpathAsync(p);
  } catch {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
    return resolvePath(p);
  }
}

/**
 * Containment check for a write TARGET that may not exist yet (a new page file).
 * `isPathContained` requires the child to already exist; this instead realpaths
 * the deepest EXISTING ancestor of `target` (catching a symlinked intermediate
 * directory that escapes the tree) and re-attaches the not-yet-created tail
 * lexically, then confirms the result stays within `root`.
 *
 * Defense-in-depth for the write-through FS sink (#1647-slug / codex #6):
 * `validateSlug` already rejects `..`/backslash/control/%2e in the slug, so this
 * guards a pre-existing hostile row or a symlinked source-tree subdirectory.
 */
export function isWriteTargetContained(target: string, root: string): boolean {
  const resolvedRoot = realpathOrResolve(root);
  let existing = resolvePath(target);
  const tail: string[] = [];
  for (let i = 0; i < 4096 && !existsSync(existing); i++) {
    tail.unshift(basename(existing));
    const parent = dirname(existing);
    if (parent === existing) break; // filesystem root
    existing = parent;
  }
  const base = realpathOrResolve(existing);
  const finalPath = tail.length ? join(base, ...tail) : base;
  const rel = relative(resolvedRoot, finalPath);
  return !relativeEscapesRoot(rel);
}