@homeflare/alchemy 0.7.0 → 0.10.0

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

@@ -0,0 +1,191 @@
+/**
+ * The allowlist, as pure argv checks. Each refusal here is a shape that would do real damage as
+ * root; each acceptance is a shape the providers or the runner actually produce.
+ */
+import { describe, expect, test } from 'bun:test';
+import { LAUNCHCTL } from './launchctl.ts';
+import {
+  INSTALL,
+  RM,
+  checkPrefixes,
+  octalMode,
+  prefixOf,
+  privilegedProblem,
+  routeExec,
+} from './sudo-allowlist.ts';
+
+const DAEMONS = '/Library/LaunchDaemons';
+const context = { prefixes: [DAEMONS, '/opt/example'], staged: '/tmp/hf-sudo-x/staged' };
+const allowed = (argv: string[]) => privilegedProblem(argv, context);
+const PLIST = `${DAEMONS}/com.example.a.plist`;
+
+describe('checkPrefixes', () => {
+  test.each([
+    [[], 'no prefixes'],
+    [['/'], 'every path'],
+    [['opt/example'], 'absolute'],
+    [['/opt/example/'], 'normalised'],
+    [['/opt/../etc'], 'normalised'],
+  ])('refuses %j', (prefixes, message) => {
+    expect(() => checkPrefixes(prefixes)).toThrow(message);
+  });
+
+  test('keeps a valid list', () => {
+    expect(checkPrefixes([DAEMONS])).toEqual([DAEMONS]);
+  });
+});
+
+describe('prefixOf', () => {
+  test('strictly under, never a sibling with the same leading text, never the prefix itself', () => {
+    expect(prefixOf('/opt/example/a.conf', context.prefixes)).toBe('/opt/example');
+    expect(prefixOf('/opt/example-other/a.conf', context.prefixes)).toBeUndefined();
+    expect(prefixOf('/opt/example', context.prefixes)).toBeUndefined();
+  });
+
+  test('a path that walks out with .. is not under anything', () => {
+    expect(prefixOf('/opt/example/../../etc/sudoers', context.prefixes)).toBeUndefined();
+  });
+});
+
+describe('launchctl shapes', () => {
+  test.each([
+    [[LAUNCHCTL, 'bootstrap', 'system', PLIST]],
+    [[LAUNCHCTL, 'bootout', 'system/com.example.a']],
+    [[LAUNCHCTL, 'kickstart', 'system/com.example.a']],
+    [[LAUNCHCTL, 'kickstart', '-k', '-p', 'system/com.example.a']],
+  ])('allows %j', (argv) => {
+    expect(allowed(argv)).toBeUndefined();
+  });
+
+  test.each([
+    // ⛔ launchctl(1): a bare domain removes the whole system domain.
+    ['bootout of the bare system domain', [LAUNCHCTL, 'bootout', 'system']],
+    ['bootout by domain plus path', [LAUNCHCTL, 'bootout', 'system', PLIST]],
+    // ⛔ launchctl(1): a directory bootstraps every plist in it.
+    ['bootstrap of a directory', [LAUNCHCTL, 'bootstrap', 'system', DAEMONS]],
+    ['bootstrap of two plists', [LAUNCHCTL, 'bootstrap', 'system', PLIST, PLIST]],
+    [
+      'bootstrap outside every prefix',
+      [LAUNCHCTL, 'bootstrap', 'system', '/tmp/com.example.a.plist'],
+    ],
+    ['bootstrap of a non-plist', [LAUNCHCTL, 'bootstrap', 'system', `${DAEMONS}/com.example.a`]],
+    // ★ Only where launchd loads daemons at boot: anywhere else is a job that vanishes on restart.
+    [
+      'bootstrap from another prefix',
+      [LAUNCHCTL, 'bootstrap', 'system', '/opt/example/com.example.a.plist'],
+    ],
+    [
+      'bootstrap from a subdirectory',
+      [LAUNCHCTL, 'bootstrap', 'system', `${DAEMONS}/sub/com.example.a.plist`],
+    ],
+    ['bootstrap into a gui domain', [LAUNCHCTL, 'bootstrap', 'gui/501', PLIST]],
+    ['a reserved label', [LAUNCHCTL, 'bootout', 'system/com.apple.xpc.foo']],
+    ['a label that is a path', [LAUNCHCTL, 'bootout', 'system/../x']],
+    [
+      'kickstart -s (suspended, for a debugger)',
+      [LAUNCHCTL, 'kickstart', '-s', 'system/com.example.a'],
+    ],
+    ['a repeated flag', [LAUNCHCTL, 'kickstart', '-k', '-k', 'system/com.example.a']],
+    ['kickstart of the bare domain', [LAUNCHCTL, 'kickstart', '-k', 'system']],
+    ['kickstart of a reserved label', [LAUNCHCTL, 'kickstart', 'system/com.apple.xpc.foo']],
+    ['enable', [LAUNCHCTL, 'enable', 'system/com.example.a']],
+    ['print, which never needs root', [LAUNCHCTL, 'print', 'system/com.example.a']],
+  ])('refuses %s', (_name, argv) => {
+    expect(allowed(argv)).toBeString();
+  });
+});
+
+test('without /Library/LaunchDaemons declared, bootstrap and bootout are refused; kickstart is not', () => {
+  const narrow = { prefixes: ['/opt/example'] };
+  // ⚠️ bootout first, then a refused rm, would leave a plist launchd loads again at boot.
+  expect(privilegedProblem([LAUNCHCTL, 'bootout', 'system/com.example.a'], narrow)).toContain(
+    '/Library/LaunchDaemons',
+  );
+  expect(privilegedProblem([LAUNCHCTL, 'bootstrap', 'system', PLIST], narrow)).toContain(
+    '/Library/LaunchDaemons',
+  );
+  expect(
+    privilegedProblem([LAUNCHCTL, 'kickstart', 'system/com.example.a'], narrow),
+  ).toBeUndefined();
+});
+
+describe('install and rm shapes', () => {
+  const staged = context.staged;
+  test.each([
+    [[INSTALL, '-S', '-m', '0644', staged, '/opt/example/a.conf']],
+    [[INSTALL, '-S', '-m', '4755', '-o', '0', staged, '/opt/example/a']],
+    [[INSTALL, '-S', '-m', '0644', '-g', '80', staged, '/opt/example/a']],
+    [[INSTALL, '-S', '-m', '0644', '-o', '0', '-g', '0', staged, PLIST]],
+    [[RM, '-f', '--', '/opt/example/a.conf']],
+  ])('allows %j', (argv) => {
+    expect(allowed(argv)).toBeUndefined();
+  });
+
+  test.each([
+    // ⛔ Copying any other source would publish a root-only file.
+    [
+      'a source it did not stage',
+      [INSTALL, '-S', '-m', '0644', '/etc/master.passwd', '/opt/example/a'],
+    ],
+    ['a destination outside every prefix', [INSTALL, '-S', '-m', '0644', staged, '/etc/sudoers']],
+    ['a destination that walks out', [INSTALL, '-S', '-m', '0644', staged, '/opt/example/../x']],
+    ['no -S', [INSTALL, '-m', '0644', staged, '/opt/example/a']],
+    ['a three-digit mode', [INSTALL, '-S', '-m', '644', staged, '/opt/example/a']],
+    ['a symbolic mode', [INSTALL, '-S', '-m', 'u+s', staged, '/opt/example/a']],
+    ['an owner by name', [INSTALL, '-S', '-m', '0644', '-o', 'root', staged, '/opt/example/a']],
+    ['-g before -o', [INSTALL, '-S', '-m', '0644', '-g', '0', '-o', '0', staged, '/opt/example/a']],
+    ['-d (make directories)', [INSTALL, '-S', '-m', '0644', '-d', staged, '/opt/example/a']],
+    ['two destinations', [INSTALL, '-S', '-m', '0644', staged, '/opt/example/a', '/opt/example/b']],
+    ['rm -r', [RM, '-rf', '--', '/opt/example/a']],
+    ['rm without --', [RM, '-f', '/opt/example/a']],
+    ['rm of two paths', [RM, '-f', '--', '/opt/example/a', '/opt/example/b']],
+    ['rm of a prefix itself', [RM, '-f', '--', '/opt/example']],
+    ['any other program', ['/bin/sh', '-c', 'true']],
+  ])('refuses %s', (_name, argv) => {
+    expect(allowed(argv)).toBeString();
+  });
+
+  test('without a staged file, no install is allowed at all', () => {
+    const argv = [INSTALL, '-S', '-m', '0644', 'undefined', '/opt/example/a'];
+    expect(privilegedProblem(argv, { prefixes: context.prefixes })).toBeString();
+  });
+
+  test('octalMode is four digits, and refuses what chmod cannot mean', () => {
+    expect(octalMode(0o644)).toBe('0644');
+    expect(octalMode(0o4755)).toBe('4755');
+    expect(octalMode(0o10000)).toBeUndefined();
+    expect(octalMode(-1)).toBeUndefined();
+    expect(octalMode(1.5)).toBeUndefined();
+  });
+});
+
+describe('routeExec', () => {
+  const route = (argv: string[]) => routeExec(argv, 501);
+  test('system-domain writes go to root', () => {
+    expect(route([LAUNCHCTL, 'bootstrap', 'system', PLIST])).toEqual({ as: 'root' });
+    expect(route([LAUNCHCTL, 'bootout', 'system/com.example.a'])).toEqual({ as: 'root' });
+    expect(route([LAUNCHCTL, 'kickstart', '-k', 'system/com.example.a'])).toEqual({ as: 'root' });
+    // A malformed system write still routes to root, where the allowlist refuses it.
+    expect(route([LAUNCHCTL, 'bootout', 'system'])).toEqual({ as: 'root' });
+  });
+
+  test('reads, lookups and the operator’s own gui domain stay unelevated', () => {
+    expect(route([LAUNCHCTL, 'print', 'system/com.example.a'])).toEqual({ as: 'operator' });
+    expect(route([LAUNCHCTL, 'print-disabled', 'system'])).toEqual({ as: 'operator' });
+    expect(route([LAUNCHCTL, 'bootstrap', 'gui/501', '/Users/x/a.plist'])).toEqual({
+      as: 'operator',
+    });
+    expect(route([LAUNCHCTL, 'bootout', 'gui/501/com.example.a'])).toEqual({ as: 'operator' });
+    expect(route(['/usr/bin/dscacheutil', '-q', 'user'])).toEqual({ as: 'operator' });
+  });
+
+  test('another user’s domain is refused, not passed through to fail on EPERM', () => {
+    expect(route([LAUNCHCTL, 'bootout', 'gui/502/com.example.a'])).toHaveProperty('refuse');
+    expect(route([LAUNCHCTL, 'kickstart', 'user/502/com.example.a'])).toHaveProperty('refuse');
+  });
+
+  test('a sudo argv is never passed through', () => {
+    expect(route(['/usr/bin/sudo', '-n', '/bin/rm', '-rf', '/'])).toHaveProperty('refuse');
+    expect(route(['sudo', 'true'])).toHaveProperty('refuse');
+  });
+});

