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.

15.1 KB
Raw Blame
/**
 * The Windows pieces of the team daemon and of `harness team status` (docs/superpowers/plans/2026-10-28-harness-team-
 * account-windows.md, Tasks 4 and 5), as pure functions and PowerShell queries the platform code runs: the privacy
 * probes, the pinned gh zips, and what status asks Windows about the account and its task.
 *
 * A query is a short script and its inputs, for lib/windows/powershell.ts `runPowershell`: the inputs travel in
 * environment variables, never in the script's text.
 */
import { closeSync, lstatSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs'
import type { JobState } from './command.js'
import type { TeamConfig } from './config.js'
import type { GhBuild } from './gh.js'
import { TeamSignInError } from './signInError.js'
import { HANDOFF_CODE } from './layout.js'
import type { PrivacyItem } from './privacy.js'
import {
  SID, WINDOWS_TEAM_HANDOFF_FILE, WINDOWS_TEAM_TASK_NAME, WINDOWS_TEAM_TASK_PATH, checkSid, checkWindowsPath, checkWindowsUser,
} from './windowsLayout.js'

export interface PowershellQuery { script: string; inputs: Record<string, string> }
/** What lib/windows/powershell.ts `runPowershell` answers. */
export interface QueryResult { status: number | null; stdout: string; stderr: string }

// ── The privacy check ─────────────────────────────────────────────────────────────────────────

/** The items a Windows check reports: ./privacy.ts lists credentials and edge with the others. */
export type WindowsPrivacyItem = PrivacyItem

export interface WindowsProbe {
  item: WindowsPrivacyItem
  what: string
  kind: 'read' | 'list'
  paths: string[]
  /** A place that must be there to be refused: the sentinel setup writes, and the profile itself. */
  mustExist: boolean
}

/** The folders people keep projects in on Windows, Visual Studio's first. */
const PROJECT_FOLDERS = ['source\\repos', 'code', 'Code', 'Projects', 'src', 'Documents']

/**
 * What the check tries on Windows, in order. `what` names a place by %USERPROFILE%, never by the owner's absolute path
 * (which carries their account name).
 *
 * Every Windows account has "Bypass traverse checking", so it may open a path inside a folder it cannot list, and a
 * missing name answers ENOENT rather than access denied. A place that is not there is therefore skipped: its absence is
 * no leak of what is in it. The sentinel must be there (setup writes it) and refused, and the profile must refuse a
 * listing, which proves the ACL every file in the profile inherits keeps the team account out.
 */
export function windowsPrivacyProbes(config: Pick<TeamConfig, 'ownerHome' | 'sentinel'>): WindowsProbe[] {
  const home = config.ownerHome
  const at = (path: string) => `${home}\\${path}`
  return [
    { item: 'sentinel', what: 'the privacy sentinel in your profile', kind: 'read', paths: [config.sentinel], mustExist: true },
    { item: 'home-listing', what: 'the list of files in your profile', kind: 'list', paths: [home], mustExist: true },
    { item: 'gitconfig', what: '%USERPROFILE%\\.gitconfig', kind: 'read', paths: [at('.gitconfig')], mustExist: false },
    { item: 'ssh', what: '%USERPROFILE%\\.ssh', kind: 'list', paths: [at('.ssh')], mustExist: false },
    { item: 'projects', what: 'your project folders (%USERPROFILE%\\source\\repos and the like)', kind: 'list', paths: PROJECT_FOLDERS.map(at), mustExist: false },
    { item: 'credentials', what: 'your Windows Credential Manager folders', kind: 'list',
      paths: [at('AppData\\Roaming\\Microsoft\\Credentials'), at('AppData\\Local\\Microsoft\\Credentials')], mustExist: false },
    { item: 'chrome', what: 'Chrome\'s profile folder', kind: 'list', paths: [at('AppData\\Local\\Google\\Chrome\\User Data')], mustExist: false },
    { item: 'edge', what: 'Edge\'s profile folder', kind: 'list', paths: [at('AppData\\Local\\Microsoft\\Edge\\User Data')], mustExist: false },
  ]
}

export interface WindowsPrivacyDeps {
  open(path: string): void
  list(path: string): void
  /** Every group SID in this process's token, deny-only ones included (`windowsGroupSids` of `whoami /groups`). */
  groupSids(): string[]
  now(): number
}

export const realWindowsPrivacyFs = {
  open: (path: string) => closeSync(openSync(path, 'r')),
  list: (path: string) => { readdirSync(path) },
}

export type WindowsPrivacyResult =
  | { passed: true; checkedAt: number }
  | { passed: false; item: WindowsPrivacyItem; detail: string; checkedAt: number }

const codeOf = (error: unknown): string | undefined => (error as NodeJS.ErrnoException | null)?.code

/** The Windows twin of ./privacy.ts `runPrivacyCheck`: each place must be refused with EPERM or EACCES. */
export function runWindowsPrivacyCheck(config: Pick<TeamConfig, 'ownerHome' | 'sentinel'>, deps: WindowsPrivacyDeps): WindowsPrivacyResult {
  const checkedAt = deps.now()
  for (const probe of windowsPrivacyProbes(config)) {
    for (const path of probe.paths) {
      try {
        if (probe.kind === 'read') deps.open(path)
        else deps.list(path)
      } catch (error) {
        const code = codeOf(error)
        if (code === 'EPERM' || code === 'EACCES') continue
        if (code === 'ENOENT' && !probe.mustExist) continue
        return { passed: false, item: probe.item, checkedAt,
          detail: `The team account was not refused ${probe.what} (it got ${code ?? 'an error'}), so your files are not private.` }
      }
      return { passed: false, item: probe.item, checkedAt, detail: `The team account could read ${probe.what}.` }
    }
  }
  if (deps.groupSids().includes(SID.administrators)) {
    return { passed: false, item: 'standard-user', checkedAt, detail: 'The team account is an administrator; it must be a standard user.' }
  }
  return { passed: true, checkedAt }
}

/** `whoami /groups /fo csv /nh`: every group of this process's token, a deny-only Administrators (UAC's filtered token)
 *  included, which .NET's WindowsIdentity.Groups leaves out. */
export const WHOAMI_GROUPS_ARGS = ['/groups', '/fo', 'csv', '/nh']

/** The fields of one CSV line, quotes taken off (`""` inside a quoted field is one quote). */
function csvFields(line: string): string[] {
  const fields: string[] = []
  let field = ''
  let quoted = false
  for (let i = 0; i < line.length; i++) {
    const char = line[i]!
    if (quoted) {
      if (char === '"' && line[i + 1] === '"') { field += '"'; i++ } else if (char === '"') quoted = false
      else field += char
    } else if (char === '"') quoted = true
    else if (char === ',') { fields.push(field); field = '' } else field += char
  }
  fields.push(field)
  return fields
}

/** `whoami /user /fo csv /nh`: one line, `"<DOMAIN\name>","<SID>"`, this process's own account. */
export const WHOAMI_USER_ARGS = ['/user', '/fo', 'csv', '/nh']

/** The account's SID in what `whoami /user /fo csv /nh` printed (its last column: a name may hold a comma), or null. */
export function windowsUserSid(stdout: string): string | null {
  const line = stdout.split('\n').map((l) => l.trim()).find(Boolean)
  const sid = line ? csvFields(line).at(-1) ?? '' : ''
  try { return checkSid(sid) } catch { return null }
}

/** The SIDs (the third column) of what `whoami /groups /fo csv /nh` printed. */
export function windowsGroupSids(stdout: string): string[] {
  return stdout.split('\n').map((line) => line.trim()).filter(Boolean).map((line) => csvFields(line)[2] ?? '').filter((sid) => sid.startsWith('S-1-'))
}

// ── gh ────────────────────────────────────────────────────────────────────────────────────────

/** A Windows gh zip: it holds `bin\gh.exe` at its top, with no folder around it, so it is unpacked into `archiveRoot`. */
export type WindowsGhBuild = GhBuild & { binary: string }

const GH_VERSION = '2.103.3'
const windowsRelease = (arch: string, sha256: string, size: number): WindowsGhBuild => ({
  version: GH_VERSION, sha256, size, archiveRoot: `gh_${GH_VERSION}_windows_${arch}`, binary: 'bin\\gh.exe', format: 'zip',
  url: `https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_windows_${arch}.zip`,
})
/** GitHub's Windows builds of gh, by `process.arch`, from the release's gh_2.103.3_checksums.txt and its asset sizes. */
export const WINDOWS_GH_BUILDS: Readonly<Record<string, WindowsGhBuild>> = {
  x64: windowsRelease('amd64', '98d0cfa794721665d7973dd728c78aff7bd836d58f10f6d7a03568eccb0a22e0', 15_197_187),
  arm64: windowsRelease('arm64', '197211c98687d7770ac331fe8a3b6c198c389108c1536cdbedf659fe4703e484', 13_637_549),
}

/** Unpacks a zip with Windows PowerShell's own Expand-Archive (there is no ditto). */
export function windowsUnzipScript(archive: string, into: string): PowershellQuery {
  return {
    script: 'Expand-Archive -LiteralPath $env:HARNESS_ARCHIVE -DestinationPath $env:HARNESS_INTO -Force',
    inputs: { HARNESS_ARCHIVE: checkWindowsPath(archive, 'gh archive'), HARNESS_INTO: checkWindowsPath(into, 'gh folder') },
  }
}

// ── The sign-in hand-over ─────────────────────────────────────────────────────────────────────

export interface WindowsHandoffFs {
  lstat(path: string): { isFile(): boolean; isDirectory(): boolean; isSymbolicLink(): boolean; size: number }
  write(path: string, text: string): void
  read(path: string): string
  unlink(path: string): void
}

const realHandoffFs: WindowsHandoffFs = {
  lstat: (path) => lstatSync(path),
  // A new file, or the one the owner left before: the folder lets nobody else add one (./windowsScript.ts step 8).
  write: (path, text) => writeFileSync(path, text),
  read: (path) => readFileSync(path, 'utf8'),
  unlink: (path) => unlinkSync(path),
}

/**
 * The owner's side: the single-use code, into the handover folder setup made. Never through a link: the folder must be
 * a plain one (Node reads a junction as a symbolic link), and the code a plain file in it.
 */
export function writeWindowsHandoff(code: string, file: string = WINDOWS_TEAM_HANDOFF_FILE, fs: WindowsHandoffFs = realHandoffFs): void {
  if (!HANDOFF_CODE.test(code)) throw new Error('not a sign-in code')
  const folder = fs.lstat(file.slice(0, file.lastIndexOf('\\')))
  if (!folder.isDirectory() || folder.isSymbolicLink()) throw new Error('the sign-in handover folder is not a plain folder: run harness team setup again')
  try {
    const old = fs.lstat(file)
    if (!old.isFile() || old.isSymbolicLink()) throw new Error('the sign-in handover file is not a plain file: run harness team setup again')
  } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
  fs.write(file, `${code}\n`)
}

/**
 * The team account's side (`team __start`): the code the owner left, read once and deleted, or null when there is none.
 * Only the owner and administrators may add a file to the folder; one that is not a plain small file holding a code is
 * deleted unread and refused, as ./handoff.ts `takeHandoffFile` refuses one on a Mac.
 */
export function takeWindowsHandoffFile(file: string, fs: WindowsHandoffFs = realHandoffFs): string | null {
  let info: ReturnType<WindowsHandoffFs['lstat']>
  try { info = fs.lstat(file) } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
    throw new TeamSignInError(`The team sign-in file could not be opened safely (${(error as NodeJS.ErrnoException).code ?? 'error'}).`, 'UNSAFE_FILE')
  }
  let text = ''
  const safe = info.isFile() && !info.isSymbolicLink() && info.size <= 4096
  try {
    if (safe) text = fs.read(file).trim()
  } finally {
    try { fs.unlink(file) } catch { /* already gone */ }
  }
  if (!safe) throw new TeamSignInError('The team sign-in file was not a plain file; it was deleted unread.', 'UNSAFE_FILE')
  if (!HANDOFF_CODE.test(text)) throw new TeamSignInError('The team sign-in file did not hold a sign-in code; it was deleted.', 'UNSAFE_FILE')
  return text
}

