@homeflare/alchemy 0.25.1 → 0.26.0

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,
+    );
+  });
+});

package/src/linux/sudo-runner.ts

@@ -0,0 +1,164 @@
+/**
+ * sshSudoRunner(): the Linux twin of `../launchd/sudo-runner.ts` — the same idea (the deploy runs
+ * as the operator, and only a fixed allowlist of calls goes through `sudo -n`), rebuilt for a
+ * non-root ssh user with passwordless sudo instead of a local macOS session. See
+ * docs/linux-sudo.md for the full argv table and what is measured versus reasoned.
+ *
+ * ⛔ `sudo -n`, NEVER A PROMPT — same rule, same reason: a deploy that stops to ask for a password
+ *   is the "no silent sudo" failure this exists to prevent.
+ * ⛔ EVERY PRIVILEGED ARGV IS LOGGED BEFORE IT RUNS, and a file's bytes never reach argv or the
+ *   log: they travel through the staged file (sudo-stage.ts) alone.
+ * ⛔ A PLAN NEVER ELEVATES. `checkWrite` and every read run through `base` — the plain
+ *   `sshRunner()` — never through sudo. Nothing here probes sudo at construction.
+ * ★ PROMISES, NOT EFFECTS, ON PURPOSE — the same divergence `../launchd/runner.ts` documents
+ *   (H3 in the provider-standard skill): a consumer's own runner is a plain async implementation.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+import { sudoRefusal } from '../launchd/sudo-said.ts';
+import { type SshRunnerOptions, sshRunner } from './ssh-runner.ts';
+import { elevatedExec } from './sudo-exec.ts';
+import {
+  CHMOD,
+  CHOWN,
+  INSTALL,
+  MKDIR,
+  MV,
+  RM,
+  RMDIR,
+  SUDO,
+  SYSTEMCTL_ABS,
+  SudoRefusedError,
+  checkPrefixes,
+  prefixOf,
+  privilegedProblem,
+  routeExec,
+} from './sudo-allowlist.ts';
+import { assertGuardedChain } from './sudo-guard.ts';
+import { type Staged, stageRemote } from './sudo-stage.ts';
+import { type Elevate, vetWrite, writeUnderPrefix } from './sudo-write.ts';
+
+export { SudoRefusedError };
+
+export type SshSudoRunnerOptions = SshRunnerOptions & {
+  /** Directories root may write under. Required; absolute, normalised, never `/`. */
+  readonly prefixes: readonly string[];
+  /** One line per privileged argv, before it runs. @default a line on stderr */
+  readonly log?: (line: string) => void;
+};
+
+/** What a sudo runner is built from. ★ Split out so the tests swap the host, never the logic. */
+export type SshSudoDeps = {
+  /** Runs everything, including `sudo` itself. `await sshRunner(options)` for the real one. */
+  readonly base: HostRunner;
+  readonly stage: (bytes: Uint8Array) => Promise<Staged>;
+  readonly log: (line: string) => void;
+};
+
+const outsidePrefixHint =
+  (path: string, prefixes: readonly string[]) =>
+  (cause: unknown): never => {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (!/permission denied|operation not permitted/i.test(message)) throw cause;
+    throw new Error(
+      `sshSudoRunner ${path}: the operator could not do this, and the path is under no declared ` +
+        `prefix (${prefixes.join(', ')}). If root owns its directory, declare that directory as ` +
+        'a prefix.',
+      { cause },
+    );
+  };
+
+export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDeps): HostRunner => {
+  const prefixes = checkPrefixes(prefixList);
+  const { base } = deps;
+
+  /** ⛔ THE ONE PLACE `sudo` IS SPAWNED: allowlist, then any host check (`before`), then the log
+   *    line, then `sudo -n -- argv`. Shared by exec()'s root branch and by writeFileAtomic. */
+  const elevate: Elevate = async (argv, context, before) => {
+    const shown = JSON.stringify(argv);
+    const problem = privilegedProblem(argv, { prefixes, ...context });
+    if (problem !== undefined)
+      throw new SudoRefusedError(`sshSudoRunner refused ${shown}: ${problem}`);
+    await before?.();
+    deps.log(`homeflare/linux sudo -n ${shown}`);
+    const result = await base.exec([SUDO, '-n', '--', ...argv]);
+    const refused = sudoRefusal(shown, result);
+    if (refused !== undefined) throw refused;
+    return result;
+  };
+
+  return {
+    checkWrite: async (path, options) => {
+      await vetWrite(base, prefixes, path, options);
+    },
+    effectiveUid: () => base.effectiveUid(),
+    exec: async (argv) => {
+      const route = routeExec(argv, prefixes);
+      if ('refuse' in route) throw new SudoRefusedError(`sshSudoRunner: ${route.refuse}`);
+      if (route.as === 'operator') return base.exec(argv);
+      return elevatedExec(base, elevate, prefixes, argv);
+    },
+    lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
+    lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    privileged: true,
+    readFile: (path) => base.readFile(path),
+    removeFile: async (path) => {
+      const prefix = prefixOf(path, prefixes);
+      if (prefix === undefined)
+        return base.removeFile(path).catch(outsidePrefixHint(path, prefixes));
+      // ★ Nothing there is success without a privileged call, so an idempotent delete logs nothing.
+      const target = await assertGuardedChain(base, prefix, path, 'file-or-absent');
+      if (target === undefined) return;
+      const argv = [RM, '-f', '--', path];
+      const result = await elevate(argv);
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`,
+        );
+      }
+    },
+    sleep: (ms) => base.sleep(ms),
+    stat: (path) => base.stat(path),
+    writeFileAtomic: async (path, bytes, options) => {
+      const vetted = await vetWrite(base, prefixes, path, options);
+      if (vetted === undefined) {
+        return base.writeFileAtomic(path, bytes, options).catch(outsidePrefixHint(path, prefixes));
+      }
+      await writeUnderPrefix(base, elevate, deps.stage, path, bytes, options, vetted.mode);
+    },
+  };
+};
+
+const REQUIRED_PROGRAMS = [SUDO, INSTALL, MV, RM, MKDIR, CHMOD, CHOWN, RMDIR, SYSTEMCTL_ABS];
+
+/**
+ * ★ READ-ONLY, OPTIONAL. One combined `test -x` so a missing coreutils package or a systemd-free
+ *   container fails at construction with a clear message, instead of at the first deploy step
+ *   that happens to need it. Never probes sudo itself.
+ */
+const checkProgramsExist = async (base: HostRunner, host: string): Promise<void> => {
+  const script = REQUIRED_PROGRAMS.map(
+    (p) => `test -x '${p}' || { echo "$0: ${p}"; exit 1; }`,
+  ).join(' && ');
+  const result = await base.exec(['/bin/sh', '-c', script, 'sshSudoRunner']);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `sshSudoRunner ${host}: ${result.stdout.trim() || result.stderr.trim()} is missing or not ` +
+        'executable on this host. sshSudoRunner sends absolute GNU coreutils and systemd paths.',
+    );
+  }
+};
+
+/** The real sudo runner: `sshRunner()` for everything, `/usr/bin/sudo -n` for the allowlist. */
+export const sshSudoRunner = async (options: SshSudoRunnerOptions): Promise<HostRunner> => {
+  const base = await sshRunner(options);
+  await checkProgramsExist(base, options.host);
+  return makeSshSudoRunner(options.prefixes, {
+    base,
+    log:
+      options.log ??
+      ((line) => {
+        process.stderr.write(`${line}\n`);
+      }),
+    stage: stageRemote(base),
+  });
+};

package/src/linux/sudo-stage.ts

@@ -0,0 +1,50 @@
+/**
+ * Where sudo-runner.ts puts a file's bytes before `install` copies them into a fresh temp file
+ * that `mv` then renames into place. The Linux twin of `../launchd/sudo-stage.ts` — rewritten,
+ * not reused, because staging happens ON THE REMOTE HOST through the base runner's own calls,
+ * never through `node:fs` against this process's local disk.
+ *
+ * ★ WHY STAGE AT ALL. The operator cannot write inside a root-owned directory, and the bytes must
+ *   not travel through argv (they would reach the log and `ps`). So they are written, as the
+ *   operator, to a private file on the SAME host, and `install` copies that one file.
+ * ⛔ A 0700 DIRECTORY, A 0600 FILE: between the write and the install, nobody but the operator and
+ *   root can read the bytes or swap the file. `mktemp -d` creates its directory 0700 by
+ *   construction (GNU coreutils); the payload's own mode is asked for explicitly.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+
+/** A file staged for `install`, and how to remove it again. */
+export type Staged = { readonly path: string; readonly dispose: () => Promise<void> };
+
+const refuse = (message: string): Error => new Error(`sshSudoRunner stage: ${message}`);
+
+/** `stage` in `SshSudoDeps` — closes over the base runner so every call writes to the same host. */
+export const stageRemote =
+  (base: HostRunner) =>
+  async (bytes: Uint8Array): Promise<Staged> => {
+    const made = await base.exec(['/usr/bin/mktemp', '-d']);
+    if (made.exitCode !== 0)
+      throw refuse(`mktemp -d -> ${String(made.exitCode)}: ${made.stderr.trim()}`);
+    const dir = made.stdout.trim();
+    if (dir === '' || !dir.startsWith('/')) {
+      throw refuse(`mktemp -d printed ${JSON.stringify(made.stdout)}, not an absolute path`);
+    }
+    const dispose = async () => {
+      const removed = await base.exec(['/usr/bin/rm', '-rf', '--', dir]);
+      // ⚠️ Best-effort: a leaked 0700 temp dir the operator owns is a nuisance, never a secret
+      //   exposure, so disposal failing never masks the write's own success or failure.
+      if (removed.exitCode !== 0) {
+        process.stderr.write(
+          `sshSudoRunner: could not remove staging dir ${dir}: ${removed.stderr.trim()}\n`,
+        );
+      }
+    };
+    try {
+      const path = `${dir}/staged`;
+      await base.writeFileAtomic(path, bytes, { mode: 0o600 });
+      return { dispose, path };
+    } catch (cause) {
+      await dispose();
+      throw cause;
+    }
+  };

package/src/linux/sudo-write.ts

@@ -0,0 +1,167 @@
+/**
+ * sshSudoRunner's `writeFileAtomic`, split out of sudo-runner.ts so that file stays the wiring.
+ *
+ * ⛔ WHY NOT `install` STRAIGHT TO `path`, THE WAY THE MAC RUNNER DOES. GNU `install` opens the
+ *   destination and writes THROUGH it (ssh-scripts.ts's header); there is no macOS-style stage-
+ *   and-rename built in. So this stages the bytes, `install`s them into a FRESH temp file in the
+ *   destination's own directory (fresh, so "writes through" changes nothing that mattered), then
+ *   `mv`s that temp file onto `path` — rename(2), same directory, so the swap is atomic and never
+ *   torn, exactly what `ssh-scripts.ts writeScript` already does for the unprivileged case.
+ * ⛔ `install` NEVER TAKES `-o`/`-g` — see sudo-allowlist-chown.ts's header (coreutils' own
+ *   `get_ids()` has no way to force numeric ids, unlike `chown`). It always installs owned by
+ *   whoever `sudo` runs it as; a non-root owner or group is set afterward by a separate,
+ *   `+`-forced `chown` on that same temp file, before `mv`.
+ * ⛔ THE DERIVED TEMP IS VERIFIED ABSENT, AS THE OPERATOR, BEFORE `install` RUNS. A 12-hex-char
+ *   collision is astronomically unlikely, but "unlikely" is not the bar a privileged write is held
+ *   to elsewhere in this runner, and the check costs one `stat` this runner already knows how to do.
+ * ⛔ ON ANY FAILURE AFTER `install` SUCCEEDS, THE TEMP IS REMOVED (also as root, since only root
+ *   can now touch it). A left-behind `.foo.hf-xxxx.tmp` would read, on the next plan, as an extra
+ *   file under the prefix that guard would find and no code would explain — and if THAT cleanup
+ *   itself fails, the thrown error says so and names the path, rather than silently swallowing it.
+ */
+import { randomBytes } from 'node:crypto';
+import type { ExecResult, HostRunner, WriteOptions } from '../launchd/runner.ts';
+import { CHOWN, INSTALL, MV, RM, SudoRefusedError, octalMode, prefixOf } from './sudo-allowlist.ts';
+import { assertInstallable, operatorGroups } from './sudo-guard.ts';
+import type { Staged } from './sudo-stage.ts';
+
+const basename = (path: string): string => path.slice(path.lastIndexOf('/') + 1);
+const dirOf = (path: string): string => path.slice(0, path.lastIndexOf('/')) || '/';
+
+/** `<dir>/.<basename>.hf-<12 hex>.tmp`, in `dest`'s own directory — never anywhere else. */
+export const deriveTemp = (dest: string): string =>
+  `${dirOf(dest)}/.${basename(dest)}.hf-${randomBytes(6).toString('hex')}.tmp`;
+
+/** What one privileged call, already checked against the allowlist, comes back as when it fails. */
+const mustSucceed = (result: ExecResult, argv: readonly string[]): void => {
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`,
+    );
+  }
+};
+
+/**
+ * The cleanup `rm`'s own failure, for the merged error below. 🔴 MEASURED (adversarial review,
+ *   round 3, 2026-09-23): a plain `ExecResult` (the shape `elevate()` resolves with for a command
+ *   that RAN but exited non-zero) has no useful `toString()` — `String(cleaned)` printed
+ *   `[object Object]`, silently dropping the one thing an operator doing manual cleanup needs:
+ *   what `rm` actually said. A thrown `Error` (a refused or transport-failed `rm`) still prints
+ *   its own message correctly, so only the `ExecResult` shape needed a name.
+ */
+const describeCleanupFailure = (cleaned: unknown): string => {
+  if (
+    typeof cleaned === 'object' &&
+    cleaned !== null &&
+    'exitCode' in cleaned &&
+    'stderr' in cleaned
+  ) {
+    const result = cleaned as ExecResult;
+    return `exit ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`;
+  }
+  return cleaned instanceof Error ? cleaned.message : String(cleaned);
+};
+
+/** A privileged call: allowlisted, logged, run. Shared with sudo-runner.ts's own exec() routing. */
+export type Elevate = (
+  argv: readonly string[],
+  context?: { readonly staged?: string; readonly temp?: string },
+  before?: () => Promise<unknown>,
+) => Promise<ExecResult>;
+
+/**
+ * Plan-time and write-time share this: valid mode, the path chain, mode/owner refusals and the
+ * read-back — everything a write can be refused for before anything is staged or run as root.
+ * `undefined` outside every prefix, where the caller falls back to `base` directly.
+ */
+export const vetWrite = async (
+  base: HostRunner,
+  prefixes: readonly string[],
+  path: string,
+  options: WriteOptions,
+): Promise<{ readonly mode: string; readonly prefix: string } | undefined> => {
+  const prefix = prefixOf(path, prefixes);
+  if (prefix === undefined) return undefined;
+  const mode = octalMode(options.mode);
+  if (mode === undefined)
+    throw new SudoRefusedError(`sshSudoRunner ${path}: mode must be 0–0o7777`);
+  const groups = await operatorGroups(base);
+  await assertInstallable(base, prefix, path, options, groups);
+  return { mode, prefix };
+};
+
+/** `+<uid>`, `:+<gid>`, or `+<uid>:+<gid>` — omitted sides leave that half of ownership alone. */
+const safeOwnerSpec = (uid: number | undefined, gid: number | undefined): string =>
+  `${uid === undefined ? '' : `+${uid}`}${gid === undefined ? '' : `:+${gid}`}`;
+
+/**
+ * A non-root owner or group, when one was declared: `install` leaves the temp root:root (see the
+ * file header), so this is the ONLY call that can hand it to someone else. `undefined` from either
+ * side when that half already matches `install`'s own default (0/omitted), so a plain root-owned
+ * write costs nothing extra here.
+ */
+const chownNeeded = (
+  options: WriteOptions,
+): { readonly uid?: number; readonly gid?: number } | undefined => {
+  const uid = options.uid !== undefined && options.uid !== 0 ? options.uid : undefined;
+  const gid = options.gid !== undefined && options.gid !== 0 ? options.gid : undefined;
+  return uid === undefined && gid === undefined
+    ? undefined
+    : { ...(uid === undefined ? {} : { uid }), ...(gid === undefined ? {} : { gid }) };
+};
+
+/**
+ * Stage, `install` into a fresh temp file beside `path`, `chown` it if a non-root owner was
+ * declared, `mv` it into place. Cleans up the temp on a failed `mv`, and always disposes the
+ * stage — whether or not the write succeeded.
+ */
+export const writeUnderPrefix = async (
+  base: HostRunner,
+  elevate: Elevate,
+  stage: (bytes: Uint8Array) => Promise<Staged>,
+  path: string,
+  bytes: Uint8Array,
+  options: WriteOptions,
+  mode: string,
+): Promise<void> => {
+  const temp = deriveTemp(path);
+  const staged = await stage(bytes);
+  try {
+    const installArgv = [INSTALL, '-m', mode, '-T', '--', staged.path, temp];
+    const before = async () => {
+      const existing = await base.stat(temp);
+      if (existing !== undefined) {
+        throw new SudoRefusedError(
+          `sshSudoRunner ${temp}: already exists (a ${existing.kind}); refusing to install over ` +
+            'it. Nothing ran as root.',
+        );
+      }
+    };
+    mustSucceed(await elevate(installArgv, { staged: staged.path, temp }, before), installArgv);
+    try {
+      const owner = chownNeeded(options);
+      if (owner !== undefined) {
+        const chownArgv = [CHOWN, safeOwnerSpec(owner.uid, owner.gid), '--', temp];
+        mustSucceed(await elevate(chownArgv, { temp }), chownArgv);
+      }
+      const mvArgv = [MV, '-f', '-T', '--', temp, path];
+      mustSucceed(await elevate(mvArgv, { temp }), mvArgv);
+    } catch (cause) {
+      const rmArgv = [RM, '-f', '--', temp];
+      const cleaned = await elevate(rmArgv, { temp })
+        .then((result) => (result.exitCode === 0 ? undefined : result))
+        .catch((rmCause: unknown) => rmCause);
+      if (cleaned !== undefined) {
+        throw new Error(
+          `${cause instanceof Error ? cause.message : String(cause)} — AND removing the leftover ` +
+            `temp ${temp} also failed (${describeCleanupFailure(cleaned)}); it needs manual ` +
+            'cleanup as root.',
+          { cause },
+        );
+      }
+      throw cause;
+    }
+  } finally {
+    await staged.dispose();
+  }
+};

