Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

8.0 KB
Raw Blame
import {
  closeSync,
  constants,
  fchmodSync,
  fstatSync,
  fsyncSync,
  lstatSync,
  mkdirSync,
  openSync,
  readFileSync,
  realpathSync,
  statSync,
} from 'node:fs'
import { homedir } from 'node:os'
import { win32 } from 'node:path'

const PRIVATE_DIRECTORY_MODE = 0o700
const PRIVATE_FILE_MODE = 0o600

function ownerUid(): number | null {
  return typeof process.getuid === 'function' ? process.getuid() : null
}

function isMissing(error: unknown): boolean {
  return (error as NodeJS.ErrnoException).code === 'ENOENT'
}

/**
 * Windows: the folders state may live in. POSIX mode bits mean nothing on NTFS (Node reports every directory as
 * 0o666 or 0o777, so the checks below refused them all, and the registry could not be saved). What protects a
 * folder there is its ACL, and the user's profile (`os.homedir()`) is one only its owner, SYSTEM and the
 * administrators can write; new folders and files in it inherit that. So state must be in the profile, or in the
 * data folder the person configured themselves (`ADAPTER_DATA_DIR`), whose ACL is then theirs to choose. Node
 * cannot set an ACL: state is created with the same modes as on Unix, which Windows ignores but for read-only.
 */
export function windowsStateRoots(environment: NodeJS.ProcessEnv = process.env, home: string = homedir()): string[] {
  const configured = environment.ADAPTER_DATA_DIR?.trim()
  return [home, ...(configured ? [configured] : [])].filter(Boolean)
}

/** Whether the real path [target] is one of [roots] or below one, compared as Windows does (case-insensitively). */
export function insideWindowsRoots(target: string, roots: readonly string[]): boolean {
  return roots.some((root) => {
    const rel = win32.relative(root, target)
    return rel === '' || (rel !== '..' && !rel.startsWith('..\\') && !win32.isAbsolute(rel))
  })
}

function realRoots(): string[] {
  return windowsStateRoots().flatMap((root) => {
    try { return [realpathSync.native(root)] } catch { return [] }
  })
}

/** The Windows check for a state path: resolved through junctions and links, it must be inside the roots. */
function requireInsideWindowsRoots(path: string, kind: 'directory' | 'file'): void {
  const real = realpathSync.native(path)
  if (!insideWindowsRoots(real, realRoots())) {
    throw new Error(`state ${kind} ${path} is outside your user profile (${homedir()}), so its contents cannot be`
      + ' trusted. Keep Harness state in your profile, or set ADAPTER_DATA_DIR to the folder you want it in.')
  }
}

/**
 * Windows: a state file a credential is read from (the hook credential, the daemon token, lib/windows/pipeAuth.ts).
 * The file must not be a link or junction itself (Node's lstat reports both as symbolic links), and resolved, it
 * must be inside the state roots. Windows' open has no O_NOFOLLOW (the constant is undefined there). So this check
 * is what keeps a link planted in the data folder from handing the daemon another file. Throws otherwise.
 */
export function requireWindowsStateFile(file: string): void {
  if (lstatSync(file).isSymbolicLink()) {
    throw new Error(`state file ${file} is a link or junction; a credential is never read through one`)
  }
  requireInsideWindowsRoots(file, 'file')
}

/**
 * Make a rename or create in [directory] durable: fsync the directory, opened with [flags] (`'r'` by default).
 * Windows cannot: Node opens a directory read-only there, and flushing such a handle is EPERM, so every state
 * save failed after its rename. NTFS journals the rename itself; the file's data was flushed before it.
 */
export function syncStateDirectory(directory: string, flags: number | string = 'r'): void {
  if (!directorySyncSupported()) return
  const fd = openSync(directory, flags)
  try { fsyncSync(fd) } finally { closeSync(fd) }
}

/**
 * Whether a directory handle can be flushed here, for a caller that holds one open to check what it is before the
 * flush (`syncStateDirectory` opens its own): not on Windows, for the same reason.
 */