package/src/launchd/sudo-allowlist.ts

@@ -0,0 +1,213 @@
+/**
+ * Everything sudo-runner.ts may run as root, as exact argv shapes, plus the rule for which calls
+ * need root at all. Pure: no I/O, so every shape is tested without sudo (sudo-allowlist.test.ts).
+ *
+ * ⛔ AN ALLOWLIST OF SHAPES, NOT OF PROGRAMS. Allowing "launchctl" would allow `bootout system` with
+ *   no service, which removes the whole system domain, and `bootstrap system <directory>`, which
+ *   loads every plist in that directory (launchctl(1), read on macOS 27.2 on 2026-09-21). Each shape
+ *   below fixes the subcommand, the domain, the flags and the number of operands, so neither of
+ *   those can be written.
+ * ⛔ PATHS ARE CHECKED LEXICALLY HERE: absolute, normalised (the same rule a HostFile path obeys,
+ *   host-file-form.ts) and STRICTLY under a prefix the stack declared. sudo-guard.ts then checks
+ *   the host with lstat: the prefix a root-only directory, no symlinks, and only regular files.
+ * ⛔ `install` COPIES ONLY THE FILE THIS RUNNER STAGED. Any other source would let the runner copy
+ *   a file only root can read (/etc/master.passwd, say) to a path the deploying user can read.
+ */
+import { pathProblems } from './host-file-form.ts';
+import { plistPathFor } from './job-form.ts';
+import { LABEL, RESERVED_LABEL_PREFIXES } from './job-validate.ts';
+import { LAUNCHCTL } from './launchctl.ts';
+
+/**
+ * A privileged call that was refused before it ran: by the allowlist, by a host check
+ * (sudo-guard.ts), or by sudo itself. ★ Here, beside the allowlist, so the guard and the runner
+ *   throw the same class and a caller can tell "nothing ran as root" from "it ran and failed".
+ */
+export class SudoRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SudoRefusedError';
+  }
+}
+
+/** ★ Absolute program paths, so neither sudo nor the command is looked up on the caller's PATH. */
+export const SUDO = '/usr/bin/sudo';
+export const INSTALL = '/usr/bin/install';
+export const RM = '/bin/rm';
+
+/** The launchctl subcommands that change a domain. Everything else launchctl does is a read. */
+const WRITES: ReadonlySet<string> = new Set(['bootstrap', 'bootout', 'kickstart']);
+
+/** A mode as `install -m` takes it: four octal digits, so `0644` and `4755` are both exact. */
+export const octalMode = (mode: number): string | undefined =>
+  Number.isSafeInteger(mode) && mode >= 0 && mode <= 0o7777
+    ? mode.toString(8).padStart(4, '0')
+    : undefined;
+
+/** Validate the stack's prefixes once, when the runner is built. */
+export const checkPrefixes = (prefixes: readonly string[]): readonly string[] => {
+  if (prefixes.length === 0) {
+    throw new Error(
+      'sudoRunner: no prefixes. Name the directories root may write, e.g. /Library/LaunchDaemons.',
+    );
+  }
+  for (const prefix of prefixes) {
+    const found = prefix === '/' ? ['"/" would allow every path'] : pathProblems(prefix);
+    if (found.length > 0) {
+      throw new Error(`sudoRunner: prefix ${JSON.stringify(prefix)}: ${found.join('; ')}`);
+    }
+  }
+  return [...prefixes];
+};
+
+/**
+ * The declared prefix `path` is strictly under, or `undefined`.
+ * ⚠️ `${prefix}/`, never a bare startsWith: `/opt/example` must not admit `/opt/example-other`.
+ */
+export const prefixOf = (path: string, prefixes: readonly string[]): string | undefined =>
+  pathProblems(path).length > 0
+    ? undefined
+    : prefixes.find((prefix) => path.startsWith(`${prefix}/`));
+
+const labelOk = (label: string): boolean =>
+  LABEL.test(label) && !RESERVED_LABEL_PREFIXES.some((prefix) => label.startsWith(prefix));
+
+/** The label of `system/<label>`, when it is one LaunchdJob itself would accept. */
+const systemLabel = (target: string | undefined): string | undefined => {
+  const label = target?.startsWith('system/') === true ? target.slice('system/'.length) : undefined;
+  return label !== undefined && labelOk(label) ? label : undefined;
+};
+
+/**
+ * A label's daemon plist, when that path is under a declared prefix.
+ * ★ ONLY `/Library/LaunchDaemons/<label>.plist`, derived by the same plistPathFor LaunchdJob uses:
+ *   it is the one directory launchd loads daemons from at boot, so a plist anywhere else under a
+ *   prefix would be a root daemon that silently vanishes at the next restart. Root never loads one.
+ */
+const daemonPlist = (label: string, prefixes: readonly string[]): string | undefined => {
+  const path = plistPathFor(label, { kind: 'system' }, undefined);
+  return prefixOf(path, prefixes) === undefined ? undefined : path;
+};
+
+const NO_DAEMON_PREFIX =
+  'needs /Library/LaunchDaemons among the prefixes, where the job’s plist is written and removed';
+
+const launchctlProblem = (
+  args: readonly string[],
+  prefixes: readonly string[],
+): string | undefined => {
+  const [sub, ...rest] = args;
+  if (sub === 'bootstrap') {
+    const given = rest[1] ?? '';
+    const name = given.slice(given.lastIndexOf('/') + 1);
+    const label = name.endsWith('.plist') ? name.slice(0, -'.plist'.length) : '';
+    const shaped = rest.length === 2 && rest[0] === 'system' && labelOk(label);
+    if (!shaped) return 'bootstrap takes exactly `system /Library/LaunchDaemons/<label>.plist`';
+    const plist = daemonPlist(label, prefixes);
+    if (plist === undefined) return `bootstrap ${NO_DAEMON_PREFIX}`;
+    return given === plist ? undefined : `bootstrap loads only ${plist}, never another path`;
+  }
+  if (sub === 'bootout') {
+    const label = rest.length === 1 ? systemLabel(rest[0]) : undefined;
+    if (label === undefined) return 'bootout takes exactly `system/<label>`, never a bare domain';
+    /**
+     * ⚠️ WITHOUT THE PREFIX, A DELETE STOPS HALFWAY. deleteJob boots the job out, then removes its
+     *   plist; with /Library/LaunchDaemons undeclared the removal is refused AFTER the bootout, the
+     *   plist stays, and launchd loads the job again at the next boot. Refused here, nothing moves.
+     */
+    return daemonPlist(label, prefixes) === undefined ? `bootout ${NO_DAEMON_PREFIX}` : undefined;
+  }
+  if (sub === 'kickstart') {
+    const flags = rest.slice(0, -1);
+    const flagsOk =
+      flags.every((flag) => flag === '-k' || flag === '-p') && new Set(flags).size === flags.length;
+    return flagsOk && systemLabel(rest[rest.length - 1]) !== undefined
+      ? undefined
+      : 'kickstart takes only -k / -p, then `system/<label>`';
+  }
+  return `launchctl ${String(sub)} is never run as root`;
+};
+
+const ID = /^\d+$/;
+
+/** `install`'s optional owner flags: none, `-o N`, `-g N`, or `-o N -g N`. Numeric ids only. */
+const idsOk = (ids: readonly string[]): boolean => {
+  const [flag, id, second, secondId] = ids;
+  if (ids.length === 0) return true;
+  if (ids.length === 2) return (flag === '-o' || flag === '-g') && ID.test(id ?? '');
+  return (
+    ids.length === 4 &&
+    flag === '-o' &&
+    ID.test(id ?? '') &&
+    second === '-g' &&
+    ID.test(secondId ?? '')
+  );
+};
+
+/** The one source `install` may copy and the prefixes, for the call being checked. */
+export type AllowContext = { readonly prefixes: readonly string[]; readonly staged?: string };
+
+/** `undefined` when `argv` is exactly an allowed privileged shape, else the reason it is not. */
+export const privilegedProblem = (
+  argv: readonly string[],
+  context: AllowContext,
+): string | undefined => {
+  const [program, ...args] = argv;
+  const under = (path: string | undefined) =>
+    path !== undefined && prefixOf(path, context.prefixes) !== undefined;
+  if (program === LAUNCHCTL) return launchctlProblem(args, context.prefixes);
+  if (program === INSTALL) {
+    // -S -m MODE [-o UID] [-g GID] STAGED DEST: nothing else, in this order.
+    const [safe, m, mode, ...rest] = args;
+    if (safe !== '-S' || m !== '-m' || mode === undefined || !/^[0-7]{4}$/.test(mode)) {
+      return 'install takes exactly `-S -m <4 octal digits> [-o <uid>] [-g <gid>] <staged> <dest>`';
+    }
+    if (rest.length < 2 || !idsOk(rest.slice(0, -2))) return 'install takes only -o <uid> -g <gid>';
+    const [source, dest] = rest.slice(-2);
+    if (source === undefined || source !== context.staged) {
+      return 'install copies only the file this runner staged';
+    }
+    return under(dest) ? undefined : 'install destination is not under a declared prefix';
+  }
+  if (program === RM) {
+    const [force, end, path, ...extra] = args;
+    return force === '-f' && end === '--' && extra.length === 0 && under(path)
+      ? undefined
+      : 'rm takes exactly `-f -- <path under a declared prefix>`';
+  }
+  return `${String(program)} is not on the sudo allowlist`;
+};
+
+/** Where one exec goes: run as the deploying user, run as root through the allowlist, or refused. */
+export type Route =
+  | { readonly as: 'operator' }
+  | { readonly as: 'root' }
+  | { readonly refuse: string };
+
+/**
+ * ★ WHY THIS REFUSES AS WELL AS ROUTES. sudoRunner reports `privileged: true`, which switches off
+ *   the providers' own "another user's gui domain needs root" refusal (job-preflight.ts). This
+ *   runner elevates only the system domain, so it gives that refusal back itself. (A write into
+ *   another user's LaunchAgents is refused by the writer first: outside every prefix, a foreign
+ *   owner needs root. This covers the delete, which reaches launchctl before any file.)
+ * ⚠️ Reads (`print`, `print-disabled`) always run as the deploying user: launchctl(1) says anyone
+ *   may read or query the system domain, and launchctl.ts measured it on 2026-09-21.
+ */
+export const routeExec = (argv: readonly string[], operatorUid: number): Route => {
+  const [program, sub] = argv;
+  if (program === 'sudo' || program?.endsWith('/sudo') === true) {
+    return {
+      refuse: 'sudoRunner never passes a sudo argv through; it elevates only its allowlist',
+    };
+  }
+  if (program !== LAUNCHCTL || sub === undefined || !WRITES.has(sub)) return { as: 'operator' };
+  const target = sub === 'kickstart' ? argv[argv.length - 1] : argv[2];
+  if (target === 'system' || target?.startsWith('system/') === true) return { as: 'root' };
+  const owner = /^(?:gui|user)\/(\d+)(?:\/|$)/.exec(target ?? '')?.[1];
+  if (owner === undefined || Number(owner) === operatorUid) return { as: 'operator' };
+  return {
+    refuse:
+      `launchctl ${sub} ${String(target)}: that domain belongs to uid ${owner}, and sudoRunner ` +
+      'elevates only the system domain. Deploy as that user, or as root.',
+  };
+};

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

