@homeflare/alchemy 0.25.1 → 0.27.0

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

@@ -0,0 +1,252 @@
+/**
+ * The allowlist, as pure argv checks — no ssh, no fake host. Each refusal here is a shape that
+ * would do real damage as root; each acceptance is a shape sshSudoRunner actually produces.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  type AllowContext,
+  CHMOD,
+  CHOWN,
+  INSTALL,
+  MKDIR,
+  MV,
+  RM,
+  RMDIR,
+  SYSTEMCTL_ABS,
+  canonicalize,
+  checkPrefixes,
+  octalMode,
+  prefixOf,
+  privilegedProblem,
+  routeExec,
+} from './sudo-allowlist.ts';
+
+const PREFIXES = ['/etc/systemd/system', '/usr/local/bin'];
+const STAGED = '/tmp/hf-sudo-1/staged';
+const TEMP = '/etc/systemd/system/.thing.service.hf-abcdef012345.tmp';
+const context: AllowContext = { prefixes: PREFIXES, staged: STAGED, temp: TEMP };
+const allowed = (argv: string[]) => privilegedProblem(argv, context);
+
+describe('checkPrefixes / prefixOf', () => {
+  test('reused from the Mac allowlist unchanged', () => {
+    expect(() => checkPrefixes([])).toThrow('no prefixes');
+    expect(checkPrefixes(PREFIXES)).toEqual(PREFIXES);
+    expect(prefixOf('/etc/systemd/system/x.service', PREFIXES)).toBe('/etc/systemd/system');
+    expect(prefixOf('/etc/systemd/system-other/x', PREFIXES)).toBeUndefined();
+    expect(octalMode(0o644)).toBe('0644');
+  });
+});
+
+describe('install shapes', () => {
+  test.each([
+    [[INSTALL, '-m', '0644', '-T', '--', STAGED, TEMP]],
+    [[INSTALL, '-m', '0755', '-T', '--', STAGED, TEMP]],
+  ])('allows %j', (argv) => {
+    expect(allowed(argv)).toBeUndefined();
+  });
+
+  test.each([
+    ['a source it did not stage', [INSTALL, '-m', '0644', '-T', '--', '/etc/master.passwd', TEMP]],
+    [
+      'a target that is not the derived temp',
+      [INSTALL, '-m', '0644', '-T', '--', STAGED, '/etc/systemd/system/x.service'],
+    ],
+    ['a temp outside every prefix', [INSTALL, '-m', '0644', '-T', '--', STAGED, '/tmp/x.tmp']],
+    ['no -T', [INSTALL, '-m', '0644', '--', STAGED, TEMP]],
+    ['a three-digit mode', [INSTALL, '-m', '644', '-T', '--', STAGED, TEMP]],
+    ['-S (the Mac flag)', [INSTALL, '-S', '-m', '0644', '-T', '--', STAGED, TEMP]],
+    ['two destinations', [INSTALL, '-m', '0644', '-T', '--', STAGED, TEMP, TEMP]],
+    // 🔴 Adversarial review, round 2: install has no `+`-forcing mechanism at all (coreutils'
+    //   `get_ids()` always tries getpwnam/getgrnam first), so -o/-g are refused outright now —
+    //   ownership is set afterward by a separate, `+`-forced chown on the same temp (below).
+    ['-o, now refused outright', [INSTALL, '-m', '0644', '-o', '0', '-T', '--', STAGED, TEMP]],
+    ['-g, now refused outright', [INSTALL, '-m', '0644', '-g', '0', '-T', '--', STAGED, TEMP]],
+  ])('refuses %s', (_name, argv) => {
+    expect(allowed(argv)).toBeString();
+  });
+});
+
+describe('the file-ownership chown, bound to the derived temp', () => {
+  test.each([
+    [[CHOWN, '+900', '--', TEMP]],
+    [[CHOWN, ':+60', '--', TEMP]],
+    [[CHOWN, '+900:+60', '--', TEMP]],
+  ])('allows %j', (argv) => {
+    expect(allowed(argv)).toBeUndefined();
+  });
+
+  test.each([
+    ['a bare digit, not +-forced', [CHOWN, '900', '--', TEMP]],
+    ['a name', [CHOWN, '+root', '--', TEMP]],
+    ['a path that is not the derived temp', [CHOWN, '+900', '--', '/usr/local/bin/other']],
+    ['only the group side forced', [CHOWN, '900:+60', '--', TEMP]],
+    ['only the owner side forced', [CHOWN, '+900:60', '--', TEMP]],
+  ])('refuses %s', (_name, argv) => {
+    expect(allowed(argv)).toBeString();
+  });
+});
+
+describe('mv and rm shapes', () => {
+  test.each([
+    [[MV, '-f', '-T', '--', TEMP, '/etc/systemd/system/thing.service']],
+    [[RM, '-f', '--', TEMP]],
+  ])('allows %j', (argv) => {
+    expect(allowed(argv)).toBeUndefined();
+  });
+
+  test.each([
+    [
+      'mv source not the derived temp',
+      [MV, '-f', '-T', '--', '/etc/systemd/system/other.tmp', '/etc/systemd/system/thing.service'],
+    ],
+    ['mv to another directory', [MV, '-f', '-T', '--', TEMP, '/usr/local/bin/thing']],
+    ['mv without -T', [MV, '-f', '--', TEMP, '/etc/systemd/system/thing.service']],
+    ['rm -r', [RM, '-rf', '--', TEMP]],
+    ['rm without --', [RM, '-f', TEMP]],
+    ['rm outside every prefix', [RM, '-f', '--', '/tmp/x']],
+    ['sudo in argv', ['/usr/bin/sudo', '-n', RM, '-f', '--', TEMP]],
+  ])('refuses %s', (_name, argv) => {
+    expect(allowed(argv)).toBeString();
+  });
+});
+
+describe('directory shapes', () => {
+  test.each([
+    [[MKDIR, '-m', '750', '--', '/etc/systemd/system/sub']],
+    [[MKDIR, '-m', '700', '--', '/etc/systemd/system/sub']],
+    [[CHMOD, '750', '--', '/usr/local/bin/sub']],
+    // ★ +-forced: this is what canonicalize() actually sends to sudo for a directory chown; the
+    //   bare `0`/`:0`/`0:0` directory-lifecycle.ts itself sends is covered by the canonicalize
+    //   test below, and is refused HERE on purpose (privilegedProblem checks the final argv).
+    [[CHOWN, '+0', '--', '/usr/local/bin/sub']],
+    [[CHOWN, ':+0', '--', '/usr/local/bin/sub']],
+    [[CHOWN, '+0:+0', '--', '/usr/local/bin/sub']],
+    [[RMDIR, '--', '/etc/systemd/system/sub']],
+  ])('allows %j', (argv) => {
+    expect(allowed(argv)).toBeUndefined();
+  });
+
+  test.each([
+    ['a relative path', [MKDIR, '-m', '750', '--', 'etc/x']],
+    ['a prefix-sibling', [MKDIR, '-m', '750', '--', '/usr/local/bin-x/sub']],
+    ['a path that walks out', [MKDIR, '-m', '750', '--', '/etc/systemd/system/../x']],
+    ['chown by name', [CHOWN, 'root', '--', '/usr/local/bin/sub']],
+    [
+      'chown, bare digit not +-forced (round 2 of the review)',
+      [CHOWN, '0', '--', '/usr/local/bin/sub'],
+    ],
+    ['chmod without --', [CHMOD, '750', '/usr/local/bin/sub']],
+    ['rmdir of two paths', [RMDIR, '--', '/usr/local/bin/sub', '/etc/systemd/system/sub']],
+    // 🔴 The three shapes the adversarial review found reachable, 2026-09-23 — see
+    //   sudo-allowlist-dir.ts's header. Each must now be refused, not merely shaped correctly.
+    ['mkdir with setuid (4750)', [MKDIR, '-m', '4750', '--', '/etc/systemd/system/sub']],
+    ['mkdir world-writable (0777)', [MKDIR, '-m', '777', '--', '/etc/systemd/system/sub']],
+    [
+      'mkdir setgid + group-writable (2775)',
+      [MKDIR, '-m', '2775', '--', '/etc/systemd/system/sub'],
+    ],
+    ['chmod group-writable (0775)', [CHMOD, '775', '--', '/usr/local/bin/sub']],
+    ['chown to a non-root uid', [CHOWN, '900', '--', '/usr/local/bin/sub']],
+    ['chown to a non-root gid only', [CHOWN, ':60', '--', '/usr/local/bin/sub']],
+    ['chown to a non-root uid and gid', [CHOWN, '900:60', '--', '/usr/local/bin/sub']],
+    ['chown to a non-root uid, even +-forced', [CHOWN, '+900', '--', '/usr/local/bin/sub']],
+  ])('refuses %s', (_name, argv) => {
+    expect(allowed(argv)).toBeString();
+  });
+});
+
+describe('systemctl shapes', () => {
+  test.each([
+    [[SYSTEMCTL_ABS, 'daemon-reload']],
+    [[SYSTEMCTL_ABS, 'enable', '--', 'thing.service']],
+    [[SYSTEMCTL_ABS, 'disable', '--', 'thing.service']],
+    [[SYSTEMCTL_ABS, 'start', '--', 'thing.timer']],
+    [[SYSTEMCTL_ABS, 'restart', '--', 'thing.service']],
+  ])('allows %j', (argv) => {
+    expect(allowed(argv)).toBeUndefined();
+  });
+
+  test.each([
+    ['--user', [SYSTEMCTL_ABS, '--user', 'enable', '--', 'thing.service']],
+    ['stop with two units', [SYSTEMCTL_ABS, 'stop', '--', 'a.service', 'b.service']],
+    ['mask', [SYSTEMCTL_ABS, 'mask', '--', 'thing.service']],
+    ['daemon-reload with an operand', [SYSTEMCTL_ABS, 'daemon-reload', 'thing.service']],
+    ['a unit that is not a valid name', [SYSTEMCTL_ABS, 'enable', '--', 'not a unit']],
+  ])('refuses %s', (_name, argv) => {
+    expect(allowed(argv)).toBeString();
+  });
+});
+
+describe('canonicalize', () => {
+  test('rewrites a bare directory chown to the +-forced form the allowlist now requires', () => {
+    expect(canonicalize(['chown', '0', '--', '/usr/local/bin/sub'])).toEqual([
+      CHOWN,
+      '+0',
+      '--',
+      '/usr/local/bin/sub',
+    ]);
+    expect(canonicalize(['chown', ':0', '--', '/usr/local/bin/sub'])).toEqual([
+      CHOWN,
+      ':+0',
+      '--',
+      '/usr/local/bin/sub',
+    ]);
+    expect(canonicalize(['chown', '900:60', '--', '/usr/local/bin/sub'])).toEqual([
+      CHOWN,
+      '+900:+60',
+      '--',
+      '/usr/local/bin/sub',
+    ]);
+  });
+
+  test('leaves every other program alone', () => {
+    expect(canonicalize(['mkdir', '-m', '750', '--', '/usr/local/bin/sub'])).toEqual([
+      MKDIR,
+      '-m',
+      '750',
+      '--',
+      '/usr/local/bin/sub',
+    ]);
+  });
+});
+
+describe('routeExec', () => {
+  const route = (argv: string[]) => routeExec(argv, PREFIXES);
+
+  test('systemctl write verbs always attempt root, even malformed', () => {
+    expect(route([SYSTEMCTL_ABS, 'daemon-reload'])).toEqual({ as: 'root' });
+    expect(route(['systemctl', 'enable', '--', 'thing.service'])).toEqual({ as: 'root' });
+    expect(route(['systemctl', 'stop', '--', 'a', 'b'])).toEqual({ as: 'root' });
+  });
+
+  test('systemctl reads stay unelevated', () => {
+    expect(route(['systemctl', 'show', '-p', 'LoadState', '--', 'thing.service'])).toEqual({
+      as: 'operator',
+    });
+  });
+
+  test('directory programs go to root only under a declared prefix', () => {
+    expect(route(['mkdir', '-m', '750', '--', '/usr/local/bin/sub'])).toEqual({ as: 'root' });
+    expect(route(['mkdir', '-m', '750', '--', '/opt/elsewhere'])).toEqual({ as: 'operator' });
+  });
+
+  test('the absolute program spelling routes the same as the bare one', () => {
+    expect(route([MKDIR, '-m', '750', '--', '/usr/local/bin/sub'])).toEqual({ as: 'root' });
+    expect(route([CHOWN, '0', '--', '/usr/local/bin/sub'])).toEqual({ as: 'root' });
+  });
+
+  test('a sudo argv is refused outright, bare or absolute', () => {
+    expect(route(['/usr/bin/sudo', '-n', RM, '-f', '--', '/etc/x'])).toHaveProperty('refuse');
+    expect(route(['sudo', 'true'])).toHaveProperty('refuse');
+  });
+
+  test('systemctl with a banned flag is refused, not routed to the operator', () => {
+    expect(route(['systemctl', 'enable', '--global', '--', 'thing.service'])).toHaveProperty(
+      'refuse',
+    );
+  });
+
+  test('everything else runs as the operator', () => {
+    expect(route(['getent', 'passwd', '900'])).toEqual({ as: 'operator' });
+  });
+});

package/src/linux/sudo-allowlist.ts

@@ -0,0 +1,223 @@
+/**
+ * Everything sshSudoRunner 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 ssh (sudo-allowlist.test.ts).
+ * The Linux twin of `../launchd/sudo-allowlist.ts` — reused directly where the rule is generic
+ * (prefixes, octal 4-digit modes, `SudoRefusedError`), rewritten where GNU coreutils and systemd
+ * need a different shape than macOS's `install -S` and `launchctl`.
+ *
+ * ⛔ AN ALLOWLIST OF SHAPES, NOT OF PROGRAMS. `chown` unqualified would let a bug hand any file to
+ *   any uid; `systemctl` unqualified would let `disable --global` reach every user's units. Each
+ *   shape below fixes the flags, the operand count and (for install/mv) which paths may appear.
+ * ⛔ `install` COPIES ONLY THE FILE THIS RUNNER STAGED, into ONLY the temp path this runner derived
+ *   for the current write — never argv's own idea of either. Binding both stops a bug (or a future
+ *   change) from turning this into "install any file the operator can read to any path root can
+ *   reach".
+ * ⛔ GNU `install` WRITES THROUGH ITS DESTINATION (ssh-scripts.ts's header), unlike macOS's, which
+ *   stages and renames on its own. So there is no `-S`: this allowlist's `install` writes a FRESH
+ *   temp file (never the live path), and only `mv` — a rename(2), atomic by construction — ever
+ *   touches the path a provider declared.
+ */
+import { NAME as UNIT_NAME } from './unit-form.ts';
+import {
+  INSTALL,
+  SUDO,
+  SudoRefusedError,
+  checkPrefixes,
+  octalMode,
+  prefixOf,
+} from '../launchd/sudo-allowlist.ts';
+import { chownProblem, forceNumericOwner } from './sudo-allowlist-chown.ts';
+import { CHMOD, CHOWN, MKDIR, RMDIR, dirProgramProblem } from './sudo-allowlist-dir.ts';
+
+export { INSTALL, SUDO, SudoRefusedError, checkPrefixes, octalMode, prefixOf };
+export { CHMOD, CHOWN, MKDIR, RMDIR } from './sudo-allowlist-dir.ts';
+
+/** ★ Absolute program paths, so neither sudo nor the command is looked up on the operator's PATH. */
+export const MV = '/usr/bin/mv';
+export const RM = '/usr/bin/rm';
+export const SYSTEMCTL_ABS = '/usr/bin/systemctl';
+
+/** The bare names `directory-lifecycle.ts` and `systemctl.ts` already send through `exec()`. */
+export const DIRECTORY_PROGRAMS: ReadonlySet<string> = new Set([
+  'mkdir',
+  'chmod',
+  'chown',
+  'rmdir',
+]);
+const DIRECTORY_PROGRAMS_ABS: ReadonlySet<string> = new Set([MKDIR, CHMOD, CHOWN, RMDIR]);
+const ABS_OF: Readonly<Record<string, string>> = {
+  chmod: CHMOD,
+  chown: CHOWN,
+  mkdir: MKDIR,
+  rmdir: RMDIR,
+  systemctl: SYSTEMCTL_ABS,
+};
+/**
+ * The bare argv a provider sends → the absolute argv sudo may run. Unknown programs pass through.
+ * ★ `chown`'s owner argument is ALSO rewritten here, to the `+`-forced form `sudo-allowlist-dir.ts`
+ *   and `sudo-allowlist-chown.ts` now require — `directory-lifecycle.ts` never has to know that
+ *   syntax exists, and the allowlist checks exactly what will actually reach `sudo`.
+ */
+export const canonicalize = (argv: readonly string[]): readonly string[] => {
+  const abs = ABS_OF[argv[0] ?? ''];
+  const program = abs ?? argv[0];
+  if (program === CHOWN) {
+    const [owner, ...rest] = argv.slice(1);
+    return [CHOWN, owner === undefined ? '' : forceNumericOwner(owner), ...rest];
+  }
+  return abs === undefined ? argv : [abs, ...argv.slice(1)];
+};
+
+const dirOf = (path: string): string => path.slice(0, path.lastIndexOf('/')) || '/';
+
+/** The one source `install` may copy, the one temp `install`/`mv` may touch, and the prefixes. */
+export type AllowContext = {
+  readonly prefixes: readonly string[];
+  readonly staged?: string;
+  readonly temp?: string;
+};
+
+/**
+ * ⛔ NEVER `-o`/`-g` — see sudo-allowlist-chown.ts's header. `install` always writes the fresh temp
+ *   owned by whoever `sudo` runs it as (root:root), with no name lookup at all; a non-root owner or
+ *   group is set afterward by a separate, `+`-forced `chown` on that same temp, before `mv`.
+ */
+const installProblem = (args: readonly string[], context: AllowContext): string | undefined => {
+  const [m, mode, t, dd, source, dest, ...extra] = args;
+  if (
+    m !== '-m' ||
+    mode === undefined ||
+    !/^[0-7]{4}$/.test(mode) ||
+    t !== '-T' ||
+    dd !== '--' ||
+    extra.length !== 0
+  ) {
+    return 'install takes exactly `-m <4 octal digits> -T -- <staged> <temp>`';
+  }
+  if (source === undefined || source !== context.staged) {
+    return 'install copies only the file this runner staged';
+  }
+  if (dest === undefined || dest !== context.temp) {
+    return 'install writes only the derived temp path for this write';
+  }
+  return prefixOf(dest, context.prefixes) === undefined
+    ? 'install destination is not under a declared prefix'
+    : undefined;
+};
+
+const mvProblem = (args: readonly string[], context: AllowContext): string | undefined => {
+  const [f, t, dd, source, dest] = args;
+  if (f !== '-f' || t !== '-T' || dd !== '--' || args.length !== 5) {
+    return 'mv takes exactly `-f -T -- <temp> <dest>`';
+  }
+  if (source === undefined || source !== context.temp) {
+    return 'mv moves only the temp path this runner just installed to';
+  }
+  if (dest === undefined || prefixOf(dest, context.prefixes) === undefined) {
+    return 'mv destination is not under a declared prefix';
+  }
+  return dirOf(source) === dirOf(dest)
+    ? undefined
+    : 'mv must stay inside the destination’s directory';
+};
+
+const rmProblem = (args: readonly string[], context: AllowContext): string | undefined => {
+  const [force, end, path, ...extra] = args;
+  return force === '-f' &&
+    end === '--' &&
+    extra.length === 0 &&
+    path !== undefined &&
+    prefixOf(path, context.prefixes) !== undefined
+    ? undefined
+    : 'rm takes exactly `-f -- <path under a declared prefix>`';
+};
+
+const BANNED_SYSTEMCTL_FLAGS: ReadonlySet<string> = new Set([
+  '--user',
+  '--global',
+  '-H',
+  '-M',
+  '--root',
+]);
+const UNIT_WRITE_VERBS: ReadonlySet<string> = new Set([
+  'enable',
+  'disable',
+  'start',
+  'stop',
+  'restart',
+]);
+
+const systemctlProblem = (
+  args: readonly string[],
+  prefixes: readonly string[],
+): string | undefined => {
+  if (args.some((arg) => BANNED_SYSTEMCTL_FLAGS.has(arg))) {
+    return 'systemctl --user/--global/-H/-M/--root is never run as root';
+  }
+  const [verb, ...rest] = args;
+  if (verb === 'daemon-reload')
+    return rest.length === 0 ? undefined : 'daemon-reload takes no operands';
+  if (verb !== undefined && UNIT_WRITE_VERBS.has(verb)) {
+    const [dd, unit, ...extra] = rest;
+    return dd === '--' && unit !== undefined && UNIT_NAME.test(unit) && extra.length === 0
+      ? undefined
+      : `${verb} takes exactly \`-- <unit>\``;
+  }
+  return `systemctl ${String(verb)} is never run as root`;
+};
+
+/** `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;
+  if (program === INSTALL) return installProblem(args, context);
+  if (program === MV) return mvProblem(args, context);
+  if (program === RM) return rmProblem(args, context);
+  if (program === SYSTEMCTL_ABS) return systemctlProblem(args, context.prefixes);
+  if (program === CHOWN) return chownProblem(args, context);
+  if (program === MKDIR || program === CHMOD || program === RMDIR) {
+    return dirProgramProblem(program, args, context.prefixes);
+  }
+  return `${String(program)} is not on the sudo allowlist`;
+};
+
+/** Where one exec goes: run as the operator, run as root through the allowlist, or refused. */
+export type Route =
+  | { readonly as: 'operator' }
+  | { readonly as: 'root' }
+  | { readonly refuse: string };
+
+/**
+ * ★ ROUTING NEVER TOUCHES THE HOST. mkdir/chmod/chown/rmdir go to root only under a declared
+ *   prefix — outside one they run as the operator, who may well own that path (H3/rule 7).
+ *   systemctl's write verbs always ATTEMPT root; the FragmentPath check that can still refuse one
+ *   needs a host read, so it runs in the runner's `before` hook, not here.
+ */
+export const routeExec = (argv: readonly string[], prefixes: readonly string[]): Route => {
+  const [program, ...args] = argv;
+  if (program === 'sudo' || program?.endsWith('/sudo') === true) {
+    return {
+      refuse: 'sshSudoRunner never passes a sudo argv through; it elevates only its allowlist',
+    };
+  }
+  if (program === 'systemctl' || program === SYSTEMCTL_ABS) {
+    if (args.some((arg) => BANNED_SYSTEMCTL_FLAGS.has(arg))) {
+      return { refuse: 'sshSudoRunner refuses systemctl --user/--global/-H/-M/--root' };
+    }
+    const [verb] = args;
+    return verb === 'daemon-reload' || (verb !== undefined && UNIT_WRITE_VERBS.has(verb))
+      ? { as: 'root' }
+      : { as: 'operator' };
+  }
+  // ★ Both spellings route the same way — a caller that happened to pass the absolute program
+  //   (nothing in this repo does today) must not silently fall through to the operator branch.
+  if (DIRECTORY_PROGRAMS.has(program ?? '') || DIRECTORY_PROGRAMS_ABS.has(program ?? '')) {
+    const path = args[args.length - 1];
+    return path !== undefined && prefixOf(path, prefixes) !== undefined
+      ? { as: 'root' }
+      : { as: 'operator' };
+  }
+  return { as: 'operator' };
+};

