@homeflare/alchemy 0.25.1 → 0.27.0

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

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

@@ -0,0 +1,103 @@
+/**
+ * The `mkdir` / `chmod` / `chown` / `rmdir` half of sudo-allowlist.ts, split out to keep that file
+ * under the house's 250-line cap. These four are `Host.Directory`'s whole write surface
+ * (directory-lifecycle.ts): this file fixes their argv to the EXACT shapes that file emits.
+ *
+ * ⛔ `chown` TAKES ONLY NUMERIC IDS, NEVER A NAME. `directory-lifecycle.ts`'s `ownerArg()` already
+ *   resolves a name to a uid/gid before building argv, so a name here would mean some other code
+ *   path built this argv — refused rather than trusted.
+ * 🔴 MEASURED (adversarial review, 2026-09-23, against this file's first shipped version): NEITHER
+ *   the mode nor the owner was checked for anything but shape. `mkdir -m 0777 -- <path>` and
+ *   `chown 1001:1001 -- <path>` both passed the allowlist untouched. A stack could declare
+ *   `HostDirectory({ path: '/etc/systemd/system/x.service.d', mode: 0o777 })`, drop a
+ *   `ExecStart=` override into it, and the runner's own next `daemon-reload` + `restart` would run
+ *   it as root — a local privilege escalation reachable through this runner's own allowlist, not a
+ *   bug in the guard (which never runs against a path this permissive by design).
+ * ⛔ SO: NO SPECIAL BITS, NO GROUP/OTHER WRITE, EVER — mirroring the file half's `modeProblem`
+ *   (`../launchd/sudo-guard.ts`) but WITHOUT its "handed to another owner" exemption. A directory's
+ *   OWNER always has write access through the owner bits alone, so no mode restriction can make a
+ *   non-root-owned directory here safe — which is why `chown` below is refused to anything but
+ *   root outright, not merely mode-restricted.
+ * 🔴 MEASURED (adversarial review, round 2, 2026-09-23, cited against gnulib's `lib/userspec.c`,
+ *   used by GNU `chown`): a purely-numeric owner string is looked up as a NAME first —
+ *   `*u == '+' ? NULL : getpwnam(u)` — and only parsed as a raw number when no such account
+ *   exists. If a host ever had a user or group literally NAMED `"0"`, `chown 0 -- path` would
+ *   silently chown to THAT account, not uid 0 — bypassing this file's own root-only restriction
+ *   without tripping it. `+` skips the name lookup outright (`if it starts with '+', skip the
+ *   look-up`, `userspec.c`), so the allowlist now requires it: `sudo-allowlist.ts`'s
+ *   `canonicalize()` rewrites the bare `0`/`:0`/`0:0` argv `directory-lifecycle.ts` actually sends
+ *   into the forced-numeric form below before this check ever runs, so the unprivileged caller
+ *   never has to know this syntax exists.
+ */
+import { prefixOf } from '../launchd/sudo-allowlist.ts';
+
+export const MKDIR = '/usr/bin/mkdir';
+export const CHMOD = '/usr/bin/chmod';
+export const CHOWN = '/usr/bin/chown';
+export const RMDIR = '/usr/bin/rmdir';
+
+/**
+ * `mkdir -m` / `chmod`'s mode, exactly as `directory-lifecycle.ts`'s own `octal()` formats it:
+ * `mode.toString(8).padStart(3, '0')` — 3 digits, or 4 when a special bit makes it longer.
+ * Parsed to a number so the setuid/setgid/group/other-write bits can be checked directly, the same
+ * mask `modeProblem` uses (`0o6000 | 0o022`).
+ */
+const parseDirMode = (text: string): number | undefined =>
+  /^([0-7]{3}|[1-7][0-7]{3})$/.test(text) ? Number.parseInt(text, 8) : undefined;
+
+const DANGEROUS_MODE_BITS = 0o6022;
+
+/** `undefined` when `mode` is a safe directory mode: no setuid/setgid, no group/other write. */
+const dirModeProblem = (mode: number | undefined): string | undefined => {
+  if (mode === undefined) return 'mode';
+  return (mode & DANGEROUS_MODE_BITS) !== 0
+    ? 'a mode with setuid/setgid or group/other write (this runner installs only 0–0o777 minus 0o022, no special bits)'
+    : undefined;
+};
+
+/**
+ * `chown`'s owner argument — root only, and `+`-forced so a same-named account can never be
+ * resolved instead of uid/gid `0`. `canonicalize()` builds these from the bare `0`/`:0`/`0:0`
+ * `directory-lifecycle.ts`'s `ownerArg()` sends; this checks what actually reaches `sudo`.
+ */
+const ROOT_OWNER = /^(\+0|:\+0|\+0:\+0)$/;
+
+export const dirProgramProblem = (
+  program: string,
+  args: readonly string[],
+  prefixes: readonly string[],
+): string | undefined => {
+  const under = (path: string | undefined) =>
+    path !== undefined && prefixOf(path, prefixes) !== undefined;
+  if (program === MKDIR) {
+    const [m, modeText, end, path, ...extra] = args;
+    const mode = modeText === undefined ? undefined : parseDirMode(modeText);
+    if (m !== '-m' || mode === undefined || end !== '--' || extra.length !== 0 || !under(path)) {
+      return 'mkdir takes exactly `-m <octal> -- <path under a declared prefix>`';
+    }
+    return dirModeProblem(mode);
+  }
+  if (program === CHMOD) {
+    const [modeText, end, path, ...extra] = args;
+    const mode = modeText === undefined ? undefined : parseDirMode(modeText);
+    if (mode === undefined || end !== '--' || extra.length !== 0 || !under(path)) {
+      return 'chmod takes exactly `<octal> -- <path under a declared prefix>`';
+    }
+    return dirModeProblem(mode);
+  }
+  if (program === CHOWN) {
+    const [owner, end, path, ...extra] = args;
+    return owner !== undefined &&
+      ROOT_OWNER.test(owner) &&
+      end === '--' &&
+      extra.length === 0 &&
+      under(path)
+      ? undefined
+      : 'chown takes exactly `+0`, `:+0` or `+0:+0` -- <path under a declared prefix>` — root ' +
+          'only, forced numeric; a directory this runner elevates never hands ownership to anyone else';
+  }
+  const [end, path, ...extra] = args;
+  return end === '--' && extra.length === 0 && under(path)
+    ? undefined
+    : 'rmdir takes exactly `-- <path under a declared prefix>`';
+};