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.

18.2 KB
Raw Blame
/**
 * The Harness Team account's privacy check (docs/plans/2026-10-24-swarm-team-account.md, Task 2), run by the team
 * daemon itself, as the team account: as its job starts (`harness team __start`) and while it serves a Swarm
 * (superTabs/machines.ts, at most every PRIVACY_RECHECK_MS).
 *
 * A second account alone is not private. On macOS every local account is in the group staff, a home folder is
 * `drwxr-x---` with that group by default, and `~/code` (755) or `~/.gitconfig` (644) inside it are readable by any
 * other account on the Mac. On Linux, Debian and Ubuntu before 21.04 make a home folder 755, readable by every account.
 * Setup makes the owner's home 700; this proves it, from the side that matters, every
 * time. Each probe must be refused with EACCES or EPERM. Reading it, or any other answer (a missing file means the
 * folder above it was searchable), fails the check, and the first failing item is what the machine reports.
 */
import { spawnSync } from 'node:child_process'
import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, readdirSync, renameSync, writeFileSync } from 'node:fs'
import { dirname } from 'node:path'
import type { TeamConfig } from './config.js'
import type { TeamEngines } from './engines.js'
import { WHOAMI_GROUPS_ARGS, runWindowsPrivacyCheck, windowsGroupSids } from './windowsTeam.js'

export type PrivacyItem =
  | 'sentinel' | 'home-listing' | 'gitconfig' | 'ssh' | 'projects' | 'keychain' | 'chrome' | 'safari' | 'firefox' | 'credentials' | 'edge'
  | 'standard-user'

export type PrivacyResult =
  | { passed: true; checkedAt: number }
  | { passed: false; item: PrivacyItem | 'unchecked'; detail: string; checkedAt: number }

interface Probe { item: PrivacyItem; what: string; kind: 'read' | 'list'; paths: string[] }

/** The folders people keep projects in: listing any of them must be refused. */
const PROJECT_FOLDERS = ['code', 'Code', 'Developer', 'Projects', 'projects', 'src', 'Documents']

/** What the check tries, in order. `what` is shown to people and sent with the machine's reading, so it names a
 *  place by `~`, never by the owner's absolute path (which carries their account name). The last three are where each
 *  system keeps the owner's secrets: the login keyring, and the browsers' profiles. */
export function privacyProbes(config: Pick<TeamConfig, 'ownerHome' | 'sentinel'>, platform: NodeJS.Platform = 'darwin'): Probe[] {
  const home = config.ownerHome
  const secrets: Probe[] = platform === 'linux'
    ? [
      // GNOME Keyring's and KWallet's files.
      { item: 'keychain', what: 'your login keyring folder', kind: 'list', paths: [`${home}/.local/share/keyrings`, `${home}/.local/share/kwalletd`] },
      { item: 'chrome', what: 'Chrome\'s profile folder', kind: 'list', paths: [`${home}/.config/google-chrome`] },
      { item: 'firefox', what: 'Firefox\'s profile folder', kind: 'list', paths: [`${home}/.mozilla`] },
    ]
    : [
      { item: 'keychain', what: 'your login Keychain folder', kind: 'list', paths: [`${home}/Library/Keychains`] },
      { item: 'chrome', what: 'Chrome\'s profile folder', kind: 'list', paths: [`${home}/Library/Application Support/Google/Chrome`] },
      { item: 'safari', what: 'Safari\'s folder', kind: 'list', paths: [`${home}/Library/Safari`] },
    ]
  return [
    { item: 'sentinel', what: 'the privacy sentinel in your home folder', kind: 'read', paths: [config.sentinel] },
    { item: 'home-listing', what: 'the list of files in your home folder', kind: 'list', paths: [home] },
    { item: 'gitconfig', what: '~/.gitconfig', kind: 'read', paths: [`${home}/.gitconfig`] },
    { item: 'ssh', what: '~/.ssh', kind: 'list', paths: [`${home}/.ssh`] },
    { item: 'projects', what: 'your project folders (~/code and the like)', kind: 'list', paths: PROJECT_FOLDERS.map((name) => `${home}/${name}`) },
    ...secrets,
  ]
}

export interface PrivacyDeps {
  /** Opens and closes [path] for reading; throws as the system does. */
  open(path: string): void
  /** Lists [path]; throws as the system does. */
  list(path: string): void
  /** This process's group ids. */
  groups(): number[]
  now(): number
  /** Which system's places to try: a Mac's unless told (the real deps say this one's). */
  platform?: NodeJS.Platform
  /** Linux: the ids of the groups whose members may become root (sudo, wheel, admin), which differ by distribution. */
  adminGids?(): number[]
  /** Windows: every group SID of this process's token, a deny-only Administrators included (./windowsTeam.ts). */
  groupSids?(): string[]
}

