@homeflare/alchemy 0.25.1 → 0.27.0

package/src/linux/sudo-guard.test.ts

@@ -0,0 +1,136 @@
+/**
+ * assertGuardedChain against the fake Linux host, unprivileged: a symlink below the prefix, a
+ * group-writable directory, a `+` ACL flag, a non-root owner above the prefix, and a directory
+ * sitting where a write expects `absent`. No sudo call anywhere in this file.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeSudoHost } from './fake-sudo.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+import { assertGuardedChain } from './sudo-guard.ts';
+
+describe('a clean prefix', () => {
+  test('a file-or-absent target that is absent is fine', async () => {
+    const { base } = fakeSudoHost();
+    const target = await assertGuardedChain(
+      base,
+      '/etc/systemd/system',
+      '/etc/systemd/system/thing.service',
+      'file-or-absent',
+    );
+    expect(target).toBeUndefined();
+  });
+
+  test('mkdir\'s "absent" expectation refuses a directory already there', async () => {
+    const { base } = fakeSudoHost({ '/usr/local/bin/sub': 0 });
+    await expect(
+      assertGuardedChain(base, '/usr/local/bin', '/usr/local/bin/sub', 'absent'),
+    ).rejects.toThrow('already exists');
+  });
+});
+
+describe('a symlink in the chain', () => {
+  test('below the prefix is refused, even root-owned', async () => {
+    const { base, fake } = fakeSudoHost();
+    fake.files.set('/etc/systemd/system/sub', {
+      bytes: new Uint8Array(),
+      gid: 0,
+      kind: 'symlink',
+      mode: 0o777,
+      uid: 0,
+    });
+    await expect(
+      assertGuardedChain(
+        base,
+        '/etc/systemd/system',
+        '/etc/systemd/system/sub/x.service',
+        'file-or-absent',
+      ),
+    ).rejects.toBeInstanceOf(SudoRefusedError);
+  });
+
+  test('above the prefix, root-owned, is followed like the merged-/usr symlinks it models', async () => {
+    const { base, fake } = fakeSudoHost();
+    fake.files.set('/etc', {
+      bytes: new Uint8Array(),
+      gid: 0,
+      kind: 'symlink',
+      mode: 0o777,
+      uid: 0,
+    });
+    const target = await assertGuardedChain(
+      base,
+      '/etc/systemd/system',
+      '/etc/systemd/system/thing.service',
+      'file-or-absent',
+    );
+    expect(target).toBeUndefined();
+  });
+
+  test('above the prefix, owned by someone else, is refused (not treated as the system’s own)', async () => {
+    const { base, fake } = fakeSudoHost();
+    fake.files.set('/etc', {
+      bytes: new Uint8Array(),
+      gid: 0,
+      kind: 'symlink',
+      mode: 0o777,
+      uid: 900,
+    });
+    await expect(
+      assertGuardedChain(
+        base,
+        '/etc/systemd/system',
+        '/etc/systemd/system/thing.service',
+        'file-or-absent',
+      ),
+    ).rejects.toThrow('is a symlink, not a directory');
+  });
+});
+
+test('a group-writable directory in the chain is refused', async () => {
+  const { base, fake } = fakeSudoHost({ '/etc/systemd/system/sub': 0 });
+  const live = fake.modes.get('/etc/systemd/system/sub');
+  if (live !== undefined) live.mode = 0o775;
+  await expect(
+    assertGuardedChain(
+      base,
+      '/etc/systemd/system',
+      '/etc/systemd/system/sub/x.service',
+      'file-or-absent',
+    ),
+  ).rejects.toThrow('writable by group or other');
+});
+
+test('an ACL `+` flag anywhere in the chain is refused, fail closed', async () => {
+  const { base } = fakeSudoHost({}, new Set(['/etc/systemd/system']));
+  await expect(
+    assertGuardedChain(
+      base,
+      '/etc/systemd/system',
+      '/etc/systemd/system/thing.service',
+      'file-or-absent',
+    ),
+  ).rejects.toThrow('POSIX ACL');
+});
+
+test('a non-root owner above the prefix is refused', async () => {
+  const { base, fake } = fakeSudoHost();
+  const live = fake.modes.get('/etc/systemd/system');
+  if (live !== undefined) live.uid = 0; // keep the prefix itself root-owned
+  fake.dirs.set('/etc', 900);
+  fake.modes.set('/etc', { gid: 0, mode: 0o755, uid: 900 });
+  await expect(
+    assertGuardedChain(
+      base,
+      '/etc/systemd/system',
+      '/etc/systemd/system/thing.service',
+      'file-or-absent',
+    ),
+  ).rejects.toThrow('not root');
+});
+
+test('a directory at a "file" destination is the trap install/rm must not fall into', async () => {
+  const { base } = fakeSudoHost({ '/etc/systemd/system/adir': 0 });
+  await expect(
+    assertGuardedChain(base, '/etc/systemd/system', '/etc/systemd/system/adir', 'file'),
+  ).rejects.toThrow('is a directory, not a file');
+});

package/src/linux/sudo-guard.ts

@@ -0,0 +1,142 @@
+/**
+ * The checks sudo-runner.ts makes against the host, as the operator, before it runs a file or
+ * directory operation as root. sudo-allowlist.ts checks the argv; this checks what the paths in
+ * it actually are — the Linux twin of `../launchd/sudo-guard.ts`, rebuilt on `sudo-listing.ts`'s
+ * ONE `ls -ldn` call instead of an lstat per directory, because ssh pays a handshake per call
+ * (ssh-runner.ts: no multiplexing unless the caller opts in) where a local syscall pays nothing.
+ *
+ * ⛔ EVERY DIRECTORY FROM `/` DOWN TO THE FILE MUST BE ROOT'S ALONE, for the same reason the Mac
+ *   guard insists on it: a directory anyone else may write lets them swap what lies under it — a
+ *   symlink where the file was — between this read and the privileged call. A root-owned symlink
+ *   ABOVE the prefix (Debian's merged-`/usr`, `/lib` -> `usr/lib`) is the system's own and is
+ *   followed, exactly as `aboveDirs`/`betweenDirs` from the Mac guard already encode; a symlink AT
+ *   or BELOW the prefix is refused outright — a write should never chase one there.
+ * ⛔ THE ACL SIGNAL IS THE `+` FLAG ALONE (sudo-listing.ts header): `ls`, not `getfacl`, which is
+ *   absent on the estate's Debian hosts. A directory that carries one is refused whatever it
+ *   grants — the guard cannot tell a read-only entry from a write one, so it fails closed.
+ */
+import type { FileStat, HostRunner, WriteOptions } from '../launchd/runner.ts';
+import {
+  aboveDirs,
+  assertReadableBack,
+  betweenDirs,
+  canRead,
+  modeProblem,
+  operatorGroups,
+} from '../launchd/sudo-guard.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+import { type Listed, readListing } from './sudo-listing.ts';
+
+export { aboveDirs, assertReadableBack, betweenDirs, canRead, modeProblem, operatorGroups };
+
+const refuse = (path: string, message: string): Error =>
+  new SudoRefusedError(`sshSudoRunner ${path}: ${message}`);
+
+const rootOnlyProblem = (entry: Listed | undefined): string | undefined => {
+  if (entry === undefined) return 'is missing';
+  if (entry.kind !== 'directory') return `is a ${entry.kind}, not a directory`;
+  if (entry.uid !== 0) return `is owned by uid ${String(entry.uid)}, not root`;
+  if ((entry.mode & 0o022) !== 0) {
+    return `is writable by group or other (mode ${entry.mode.toString(8).padStart(4, '0')})`;
+  }
+  if (entry.acl) return 'carries a POSIX ACL this runner cannot verify the grants of (ls -ldn `+`)';
+  return undefined;
+};
+
+/** What must be at `path` itself, for the operation about to run there. */
+export type ChainExpect = 'file' | 'file-or-absent' | 'directory' | 'absent';
+
+/**
+ * ⚠️ NOT PART OF THE `ls -ldn` BATCH, on purpose — mirroring the Mac guard's own
+ *   `assertPlainPath`, whose ACL check also excludes `path` itself (`assertNoAclGrants(base,
+ *   path, [...above, prefix, ...dirs])`, never `path` in that list). `readListing`'s
+ *   `parseListing` requires every requested path to have a line (sudo-listing.ts), so a target
+ *   that is legitimately ABSENT — the common case for a create — would make the whole batched
+ *   read look unparseable if it were included. A plain `stat` handles "nothing there" correctly.
+ */
+const targetProblem = (entry: FileStat | undefined, expect: ChainExpect): string | undefined => {
+  if (expect === 'absent')
+    return entry === undefined ? undefined : `already exists (a ${entry.kind})`;
+  if (entry === undefined) return expect === 'file-or-absent' ? undefined : 'is missing';
+  if (expect === 'file-or-absent')
+    return entry.kind === 'file' ? undefined : `is a ${entry.kind}, not a file`;
+  return entry.kind === expect ? undefined : `is a ${entry.kind}, not a ${expect}`;
+};
+
+/**
+ * Refuse a prefix that is not root-only, a symlink or wrong kind between the prefix and `path`,
+ * an ACL anywhere in the chain, or a target that is not what `expect` says. ONE `ls -ldn` for the
+ * directory chain, plus one plain `stat` for the target (see `targetProblem`'s note on why they
+ * are separate calls). ⚠️ Reads only, as the operator — so `checkWrite` runs this at plan time too.
+ */
+export const assertGuardedChain = async (
+  base: HostRunner,
+  prefix: string,
+  path: string,
+  expect: ChainExpect,
+): Promise<FileStat | undefined> => {
+  const above = aboveDirs(prefix);
+  const between = betweenDirs(prefix, path);
+  const chain = [...above, prefix, ...between];
+  const listed = await readListing(base, '/usr/bin/ls', path, chain);
+  for (const dir of above) {
+    const entry = listed.get(dir);
+    // ★ A root-owned symlink ABOVE the prefix is the system's own and is followed, as every path
+    //   lookup does; a symlink anywhere else in the chain is refused by rootOnlyProblem below.
+    const problem =
+      entry?.kind === 'symlink' && entry.uid === 0 ? undefined : rootOnlyProblem(entry);
+    if (problem !== undefined) {
+      throw refuse(
+        path,
+        `${dir}, above the declared prefix ${prefix}, ${problem}. Whoever may change it may swap ` +
+          'the prefix itself; every directory from / down must be root-only. Nothing ran as root.',
+      );
+    }
+  }
+  const prefixProblem = rootOnlyProblem(listed.get(prefix));
+  if (prefixProblem !== undefined) {
+    throw refuse(
+      path,
+      `the declared prefix ${prefix} ${prefixProblem}. Declare only a real directory that root ` +
+        'owns and only root may write. Nothing ran as root.',
+    );
+  }
+  for (const dir of between) {
+    const problem = rootOnlyProblem(listed.get(dir));
+    if (problem !== undefined) {
+      throw refuse(
+        path,
+        `${dir} ${problem}. Every directory from the prefix ${prefix} down to the file must be ` +
+          'one that root owns and only root may write. Nothing ran as root.',
+      );
+    }
+  }
+  const target = await base.stat(path);
+  const problem = targetProblem(target, expect);
+  if (problem !== undefined) throw refuse(path, `${problem}. Nothing ran as root.`);
+  return target;
+};
+
+/**
+ * The mode/owner and read-back checks for a file write under `prefix`, plus the path chain.
+ * ★ Reads only, as the operator — the same checks run at plan time (`checkWrite`) and before the
+ *   install/mv pair. `expect` is `'file-or-absent'`: a write may create or replace.
+ */
+export const assertInstallable = async (
+  base: HostRunner,
+  prefix: string,
+  path: string,
+  options: WriteOptions,
+  groups: readonly number[] | undefined,
+): Promise<void> => {
+  const mode = modeProblem(options);
+  if (mode !== undefined) {
+    throw refuse(
+      path,
+      `${mode}. Declare a mode without those bits (0644, 0640, 0755), or give the file to its ` +
+        'real owner. Nothing ran as root.',
+    );
+  }
+  await assertGuardedChain(base, prefix, path, 'file-or-absent');
+  await assertReadableBack(base, path, options, groups);
+};

