@homeflare/alchemy 0.6.0 → 0.8.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-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()]);
+    }
+  });
+});

package/src/launchd/sudo-guard.ts

@@ -0,0 +1,151 @@
+/**
+ * The checks sudo-runner.ts makes against the host, as the deploying user, before it runs anything
+ * as root. sudo-allowlist.ts checks the argv; this checks what the paths in it actually are.
+ *
+ * ⛔ WHAT IS LOGGED IS WHAT IS WRITTEN. A symlinked directory under a prefix would make
+ *   `install` or `rm`, running as root, act on a path the log never named. So every directory
+ *   between the prefix and the file must be a real directory.
+ * ⚠️ These checks run before the privileged call, so they guard against a mistaken declaration, not
+ *   against someone who can already write inside a prefix and swap a path in between. The prefix
+ *   itself is checked to be root-only (prefixProblem); a directory BELOW it that another user owns
+ *   is not, and that user could swap what lies under it in that window.
+ */
+import type { FileStat, HostRunner, WriteOptions } from './runner.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+
+const refuse = (path: string, message: string): Error =>
+  new SudoRefusedError(`sudoRunner ${path}: ${message}`);
+
+/** The directories strictly between `prefix` and the file at `path`. */
+export const betweenDirs = (prefix: string, path: string): string[] => {
+  const parts = path
+    .slice(prefix.length + 1)
+    .split('/')
+    .slice(0, -1);
+  return parts.map((_, index) => `${prefix}/${parts.slice(0, index + 1).join('/')}`);
+};
+
+/**
+ * What must be at `path` itself: a regular file, or (for a write or a remove) nothing yet.
+ * ⚠️ A DIRECTORY AT THE DESTINATION IS THE TRAP: `install src dir` copies INTO the directory
+ *   (install(1)), and install decides that with stat, so a symlink to a directory does the same.
+ */
+export type Expect = 'file' | 'file-or-absent';
+
+/**
+ * ⛔ THE PREFIX ITSELF MUST BE A DIRECTORY ONLY ROOT CAN CHANGE, checked at every call rather than
+ *   trusted from the declaration. A symlinked prefix makes root write wherever it points, which the
+ *   log never names (`/opt/example` -> `/etc` turns a HostFile at `/opt/example/sudoers` into
+ *   `/etc/sudoers`). A prefix another user owns or may write lets that user swap a directory below
+ *   it for a symlink between this check and the privileged call.
+ * ⚠️ lstat of the prefix itself: a symlink ABOVE it (`/etc` -> `/private/etc` on macOS) is the
+ *   system's and is followed, as every path lookup does. ACLs are not read; mode bits only.
+ * ★ MEASURED 2026-09-21 on macOS 27.2 (`ls -ldn`): /Library/LaunchDaemons, /private/etc, /opt and
+ *   /usr/local are uid 0, mode 0755, so the prefixes a host stack declares pass as they are.
+ */
+const prefixProblem = (stat: FileStat | undefined): string | undefined => {
+  if (stat === undefined) return 'is missing';
+  if (stat.kind !== 'directory') return `is a ${stat.kind}, not a directory`;
+  if (stat.uid !== 0) return `is owned by uid ${String(stat.uid)}, not root`;
+  if ((stat.mode & 0o022) !== 0) {
+    return `is writable by group or other (mode ${stat.mode.toString(8).padStart(4, '0')})`;
+  }
+  return undefined;
+};
+
+/**
+ * Refuse a prefix that is not a root-only directory, a symlink or a non-directory between the
+ * prefix and `path`, and anything but a file at it.
+ */
+export const assertPlainPath = async (
+  base: HostRunner,
+  prefix: string,
+  path: string,
+  expect: Expect,
+): Promise<'file' | 'absent'> => {
+  const dirs = betweenDirs(prefix, path);
+  const [prefixStat, ...stats] = await Promise.all([prefix, ...dirs].map((dir) => base.stat(dir)));
+  const bad = prefixProblem(prefixStat);
+  if (bad !== undefined) {
+    throw refuse(
+      path,
+      `the declared prefix ${prefix} ${bad}. Declare only a real directory that root owns and ` +
+        'only root may write. Nothing ran as root.',
+    );
+  }
+  for (const [index, stat] of stats.entries()) {
+    if (stat?.kind !== 'directory') {
+      throw refuse(
+        path,
+        `${String(dirs[index])} is ${stat === undefined ? 'missing' : `a ${stat.kind}`}; root ` +
+          'writes only through real directories under a declared prefix.',
+      );
+    }
+  }
+  const target = await base.stat(path);
+  if (target === undefined && expect === 'file-or-absent') return 'absent';
+  if (target?.kind === 'file') return 'file';
+  throw refuse(path, `is ${target === undefined ? 'missing' : `a ${target.kind}`}, not a 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;
+};