/** The administrator groups Linux distributions use: sudo (Debian, Ubuntu), wheel (Fedora, Arch), admin (older Ubuntu). */
const LINUX_ADMIN_GROUPS = ['sudo', 'wheel', 'admin']

/** The group ids in `getent group …`'s answer (`name:x:gid:members` a line); a line that is not one is skipped. */
export function adminGroupIds(stdout: string): number[] {
  return stdout.split('\n').map((line) => line.split(':')).filter((fields) => fields.length >= 3 && fields[2] !== '')
    .map((fields) => Number(fields[2])).filter((gid) => Number.isInteger(gid) && gid >= 0)
}

export const realPrivacyDeps: PrivacyDeps = {
  open: (path) => closeSync(openSync(path, 'r')),
  list: (path) => { readdirSync(path) },
  groups: () => process.getgroups?.() ?? [],
  now: () => Date.now(),
  platform: process.platform,
  // Through NSS, as the system itself looks groups up. getent exits 2 when one of them is missing, and prints the others.
  adminGids: () => adminGroupIds(spawnSync('getent', ['group', ...LINUX_ADMIN_GROUPS], { encoding: 'utf8', timeout: 5_000 }).stdout ?? ''),
  groupSids: () => windowsGroupSids(spawnSync('whoami', WHOAMI_GROUPS_ARGS, { encoding: 'utf8', timeout: 5_000, windowsHide: true }).stdout ?? ''),
}

/** The group macOS administrators are in. */
const ADMIN_GID = 80

const refused = (error: unknown): boolean => {
  const code = (error as NodeJS.ErrnoException | null)?.code
  return code === 'EACCES' || code === 'EPERM'
}

export function runPrivacyCheck(config: Pick<TeamConfig, 'ownerHome' | 'sentinel'>, deps: PrivacyDeps = realPrivacyDeps): PrivacyResult {
  const platform = deps.platform ?? 'darwin'
  // Windows' places and rules (./windowsTeam.ts): every account may open a path it cannot list, so a missing place is
  // skipped there, and administrators are told by SID.
  if (platform === 'win32') return runWindowsPrivacyCheck(config, { open: deps.open, list: deps.list, groupSids: deps.groupSids ?? (() => []), now: deps.now })
  const checkedAt = deps.now()
  for (const probe of privacyProbes(config, platform)) {
    for (const path of probe.paths) {
      try {
        if (probe.kind === 'read') deps.open(path)
        else deps.list(path)
      } catch (error) {
        if (refused(error)) continue
        const code = (error as NodeJS.ErrnoException | null)?.code ?? 'an error'
        // ENOENT under a home folder at 700 cannot happen: the folder would have refused the search first.
        return { passed: false, item: probe.item, checkedAt,
          detail: `The team account was not refused ${probe.what} (it got ${code}), so your home folder is not private.` }
      }
      return { passed: false, item: probe.item, checkedAt, detail: `The team account could read ${probe.what}.` }
    }
  }
  const admins = platform === 'linux' ? deps.adminGids?.() ?? [] : [ADMIN_GID]
  if (deps.groups().some((gid) => admins.includes(gid))) {
    return { passed: false, item: 'standard-user', checkedAt, detail: 'The team account is an administrator; it must be a standard user.' }
  }
  return { passed: true, checkedAt }
}

/** What the team daemon reports for the owner's `harness team status`, in the team account's status folder. */
export interface TeamStatus {
  version: 1
  signIn?: { state: 'signed-in' | 'failed' | 'signed-out'; at: number; detail?: string }
  privacy?: PrivacyResult
  /** Claude Code and Codex in the team account (./engines.ts). */
  engines?: TeamEngines
  /** The data of ended sessions not deleted yet (superTabs/inCore/teamPurge.ts): a count, never a name. */
  purges?: { pending: number; unreadable: boolean; at: number }
  /** A model API handed over on Windows (./modelHandoff.ts): whether it went in, never what it was. */
  model?: { state: "applied" | "failed"; at: number; detail?: string }
}

/** The `engines` field of the status file, or undefined when it is not one. */
export function enginesOf(value: unknown): TeamEngines | undefined {
  if (!value || typeof value !== 'object') return undefined
  const v = value as Record<string, unknown>
  if (typeof v.checkedAt !== 'number' || !Number.isFinite(v.checkedAt)) return undefined
  const result = { checkedAt: v.checkedAt } as TeamEngines
  for (const engine of ['claude', 'codex'] as const) {
    const e = v[engine] as Record<string, unknown> | undefined
    if (!e || typeof e !== 'object' || typeof e.installed !== 'boolean' || (typeof e.signedIn !== 'boolean' && e.signedIn !== null)) return undefined
    result[engine] = { installed: e.installed, signedIn: e.signedIn as boolean | null }
  }
  return result
}

