@homeflare/alchemy 0.25.1 → 0.26.0

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>`';
+};

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