@homeflare/alchemy 0.25.1 → 0.26.0

package/src/launchd/sudo-guard-mode.ts

@@ -0,0 +1,111 @@
+/**
+ * The mode/owner and read-back half of sudo-guard.ts, split out to keep that file under the
+ * house's 250-line cap. `assertPlainPath` (path chain) stays there; this is "is the mode/owner
+ * safe, and can the deploying user read the result back" — re-exported from sudo-guard.ts so
+ * nothing importing from there has to know this file exists.
+ */
+import type { HostRunner, WriteOptions } from './runner.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+
+const refuse = (path: string, message: string): Error =>
+  new SudoRefusedError(`sudoRunner ${path}: ${message}`);
+
+/**
+ * ⛔ A ROOT-OWNED FILE UNDER A PREFIX IS ROOT'S TO CHANGE, AND ONLY ROOT'S (decided 2026-09-21).
+ *   Group- or world-writable, anyone in that class rewrites a file root installed — a daemon's
+ *   config, a script a LaunchDaemon runs as root — which is root by another name. Setuid or setgid,
+ *   it runs as root (or its group) for whoever executes it. install(1) would apply either, as root.
+ * ★ Root-owned is an omitted owner (the runner installs as root under a prefix) or uid 0. A file
+ *   handed to another user is that user's to change; the sticky bit changes nothing on a file.
+ * 🔴 MEASURED (adversarial review, 2026-09-23, round 1): "handed to another user" checked only
+ *   `uid`, never `gid`. `{ uid: 501, gid: 0, mode: 0o2775 }` — a setgid file owned by an
+ *   unprivileged uid but GROUPED to root — passed untouched, because a non-zero uid alone skipped
+ *   every check below. Fixed by also treating `gid: 0` as root-adjacent.
+ * 🔴 MEASURED (adversarial review, round 2, same day): the round-1 fix still missed an OMITTED
+ *   `gid`. `remote-file-plan.ts`'s `identity()` returns no `gid` key at all when a `RemoteFile`
+ *   declares no `group`, so `{ uid: 501, mode: 0o2775 }` reaches this check with `gid: undefined`
+ *   — neither `0` nor genuinely someone else's. `sudo-write.ts` then omits `-g` from `install`
+ *   entirely, and GNU `install`, run as root via `sudo -n`, defaults an omitted `-g` to the
+ *   INVOKING PROCESS's group — root's own — whenever the destination directory is not itself
+ *   setgid (which none of this runner's declared prefixes are, measured in linux-host-measured.md).
+ *   The file lands exactly as `{ uid: 501, gid: 0, mode: 0o2775 }` — the identical escalation the
+ *   round-1 fix closed, reached by OMISSION instead of an explicit `group: 0`. So "root-adjacent"
+ *   now also means an omitted `gid`: only a file with a genuinely non-root, EXPLICITLY GIVEN owner
+ *   AND group is someone else's alone to make setuid/setgid or writable — an omission is never
+ *   read as a safe default on either side, uid or gid.
+ */
+export const modeProblem = (options: WriteOptions): string | undefined => {
+  const rootAdjacent =
+    options.uid === undefined ||
+    options.uid === 0 ||
+    options.gid === undefined ||
+    options.gid === 0;
+  if (!rootAdjacent) return undefined;
+  const found: string[] = [];
+  if ((options.mode & 0o6000) !== 0) found.push('setuid/setgid');
+  if ((options.mode & 0o022) !== 0) found.push('writable by group or other');
+  if (found.length === 0) return undefined;
+  return `mode ${options.mode.toString(8).padStart(4, '0')} is ${found.join(' and ')} on a root-owned file`;
+};
+
+/**
+ * POSIX read permission for one uid: owner class, else group class, else other. `undefined` when
+ * only group membership could decide and the groups are unknown.
+ * ⚠️ EXACTLY ONE CLASS APPLIES. A group member gets the group bits even when the other bits are
+ *   wider (`0604` hides a file from its group), so "other can read" is not enough on its own.
+ */
+export const canRead = (
+  file: { readonly uid: number; readonly gid: number; readonly mode: number },
+  uid: number,
+  groups: readonly number[] | undefined,
+): boolean | undefined => {
+  if (uid === 0) return true;
+  if (file.uid === uid) return (file.mode & 0o400) !== 0;
+  const groupRead = (file.mode & 0o040) !== 0;
+  const otherRead = (file.mode & 0o004) !== 0;
+  // Membership cannot change the answer when both classes agree.
+  if (groupRead === otherRead) return groupRead;
+  if (groups === undefined) return undefined;
+  return groups.includes(file.gid) ? groupRead : otherRead;
+};
+
+/**
+ * ⛔ REFUSE A FILE THE DEPLOYING USER COULD NOT READ BACK, before writing it. Both providers read
+ *   every write back to verify it (host-file-lifecycle.ts, job-lifecycle.ts) and read it again at
+ *   every plan, as the deploying user; this runner elevates writes, never reads. A root-only
+ *   `0600` would be installed, then fail the read-back with EACCES and stay on disk with no state,
+ *   so every later plan would fail too.
+ * ★ An omitted owner is root (under a prefix the runner writes as root). An omitted group is the
+ *   parent directory's, which is the group a new file gets on macOS.
+ * ⚠️ Unknown groups never refuse: the read-back after the write stays the final judge.
+ */
+export const assertReadableBack = async (
+  base: HostRunner,
+  path: string,
+  options: WriteOptions,
+  groups: readonly number[] | undefined,
+): Promise<void> => {
+  const operator = base.effectiveUid();
+  const parent = path.slice(0, path.lastIndexOf('/')) || '/';
+  const gid = options.gid ?? (await base.stat(parent))?.gid ?? 0;
+  const file = { gid, mode: options.mode, uid: options.uid ?? 0 };
+  if (canRead(file, operator, groups) !== false) return;
+  throw refuse(
+    path,
+    `owner ${String(file.uid)}, group ${String(gid)}, mode ${file.mode.toString(8)} would hide it ` +
+      `from the deploying user (uid ${String(operator)}), who reads every file back. Declare a ` +
+      'mode that user can read, or deploy as root. Nothing was written.',
+  );
+};
+
+/**
+ * The deploying user's groups, from `id -G`; `undefined` when that fails.
+ * ⚠️ NOT process.getgroups(). MEASURED 2026-09-21 on macOS 27.2: getgroups() returned 16 groups
+ *   where `id -G` returned 18, because macOS caps a process's own list at 16. A group past the
+ *   16th would read as "not a member" and refuse a file the user can in fact read.
+ */
+export const operatorGroups = async (base: HostRunner): Promise<readonly number[] | undefined> => {
+  const result = await base.exec(['/usr/bin/id', '-G']);
+  const ids = result.stdout.trim().split(/\s+/);
+  return result.exitCode === 0 && ids.every((id) => /^\d+$/.test(id)) ? ids.map(Number) : undefined;
+};