/** A status is well under 1 KiB: its one free text is capped at 300 characters. */
const STATUS_MAX_BYTES = 64 * 1024
/** Plenty for a small file and a Node start on a busy machine; a read still waiting then is being held (audit W4). */
const STATUS_READ_DEADLINE_MS = 5_000

/**
 * On Windows an open waits for an oplock the file's owner holds, for as long as it holds it, and the Team account owns this file
 * (audit W4): it would stop whoever opens it. So the open happens in a child, which can be killed: unlike a worker stuck in a
 * synchronous call, or a thread-pool thread every file operation shares. It keeps the same limits as the read below.
 */
const STATUS_CHILD_SOURCE = `const fs = require('fs'), max = ${STATUS_MAX_BYTES}
const fd = fs.openSync(process.argv[1], 'r'), stat = fs.fstatSync(fd)
if (!stat.isFile() || stat.size > max) process.exit(3)
const buffer = Buffer.alloc(max + 1)
let length = 0
for (let got = 1; got > 0 && length < buffer.length; length += got) got = fs.readSync(fd, buffer, length, buffer.length - length, null)
if (length > max) process.exit(3)
process.stdout.write(buffer.subarray(0, length))`
const statusChildArgs = (path: string): string[] => ['-e', STATUS_CHILD_SOURCE, '--', path]
/** No window, and none of this process's settings, NODE_OPTIONS among them. */
const statusChildOptions = () => ({ windowsHide: true, env: process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {} })