package/src/linux/sudo-lifecycle.test.ts

@@ -0,0 +1,151 @@
+/**
+ * `Systemd.Unit` and `Remote.File`'s own lifecycle functions, driven through sshSudoRunner over
+ * the fake Linux host — proving the two families this runner exists for actually work end to end,
+ * not just that the runner's own primitives do. No sudo runs anywhere but through the fake.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeSudoHost } from './fake-sudo.ts';
+import { SudoRefusedError } from './sudo-runner.ts';
+import { deleteFile, reconcileFile } from './remote-file-lifecycle.ts';
+import type { RemoteFileProps } from './remote-file-form.ts';
+import { deleteUnit, diffUnit, reconcileUnit } from './unit-lifecycle.ts';
+import type { SystemdUnitProps } from './unit-form.ts';
+
+const UNIT: SystemdUnitProps = {
+  name: 'hf-thing.service',
+  sections: [
+    { lines: [['Description', 'a thing']], name: 'Unit' },
+    { lines: [['ExecStart', '/usr/local/bin/hf-thing']], name: 'Service' },
+    { lines: [['WantedBy', 'multi-user.target']], name: 'Install' },
+  ],
+};
+
+describe('Systemd.Unit through sshSudoRunner', () => {
+  test('create writes, reloads, enables and starts — all elevated', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    const attrs = await reconcileUnit(runner, UNIT, undefined);
+    expect(attrs.active).toBe(true);
+    expect(attrs.enabled).toBe(true);
+    const verbs = privileged().map((call) => call[0]);
+    expect(verbs.filter((v) => v === 'systemctl')).toEqual([]); // canonicalised to the absolute path
+    expect(verbs).toContain('/usr/bin/systemctl');
+    // write (install+mv), daemon-reload, enable, start.
+    expect(privileged().filter((c) => c[0] === '/usr/bin/install')).toHaveLength(1);
+    expect(
+      privileged().some((c) => c[0] === '/usr/bin/systemctl' && c[1] === 'daemon-reload'),
+    ).toBe(true);
+    expect(privileged().some((c) => c[1] === 'enable')).toBe(true);
+    expect(privileged().some((c) => c[1] === 'start')).toBe(true);
+  });
+
+  test('an unchanged unit is reconciled again with zero privileged calls', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    const created = await reconcileUnit(runner, UNIT, undefined);
+    expect(await diffUnit(runner, UNIT, created)).toEqual({ action: 'noop' });
+    const before = privileged().length;
+    const again = await reconcileUnit(runner, UNIT, created);
+    expect(privileged().length).toBe(before); // ★ no restart, no reload — the whole point.
+    expect(again.active).toBe(true);
+  });
+
+  test('a restartOn digest change updates and restarts, via elevated calls only', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    const created = await reconcileUnit(runner, UNIT, undefined);
+    const changed: SystemdUnitProps = { ...UNIT, restartOn: ['new-digest'] };
+    expect((await diffUnit(runner, changed, created))?.action).toBe('update');
+    const before = privileged().length;
+    const updated = await reconcileUnit(runner, changed, created);
+    expect(privileged().length).toBeGreaterThan(before);
+    expect(updated.configSha256).not.toBe(created.configSha256);
+  });
+
+  test('delete stops, disables, removes the file, reloads — all elevated', async () => {
+    const { fake, privileged, runner } = fakeSudoHost();
+    const created = await reconcileUnit(runner, UNIT, undefined);
+    await deleteUnit(runner, created);
+    expect(fake.files.has(created.unitPath)).toBe(false);
+    const verbs = privileged()
+      .filter((c) => c[0] === '/usr/bin/systemctl')
+      .map((c) => c[1]);
+    expect(verbs).toContain('stop');
+    expect(verbs).toContain('disable');
+    expect(verbs).toContain('daemon-reload');
+    expect(privileged().some((c) => c[0] === '/usr/bin/rm')).toBe(true);
+  });
+
+  test('a vendor unit outside every prefix is unreachable, refused before sudo runs', async () => {
+    const { fake, privileged, runner } = fakeSudoHost();
+    fake.placeUnit('/usr/lib/systemd/system/pveproxy.service', '[Service]\nExecStart=/x\n', {
+      active: true,
+      enabled: true,
+    });
+    await expect(runner.exec(['systemctl', 'restart', '--', 'pveproxy.service'])).rejects.toThrow(
+      SudoRefusedError,
+    );
+    await expect(runner.exec(['systemctl', 'restart', '--', 'pveproxy.service'])).rejects.toThrow(
+      'FragmentPath',
+    );
+    expect(privileged()).toEqual([]);
+  });
+
+  // 🔴 Adversarial review, round 2: a masked vendor unit also reads FragmentPath empty, which
+  //   used to fall into the "no file, elevate anyway" exemption regardless of verb.
+  test('a masked unit is refused, even one this runner’s own prefix could otherwise reach', async () => {
+    const { fake, privileged, runner } = fakeSudoHost();
+    fake.placeUnit('/etc/systemd/system/pveproxy.service', '[Service]\nExecStart=/x\n', {
+      active: false,
+      enabled: false,
+      masked: true,
+    });
+    for (const verb of ['enable', 'start', 'stop', 'disable', 'restart']) {
+      await expect(runner.exec(['systemctl', verb, '--', 'pveproxy.service'])).rejects.toThrow(
+        'is masked',
+      );
+    }
+    expect(privileged()).toEqual([]);
+  });
+
+  // 🔴 Adversarial review, round 2: the empty-FragmentPath exemption used to admit every write
+  //   verb, not just the two `deleteUnit` actually needs — so a kernel-generated pseudo-unit like
+  //   `init.scope` (empty FragmentPath, never file-backed) could still elevate enable/start/restart.
+  test('a unit with no file at all elevates stop/disable but refuses enable/start/restart', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    for (const verb of ['enable', 'start', 'restart']) {
+      await expect(runner.exec(['systemctl', verb, '--', 'init.scope'])).rejects.toThrow(
+        'is not stop/disable',
+      );
+    }
+    expect(privileged()).toEqual([]);
+    // stop/disable of a genuinely unknown unit still REACHES systemctl as root (which itself
+    // then judges it, exit 0 or not) — this runner's job is only to decide whether to ASK as
+    // root, not to pre-judge every unit name that might exist.
+    await runner.exec(['systemctl', 'stop', '--', 'init.scope']);
+    expect(privileged().some((c) => c[0] === '/usr/bin/systemctl' && c[1] === 'stop')).toBe(true);
+  });
+});
+
+const SCRIPT: RemoteFileProps = {
+  content: '#!/bin/sh\necho hi\n',
+  mode: 0o755,
+  path: '/usr/local/bin/hf-thing',
+};
+
+describe('Remote.File through sshSudoRunner', () => {
+  test('create, update and delete, all through install/mv/rm', async () => {
+    const { fake, privileged, runner } = fakeSudoHost();
+    const created = await reconcileFile(runner, SCRIPT);
+    expect(fake.files.get(SCRIPT.path)?.mode).toBe(0o755);
+    expect(privileged().map((c) => c[0])).toEqual(['/usr/bin/install', '/usr/bin/mv']);
+
+    const updated = await reconcileFile(
+      runner,
+      { ...SCRIPT, content: '#!/bin/sh\necho bye\n' },
+      created,
+    );
+    expect(new TextDecoder().decode(fake.files.get(SCRIPT.path)?.bytes)).toContain('bye');
+
+    await deleteFile(runner, updated);
+    expect(fake.files.has(SCRIPT.path)).toBe(false);
+    expect(privileged().some((c) => c[0] === '/usr/bin/rm' && c.at(-1) === SCRIPT.path)).toBe(true);
+  });
+});

package/src/linux/sudo-runner.test.ts

@@ -0,0 +1,206 @@
+/**
+ * sshSudoRunner over the fake Linux host end to end: writeFileAtomic's exact argv sequence and
+ * final bytes/mode/owner, a failed `mv` cleaning up the temp, `removeFile` of an absent path never
+ * calling sudo, `checkWrite` never calling sudo, and every logged line carrying no file content.
+ */
+import { describe, expect, test } from 'bun:test';
+import { CHOWN, INSTALL, MKDIR, MV, RM, RMDIR } from './sudo-allowlist.ts';
+import { fakeSudoHost } from './fake-sudo.ts';
+import { SudoRefusedError } from './sudo-runner.ts';
+
+const SECRET = 'super-secret-config-value=hunter2\n';
+const DEST = '/etc/systemd/system/thing.service';
+
+describe('what it claims', () => {
+  test('privileged, as the operator: it elevates calls, it is not root', () => {
+    const { runner } = fakeSudoHost();
+    expect(runner.privileged).toBe(true);
+    expect(runner.effectiveUid()).toBe(1000);
+  });
+});
+
+describe('writeFileAtomic under a prefix', () => {
+  test('install into a derived temp, then mv onto the path — exact argv, and the bytes land', async () => {
+    const { fake, logs, privileged, runner } = fakeSudoHost();
+    await runner.writeFileAtomic(DEST, new TextEncoder().encode(SECRET), {
+      gid: 0,
+      mode: 0o644,
+      uid: 0,
+    });
+
+    const calls = privileged();
+    expect(calls).toHaveLength(2);
+    const [install, mv] = calls;
+    expect(install?.[0]).toBe(INSTALL);
+    expect(install?.slice(1, 3)).toEqual(['-m', '0644']);
+    // install: [-m, mode, -T, --, staged, temp] — the temp is derived FROM dest, in its directory.
+    expect(install?.at(-1)).toMatch(
+      /^\/etc\/systemd\/system\/\.thing\.service\.hf-[0-9a-f]{12}\.tmp$/,
+    );
+    expect(mv?.[0]).toBe(MV);
+    expect(mv?.slice(1, 3)).toEqual(['-f', '-T']);
+    // mv: [-f, -T, --, temp, dest] — its source is exactly install's target.
+    expect(mv?.at(-2)).toBe(install?.at(-1));
+    expect(mv?.at(-1)).toBe(DEST);
+
+    const file = fake.files.get(DEST);
+    expect(file?.mode).toBe(0o644);
+    expect(file?.uid).toBe(0);
+    expect(new TextDecoder().decode(file?.bytes)).toBe(SECRET);
+    // ⛔ Bytes never travel through argv or the log.
+    expect(logs.some((line) => line.includes('hunter2'))).toBe(false);
+    for (const line of logs) expect(line.startsWith('homeflare/linux sudo -n ')).toBe(true);
+    // No temp file left behind, and the staging directory is gone too.
+    expect([...fake.files.keys()].some((path) => path.includes('.hf-'))).toBe(false);
+    expect([...fake.dirs.keys()].some((path) => path.startsWith('/tmp/hf-sudo-'))).toBe(false);
+  });
+
+  test('a failed mv removes the temp it just installed, then still throws', async () => {
+    const { fake, privileged, runner, state } = fakeSudoHost();
+    state.mvFailure = { exitCode: 1, stderr: 'mv: simulated failure', stdout: '' };
+    await expect(
+      runner.writeFileAtomic(DEST, new TextEncoder().encode('x'), { mode: 0o644 }),
+    ).rejects.toThrow('simulated failure');
+
+    const calls = privileged();
+    expect(calls.map((c) => c[0])).toEqual([INSTALL, MV, RM]);
+    // ★ rm's argument is install's own temp target — the exact path mv failed to move.
+    expect(calls[2]?.at(-1)).toBe(calls[0]?.at(-1));
+    expect(fake.files.has(DEST)).toBe(false);
+    expect([...fake.files.keys()].some((path) => path.includes('.hf-'))).toBe(false);
+    expect([...fake.dirs.keys()].some((path) => path.startsWith('/tmp/hf-sudo-'))).toBe(false);
+  });
+
+  // 🔴 Adversarial review, round 2: a failed CLEANUP rm after a failed mv used to be swallowed
+  //   silently — the operator learned only about the mv failure, never that a root-owned temp
+  //   was now littered on the host. The thrown error must say so and name the path.
+  test('a cleanup rm that ALSO fails is reported, not swallowed — names the leftover temp', async () => {
+    const { privileged, runner, state } = fakeSudoHost();
+    state.mvFailure = { exitCode: 1, stderr: 'mv: simulated failure', stdout: '' };
+    state.rmFailure = { exitCode: 1, stderr: 'rm: simulated cleanup failure', stdout: '' };
+    const write = runner.writeFileAtomic(DEST, new TextEncoder().encode('x'), { mode: 0o644 });
+    await expect(write).rejects.toThrow('simulated failure');
+    await expect(write).rejects.toThrow('also failed');
+    // 🔴 Adversarial review, round 3: `String(cleaned)` on the raw ExecResult printed
+    //   `[object Object]`, silently dropping rm's own stderr — assert the actual text survives.
+    await expect(write).rejects.toThrow('rm: simulated cleanup failure');
+    const calls = privileged();
+    expect(calls.map((c) => c[0])).toEqual([INSTALL, MV, RM]);
+    await expect(write).rejects.toThrow(calls[0]?.at(-1) ?? 'unreachable');
+  });
+
+  // 🔴 Adversarial review, round 2: install never carries -o/-g (coreutils has no way to force
+  //   numeric there); a non-root owner or group is set by a separate, +-forced chown on the same
+  //   temp, before mv — and only when one is actually declared, never for a plain root write.
+  test('a non-root owner is set by a +-forced chown on the temp, between install and mv', async () => {
+    const { fake, privileged, runner } = fakeSudoHost();
+    const path = '/usr/local/bin/hf-thing';
+    await runner.writeFileAtomic(path, new TextEncoder().encode('x'), {
+      gid: 60,
+      mode: 0o644,
+      uid: 900,
+    });
+    const calls = privileged();
+    expect(calls.map((c) => c[0])).toEqual([INSTALL, CHOWN, MV]);
+    expect(calls[0]?.includes('-o')).toBe(false);
+    expect(calls[0]?.includes('-g')).toBe(false);
+    expect(calls[1]).toEqual([CHOWN, '+900:+60', '--', calls[0]?.at(-1) ?? '']);
+    expect(fake.files.get(path)).toMatchObject({ gid: 60, uid: 900 });
+  });
+
+  test('a plain root write never chowns — install’s own default already matches', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    await runner.writeFileAtomic(DEST, new TextEncoder().encode('x'), { mode: 0o644 });
+    expect(privileged().map((c) => c[0])).toEqual([INSTALL, MV]);
+  });
+
+  test('the derived temp is verified absent before install runs', async () => {
+    const { base, privileged, runner } = fakeSudoHost();
+    // The temp's 12-hex suffix is random, so simulate a collision by making `stat` claim
+    // something is already at any `.hf-….tmp` path — `dest` itself is unaffected, so vetWrite's
+    // own read of it still sees the real (absent) state.
+    const originalStat = base.stat;
+    base.stat = async (path) =>
+      /\.hf-[0-9a-f]{12}\.tmp$/.test(path)
+        ? { gid: 0, kind: 'file', mode: 0o600, size: 0, uid: 0 }
+        : originalStat(path);
+    await expect(
+      runner.writeFileAtomic(DEST, new TextEncoder().encode('x'), { mode: 0o644 }),
+    ).rejects.toBeInstanceOf(SudoRefusedError);
+    await expect(
+      runner.writeFileAtomic(DEST, new TextEncoder().encode('x'), { mode: 0o644 }),
+    ).rejects.toThrow('already exists');
+    // ★ Refused before `install` ever ran — nothing was staged as root over a collision.
+    expect(privileged()).toEqual([]);
+  });
+});
+
+describe('checkWrite', () => {
+  test('never calls sudo, under a prefix or outside one', async () => {
+    const { runner, logs, privileged } = fakeSudoHost();
+    await runner.checkWrite?.(DEST, { mode: 0o644, uid: 0, gid: 0 });
+    await expect(runner.checkWrite?.('/opt/elsewhere/x', { mode: 0o644 })).resolves.toBeUndefined();
+    expect(privileged()).toEqual([]);
+    expect(logs).toEqual([]);
+  });
+});
+
+describe('removeFile', () => {
+  test('an absent path under a prefix is a no-op, no sudo', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    await runner.removeFile('/etc/systemd/system/absent.service');
+    expect(privileged()).toEqual([]);
+  });
+
+  test('a present file under a prefix is removed with rm -f --', async () => {
+    const { fake, privileged, runner } = fakeSudoHost();
+    fake.files.set(DEST, { bytes: new Uint8Array(), gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+    await runner.removeFile(DEST);
+    expect(privileged()).toEqual([[RM, '-f', '--', DEST]]);
+    expect(fake.files.has(DEST)).toBe(false);
+  });
+});
+
+describe('exec routing', () => {
+  test('mkdir/chown under a prefix run as root with absolute argv, chown +-forced', async () => {
+    const { fake, privileged, runner } = fakeSudoHost();
+    await runner.exec(['mkdir', '-m', '750', '--', '/usr/local/bin/sub']);
+    await runner.exec(['chown', '0:0', '--', '/usr/local/bin/sub']);
+    expect(privileged()).toEqual([
+      [MKDIR, '-m', '750', '--', '/usr/local/bin/sub'],
+      [CHOWN, '+0:+0', '--', '/usr/local/bin/sub'],
+    ]);
+    expect(fake.modes.get('/usr/local/bin/sub')).toEqual({ gid: 0, mode: 0o750, uid: 0 });
+  });
+
+  test('mkdir/chmod/chown with a dangerous mode or a non-root owner are refused before sudo', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    await expect(
+      runner.exec(['mkdir', '-m', '777', '--', '/usr/local/bin/world']),
+    ).rejects.toBeInstanceOf(SudoRefusedError);
+    await expect(
+      runner.exec(['chown', '900:60', '--', '/usr/local/bin/sub']),
+    ).rejects.toBeInstanceOf(SudoRefusedError);
+    expect(privileged()).toEqual([]);
+  });
+
+  test('rmdir under a prefix runs as root', async () => {
+    const { fake, privileged, runner } = fakeSudoHost({ '/usr/local/bin/sub': 0 });
+    await runner.exec(['rmdir', '--', '/usr/local/bin/sub']);
+    expect(privileged()).toEqual([[RMDIR, '--', '/usr/local/bin/sub']]);
+    expect(fake.dirs.has('/usr/local/bin/sub')).toBe(false);
+  });
+
+  test('mkdir outside every prefix runs as the operator, no sudo', async () => {
+    const { privileged, runner } = fakeSudoHost({ '/opt': 0 });
+    const result = await runner.exec(['mkdir', '-m', '750', '--', '/opt/elsewhere']);
+    expect(result.exitCode).toBe(0);
+    expect(privileged()).toEqual([]);
+  });
+
+  test('a sudo argv is refused before anything runs', async () => {
+    await expect(fakeSudoHost().runner.exec(['sudo', 'true'])).rejects.toBeInstanceOf(
+      SudoRefusedError,
+    );
+  });
+});