@homeflare/alchemy 0.25.1 → 0.27.0

package/src/linux/sudo-runner.ts

@@ -0,0 +1,164 @@
+/**
+ * sshSudoRunner(): the Linux twin of `../launchd/sudo-runner.ts` — the same idea (the deploy runs
+ * as the operator, and only a fixed allowlist of calls goes through `sudo -n`), rebuilt for a
+ * non-root ssh user with passwordless sudo instead of a local macOS session. See
+ * docs/linux-sudo.md for the full argv table and what is measured versus reasoned.
+ *
+ * ⛔ `sudo -n`, NEVER A PROMPT — same rule, same reason: a deploy that stops to ask for a password
+ *   is the "no silent sudo" failure this exists to prevent.
+ * ⛔ EVERY PRIVILEGED ARGV IS LOGGED BEFORE IT RUNS, and a file's bytes never reach argv or the
+ *   log: they travel through the staged file (sudo-stage.ts) alone.
+ * ⛔ A PLAN NEVER ELEVATES. `checkWrite` and every read run through `base` — the plain
+ *   `sshRunner()` — never through sudo. Nothing here probes sudo at construction.
+ * ★ PROMISES, NOT EFFECTS, ON PURPOSE — the same divergence `../launchd/runner.ts` documents
+ *   (H3 in the provider-standard skill): a consumer's own runner is a plain async implementation.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+import { sudoRefusal } from '../launchd/sudo-said.ts';
+import { type SshRunnerOptions, sshRunner } from './ssh-runner.ts';
+import { elevatedExec } from './sudo-exec.ts';
+import {
+  CHMOD,
+  CHOWN,
+  INSTALL,
+  MKDIR,
+  MV,
+  RM,
+  RMDIR,
+  SUDO,
+  SYSTEMCTL_ABS,
+  SudoRefusedError,
+  checkPrefixes,
+  prefixOf,
+  privilegedProblem,
+  routeExec,
+} from './sudo-allowlist.ts';
+import { assertGuardedChain } from './sudo-guard.ts';
+import { type Staged, stageRemote } from './sudo-stage.ts';
+import { type Elevate, vetWrite, writeUnderPrefix } from './sudo-write.ts';
+
+export { SudoRefusedError };
+
+export type SshSudoRunnerOptions = SshRunnerOptions & {
+  /** Directories root may write under. Required; absolute, normalised, never `/`. */
+  readonly prefixes: readonly string[];
+  /** One line per privileged argv, before it runs. @default a line on stderr */
+  readonly log?: (line: string) => void;
+};
+
+/** What a sudo runner is built from. ★ Split out so the tests swap the host, never the logic. */
+export type SshSudoDeps = {
+  /** Runs everything, including `sudo` itself. `await sshRunner(options)` for the real one. */
+  readonly base: HostRunner;
+  readonly stage: (bytes: Uint8Array) => Promise<Staged>;
+  readonly log: (line: string) => void;
+};
+
+const outsidePrefixHint =
+  (path: string, prefixes: readonly string[]) =>
+  (cause: unknown): never => {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (!/permission denied|operation not permitted/i.test(message)) throw cause;
+    throw new Error(
+      `sshSudoRunner ${path}: the operator could not do this, and the path is under no declared ` +
+        `prefix (${prefixes.join(', ')}). If root owns its directory, declare that directory as ` +
+        'a prefix.',
+      { cause },
+    );
+  };
+
+export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDeps): HostRunner => {
+  const prefixes = checkPrefixes(prefixList);
+  const { base } = deps;
+
+  /** ⛔ THE ONE PLACE `sudo` IS SPAWNED: allowlist, then any host check (`before`), then the log
+   *    line, then `sudo -n -- argv`. Shared by exec()'s root branch and by writeFileAtomic. */
+  const elevate: Elevate = async (argv, context, before) => {
+    const shown = JSON.stringify(argv);
+    const problem = privilegedProblem(argv, { prefixes, ...context });
+    if (problem !== undefined)
+      throw new SudoRefusedError(`sshSudoRunner refused ${shown}: ${problem}`);
+    await before?.();
+    deps.log(`homeflare/linux sudo -n ${shown}`);
+    const result = await base.exec([SUDO, '-n', '--', ...argv]);
+    const refused = sudoRefusal(shown, result);
+    if (refused !== undefined) throw refused;
+    return result;
+  };
+
+  return {
+    checkWrite: async (path, options) => {
+      await vetWrite(base, prefixes, path, options);
+    },
+    effectiveUid: () => base.effectiveUid(),
+    exec: async (argv) => {
+      const route = routeExec(argv, prefixes);
+      if ('refuse' in route) throw new SudoRefusedError(`sshSudoRunner: ${route.refuse}`);
+      if (route.as === 'operator') return base.exec(argv);
+      return elevatedExec(base, elevate, prefixes, argv);
+    },
+    lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
+    lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    privileged: true,
+    readFile: (path) => base.readFile(path),
+    removeFile: async (path) => {
+      const prefix = prefixOf(path, prefixes);
+      if (prefix === undefined)
+        return base.removeFile(path).catch(outsidePrefixHint(path, prefixes));
+      // ★ Nothing there is success without a privileged call, so an idempotent delete logs nothing.
+      const target = await assertGuardedChain(base, prefix, path, 'file-or-absent');
+      if (target === undefined) return;
+      const argv = [RM, '-f', '--', path];
+      const result = await elevate(argv);
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`,
+        );
+      }
+    },
+    sleep: (ms) => base.sleep(ms),
+    stat: (path) => base.stat(path),
+    writeFileAtomic: async (path, bytes, options) => {
+      const vetted = await vetWrite(base, prefixes, path, options);
+      if (vetted === undefined) {
+        return base.writeFileAtomic(path, bytes, options).catch(outsidePrefixHint(path, prefixes));
+      }
+      await writeUnderPrefix(base, elevate, deps.stage, path, bytes, options, vetted.mode);
+    },
+  };
+};
+
+const REQUIRED_PROGRAMS = [SUDO, INSTALL, MV, RM, MKDIR, CHMOD, CHOWN, RMDIR, SYSTEMCTL_ABS];
+
+/**
+ * ★ READ-ONLY, OPTIONAL. One combined `test -x` so a missing coreutils package or a systemd-free
+ *   container fails at construction with a clear message, instead of at the first deploy step
+ *   that happens to need it. Never probes sudo itself.
+ */
+const checkProgramsExist = async (base: HostRunner, host: string): Promise<void> => {
+  const script = REQUIRED_PROGRAMS.map(
+    (p) => `test -x '${p}' || { echo "$0: ${p}"; exit 1; }`,
+  ).join(' && ');
+  const result = await base.exec(['/bin/sh', '-c', script, 'sshSudoRunner']);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `sshSudoRunner ${host}: ${result.stdout.trim() || result.stderr.trim()} is missing or not ` +
+        'executable on this host. sshSudoRunner sends absolute GNU coreutils and systemd paths.',
+    );
+  }
+};
+
+/** The real sudo runner: `sshRunner()` for everything, `/usr/bin/sudo -n` for the allowlist. */
+export const sshSudoRunner = async (options: SshSudoRunnerOptions): Promise<HostRunner> => {
+  const base = await sshRunner(options);
+  await checkProgramsExist(base, options.host);
+  return makeSshSudoRunner(options.prefixes, {
+    base,
+    log:
+      options.log ??
+      ((line) => {
+        process.stderr.write(`${line}\n`);
+      }),
+    stage: stageRemote(base),
+  });
+};

package/src/linux/sudo-stage.ts

@@ -0,0 +1,50 @@
+/**
+ * Where sudo-runner.ts puts a file's bytes before `install` copies them into a fresh temp file
+ * that `mv` then renames into place. The Linux twin of `../launchd/sudo-stage.ts` — rewritten,
+ * not reused, because staging happens ON THE REMOTE HOST through the base runner's own calls,
+ * never through `node:fs` against this process's local disk.
+ *
+ * ★ WHY STAGE AT ALL. The operator cannot write inside a root-owned directory, and the bytes must
+ *   not travel through argv (they would reach the log and `ps`). So they are written, as the
+ *   operator, to a private file on the SAME host, and `install` copies that one file.
+ * ⛔ A 0700 DIRECTORY, A 0600 FILE: between the write and the install, nobody but the operator and
+ *   root can read the bytes or swap the file. `mktemp -d` creates its directory 0700 by
+ *   construction (GNU coreutils); the payload's own mode is asked for explicitly.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+
+/** A file staged for `install`, and how to remove it again. */
+export type Staged = { readonly path: string; readonly dispose: () => Promise<void> };
+
+const refuse = (message: string): Error => new Error(`sshSudoRunner stage: ${message}`);
+
+/** `stage` in `SshSudoDeps` — closes over the base runner so every call writes to the same host. */
+export const stageRemote =
+  (base: HostRunner) =>
+  async (bytes: Uint8Array): Promise<Staged> => {
+    const made = await base.exec(['/usr/bin/mktemp', '-d']);
+    if (made.exitCode !== 0)
+      throw refuse(`mktemp -d -> ${String(made.exitCode)}: ${made.stderr.trim()}`);
+    const dir = made.stdout.trim();
+    if (dir === '' || !dir.startsWith('/')) {
+      throw refuse(`mktemp -d printed ${JSON.stringify(made.stdout)}, not an absolute path`);
+    }
+    const dispose = async () => {
+      const removed = await base.exec(['/usr/bin/rm', '-rf', '--', dir]);
+      // ⚠️ Best-effort: a leaked 0700 temp dir the operator owns is a nuisance, never a secret
+      //   exposure, so disposal failing never masks the write's own success or failure.
+      if (removed.exitCode !== 0) {
+        process.stderr.write(
+          `sshSudoRunner: could not remove staging dir ${dir}: ${removed.stderr.trim()}\n`,
+        );
+      }
+    };
+    try {
+      const path = `${dir}/staged`;
+      await base.writeFileAtomic(path, bytes, { mode: 0o600 });
+      return { dispose, path };
+    } catch (cause) {
+      await dispose();
+      throw cause;
+    }
+  };

package/src/linux/sudo-write.ts

@@ -0,0 +1,167 @@
+/**
+ * sshSudoRunner's `writeFileAtomic`, split out of sudo-runner.ts so that file stays the wiring.
+ *
+ * ⛔ WHY NOT `install` STRAIGHT TO `path`, THE WAY THE MAC RUNNER DOES. GNU `install` opens the
+ *   destination and writes THROUGH it (ssh-scripts.ts's header); there is no macOS-style stage-
+ *   and-rename built in. So this stages the bytes, `install`s them into a FRESH temp file in the
+ *   destination's own directory (fresh, so "writes through" changes nothing that mattered), then
+ *   `mv`s that temp file onto `path` — rename(2), same directory, so the swap is atomic and never
+ *   torn, exactly what `ssh-scripts.ts writeScript` already does for the unprivileged case.
+ * ⛔ `install` NEVER TAKES `-o`/`-g` — see sudo-allowlist-chown.ts's header (coreutils' own
+ *   `get_ids()` has no way to force numeric ids, unlike `chown`). It always installs owned by
+ *   whoever `sudo` runs it as; a non-root owner or group is set afterward by a separate,
+ *   `+`-forced `chown` on that same temp file, before `mv`.
+ * ⛔ THE DERIVED TEMP IS VERIFIED ABSENT, AS THE OPERATOR, BEFORE `install` RUNS. A 12-hex-char
+ *   collision is astronomically unlikely, but "unlikely" is not the bar a privileged write is held
+ *   to elsewhere in this runner, and the check costs one `stat` this runner already knows how to do.
+ * ⛔ ON ANY FAILURE AFTER `install` SUCCEEDS, THE TEMP IS REMOVED (also as root, since only root
+ *   can now touch it). A left-behind `.foo.hf-xxxx.tmp` would read, on the next plan, as an extra
+ *   file under the prefix that guard would find and no code would explain — and if THAT cleanup
+ *   itself fails, the thrown error says so and names the path, rather than silently swallowing it.
+ */
+import { randomBytes } from 'node:crypto';
+import type { ExecResult, HostRunner, WriteOptions } from '../launchd/runner.ts';
+import { CHOWN, INSTALL, MV, RM, SudoRefusedError, octalMode, prefixOf } from './sudo-allowlist.ts';
+import { assertInstallable, operatorGroups } from './sudo-guard.ts';
+import type { Staged } from './sudo-stage.ts';
+
+const basename = (path: string): string => path.slice(path.lastIndexOf('/') + 1);
+const dirOf = (path: string): string => path.slice(0, path.lastIndexOf('/')) || '/';
+
+/** `<dir>/.<basename>.hf-<12 hex>.tmp`, in `dest`'s own directory — never anywhere else. */
+export const deriveTemp = (dest: string): string =>
+  `${dirOf(dest)}/.${basename(dest)}.hf-${randomBytes(6).toString('hex')}.tmp`;
+
+/** What one privileged call, already checked against the allowlist, comes back as when it fails. */
+const mustSucceed = (result: ExecResult, argv: readonly string[]): void => {
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`,
+    );
+  }
+};
+
+/**
+ * The cleanup `rm`'s own failure, for the merged error below. 🔴 MEASURED (adversarial review,
+ *   round 3, 2026-09-23): a plain `ExecResult` (the shape `elevate()` resolves with for a command
+ *   that RAN but exited non-zero) has no useful `toString()` — `String(cleaned)` printed
+ *   `[object Object]`, silently dropping the one thing an operator doing manual cleanup needs:
+ *   what `rm` actually said. A thrown `Error` (a refused or transport-failed `rm`) still prints
+ *   its own message correctly, so only the `ExecResult` shape needed a name.
+ */
+const describeCleanupFailure = (cleaned: unknown): string => {
+  if (
+    typeof cleaned === 'object' &&
+    cleaned !== null &&
+    'exitCode' in cleaned &&
+    'stderr' in cleaned
+  ) {
+    const result = cleaned as ExecResult;
+    return `exit ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`;
+  }
+  return cleaned instanceof Error ? cleaned.message : String(cleaned);
+};
+
+/** A privileged call: allowlisted, logged, run. Shared with sudo-runner.ts's own exec() routing. */
+export type Elevate = (
+  argv: readonly string[],
+  context?: { readonly staged?: string; readonly temp?: string },
+  before?: () => Promise<unknown>,
+) => Promise<ExecResult>;
+
+/**
+ * Plan-time and write-time share this: valid mode, the path chain, mode/owner refusals and the
+ * read-back — everything a write can be refused for before anything is staged or run as root.
+ * `undefined` outside every prefix, where the caller falls back to `base` directly.
+ */
+export const vetWrite = async (
+  base: HostRunner,
+  prefixes: readonly string[],
+  path: string,
+  options: WriteOptions,
+): Promise<{ readonly mode: string; readonly prefix: string } | undefined> => {
+  const prefix = prefixOf(path, prefixes);
+  if (prefix === undefined) return undefined;
+  const mode = octalMode(options.mode);
+  if (mode === undefined)
+    throw new SudoRefusedError(`sshSudoRunner ${path}: mode must be 0–0o7777`);
+  const groups = await operatorGroups(base);
+  await assertInstallable(base, prefix, path, options, groups);
+  return { mode, prefix };
+};
+
+/** `+<uid>`, `:+<gid>`, or `+<uid>:+<gid>` — omitted sides leave that half of ownership alone. */
+const safeOwnerSpec = (uid: number | undefined, gid: number | undefined): string =>
+  `${uid === undefined ? '' : `+${uid}`}${gid === undefined ? '' : `:+${gid}`}`;
+
+/**
+ * A non-root owner or group, when one was declared: `install` leaves the temp root:root (see the
+ * file header), so this is the ONLY call that can hand it to someone else. `undefined` from either
+ * side when that half already matches `install`'s own default (0/omitted), so a plain root-owned
+ * write costs nothing extra here.
+ */
+const chownNeeded = (
+  options: WriteOptions,
+): { readonly uid?: number; readonly gid?: number } | undefined => {
+  const uid = options.uid !== undefined && options.uid !== 0 ? options.uid : undefined;
+  const gid = options.gid !== undefined && options.gid !== 0 ? options.gid : undefined;
+  return uid === undefined && gid === undefined
+    ? undefined
+    : { ...(uid === undefined ? {} : { uid }), ...(gid === undefined ? {} : { gid }) };
+};
+
+/**
+ * Stage, `install` into a fresh temp file beside `path`, `chown` it if a non-root owner was
+ * declared, `mv` it into place. Cleans up the temp on a failed `mv`, and always disposes the
+ * stage — whether or not the write succeeded.
+ */
+export const writeUnderPrefix = async (
+  base: HostRunner,
+  elevate: Elevate,
+  stage: (bytes: Uint8Array) => Promise<Staged>,
+  path: string,
+  bytes: Uint8Array,
+  options: WriteOptions,
+  mode: string,
+): Promise<void> => {
+  const temp = deriveTemp(path);
+  const staged = await stage(bytes);
+  try {
+    const installArgv = [INSTALL, '-m', mode, '-T', '--', staged.path, temp];
+    const before = async () => {
+      const existing = await base.stat(temp);
+      if (existing !== undefined) {
+        throw new SudoRefusedError(
+          `sshSudoRunner ${temp}: already exists (a ${existing.kind}); refusing to install over ` +
+            'it. Nothing ran as root.',
+        );
+      }
+    };
+    mustSucceed(await elevate(installArgv, { staged: staged.path, temp }, before), installArgv);
+    try {
+      const owner = chownNeeded(options);
+      if (owner !== undefined) {
+        const chownArgv = [CHOWN, safeOwnerSpec(owner.uid, owner.gid), '--', temp];
+        mustSucceed(await elevate(chownArgv, { temp }), chownArgv);
+      }
+      const mvArgv = [MV, '-f', '-T', '--', temp, path];
+      mustSucceed(await elevate(mvArgv, { temp }), mvArgv);
+    } catch (cause) {
+      const rmArgv = [RM, '-f', '--', temp];
+      const cleaned = await elevate(rmArgv, { temp })
+        .then((result) => (result.exitCode === 0 ? undefined : result))
+        .catch((rmCause: unknown) => rmCause);
+      if (cleaned !== undefined) {
+        throw new Error(
+          `${cause instanceof Error ? cause.message : String(cause)} — AND removing the leftover ` +
+            `temp ${temp} also failed (${describeCleanupFailure(cleaned)}); it needs manual ` +
+            'cleanup as root.',
+          { cause },
+        );
+      }
+      throw cause;
+    }
+  } finally {
+    await staged.dispose();
+  }
+};