/** For `harness team status` and setup, which wait for their answer. */
function readStatusInChild(path: string, deadlineMs: number): string {
  const result = spawnSync(process.execPath, statusChildArgs(path), { ...statusChildOptions(), timeout: deadlineMs, maxBuffer: STATUS_MAX_BYTES + 1,
    encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
  if (result.status !== 0) throw new Error('not a status file')
  return result.stdout
}

/**
 * The status file, which the Team account may replace with anything, and which the owner reads (`harness team status`,
 * setup). A FIFO there blocked a plain read for good and stopped the owner's Swarm service at every restart; a
 * link to /dev/zero would run until memory is gone (audit M5). So: never through a link, never waiting on a FIFO, a plain file
 * only, and never more than the limit, whatever fstat said a moment ago. As ./handoff.ts reads its code. Throws otherwise.
 */
export function readStatusFile(path: string, platform: NodeJS.Platform = process.platform, deadlineMs: number = STATUS_READ_DEADLINE_MS): string {
  if (platform === 'win32') return readStatusInChild(path, deadlineMs)
  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
  try {
    const stat = fstatSync(fd)
    if (!stat.isFile() || stat.size > STATUS_MAX_BYTES) throw new Error('not a status file')
    const buffer = Buffer.alloc(STATUS_MAX_BYTES + 1)
    let length = 0
    for (let got = 1; got > 0 && length < buffer.length; length += got) got = readSync(fd, buffer, length, buffer.length - length, null)
    if (length > STATUS_MAX_BYTES) throw new Error('not a status file')
    return buffer.toString('utf8', 0, length)
  } finally { closeSync(fd) }
}

/** Free text from the status file, fit for the owner's terminal: the Team account wrote it, and `harness team status` prints it
 *  (audit L1). Without control characters, which carry escape codes, and format characters, which reorder or hide text. Cut
 *  after that, so padding cannot push the words out. */
const statusText = (text: string): string => text.replace(/[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/gu, '').slice(0, 300)

const ITEMS = new Set<string>(['sentinel', 'home-listing', 'gitconfig', 'ssh', 'projects', 'keychain', 'chrome', 'safari', 'firefox', 'credentials', 'edge',
  'standard-user', 'unchecked'])

function privacyOf(value: unknown): PrivacyResult | undefined {
  if (!value || typeof value !== 'object') return undefined
  const v = value as Record<string, unknown>
  if (typeof v.checkedAt !== 'number' || !Number.isFinite(v.checkedAt)) return undefined
  if (v.passed === true) return { passed: true, checkedAt: v.checkedAt }
  if (v.passed === false && typeof v.item === 'string' && ITEMS.has(v.item) && typeof v.detail === 'string') {
    return { passed: false, item: v.item as PrivacyItem, detail: statusText(v.detail), checkedAt: v.checkedAt }
  }
  return undefined
}

export function readTeamStatus(path: string, read: (path: string) => string = (at) => readStatusFile(at)): TeamStatus | null {
  let raw: unknown
  try { raw = JSON.parse(read(path)) } catch { return null }
  if (!raw || typeof raw !== 'object' || (raw as { version?: unknown }).version !== 1) return null
  const value = raw as Record<string, unknown>
  const status: TeamStatus = { version: 1 }
  const signIn = value.signIn as Record<string, unknown> | undefined
  if (signIn && typeof signIn === 'object' && ['signed-in', 'failed', 'signed-out'].includes(String(signIn.state)) && typeof signIn.at === 'number') {
    status.signIn = { state: signIn.state as 'signed-in', at: signIn.at, ...(typeof signIn.detail === 'string' ? { detail: statusText(signIn.detail) } : {}) }
  }
  const privacy = privacyOf(value.privacy)
  if (privacy) status.privacy = privacy
  const engines = enginesOf(value.engines)
  if (engines) status.engines = engines
  const purges = value.purges as Record<string, unknown> | undefined
  if (purges && typeof purges === 'object' && Number.isSafeInteger(purges.pending) && (purges.pending as number) >= 0
    && typeof purges.unreadable === 'boolean' && typeof purges.at === 'number' && Number.isFinite(purges.at)) {
    status.purges = { pending: purges.pending as number, unreadable: purges.unreadable, at: purges.at }
  }
  const model = value.model as Record<string, unknown> | undefined
  if (model && typeof model === "object" && (model.state === "applied" || model.state === "failed") && typeof model.at === "number" && Number.isFinite(model.at)) {
    status.model = { state: model.state, at: model.at, ...(typeof model.detail === "string" ? { detail: statusText(model.detail) } : {}) }
  }
  return status
}

/** Merge [update] into the status file, through a temporary file and a rename: the owner's reader never sees half. */
export function writeTeamStatus(path: string, update: Partial<Omit<TeamStatus, 'version'>>): void {
  const next: TeamStatus = { ...(readTeamStatus(path) ?? { version: 1 }), ...update, version: 1 }
  mkdirSync(dirname(path), { recursive: true })
  const temp = `${path}.${process.pid}.next`
  writeFileSync(temp, `${JSON.stringify(next)}\n`, { mode: 0o644 })
  renameSync(temp, path)
}

/** How often a team daemon serving a Swarm checks again: a home folder opened again shows within this long. */
export const PRIVACY_RECHECK_MS = 5 * 60_000

/**
 * The privacy field of the machine's Super Tab reading (superTabs/machines.ts), which routing reads (Task 3):
 * - `account`: this daemon runs in the Harness Team account; `passed`, or the first item that failed.
 * - `dedicated`: the whole computer is for agents (`harness team on`), with no owner's files on it to protect.
 * The owner's own daemon reports nothing.
 */
export type PrivacyObservation =
  | { mode: 'account'; passed: true; checkedAt: number }
  | { mode: 'account'; passed: false; item: PrivacyItem | 'unchecked'; detail: string; checkedAt: number }
  | { mode: 'dedicated' }

export interface PrivacyObserverDeps {
  config(): TeamConfig | null
  /** The account this process runs as. */
  user(): string
  /** This computer's stored sign-in is a team session. */
  teamSession(): boolean
  check(config: TeamConfig): PrivacyResult
  writeStatus(path: string, update: Partial<Omit<TeamStatus, 'version'>>): void
  now(): number
}

export class TeamPrivacyObserver {
  private last: PrivacyResult | null = null
  private signedIn: boolean | null = null
  constructor(private readonly deps: PrivacyObserverDeps) {}

  /** This daemon runs in the Harness Team account that setup made. */
  inTeamAccount(): TeamConfig | null {
    const config = this.deps.config()
    return config && config.user === this.deps.user() ? config : null
  }

  observe(): PrivacyObservation | null {
    const config = this.inTeamAccount()
    if (config) {
      const now = this.deps.now()
      const signedIn = this.deps.teamSession()
      if (signedIn !== this.signedIn) {
        if (!signedIn) {
          try {
            this.deps.writeStatus(config.statusFile, { signIn: { state: 'signed-out', at: now,
              detail: 'The Team sign-in is no longer available.' } })
            this.signedIn = signedIn
          } catch { /* Try the status write again at the next observation; privacy is checked independently. */ }
        } else this.signedIn = signedIn
      }
      if (!this.last || now - this.last.checkedAt >= PRIVACY_RECHECK_MS || now < this.last.checkedAt) {
        try {
          this.last = this.deps.check(config)
        } catch (error) {
          this.last = { passed: false, item: 'unchecked', checkedAt: now, detail: `The privacy check did not run: ${(error as Error).message}` }
        }
        // The owner's status line is a convenience; the reading is what routing trusts.
        try { this.deps.writeStatus(config.statusFile, { privacy: this.last }) } catch { /* reported next time */ }
      }
      return { mode: 'account', ...this.last }
    }
    return this.deps.teamSession() ? { mode: 'dedicated' } : null
  }
}