export function directorySyncSupported(): boolean {
  return process.platform !== 'win32'
}

function secureWindowsStateDirectory(directory: string, create: boolean): void {
  if (create) mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY_MODE })
  if (!statSync(directory).isDirectory()) throw new Error('state directory has unsafe owner or type')
  requireInsideWindowsRoots(directory, 'directory')
}

export function secureStateDirectory(directory: string, create = true): void {
  if (process.platform === 'win32') {
    secureWindowsStateDirectory(directory, create)
    return
  }
  if (create) mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY_MODE })
  const fd = openSync(
    directory,
    constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
  )
  try {
    const stat = fstatSync(fd)
    const uid = ownerUid()
    if (!stat.isDirectory() || (uid !== null && stat.uid !== uid)) {
      throw new Error('state directory has unsafe owner or type')
    }
    const mode = stat.mode & 0o777
    // Refuse — deliberately do NOT chmod and carry on. If another account could write here, it could
    // already have planted the registry, the token or the hook credential, and tightening afterwards
    // would leave us trusting whatever it left behind. Three tests pin this (registry.spec.ts,
    // hookAuth.spec.ts, terminalConfigSnapshot.spec.ts); the fix belongs at creation time, and every
    // site that makes a directory under ADAPTER_DATA_DIR now passes mode 0o700 so Ubuntu's default
    // umask 0002 can no longer produce a 0775 one. This branch is what a PRE-EXISTING 0775 directory
    // (made by an older build on Ubuntu) lands in, so the message has to say what to do about it.
    if ((mode & 0o022) !== 0) {
      throw new Error(`state directory ${directory} is group/world writable, so its contents cannot be`
        + ` trusted. If you did not set that mode yourself, delete it; otherwise: chmod 700 ${directory}`)
    }
    if (mode !== PRIVATE_DIRECTORY_MODE) {
      fchmodSync(fd, PRIVATE_DIRECTORY_MODE)
      if ((fstatSync(fd).mode & 0o777) !== PRIVATE_DIRECTORY_MODE) {
        throw new Error('state directory permissions could not be tightened')
      }
    }
  } finally {
    closeSync(fd)
  }
}

function inspectPrivateStateFile(fd: number, maxBytes: number): void {
  const stat = fstatSync(fd)
  const uid = ownerUid()
  if (!stat.isFile() || (uid !== null && stat.uid !== uid)) {
    throw new Error('state file has unsafe owner or type')
  }
  if (stat.size > maxBytes) throw new Error('state file exceeds its size limit')
  // Windows: the mode is not what protects it (see windowsStateRoots); the callers checked where it is.
  if (process.platform === 'win32') return
  const mode = stat.mode & 0o777
  // Same reasoning as secureStateDirectory: a file another account could have rewritten is not made
  // trustworthy by tightening it now. Every writer under ADAPTER_DATA_DIR already passes mode 0o600.
  if ((mode & 0o022) !== 0) throw new Error('state file is group/world writable')
  if (mode !== PRIVATE_FILE_MODE) {
    fchmodSync(fd, PRIVATE_FILE_MODE)
    if ((fstatSync(fd).mode & 0o777) !== PRIVATE_FILE_MODE) {
      throw new Error('state file permissions could not be tightened')
    }
  }
}

export function readPrivateStateFile(file: string, maxBytes = Number.MAX_SAFE_INTEGER): string {
  if (process.platform === 'win32') requireInsideWindowsRoots(file, 'file')
  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
  try {
    inspectPrivateStateFile(fd, maxBytes)
    return readFileSync(fd, 'utf8')
  } finally {
    closeSync(fd)
  }
}

export function hardenPrivateStateFileIfPresent(
  file: string,
  maxBytes = Number.MAX_SAFE_INTEGER,
): boolean {
  let fd: number
  try {
    if (process.platform === 'win32') requireInsideWindowsRoots(file, 'file')
    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
  } catch (error) {
    if (isMissing(error)) return false
    throw error
  }
  try {
    inspectPrivateStateFile(fd, maxBytes)
    return true
  } finally {
    closeSync(fd)
  }
}