@@ -0,0 +1,121 @@
+/**
+ * sudoRunner's red-team refusals (2026-09-21), over the fake host (fake-sudo.ts): a directory ABOVE
+ * the prefix that someone other than root may change, and an ACL anywhere from / down that grants a
+ * write right. Either lets that someone swap the path between the guard and `sudo -n`. Each is
+ * refused before anything is staged or run as root, and at plan time through `checkWrite`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { OPERATOR, fakeSudoHost } from './fake-sudo.ts';
+import { diffFile, reconcileFile } from './host-file-lifecycle.ts';
+import type { HostRunner } from './runner.ts';
+import { aclGrants, assertNoAclGrants } from './sudo-acl.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+import { aboveDirs } from './sudo-guard.ts';
+
+const CONF = '/opt/example/app/a.conf';
+const bytes = (text: string) => new TextEncoder().encode(text);
+type Host = ReturnType<typeof fakeSudoHost>;
+const entry = (kind: 'directory' | 'symlink', mode: number, uid = 0) => ({
+  bytes: bytes(''),
+  gid: 0,
+  kind,
+  mode,
+  uid,
+});
+
+/** As `ls -lden` printed them on macOS 27.2 (sudo-acl.ts): a UUID qualifier, one entry a line. */
+const UUID = 'ABCDEFAB-CDEF-ABCD-EFAB-CDEF00000014';
+
+test('aboveDirs is / down to the parent of the prefix', () => {
+  expect(aboveDirs('/Library/LaunchDaemons')).toEqual(['/', '/Library']);
+  expect(aboveDirs('/opt/example')).toEqual(['/', '/opt']);
+  expect(aboveDirs('/opt')).toEqual(['/']);
+});
+
+describe('aclGrants', () => {
+  test('an allow of a write right counts; deny, and read-only rights, do not', () => {
+    const listing = [
+      `drwxr-xr-x@ 3 0 0 96 Sep 21 19:36 /opt/example`,
+      ` 0: ${UUID} allow add_file,add_subdirectory,delete_child`,
+      ` 1: ${UUID} inherited allow write,file_inherit`,
+      ` 2: ${UUID} deny delete`,
+      ` 3: ${UUID} allow list,search,readattr`,
+    ].join('\n');
+    expect(aclGrants(listing)).toEqual([
+      `0: ${UUID} allow add_file,add_subdirectory,delete_child`,
+      `1: ${UUID} inherited allow write,file_inherit`,
+    ]);
+  });
+
+  test('fails closed when the ACLs cannot be read', async () => {
+    const base = { exec: async () => ({ exitCode: 1, stderr: 'ls: x', stdout: '' }) };
+    const read = assertNoAclGrants(base as unknown as HostRunner, CONF, ['/']);
+    await expect(read).rejects.toThrow('could not read the ACLs');
+  });
+});
+
+const refusedBeforeSudo = async (host: Host, says: string | RegExp) => {
+  const write = host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 });
+  await expect(write).rejects.toBeInstanceOf(SudoRefusedError);
+  await expect(write).rejects.toThrow(says);
+  expect(host.state.stagedCount).toBe(0);
+  expect(host.sudoCalls).toEqual([]);
+};
+
+describe('every directory above the prefix', () => {
+  test.each([
+    ['owned by the operator', (h: Host) => h.fake.dirs.set('/opt', OPERATOR), 'uid 501'],
+    ['group-writable', (h: Host) => h.fake.files.set('/opt', entry('directory', 0o775)), '0775'],
+    [
+      'a symlink the operator owns',
+      (h: Host) => h.fake.files.set('/opt', entry('symlink', 0o755, OPERATOR)),
+      'symlink',
+    ],
+  ] as const)('%s is refused before staging or sudo', async (_n, setup, says) => {
+    const host = fakeSudoHost();
+    setup(host);
+    await refusedBeforeSudo(host, says);
+    await expect(host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 })).rejects.toThrow(
+      /\/opt, above the declared prefix \/opt\/example/,
+    );
+  });
+
+  test("a root-owned symlink (/etc -> private/etc) is root's own, and followed", async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set('/opt', entry('symlink', 0o755));
+    await host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 });
+    expect(host.fake.files.get(CONF)).toMatchObject({ mode: 0o644, uid: 0 });
+  });
+
+  test('a HostFile plan that would write under it fails, still without sudo', async () => {
+    const host = fakeSudoHost();
+    const output = await reconcileFile(host.runner, { content: 'x', path: CONF });
+    host.fake.dirs.set('/opt', OPERATOR);
+    const before = host.sudoCalls.length;
+    await expect(diffFile(host.runner, { content: 'y', path: CONF }, output)).rejects.toThrow(
+      'uid 501',
+    );
+    expect(host.sudoCalls).toHaveLength(before);
+  });
+});
+
+describe('an ACL from / down to the file', () => {
+  test.each(['/', '/opt', '/opt/example', '/opt/example/app'])(
+    'that grants a write right on %s is refused before staging or sudo',
+    async (dir) => {
+      const host = fakeSudoHost();
+      host.fake.acls.set(dir, [` 0: ${UUID} allow add_file,delete_child`]);
+      await refusedBeforeSudo(host, 'carries an ACL');
+      host.fake.files.set(CONF, { bytes: bytes('x'), gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+      await expect(host.runner.removeFile(CONF)).rejects.toThrow('carries an ACL');
+      expect(host.sudoCalls).toEqual([]);
+    },
+  );
+
+  test('a deny-only ACL (as on a home folder) is no refusal', async () => {
+    const host = fakeSudoHost();
+    host.fake.acls.set('/opt/example/app', [` 0: ${UUID} deny delete`]);
+    await host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 });
+    expect(host.fake.files.get(CONF)).toMatchObject({ uid: 0 });
+  });
+});

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