package/src/launchd/sudo-guard.ts

@@ -23,6 +23,9 @@
 import type { FileStat, HostRunner, WriteOptions } from './runner.ts';
 import { assertNoAclGrants } from './sudo-acl.ts';
 import { SudoRefusedError } from './sudo-allowlist.ts';
+import { assertReadableBack, modeProblem } from './sudo-guard-mode.ts';
+
+export { assertReadableBack, canRead, modeProblem, operatorGroups } from './sudo-guard-mode.ts';
 
 const refuse = (path: string, message: string): Error =>
   new SudoRefusedError(`sudoRunner ${path}: ${message}`);
@@ -126,23 +129,6 @@ export const assertPlainPath = async (
   throw refuse(path, `is ${target === undefined ? 'missing' : `a ${target.kind}`}, not a file`);
 };
 
-/**
- * ⛔ A ROOT-OWNED FILE UNDER A PREFIX IS ROOT'S TO CHANGE, AND ONLY ROOT'S (decided 2026-09-21).
- *   Group- or world-writable, anyone in that class rewrites a file root installed — a daemon's
- *   config, a script a LaunchDaemon runs as root — which is root by another name. Setuid or setgid,
- *   it runs as root (or its group) for whoever executes it. install(1) would apply either, as root.
- * ★ Root-owned is an omitted owner (the runner installs as root under a prefix) or uid 0. A file
- *   handed to another user is that user's to change; the sticky bit changes nothing on a file.
- */
-export const modeProblem = (options: WriteOptions): string | undefined => {
-  if (options.uid !== undefined && options.uid !== 0) return undefined;
-  const found: string[] = [];
-  if ((options.mode & 0o6000) !== 0) found.push('setuid/setgid');
-  if ((options.mode & 0o022) !== 0) found.push('writable by group or other');
-  if (found.length === 0) return undefined;
-  return `mode ${options.mode.toString(8).padStart(4, '0')} is ${found.join(' and ')} on a root-owned file`;
-};
-
 /**
  * Every check a write under `prefix` meets before anything is staged or run as root: the mode, the
  * path (assertPlainPath) and the read-back (assertReadableBack). ★ Reads only, as the deploying
@@ -166,65 +152,3 @@ export const assertInstallable = async (
   await assertPlainPath(base, prefix, path, 'file-or-absent');
   await assertReadableBack(base, path, options, groups);
 };
-
-/**
- * POSIX read permission for one uid: owner class, else group class, else other. `undefined` when
- * only group membership could decide and the groups are unknown.
- * ⚠️ EXACTLY ONE CLASS APPLIES. A group member gets the group bits even when the other bits are
- *   wider (`0604` hides a file from its group), so "other can read" is not enough on its own.
- */
-export const canRead = (
-  file: { readonly uid: number; readonly gid: number; readonly mode: number },
-  uid: number,
-  groups: readonly number[] | undefined,
-): boolean | undefined => {
-  if (uid === 0) return true;
-  if (file.uid === uid) return (file.mode & 0o400) !== 0;
-  const groupRead = (file.mode & 0o040) !== 0;
-  const otherRead = (file.mode & 0o004) !== 0;
-  // Membership cannot change the answer when both classes agree.
-  if (groupRead === otherRead) return groupRead;
-  if (groups === undefined) return undefined;
-  return groups.includes(file.gid) ? groupRead : otherRead;
-};
-
-/**
- * ⛔ REFUSE A FILE THE DEPLOYING USER COULD NOT READ BACK, before writing it. Both providers read
- *   every write back to verify it (host-file-lifecycle.ts, job-lifecycle.ts) and read it again at
- *   every plan, as the deploying user; this runner elevates writes, never reads. A root-only
- *   `0600` would be installed, then fail the read-back with EACCES and stay on disk with no state,
- *   so every later plan would fail too.
- * ★ An omitted owner is root (under a prefix the runner writes as root). An omitted group is the
- *   parent directory's, which is the group a new file gets on macOS.
- * ⚠️ Unknown groups never refuse: the read-back after the write stays the final judge.
- */
-export const assertReadableBack = async (
-  base: HostRunner,
-  path: string,
-  options: WriteOptions,
-  groups: readonly number[] | undefined,
-): Promise<void> => {
-  const operator = base.effectiveUid();
-  const parent = path.slice(0, path.lastIndexOf('/')) || '/';
-  const gid = options.gid ?? (await base.stat(parent))?.gid ?? 0;
-  const file = { gid, mode: options.mode, uid: options.uid ?? 0 };
-  if (canRead(file, operator, groups) !== false) return;
-  throw refuse(
-    path,
-    `owner ${String(file.uid)}, group ${String(gid)}, mode ${file.mode.toString(8)} would hide it ` +
-      `from the deploying user (uid ${String(operator)}), who reads every file back. Declare a ` +
-      'mode that user can read, or deploy as root. Nothing was written.',
-  );
-};
-
-/**
- * The deploying user's groups, from `id -G`; `undefined` when that fails.
- * ⚠️ NOT process.getgroups(). MEASURED 2026-09-21 on macOS 27.2: getgroups() returned 16 groups
- *   where `id -G` returned 18, because macOS caps a process's own list at 16. A group past the
- *   16th would read as "not a member" and refuse a file the user can in fact read.
- */
-export const operatorGroups = async (base: HostRunner): Promise<readonly number[] | undefined> => {
-  const result = await base.exec(['/usr/bin/id', '-G']);
-  const ids = result.stdout.trim().split(/\s+/);
-  return result.exitCode === 0 && ids.every((id) => /^\d+$/.test(id)) ? ids.map(Number) : undefined;
-};