package/src/linux/unit-form.ts

@@ -155,7 +155,8 @@ export const unitText = (props: SystemdUnitProps): string =>
 export const unitPathFor = (props: SystemdUnitProps): string =>
   `${props.directory ?? DEFAULT_UNIT_DIRECTORY}/${props.name}`;
 
-const NAME = /^[A-Za-z0-9][A-Za-z0-9_.@:-]*\.([a-z]+)$/;
+/** ★ Exported so sudo-allowlist.ts validates a systemctl unit operand against the same pattern. */
+export const NAME = /^[A-Za-z0-9][A-Za-z0-9_.@:-]*\.([a-z]+)$/;
 /** systemd's own unit types. ★ Fixed vocabulary from `systemd.unit(5)`, not a guess at directives. */
 const TYPES = new Set([
   'automount',

package/src/litellm/fake-litellm.ts

@@ -48,6 +48,8 @@ export const startFakeLitellm = (options?: {
     new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
 
   const server = Bun.serve({
+    // ⚠️ Loopback, not the wildcard default — see proxmox/fake-pve-lxc.ts for the race.
+    hostname: '127.0.0.1',
     port: 0,
     fetch: async (req) => {
       const url = new URL(req.url);

package/src/proxmox/client.test.ts

@@ -12,7 +12,11 @@ import { PveError, pveWith } from './client.ts';
 import type { PveCredential, PveTarget } from './credentials.ts';
 import { orderedMembers, resetLastGoodForTest } from './members.ts';
 
-type ServeOptions = { fetch(request: Request): Response | Promise<Response>; port: number };
+type ServeOptions = {
+  fetch(request: Request): Response | Promise<Response>;
+  hostname: string;
+  port: number;
+};
 const { Bun } = globalThis as unknown as {
   Bun: { serve(options: ServeOptions): { port: number; stop(closeActive: boolean): void } };
 };
@@ -84,6 +88,8 @@ const counting = (data: unknown) => {
       hits += 1;
       return Response.json({ data });
     },
+    // ⚠️ Loopback, not the wildcard default — see fake-pve-lxc.ts for the measured race.
+    hostname: '127.0.0.1',
     port: 0,
   });
   return { hits: () => hits, port: server.port, stop: () => server.stop(true) };
@@ -106,7 +112,11 @@ describe('cluster member failover', () => {
 
   it('does not fail over on HTTP 500 from the first member', async () => {
     resetLastGoodForTest();
-    const bad = Bun.serve({ fetch: () => new Response('fail', { status: 500 }), port: 0 });
+    const bad = Bun.serve({
+      fetch: () => new Response('fail', { status: 500 }),
+      hostname: '127.0.0.1',
+      port: 0,
+    });
     const good = counting([]);
     try {
       const error = await run(pveWith(target([A, B]), CRED, 'GET', 'pools').pipe(Effect.flip), {
@@ -144,7 +154,11 @@ describe('cluster member failover', () => {
 
   it('does not re-send a write after a transport timeout', async () => {
     resetLastGoodForTest();
-    const hang = Bun.serve({ fetch: () => new Promise<Response>(() => {}), port: 0 });
+    const hang = Bun.serve({
+      fetch: () => new Promise<Response>(() => {}),
+      hostname: '127.0.0.1',
+      port: 0,
+    });
     const backup = counting('UPID:1');
     try {
       await run(

package/src/proxmox/fake-pve-lxc.ts

@@ -185,7 +185,16 @@ export const fakePve = (): FakePve => {
     return json({ data: null, message: 'unhandled\n' }, 501);
   };
 
-  const server = Bun.serve({ fetch: handle, port: 0 });
+  // 🔴 LOOPBACK, NOT THE DEFAULT WILDCARD — AND THAT WAS THE FLAKE. Measured 2026-09-23 on
+  //   macOS: `Bun.serve({ port: 0 })` binds 0.0.0.0, and the kernel will hand a wildcard
+  //   port-0 bind a port some OTHER socket already holds on 127.0.0.1 (16,373 binds in, it
+  //   did). Loopback traffic then goes to the more specific listener, so this fake's own
+  //   requests reached another process's server — another test suite's fake, when several
+  //   agents run `bun test` at once — and a plan failed with "Transport error" on a GET to a
+  //   server that was up. A 127.0.0.1 port-0 bind is never handed a port in use on
+  //   127.0.0.1, and nothing more specific can shadow it. tests/loopback-servers.test.ts
+  //   keeps every test server this way.
+  const server = Bun.serve({ fetch: handle, hostname: '127.0.0.1', port: 0 });
   const port = String(server.port);
   const remapped = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
     const url = new URL(input instanceof Request ? input.url : String(input));