/** Asks Task Scheduler to start the team daemon's task; prints nothing. Setup's task lets its owner start it. */
export function windowsStartTaskScript(): PowershellQuery {
  return {
    script: 'Start-ScheduledTask -TaskPath $env:HARNESS_TASK_PATH -TaskName $env:HARNESS_TASK_NAME',
    inputs: { HARNESS_TASK_PATH: WINDOWS_TEAM_TASK_PATH, HARNESS_TASK_NAME: WINDOWS_TEAM_TASK_NAME },
  }
}

// ── harness team status ───────────────────────────────────────────────────────────────────────

/** Whether a local account by that name exists; any account may ask. Prints `yes` or `no`. */
export function windowsAccountExistsScript(user: string): PowershellQuery {
  return {
    script: "if (Get-LocalUser -Name $env:HARNESS_TEAM_USER -ErrorAction SilentlyContinue) { 'yes' } else { 'no' }",
    inputs: { HARNESS_TEAM_USER: checkWindowsUser(user, 'team account') },
  }
}

export const parseWindowsAccountExists = (result: QueryResult): boolean => result.status === 0 && result.stdout.trim() === 'yes'

/**
 * The team task as Task Scheduler has it, one JSON line: its state (`Ready`, `Running`, `Disabled`), its last result,
 * and the process of a running instance, which only Task Scheduler's COM interface gives. Setup's task lets every
 * signed-in account read it (./windowsScript.ts `teamTaskXml`), so a standard owner sees it too.
 */