package/src/linux/unit-form.ts

@@ -155,7 +155,8 @@ export const unitText = (props: SystemdUnitProps): string =>
 export const unitPathFor = (props: SystemdUnitProps): string =>
   `${props.directory ?? DEFAULT_UNIT_DIRECTORY}/${props.name}`;
 
-const NAME = /^[A-Za-z0-9][A-Za-z0-9_.@:-]*\.([a-z]+)$/;
+/** ★ Exported so sudo-allowlist.ts validates a systemctl unit operand against the same pattern. */
+export const NAME = /^[A-Za-z0-9][A-Za-z0-9_.@:-]*\.([a-z]+)$/;
 /** systemd's own unit types. ★ Fixed vocabulary from `systemd.unit(5)`, not a guess at directives. */
 const TYPES = new Set([
   'automount',

package/src/litellm/fake-litellm.ts

@@ -48,6 +48,8 @@ export const startFakeLitellm = (options?: {
     new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
 
   const server = Bun.serve({
+    // ⚠️ Loopback, not the wildcard default — see proxmox/fake-pve-lxc.ts for the race.
+    hostname: '127.0.0.1',
     port: 0,
     fetch: async (req) => {
       const url = new URL(req.url);

package/src/proxmox/client.test.ts

@@ -12,7 +12,11 @@ import { PveError, pveWith } from './client.ts';
 import type { PveCredential, PveTarget } from './credentials.ts';
 import { orderedMembers, resetLastGoodForTest } from './members.ts';
 
-type ServeOptions = { fetch(request: Request): Response | Promise<Response>; port: number };
+type ServeOptions = {
+  fetch(request: Request): Response | Promise<Response>;
+  hostname: string;
+  port: number;
+};
 const { Bun } = globalThis as unknown as {
   Bun: { serve(options: ServeOptions): { port: number; stop(closeActive: boolean): void } };
 };
@@ -84,6 +88,8 @@ const counting = (data: unknown) => {
       hits += 1;
       return Response.json({ data });
     },
+    // ⚠️ Loopback, not the wildcard default — see fake-pve-lxc.ts for the measured race.
+    hostname: '127.0.0.1',
     port: 0,
   });
   return { hits: () => hits, port: server.port, stop: () => server.stop(true) };
@@ -106,7 +112,11 @@ describe('cluster member failover', () => {
 
   it('does not fail over on HTTP 500 from the first member', async () => {
     resetLastGoodForTest();
-    const bad = Bun.serve({ fetch: () => new Response('fail', { status: 500 }), port: 0 });
+    const bad = Bun.serve({
+      fetch: () => new Response('fail', { status: 500 }),
+      hostname: '127.0.0.1',
+      port: 0,
+    });
     const good = counting([]);
     try {
       const error = await run(pveWith(target([A, B]), CRED, 'GET', 'pools').pipe(Effect.flip), {
@@ -144,7 +154,11 @@ describe('cluster member failover', () => {
 
   it('does not re-send a write after a transport timeout', async () => {
     resetLastGoodForTest();
-    const hang = Bun.serve({ fetch: () => new Promise<Response>(() => {}), port: 0 });
+    const hang = Bun.serve({
+      fetch: () => new Promise<Response>(() => {}),
+      hostname: '127.0.0.1',
+      port: 0,
+    });
     const backup = counting('UPID:1');
     try {
       await run(