@@ -0,0 +1,100 @@
+/**
+ * The guard's pure parts, the `id -G` parse, and the real staging code on a real temp directory.
+ * Nothing here runs sudo or writes outside `os.tmpdir()`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { fakeRunner } from './fake-runner.ts';
+import type { ExecResult } from './runner.ts';
+import { betweenDirs, canRead, operatorGroups } from './sudo-guard.ts';
+import { stageFile } from './sudo-stage.ts';
+
+describe('canRead', () => {
+  const file = (uid: number, gid: number, mode: number) => ({ gid, mode, uid });
+  test.each([
+    ['root reads anything', file(0, 0, 0o000), 0, [], true],
+    ['the owner gets the owner bits only', file(501, 20, 0o044), 501, [20], false],
+    ['a member gets the group bits', file(0, 80, 0o640), 501, [80], true],
+    // ⚠️ Exactly one class applies: a member of the group does not fall through to "other".
+    ['a member is hidden by 0604', file(0, 80, 0o604), 501, [80], false],
+    ['a non-member gets the other bits', file(0, 80, 0o604), 501, [20], true],
+    ['0640 hides it from a non-member', file(0, 0, 0o640), 501, [20, 80], false],
+    ['0600 root-only hides it', file(0, 0, 0o600), 501, [0], false],
+    ['0644 is readable whatever the groups', file(0, 0, 0o644), 501, undefined, true],
+    ['0600 is unreadable whatever the groups', file(0, 0, 0o600), 501, undefined, false],
+    [
+      'only membership could decide, and it is unknown',
+      file(0, 80, 0o640),
+      501,
+      undefined,
+      undefined,
+    ],
+  ] as const)('%s', (_name, f, uid, groups, expected) => {
+    expect(canRead(f, uid, groups)).toBe(expected);
+  });
+});
+
+test('betweenDirs lists every directory strictly between the prefix and the file', () => {
+  expect(betweenDirs('/opt/example', '/opt/example/a.conf')).toEqual([]);
+  expect(betweenDirs('/opt/example', '/opt/example/app/etc/a.conf')).toEqual([
+    '/opt/example/app',
+    '/opt/example/app/etc',
+  ]);
+});
+
+describe('operatorGroups', () => {
+  const withId = (result: ExecResult) => {
+    const { runner } = fakeRunner();
+    const calls: string[][] = [];
+    return {
+      calls,
+      runner: {
+        ...runner,
+        exec: async (argv: readonly string[]) => (calls.push([...argv]), result),
+      },
+    };
+  };
+
+  test('parses `id -G`, run as the operator with an absolute path', async () => {
+    const host = withId({ exitCode: 0, stderr: '', stdout: '20 12 61 80 400 702\n' });
+    expect(await operatorGroups(host.runner)).toEqual([20, 12, 61, 80, 400, 702]);
+    expect(host.calls).toEqual([['/usr/bin/id', '-G']]);
+  });
+
+  test.each([
+    ['a failed lookup, whatever it printed', { exitCode: 1, stderr: 'id: failed', stdout: '20\n' }],
+    ['empty output', { exitCode: 0, stderr: '', stdout: '\n' }],
+    ['anything but numbers', { exitCode: 0, stderr: '', stdout: '20 staff\n' }],
+  ])('%s is unknown, never an empty list', async (_name, result) => {
+    expect(await operatorGroups(withId(result).runner)).toBeUndefined();
+  });
+});
+
+describe('stageFile (real temp directory)', () => {
+  test('0600 file in a 0700 directory, exact bytes, gone after dispose', async () => {
+    const staged = await stageFile(new TextEncoder().encode('listen: 127.0.0.1:9100\n'));
+    try {
+      expect(await Bun.file(staged.path).text()).toBe('listen: 127.0.0.1:9100\n');
+      expect((await stat(staged.path)).mode & 0o777).toBe(0o600);
+      expect((await stat(dirname(staged.path))).mode & 0o777).toBe(0o700);
+    } finally {
+      await staged.dispose();
+    }
+    // ⚠️ stat, not Bun.file().exists(): measured 2026-09-21 on bun 1.4.0, exists() is false for a
+    //   directory that DOES exist, so it could never catch a leaked staging directory.
+    await expect(stat(dirname(staged.path))).rejects.toThrow('ENOENT');
+  });
+
+  test('two stagings never share a file', async () => {
+    const [a, b] = await Promise.all([
+      stageFile(new Uint8Array([1])),
+      stageFile(new Uint8Array([2])),
+    ]);
+    try {
+      expect(a?.path).not.toBe(b?.path);
+    } finally {
+      await Promise.all([a?.dispose(), b?.dispose()]);
+    }
+  });
+});