export function windowsJobStateScript(): PowershellQuery {
  return {
    script: [
      '$task = Get-ScheduledTask -TaskPath $env:HARNESS_TASK_PATH -TaskName $env:HARNESS_TASK_NAME -ErrorAction SilentlyContinue',
      "if (-not $task) { '{\"loaded\":false}'; exit 0 }",
      '$info = Get-ScheduledTaskInfo -TaskPath $env:HARNESS_TASK_PATH -TaskName $env:HARNESS_TASK_NAME',
      '$enginePid = $null',
      'try {',
      '  $scheduler = New-Object -ComObject Schedule.Service',
      '  $scheduler.Connect()',
      "  foreach ($instance in @($scheduler.GetFolder($env:HARNESS_TASK_PATH.TrimEnd('\\')).GetTask($env:HARNESS_TASK_NAME).GetInstances(0))) { $enginePid = [int]$instance.EnginePID }",
      '} catch { }',
      '[pscustomobject]@{ loaded = $true; state = [string]$task.State; pid = $enginePid; lastResult = $info.LastTaskResult } | ConvertTo-Json -Compress',
    ].join('\n'),
    inputs: { HARNESS_TASK_PATH: WINDOWS_TEAM_TASK_PATH, HARNESS_TASK_NAME: WINDOWS_TEAM_TASK_NAME },
  }
}

export function parseWindowsJobState(result: QueryResult): JobState {
  const none: JobState = { loaded: false, pid: null, state: null }
  if (result.status !== 0) return none
  let value: unknown
  try { value = JSON.parse(result.stdout.trim()) } catch { return none }
  if (!value || typeof value !== 'object' || (value as { loaded?: unknown }).loaded !== true) return none
  const { state, pid } = value as { state?: unknown; pid?: unknown }
  return { loaded: true, pid: typeof pid === 'number' && Number.isInteger(pid) && pid > 0 ? pid : null, state: typeof state === 'string' ? state : null }
}