package/src/linux/sudo-exec.ts

@@ -0,0 +1,118 @@
+/**
+ * `sshSudoRunner.exec()`'s root branch: the host reads that decide whether a routed-to-root
+ * directory or systemctl call may actually elevate. Split out of sudo-runner.ts, which keeps only
+ * the wiring. sudo-allowlist.ts's `routeExec` already decided root vs operator vs refuse from the
+ * argv alone; this is the part that needs the host.
+ *
+ * ⛔ THE FragmentPath CHECK IS WHAT MAKES `pveproxy.service` UNREACHABLE. A vendor unit's file
+ *   lives under `/usr/lib/systemd/system` or `/lib/systemd/system` — never a prefix this runner
+ *   would declare — so `enable`/`start`/… on it is refused before sudo runs. A unit with NO file
+ *   at all (FragmentPath empty) is let through for `stop`/`disable` only, because
+ *   `unit-lifecycle.ts` `deleteUnit` calls exactly those two on a unit whose file this same
+ *   delete already removed a moment before — refusing that would make a second, idempotent
+ *   delete pass fail.
+ * 🔴 MEASURED (adversarial review, round 2, 2026-09-23): two gaps in this check, both closed here.
+ *   (1) A MASKED unit (`systemctl mask`, a symlink to `/dev/null`) also reads `FragmentPath=`
+ *   empty, so `enable`/`start`/`restart` on a masked `pveproxy.service` would have elevated —
+ *   `systemctl` itself would then refuse the write, but nothing here should even try; masking is
+ *   someone's deliberate decision (`unit-preflight.ts`'s `assertUsable` already refuses it at the
+ *   PROVIDER layer, and this is the same rule enforced again at the lowest level, in case a
+ *   caller reaches `exec()` directly). (2) The empty-FragmentPath exemption applied to EVERY
+ *   write verb, not just the two `deleteUnit` actually needs — so `enable`/`start`/`restart` on a
+ *   kernel-generated pseudo-unit with no file at all (`init.scope`, a `session-N.scope`; `.scope`
+ *   is a valid type in `unit-form.ts`'s `TYPES` set) would also have elevated. Grepped: no code
+ *   in this package ever calls `enable`/`start`/`restart` on a unit it has not itself just
+ *   written a file for, so narrowing the exemption to `stop`/`disable` costs nothing legitimate.
+ */
+import type { ExecResult, HostRunner } from '../launchd/runner.ts';
+import { SYSTEMCTL_ABS, SudoRefusedError, canonicalize, prefixOf } from './sudo-allowlist.ts';
+import { type ChainExpect, assertGuardedChain } from './sudo-guard.ts';
+import type { Elevate } from './sudo-write.ts';
+import { parseShow } from './systemctl.ts';
+
+const DIR_EXPECT: Readonly<Record<string, ChainExpect>> = {
+  chmod: 'directory',
+  chown: 'directory',
+  mkdir: 'absent',
+  rmdir: 'directory',
+};
+
+/** The only two verbs `deleteUnit` ever sends against a unit whose file may already be gone. */
+const EMPTY_FRAGMENT_OK: ReadonlySet<string> = new Set(['stop', 'disable']);
+
+const unitStatusOf = async (
+  base: HostRunner,
+  unit: string,
+): Promise<{ readonly fragmentPath: string; readonly loadState: string }> => {
+  const result = await base.exec([
+    SYSTEMCTL_ABS,
+    'show',
+    '--no-pager',
+    '-p',
+    'FragmentPath,LoadState',
+    '--',
+    unit,
+  ]);
+  if (result.exitCode !== 0) {
+    throw new SudoRefusedError(
+      `sshSudoRunner ${unit}: could not read FragmentPath/LoadState (systemctl show exit ` +
+        `${String(result.exitCode)}). Nothing ran as root.`,
+    );
+  }
+  const fields = parseShow(result.stdout);
+  return {
+    fragmentPath: fields.get('FragmentPath') ?? '',
+    loadState: fields.get('LoadState') ?? '',
+  };
+};
+
+/** `argv` has already been routed to root; canonicalise it and run the read this shape needs. */
+export const elevatedExec = (
+  base: HostRunner,
+  elevate: Elevate,
+  prefixes: readonly string[],
+  argv: readonly string[],
+): Promise<ExecResult> => {
+  const canonical = canonicalize(argv);
+  const expect = DIR_EXPECT[argv[0] ?? ''];
+  if (expect !== undefined) {
+    const path = argv[argv.length - 1] ?? '';
+    const prefix = prefixOf(path, prefixes);
+    return elevate(canonical, {}, async () => {
+      // ★ routeExec already required a prefix to route here; this re-derives it rather than
+      //   trust the caller, so a future routing bug fails the guard instead of skipping it.
+      if (prefix === undefined) {
+        throw new SudoRefusedError(
+          `sshSudoRunner ${path}: not under a declared prefix. Nothing ran as root.`,
+        );
+      }
+      await assertGuardedChain(base, prefix, path, expect);
+    });
+  }
+  if (canonical[0] !== SYSTEMCTL_ABS || canonical[1] === 'daemon-reload') return elevate(canonical);
+  const verb = canonical[1] ?? '';
+  const unit = canonical[3] ?? '';
+  return elevate(canonical, {}, async () => {
+    const { fragmentPath, loadState } = await unitStatusOf(base, unit);
+    if (loadState === 'masked') {
+      throw new SudoRefusedError(
+        `sshSudoRunner ${unit}: is masked. Masking is someone's decision, not drift; unmask it ` +
+          'deliberately, then redeploy. Nothing ran as root.',
+      );
+    }
+    if (fragmentPath === '') {
+      if (EMPTY_FRAGMENT_OK.has(verb)) return;
+      throw new SudoRefusedError(
+        `sshSudoRunner ${unit}: has no unit file (FragmentPath empty), and ${verb} is not ` +
+          'stop/disable — refusing rather than run it against whatever systemd currently thinks ' +
+          `${unit} is (a kernel-generated unit, say). Nothing ran as root.`,
+      );
+    }
+    if (prefixOf(fragmentPath, prefixes) === undefined) {
+      throw new SudoRefusedError(
+        `sshSudoRunner ${unit}: FragmentPath ${fragmentPath} is outside every declared prefix ` +
+          `(${prefixes.join(', ')}); refusing to touch a unit this runner does not own. Nothing ran as root.`,
+      );
+    }
+  });
+};