package/src/launchd/sudo-modes.test.ts

@@ -34,7 +34,44 @@ describe('modeProblem', () => {
     ['4755 root is setuid', { mode: 0o4755 }, 'setuid/setgid'],
     ['2755 root is setgid', { mode: 0o2755, uid: 0 }, 'setuid/setgid'],
     ['6777 root is both', { mode: 0o6777 }, 'setuid/setgid and writable by group or other'],
-    ['0664 handed to another user is theirs to change', { mode: 0o664, uid: OPERATOR }, undefined],
+    [
+      '0664 handed to another user AND an explicitly non-root group is theirs to change',
+      { gid: 80, mode: 0o664, uid: OPERATOR },
+      undefined,
+    ],
+    // 🔴 Adversarial review, 2026-09-23, round 1: the non-root-uid exemption alone let a
+    //   setgid-root file through untouched as long as its OWNER was merely non-zero — the group is
+    //   root's just as much as the owner being uid 0 would be. gid 0 must keep every check active.
+    [
+      'setgid to root’s own group, handed to another OWNER, is still root’s file to protect',
+      { gid: 0, mode: 0o2775, uid: OPERATOR },
+      'setuid/setgid',
+    ],
+    [
+      'group-writable with root’s own group, handed to another owner',
+      { gid: 0, mode: 0o664, uid: OPERATOR },
+      'writable by group or other',
+    ],
+    [
+      'handed to another owner AND another group is genuinely theirs, setgid included',
+      { gid: 80, mode: 0o2775, uid: OPERATOR },
+      undefined,
+    ],
+    // 🔴 Adversarial review, round 2: an OMITTED gid is not "someone else's" either — GNU install,
+    //   run as root via sudo, defaults a missing -g to root's OWN group whenever the destination
+    //   directory is not itself setgid (none of this runner's prefixes are), so a `RemoteFile`
+    //   with an owner but no declared `group` reaches this check exactly as `gid: 0` would, and
+    //   must be refused exactly as `gid: 0` is above.
+    [
+      'setgid, handed to another owner, with the group simply never declared',
+      { mode: 0o2775, uid: OPERATOR },
+      'setuid/setgid',
+    ],
+    [
+      'group-writable, handed to another owner, with the group simply never declared',
+      { mode: 0o664, uid: OPERATOR },
+      'writable by group or other',
+    ],
   ] as const)('%s', (_name, options, found) => {
     const problem = modeProblem(options);
     if (found === undefined) expect(problem).toBeUndefined();

package/src/linux/fake-sudo-root.ts

@@ -0,0 +1,157 @@
+/**
+ * The "as root" half of fake-sudo.ts: what each allowlisted program does against the SAME
+ * in-memory host `fake-linux-host.ts` builds, once `/usr/bin/sudo` has decided to run it.
+ *
+ * ⛔ TEST-ONLY, like fake-linux-host.ts: no provider imports it, it is not on the barrel.
+ * ★ CHOWN AND MKDIR ARE HANDLED HERE, NOT BY DELEGATING TO `fake.runner.exec()` — the fake's own
+ *   `chown` refuses when its FIXED `root` flag is false (which it is: the base host models an
+ *   unprivileged operator), and `mkdir`/`chmod`/`rmdir` do not check ownership at all. Only a
+ *   handler that writes `fake.dirs` / `fake.modes` / `fake.files` directly proves the runner's
+ *   OWN allowlist and guard are what gate root, not a permission check the fake happens to have.
+ * ★ INSTALL AND MV READ AND WRITE `fake.files` DIRECTLY TOO, because the staged file the operator
+ *   wrote (via `stageRemote`'s ordinary `writeFileAtomic`) already lives there — there is no
+ *   separate "staged bytes" side-channel to model, unlike the Mac fake's local temp files.
+ */
+import type { ExecResult, FileStat } from '../launchd/runner.ts';
+import { CHMOD, CHOWN, INSTALL, MKDIR, MV, RM, RMDIR, SYSTEMCTL_ABS } from './sudo-allowlist.ts';
+import type { fakeLinuxHost } from './fake-linux-host.ts';
+
+type Fake = ReturnType<typeof fakeLinuxHost>;
+
+/** What a test can force `sudo`'s next `mv` / `rm` to answer instead of actually running it. */
+export type RootState = { mvFailure?: ExecResult; rmFailure?: ExecResult };
+
+const ok = (stdout = ''): ExecResult => ({ exitCode: 0, stderr: '', stdout });
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+const parent = (path: string): string => path.slice(0, path.lastIndexOf('/')) || '/';
+
+const applyOwner = (live: { uid: number; gid: number }, owner: string): void => {
+  const [uidPart, gidPart] = owner.includes(':') ? owner.split(':') : [owner, undefined];
+  if (uidPart !== undefined && uidPart !== '') live.uid = Number(uidPart);
+  if (gidPart !== undefined && gidPart !== '') live.gid = Number(gidPart);
+};
+
+const dirRoot = (fake: Fake, argv: readonly string[]): ExecResult | undefined => {
+  const [program, ...args] = argv;
+  if (program === MKDIR) {
+    const [, mode, , path] = args;
+    if (path === undefined) return fail(1, 'mkdir: missing operand');
+    fake.dirs.set(path, 0);
+    fake.modes.set(path, { gid: 0, mode: Number.parseInt(mode ?? '755', 8), uid: 0 });
+    return ok();
+  }
+  if (program === CHMOD) {
+    const [mode, , path] = args;
+    const live = path === undefined ? undefined : fake.modes.get(path);
+    if (live === undefined) return fail(1, `chmod: ${String(path)}: No such file or directory`);
+    live.mode = Number.parseInt(mode ?? '755', 8);
+    return ok();
+  }
+  if (program === RMDIR) {
+    const [, path] = args;
+    if (path === undefined || !fake.dirs.has(path)) {
+      return fail(1, `rmdir: '${String(path)}': No such file or directory`);
+    }
+    if ([...fake.files.keys()].some((file) => parent(file) === path)) {
+      return fail(1, `rmdir: failed to remove '${path}': Directory not empty`);
+    }
+    fake.dirs.delete(path);
+    fake.modes.delete(path);
+    return ok();
+  }
+  return undefined;
+};
+
+const fileRoot = (
+  fake: Fake,
+  argv: readonly string[],
+  state: RootState,
+): ExecResult | undefined => {
+  const [program, ...args] = argv;
+  if (program === INSTALL) {
+    const tIndex = args.indexOf('-T');
+    const [source, dest] = args.slice(-2);
+    const ids = args.slice(2, tIndex);
+    const owned = ids.includes('-o') ? Number(ids[ids.indexOf('-o') + 1]) : 0;
+    const grouped = ids.includes('-g') ? Number(ids[ids.indexOf('-g') + 1]) : 0;
+    const bytes = source === undefined ? undefined : fake.files.get(source)?.bytes;
+    if (bytes === undefined || dest === undefined) {
+      return fail(1, `install: cannot stat '${String(source)}': No such file or directory`);
+    }
+    const kind: FileStat['kind'] = 'file';
+    fake.files.set(dest, {
+      bytes,
+      gid: grouped,
+      kind,
+      mode: Number.parseInt(args[1] ?? '644', 8),
+      uid: owned,
+    });
+    return ok();
+  }
+  if (program === MV) {
+    if (state.mvFailure !== undefined) {
+      const failure = state.mvFailure;
+      delete state.mvFailure; // ★ once, like a real transient failure — not every mv after it
+      return failure;
+    }
+    const [source, dest] = args.slice(-2);
+    const entry = source === undefined ? undefined : fake.files.get(source);
+    if (entry === undefined || dest === undefined) {
+      return fail(1, `mv: cannot stat '${String(source)}': No such file or directory`);
+    }
+    fake.files.delete(source ?? '');
+    fake.files.set(dest, entry);
+    return ok();
+  }
+  if (program === RM) {
+    if (state.rmFailure !== undefined) {
+      const failure = state.rmFailure;
+      delete state.rmFailure; // ★ once, like a real transient failure
+      return failure;
+    }
+    const [, , path] = args;
+    if (path !== undefined) fake.files.delete(path);
+    return ok();
+  }
+  return undefined;
+};
+
+/**
+ * `chown` on either a directory (`fake.modes`) or a file (`fake.files` — the derived temp,
+ * `sudo-write.ts`'s own non-root-owner step). `applyOwner` accepts the `+`-forced spec
+ * unchanged: `Number('+501')` parses to `501` in JS, same as a bare digit string.
+ */
+const chownRoot = (fake: Fake, argv: readonly string[]): ExecResult | undefined => {
+  if (argv[0] !== CHOWN) return undefined;
+  const [owner, , path] = argv.slice(1);
+  if (owner === undefined || path === undefined) {
+    return fail(1, `chown: ${String(path)}: No such file or directory`);
+  }
+  const dir = fake.modes.get(path);
+  if (dir !== undefined) {
+    applyOwner(dir, owner);
+    return ok();
+  }
+  const file = fake.files.get(path);
+  if (file !== undefined) {
+    applyOwner(file, owner);
+    return ok();
+  }
+  return fail(1, `chown: ${path}: No such file or directory`);
+};
+
+/** Everything `/usr/bin/sudo -n --` may run, dispatched as root against the same fake host. */
+export const asRoot = async (
+  fake: Fake,
+  argv: readonly string[],
+  state: RootState = {},
+): Promise<ExecResult> => {
+  const chown = chownRoot(fake, argv);
+  if (chown !== undefined) return chown;
+  const dir = dirRoot(fake, argv);
+  if (dir !== undefined) return dir;
+  const file = fileRoot(fake, argv, state);
+  if (file !== undefined) return file;
+  if (argv[0] === SYSTEMCTL_ABS) return fake.runner.exec(['systemctl', ...argv.slice(1)]);
+  return fail(1, `sudo: ${String(argv[0])}: command not found`);
+};

package/src/linux/fake-sudo.ts

@@ -0,0 +1,142 @@
+/**
+ * sshSudoRunner over fake-linux-host.ts, for the tests beside it: the operator is uid 1000 and
+ * unprivileged, and `/usr/bin/sudo` is a tiny interpreter (fake-sudo-root.ts) that runs the
+ * allowlisted programs against the SAME in-memory host, as root. No test anywhere runs ssh or a
+ * real sudo.
+ *
+ * ⛔ TEST-ONLY, like fake-linux-host.ts: no provider imports it, it is not on the barrel.
+ * ★ `ls -ldn` AND `mktemp -d` ARE MODELLED HERE, AS THE OPERATOR — sudo-guard.ts's chain read and
+ *   sudo-stage.ts's staging both run unprivileged, so both need a host that answers them without
+ *   sudo. `ls` reads through `fake.runner.stat()` (already correct for declared dirs, their
+ *   implied root-owned ancestors, and files) and formats one `ls -ldn`-shaped line per path;
+ *   `mktemp -d` registers a fresh 0700 directory the operator owns.
+ * ★ SUDO REFUSES A CALL THAT WAS NOT LOGGED FIRST, so every test holds the runner to "logged
+ *   before it runs", exactly as the Mac fake does.
+ */
+import type { ExecResult, FileStat, HostRunner } from '../launchd/runner.ts';
+import { SUDO_SAYS } from '../launchd/fake-sudo.ts';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { type RootState, asRoot } from './fake-sudo-root.ts';
+import { SUDO } from './sudo-allowlist.ts';
+import { makeSshSudoRunner } from './sudo-runner.ts';
+import { stageRemote } from './sudo-stage.ts';
+
+export { SUDO_SAYS } from '../launchd/fake-sudo.ts';
+
+export const OPERATOR = 1000;
+export const PREFIXES = ['/etc/systemd/system', '/usr/local/bin'];
+
+const ok = (stdout = ''): ExecResult => ({ exitCode: 0, stderr: '', stdout });
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+
+const permString = (mode: number): string => {
+  const triplet = (shift: number, special: number, ch: string, upper: string) => {
+    const r = (mode & (0o4 << shift)) === 0 ? '-' : 'r';
+    const w = (mode & (0o2 << shift)) === 0 ? '-' : 'w';
+    const exec = (mode & (0o1 << shift)) !== 0;
+    const marked = (mode & special) !== 0;
+    return `${r}${w}${marked ? (exec ? ch : upper) : exec ? 'x' : '-'}`;
+  };
+  return `${triplet(6, 0o4000, 's', 'S')}${triplet(3, 0o2000, 's', 'S')}${triplet(0, 0o1000, 't', 'T')}`;
+};
+
+const lsLine = (path: string, stat: FileStat, acl: boolean): string => {
+  const kind = stat.kind === 'directory' ? 'd' : stat.kind === 'symlink' ? 'l' : '-';
+  const target = stat.kind === 'symlink' ? ` -> ${path}.target` : '';
+  return (
+    `${kind}${permString(stat.mode)}${acl ? '+' : ''} 1 ${String(stat.uid)} ${String(stat.gid)} ` +
+    `${String(stat.size)} Sep 22 10:12 ${path}${target}`
+  );
+};
+
+/**
+ * `extraDirs` adds more directories to the fake filesystem (a pre-existing tree outside every
+ * prefix, say); it never changes the runner's OWN prefixes, which stay `PREFIXES` throughout.
+ * `acl` is the set of directory paths a test wants to carry the `+` (POSIX ACL) flag.
+ */
+export const fakeSudoHost = (
+  extraDirs: Record<string, number> = {},
+  acl: ReadonlySet<string> = new Set(),
+) => {
+  const fake = fakeLinuxHost({
+    dirs: { '/etc/systemd/system': 0, '/usr/local/bin': 0, ...extraDirs },
+    euid: OPERATOR,
+    users: { app: { gid: 60, home: '/opt/app', uid: 900 } },
+  });
+  let mktempCount = 0;
+  const logs: string[] = [];
+  const sudoCalls: string[][] = [];
+  const state: RootState & { sudo: 'ok' | keyof typeof SUDO_SAYS } = { sudo: 'ok' };
+
+  const handleLs = async (paths: readonly string[]): Promise<ExecResult> => {
+    const lines: string[] = [];
+    for (const path of paths) {
+      const stat = await fake.runner.stat(path);
+      if (stat === undefined)
+        return fail(2, `ls: cannot access '${path}': No such file or directory`);
+      lines.push(lsLine(path, stat, acl.has(path)));
+    }
+    return ok(`${lines.join('\n')}\n`);
+  };
+
+  const handleMktemp = (): ExecResult => {
+    mktempCount += 1;
+    const dir = `/tmp/hf-sudo-${String(mktempCount)}`;
+    fake.dirs.set(dir, OPERATOR);
+    fake.modes.set(dir, { gid: 0, mode: 0o700, uid: OPERATOR });
+    return ok(`${dir}\n`);
+  };
+
+  /** `rm -rf -- <dir>`, as the operator — `sudo-stage.ts`'s own cleanup of its staging directory. */
+  const handleRm = (argv: readonly string[]): ExecResult => {
+    const target = argv.at(-1);
+    if (target === undefined) return fail(1, 'rm: missing operand');
+    const under = (path: string) => path === target || path.startsWith(`${target}/`);
+    for (const path of [...fake.files.keys()].filter(under)) fake.files.delete(path);
+    for (const path of [...fake.dirs.keys()].filter(under)) {
+      fake.dirs.delete(path);
+      fake.modes.delete(path);
+    }
+    return ok();
+  };
+
+  const base: HostRunner = {
+    ...fake.runner,
+    exec: async (argv) => {
+      // ★ Read-only, operator-level calls now go by absolute path too (cosmetic hardening from
+      //   the 2026-09-23 adversarial review — see the sources' own headers); fakeLinuxHost's own
+      //   dispatcher only recognises the bare names it was built against, so both spellings are
+      //   handled here and `systemctl`'s absolute form is translated back to bare before it is
+      //   handed off, rather than teaching the shared fixture a second spelling.
+      if (argv[0] === 'ls' || argv[0] === '/usr/bin/ls') {
+        if (argv[1] === '-ldn') return handleLs(argv.slice(3));
+      }
+      if ((argv[0] === 'mktemp' || argv[0] === '/usr/bin/mktemp') && argv[1] === '-d') {
+        return handleMktemp();
+      }
+      if (argv[0] === 'rm' || argv[0] === '/usr/bin/rm') return handleRm(argv);
+      if (argv[0] === '/usr/bin/systemctl')
+        return fake.runner.exec(['systemctl', ...argv.slice(1)]);
+      if (argv[0] !== SUDO) return fake.runner.exec(argv);
+      sudoCalls.push([...argv]);
+      if (logs[logs.length - 1] !== `homeflare/linux sudo -n ${JSON.stringify(argv.slice(3))}`) {
+        throw new Error(`fake sudo: ${JSON.stringify(argv)} was not logged before it ran`);
+      }
+      if (state.sudo !== 'ok') return fail(1, SUDO_SAYS[state.sudo]);
+      return asRoot(fake, argv.slice(3), state);
+    },
+  };
+
+  const runner = makeSshSudoRunner(PREFIXES, {
+    base,
+    log: (line) => logs.push(line),
+    // ★ The real stager, unmodified: it only ever calls `base.exec`/`base.writeFileAtomic`, both
+    //   of which this fake's `mktemp`/`ls`/operator-level paths already answer.
+    stage: stageRemote(base),
+  });
+  /** The privileged commands run, without the `sudo -n --` in front. */
+  const privileged = () => sudoCalls.map((call) => call.slice(3));
+  // ★ `base` (unprivileged, but with `ls`/`mktemp` support) is exposed for sudo-guard.test.ts,
+  //   which exercises assertGuardedChain directly, below the runner it is a building block of.
+  return { base, fake, logs, privileged, runner, state };
+};

package/src/linux/index.ts

@@ -19,6 +19,8 @@ export type { RemoteFileAttributes, RemoteFileProps } from './remote-file-form.t
 export { RemoteFile, RemoteFileProvider } from './remote-file.ts';
 export type { SshRunnerOptions } from './ssh-runner.ts';
 export { sshRunner } from './ssh-runner.ts';
+export type { SshSudoRunnerOptions } from './sudo-runner.ts';
+export { sshSudoRunner } from './sudo-runner.ts';
 export type {
   ExecResult,
   FileStat,

package/src/linux/sudo-allowlist-chown.ts

@@ -0,0 +1,71 @@
+/**
+ * `chown`'s two privileged shapes, split out of sudo-allowlist.ts to keep it under the house's
+ * 250-line cap: the ROOT-ONLY directory form (sudo-allowlist-dir.ts owns that check) and the
+ * FILE-ownership form used only on the derived temp file `sudo-write.ts` `install`s into, for a
+ * `RemoteFile` whose declared owner or group is not root.
+ *
+ * ⛔ `install`'S OWN `-o`/`-g` ARE NEVER USED, ON EITHER PLATFORM'S ALLOWLIST NOW. 🔴 MEASURED
+ *   (adversarial review, round 2, 2026-09-23, against coreutils 9.7 `src/install.c` `get_ids()`):
+ *   unlike `chown`, `install` does NOT go through gnulib's `+`-aware `userspec.c` at all — its own
+ *   `get_ids()` calls `getpwnam(owner_name)` / `getgrnam(group_name)` FIRST for ANY string,
+ *   falling back to `xstrtoumax` only when no such account exists, with no `+`-prefix escape of
+ *   any kind. So `install -o 0` on a host with a user or group literally named `"0"` installs
+ *   owned by THAT account, not uid 0 — and there is no argv shape that closes this for `install`
+ *   itself. The fix is to never let `install` set ownership: it always runs with no `-o`/`-g` (so
+ *   the fresh temp file lands owned by whoever `sudo` runs it as — root:root, with no name lookup
+ *   at all, since omitting the flags skips `get_ids` entirely), and this file's `chown` shape sets
+ *   the FINAL ownership afterward, on the same temp file, before `mv`. `chown` DOES support `+`
+ *   (gnulib `userspec.c`: `*u == '+' ? NULL : getpwnam(u)`, "if it starts with '+', skip the
+ *   look-up") — repeated on each side of a `user:group` spec independently — so this is where the
+ *   fix actually lands: `+<uid>`, `:+<gid>`, or `+<uid>:+<gid>`, never a bare digit string.
+ */
+import { CHOWN, dirProgramProblem } from './sudo-allowlist-dir.ts';
+
+/** Bare `directory-lifecycle.ts` argv (`0`, `:0`, `0:0`, …) → the `+`-forced form sudo may run. */
+export const forceNumericOwner = (spec: string): string => {
+  const [uidPart, gidPart] = spec.includes(':') ? spec.split(':') : [spec, undefined];
+  const uid = uidPart === undefined || uidPart === '' ? '' : `+${uidPart}`;
+  const gid = gidPart === undefined ? '' : `:+${gidPart}`;
+  return `${uid}${gid}`;
+};
+
+/** `+<uid>`, `:+<gid>`, or `+<uid>:+<gid>` — numeric, `+`-forced, either or both sides. */
+const SAFE_OWNER = /^(\+\d+(:\+\d+)?|:\+\d+)$/;
+
+/**
+ * `chown <safe spec> -- <temp>`, bound to the exact temp `install` just wrote — the file-ownership
+ * half of `writeUnderPrefix`'s sequence. Any owner/group is allowed (a `RemoteFile` may declare
+ * one), as long as it is numeric and forced; the temp binding is what stops it reaching anywhere
+ * else, the same way `mv`'s own binding does.
+ */
+const fileChownProblem = (args: readonly string[], temp: string): string | undefined => {
+  const [owner, end, path, ...extra] = args;
+  if (
+    owner !== undefined &&
+    SAFE_OWNER.test(owner) &&
+    end === '--' &&
+    extra.length === 0 &&
+    path === temp
+  ) {
+    return undefined;
+  }
+  return (
+    'chown on the staged temp takes exactly `+<uid>`, `:+<gid>` or `+<uid>:+<gid>` -- ' +
+    '<the exact temp install just wrote>, numeric and +-forced'
+  );
+};
+
+/**
+ * `chown`'s dispatch: a call bound to `context.temp` (its last argument equals it) is the
+ * file-ownership form above; everything else is the directory form, root-only
+ * (`sudo-allowlist-dir.ts`'s own `ROOT_OWNER`, `+`-forced the same way).
+ */
+export const chownProblem = (
+  args: readonly string[],
+  context: { readonly prefixes: readonly string[]; readonly temp?: string },
+): string | undefined => {
+  const path = args[args.length - 1];
+  if (context.temp !== undefined && path === context.temp)
+    return fileChownProblem(args, context.temp);
+  return dirProgramProblem(CHOWN, args, context.prefixes);
+};