@homeflare/alchemy 0.54.0 → 0.56.0

package/src/linux/sudo-runner-privileged-read.test.ts

@@ -0,0 +1,200 @@
+/**
+ * sshSudoRunner `privilegedReads`: an exact-path, root-owned-regular-file-only sudo read, so a
+ * plan can diff a declared 0600 file without a general root-read primitive.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { FileStat, HostRunner } from '../launchd/runner.ts';
+import { CHOWN, INSTALL, SUDO } from './sudo-allowlist.ts';
+import { fakeSudoHost } from './fake-sudo.ts';
+import {
+  BASE64,
+  SudoRefusedError,
+  checkPrivilegedReads,
+  makeSshSudoRunner,
+} from './sudo-runner.ts';
+
+const SECRETISH = '/opt/app/config.yaml';
+const file = (uid: number, kind: FileStat['kind'] = 'file'): FileStat =>
+  ({ kind, mode: 0o600, uid, gid: 0, size: 5 }) as unknown as FileStat;
+
+const host = (stat: FileStat | undefined, exitCode = 0) => {
+  const execs: string[][] = [];
+  const operatorReads: string[] = [];
+  const base = {
+    platform: 'linux',
+    privileged: false,
+    effectiveUid: () => 1001,
+    stat: async () => stat,
+    readFile: async (path: string) => {
+      operatorReads.push(path);
+      return new TextEncoder().encode('operator');
+    },
+    exec: async (argv: string[]) => {
+      execs.push(argv);
+      return {
+        exitCode,
+        stdout: `${Buffer.from('hello').toString('base64')}\n`,
+        stderr: exitCode === 0 ? '' : 'boom',
+      };
+    },
+  } as unknown as HostRunner;
+  const runner = makeSshSudoRunner(['/opt/app/data'], {
+    base,
+    log: () => undefined,
+    stage: async () => {
+      throw new Error('unused');
+    },
+    privilegedReads: [SECRETISH],
+  });
+  return { execs, operatorReads, runner };
+};
+
+describe('privilegedReads', () => {
+  test('a listed root-owned file is read with exactly sudo -n -- base64 -- <path>', async () => {
+    const { execs, runner } = host(file(0));
+    expect(new TextDecoder().decode(await runner.readFile(SECRETISH))).toBe('hello');
+    expect(execs).toEqual([[SUDO, '-n', '--', BASE64, '--', SECRETISH]]);
+  });
+
+  test('an unlisted path is read as the operator, never elevated', async () => {
+    const { execs, operatorReads, runner } = host(file(0));
+    await runner.readFile('/etc/caddy/cf-token.env');
+    await runner.readFile(`${SECRETISH}.bak`);
+    await runner.readFile('/opt/app');
+    expect(execs).toEqual([]);
+    expect(operatorReads).toEqual(['/etc/caddy/cf-token.env', `${SECRETISH}.bak`, '/opt/app']);
+  });
+
+  test('a symlink, a directory or a non-root file at the listed path is refused', async () => {
+    for (const stat of [file(0, 'symlink'), file(0, 'directory'), file(1001)]) {
+      const { execs, runner } = host(stat);
+      await expect(runner.readFile(SECRETISH)).rejects.toBeInstanceOf(SudoRefusedError);
+      expect(execs).toEqual([]);
+    }
+  });
+
+  test('an absent listed file reads as absent', async () => {
+    const { execs, runner } = host(undefined);
+    expect(await runner.readFile(SECRETISH)).toBeUndefined();
+    expect(execs).toEqual([]);
+  });
+
+  test('a failed sudo read throws', async () => {
+    const { runner } = host(file(0), 1);
+    await expect(runner.readFile(SECRETISH)).rejects.toThrow('-> 1');
+  });
+
+  test('only normalized absolute paths may be listed', () => {
+    for (const bad of ['relative', '/opt/../etc/shadow', '/opt//x', '/opt/x/', '/opt/./x', '/']) {
+      expect(() => checkPrivilegedReads([bad])).toThrow(SudoRefusedError);
+    }
+    expect(checkPrivilegedReads([SECRETISH]).has(SECRETISH)).toBe(true);
+  });
+});
+
+/**
+ * The write side of the same grant (the /etc/nut convergence, 2026-10-18): a file the runner
+ * reads back as root may be WRITTEN with a mode that hides it from the operator — its read-back
+ * goes through `sudo -n base64`, so it cannot strand itself. Every other refusal (setuid,
+ * group-writable, the path chain) still applies, and an UNLISTED file with the same mode keeps
+ * refusing exactly as before.
+ */
+describe('privilegedReads on the write path', () => {
+  const NUTISH = '/etc/nut/upsd.users';
+  const bytes = new TextEncoder().encode('new bytes\n');
+  const owner = { gid: 113, mode: 0o640, uid: 0 };
+
+  const mk = (options: { readonly listed?: boolean } = {}) =>
+    fakeSudoHost({}, new Set(), {
+      operatorGroups: [1000],
+      prefixes: ['/etc/nut'],
+      ...(options.listed === false ? {} : { privilegedReads: [NUTISH] }),
+    });
+
+  test('plan-time checkWrite passes for the listed 0640 root:nut file, refuses when unlisted', async () => {
+    const { runner } = mk();
+    const unlisted = mk({ listed: false });
+    if (runner.checkWrite === undefined || unlisted.runner.checkWrite === undefined) {
+      throw new Error('sshSudoRunner must expose checkWrite');
+    }
+    await runner.checkWrite(NUTISH, owner);
+    await expect(unlisted.runner.checkWrite(NUTISH, owner)).rejects.toThrow('would hide it');
+  });
+
+  test('writeFileAtomic installs and chowns the listed 0640 root:nut file under the prefix', async () => {
+    const { fake, privileged, runner } = mk();
+    fake.files.set(NUTISH, {
+      bytes: new TextEncoder().encode('old'),
+      gid: 113,
+      kind: 'file',
+      mode: 0o640,
+      uid: 0,
+    });
+    await runner.writeFileAtomic(NUTISH, bytes, owner);
+    const root = privileged();
+    expect(root.some((call) => call[0] === INSTALL)).toBe(true);
+    expect(root.some((call) => call[0] === CHOWN && call[1] === ':+113')).toBe(true);
+    const after = fake.files.get(NUTISH);
+    expect(new TextDecoder().decode(after?.bytes)).toBe('new bytes\n');
+    expect(after?.mode).toBe(0o640);
+    expect(after?.uid).toBe(0);
+    expect(after?.gid).toBe(113);
+    /**
+     * ★ THE JOINED GUARANTEE (deepseek round-2 ask): the file the guard let us write in a mode
+     *   that hides it from the operator reads back AS ROOT through the listed path — never
+     *   EACCES, never the operator's own read. This is the stranding the guard existed to
+     *   prevent, now provably absent end-to-end.
+     */
+    const before = root.length;
+    expect(new TextDecoder().decode(await runner.readFile(NUTISH))).toBe('new bytes\n');
+    expect(privileged()[before]).toEqual([BASE64, '--', NUTISH]);
+  });
+
+  test('an unlisted 0640 write still refuses, and nothing runs as root', async () => {
+    const { privileged, runner } = mk({ listed: false });
+    await expect(runner.writeFileAtomic(NUTISH, bytes, owner)).rejects.toThrow('would hide it');
+    expect(privileged()).toEqual([]);
+  });
+
+  test('with the set non-empty, a sibling under the same prefix still refuses', async () => {
+    // The skip is set MEMBERSHIP, never a prefix match: with NUTISH listed, its sibling
+    // upsmon.conf — same directory, same shape, same mode — keeps the refusal
+    // (glm round-2 ask, 2026-10-18).
+    const { privileged, runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    await expect(runner.checkWrite('/etc/nut/upsmon.conf', owner)).rejects.toThrow('would hide it');
+    expect(privileged()).toEqual([]);
+  });
+
+  test('a listed file still refuses setuid and group-writable modes', async () => {
+    const { runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    await expect(runner.checkWrite(NUTISH, { gid: 0, mode: 0o4755, uid: 0 })).rejects.toThrow(
+      'setuid/setgid',
+    );
+    await expect(runner.checkWrite(NUTISH, { gid: 0, mode: 0o0660, uid: 0 })).rejects.toThrow(
+      'writable by group',
+    );
+  });
+
+  test('a listed path handed to a non-root uid is refused outright, whatever its mode', async () => {
+    // The elevated read itself refuses anything but a root-owned regular file, so a handoff —
+    // even one with operator-readable other bits (0644 uid 1001) that the plain read-back check
+    // would pass — would land and then fail EVERY read: the stranding the guard exists to
+    // prevent (deepseek round-1; the other-readable case is the glm round ask).
+    const { privileged, runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    for (const handoff of [
+      { gid: 113, mode: 0o640, uid: 1001 },
+      { gid: 0, mode: 0o644, uid: 1001 },
+    ]) {
+      await expect(runner.checkWrite(NUTISH, handoff)).rejects.toThrow(
+        'Handing it to uid 1001 would land and then fail every read',
+      );
+      await expect(runner.writeFileAtomic(NUTISH, bytes, handoff)).rejects.toThrow(
+        'Keep it root-owned',
+      );
+    }
+    expect(privileged()).toEqual([]);
+  });
+});

package/src/linux/sudo-runner.ts

@@ -8,7 +8,9 @@
  *   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
+ * ⛔ A PLAN ELEVATES EXACTLY ONE KIND OF CALL: the `privilegedReads` file's own read (below) —
+ *   the read a plan diff needs on a declared root-owned file. Every other read, and every
+ *   `checkWrite` host probe (`id -G`, `ls`, `stat`), runs 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.
@@ -44,6 +46,14 @@ export type SshSudoRunnerOptions = SshRunnerOptions & {
   readonly prefixes: readonly string[];
   /** One line per privileged argv, before it runs. @default a line on stderr */
   readonly log?: (line: string) => void;
+  /**
+   * ★ Exact absolute paths of root-owned files the operator cannot read but a plan must diff
+   *   (a declared 0600 file). Each is read with `sudo -n -- /usr/bin/base64 -- <path>`, and ONLY
+   *   when it is the exact string listed here, a regular file (lstat: never a symlink) and owned
+   *   by uid 0. ⛔ Not a prefix and not a pattern: a general sudo read would be a root-read
+   *   primitive reaching every credential on the host, so each file is named one by one.
+   */
+  readonly privilegedReads?: readonly string[];
 };
 
 /** What a sudo runner is built from. ★ Split out so the tests swap the host, never the logic. */
@@ -52,8 +62,31 @@ export type SshSudoDeps = {
   readonly base: HostRunner;
   readonly stage: (bytes: Uint8Array) => Promise<Staged>;
   readonly log: (line: string) => void;
+  readonly privilegedReads?: readonly string[];
 };
 
+export const BASE64 = '/usr/bin/base64';
+
+/** Refuses anything but a normalized absolute path: no `.`/`..` segment, no `//`, no trailing `/`. */
+export const checkPrivilegedReads = (paths: readonly string[] = []): ReadonlySet<string> => {
+  for (const path of paths) {
+    const segments = path.split('/').slice(1);
+    if (
+      !path.startsWith('/') ||
+      path.endsWith('/') ||
+      segments.some((segment) => segment === '' || segment === '.' || segment === '..') ||
+      /[\0\n]/.test(path)
+    )
+      throw new SudoRefusedError(
+        `sshSudoRunner: privilegedReads entry ${JSON.stringify(path)} is not a normalized absolute file path`,
+      );
+  }
+  return new Set(paths);
+};
+
+const decodeBase64 = (text: string): Uint8Array =>
+  new Uint8Array(Buffer.from(text.replaceAll('\n', ''), 'base64'));
+
 const outsidePrefixHint =
   (path: string, prefixes: readonly string[]) =>
   (cause: unknown): never => {
@@ -70,6 +103,7 @@ const outsidePrefixHint =
 export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDeps): HostRunner => {
   const prefixes = checkPrefixes(prefixList);
   const { base } = deps;
+  const readable = checkPrivilegedReads(deps.privilegedReads);
 
   /** ⛔ 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. */
@@ -88,7 +122,7 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
 
   return {
     checkWrite: async (path, options) => {
-      await vetWrite(base, prefixes, path, options);
+      await vetWrite(base, prefixes, path, options, readable);
     },
     effectiveUid: () => base.effectiveUid(),
     exec: async (argv) => {
@@ -103,7 +137,27 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
     //   this runner elevates on the SAME target `base` (sshRunner) already declared.
     platform: base.platform,
     privileged: true,
-    readFile: (path) => base.readFile(path),
+    readFile: async (path) => {
+      if (!readable.has(path)) return base.readFile(path);
+      const stat = await base.stat(path);
+      if (stat === undefined) return undefined;
+      if (stat.kind !== 'file' || stat.uid !== 0)
+        throw new SudoRefusedError(
+          `sshSudoRunner refused a privileged read of ${path}: it is a ${stat.kind} owned by uid ` +
+            `${String(stat.uid)}, and only a root-owned regular file is read as root`,
+        );
+      const argv = [BASE64, '--', path];
+      const shown = JSON.stringify(argv);
+      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;
+      if (result.exitCode !== 0)
+        throw new Error(
+          `sudo -n ${shown} -> ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`,
+        );
+      return decodeBase64(result.stdout);
+    },
     removeFile: async (path) => {
       const prefix = prefixOf(path, prefixes);
       if (prefix === undefined)
@@ -122,7 +176,7 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
     sleep: (ms) => base.sleep(ms),
     stat: (path) => base.stat(path),
     writeFileAtomic: async (path, bytes, options) => {
-      const vetted = await vetWrite(base, prefixes, path, options);
+      const vetted = await vetWrite(base, prefixes, path, options, readable);
       if (vetted === undefined) {
         return base.writeFileAtomic(path, bytes, options).catch(outsidePrefixHint(path, prefixes));
       }
@@ -157,6 +211,7 @@ export const sshSudoRunner = async (options: SshSudoRunnerOptions): Promise<Host
   await checkProgramsExist(base, options.host);
   return makeSshSudoRunner(options.prefixes, {
     base,
+    ...(options.privilegedReads === undefined ? {} : { privilegedReads: options.privilegedReads }),
     log:
       options.log ??
       ((line) => {

package/src/linux/sudo-write.ts

@@ -73,12 +73,16 @@ export type Elevate = (
  * 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.
+ * ★ `privilegedReads` is the runner's exact-path elevated-read set: a file on it is read back as
+ *   root (sudo-runner.ts's readFile), so the read-back refusal does not apply to it — the other
+ *   checks in assertInstallable still do.
  */
 export const vetWrite = async (
   base: HostRunner,
   prefixes: readonly string[],
   path: string,
   options: WriteOptions,
+  privilegedReads?: ReadonlySet<string>,
 ): Promise<{ readonly mode: string; readonly prefix: string } | undefined> => {
   const prefix = prefixOf(path, prefixes);
   if (prefix === undefined) return undefined;
@@ -86,7 +90,7 @@ export const vetWrite = async (
   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);
+  await assertInstallable(base, prefix, path, options, groups, privilegedReads);
   return { mode, prefix };
 };
 

package/src/proxmox/index.ts

@@ -130,3 +130,16 @@ export { ProxmoxStorage, ProxmoxStorageProvider } from './storage.ts';
 export { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
 export { type FromEnv } from '../secrets/write-only.ts';
 export { ProxmoxZfsPool, ProxmoxZfsPoolProvider } from './zfs-pool.ts';
+
+// ★ 2026-10-14: scoped PVE API helper for Ceph / CT ops without SSH (scoped-api.ts).
+export {
+  CEPH_FLAGS,
+  CT_CONFIG_KEYS,
+  type CephFlag,
+  type CtConfigPatch,
+  type ScopedCall,
+  type ScopedTier,
+  pveScoped,
+  scopedCalls,
+  scopedTarget,
+} from './scoped-api.ts';

package/src/proxmox/scoped-api.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { type PveTarget, mintTier } from './credentials.ts';
+import { CT_CONFIG_KEYS, scopedCalls, scopedTarget } from './scoped-api.ts';
+
+const target: PveTarget = { mount: 'proxmox-tb4', members: ['n2.mgmt.example'], scheme: 'pve' };
+
+describe('pveScoped', () => {
+  it('pins BOTH roles to the scoped tier, so neither read nor provision can be minted', () => {
+    for (const tier of ['ceph-ops', 'ct-config'] as const) {
+      const t = scopedTarget(target, tier);
+      assert.equal(mintTier(t, 'read'), tier);
+      assert.equal(mintTier(t, 'provision'), tier);
+    }
+  });
+  it('ceph calls are fixed paths on the ceph-ops tier', () => {
+    assert.deepEqual(scopedCalls.cephStatus(), {
+      tier: 'ceph-ops',
+      role: 'read',
+      method: 'GET',
+      path: '/cluster/ceph/status',
+    });
+    assert.deepEqual(scopedCalls.cephSetFlag('noout', false), {
+      tier: 'ceph-ops',
+      role: 'provision',
+      method: 'PUT',
+      path: '/cluster/ceph/flags/noout',
+      form: { value: '0' },
+    });
+    assert.equal(scopedCalls.cephOsd('n3', 13, 'in').path, '/nodes/n3/ceph/osd/13/in');
+  });
+  it('refuses flags, nodes, ids and actions outside the closed set', () => {
+    assert.throws(() => scopedCalls.cephSetFlag('pause' as never, true));
+    assert.throws(() => scopedCalls.cephOsd('../n2', 1, 'in'));
+    assert.throws(() => scopedCalls.cephOsd('n2', -1, 'out'));
+    assert.throws(() => scopedCalls.ctConfig('n2', 99));
+    assert.throws(() => scopedCalls.ctPower('n2', 100, 'destroy' as never));
+  });
+  it('ct config writes only the keys HFCTConfig covers, on the ct-config tier', () => {
+    const c = scopedCalls.ctSetConfig('n2', 100, { cores: 8, memory: 16384, onboot: true });
+    assert.deepEqual(c, {
+      tier: 'ct-config',
+      role: 'provision',
+      method: 'PUT',
+      path: '/nodes/n2/lxc/100/config',
+      form: { cores: '8', memory: '16384', onboot: '1' },
+    });
+    assert.throws(() => scopedCalls.ctSetConfig('n2', 100, { rootfs: 'x' } as never));
+    assert.throws(() => scopedCalls.ctSetConfig('n2', 100, {}));
+    assert.ok(!(CT_CONFIG_KEYS as readonly string[]).includes('rootfs'));
+  });
+});

package/src/proxmox/scoped-api.ts

@@ -0,0 +1,148 @@
+/**
+ * `pveScoped`: the agent helper for Ceph and container operations over the PVE API when SSH to a
+ * node is not available (2026-10-14, "PVE API path").
+ *
+ * ★ EVERY CALL MINTS A SCOPED TIER, NEVER `provision`. A call names its tier (`ceph-ops` or
+ *   `ct-config`); `scopedTarget` pins BOTH of the target's roles to that tier (credentials.ts's
+ *   "set both roles or neither"), so no read or write in it can fall back to the estate-wide tier.
+ *   In the estate those tiers are `proxmox-tb4/creds/{ceph-ops,ct-config}` → hf-ceph-ops@pve
+ *   (HFCephOps on `/`) and hf-ct-config@pve (HFCTConfig on `/vms`); the PVE ACL is the boundary.
+ * ★ A CLOSED SET OF OPERATIONS. Each builder returns a fixed method + path, with every path
+ *   segment validated, and `ctSetConfig` accepts only the keys HFCTConfig can change anyway.
+ *   No free-form path, so an agent cannot turn this into a general PVE client.
+ * ⛔ The minted secret never leaves `mint`/`pve()` (mint.ts's ⛔). Results are PVE's `data`.
+ * ⛔ Not a substitute for Alchemy: a change that should persist (a declared CT's cores, a Ceph
+ *   flag that a stack owns) still lands as a reviewed PR. This is the break-glass read/act path.
+ */
+import type * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/http/HttpClient';
+import type { PveCredentialDenied } from './credential-errors.ts';
+import { type PveForm, pve } from './client.ts';
+import type { PveRole, PveTarget } from './credentials.ts';
+
+export type ScopedTier = 'ceph-ops' | 'ct-config';
+
+export type ScopedCall = {
+  readonly tier: ScopedTier;
+  readonly role: PveRole;
+  readonly method: 'GET' | 'POST' | 'PUT';
+  readonly path: string;
+  readonly form?: PveForm;
+};
+
+/** The target with BOTH roles pinned to `tier`: nothing here can mint `read`/`provision`. */
+export const scopedTarget = (target: PveTarget, tier: ScopedTier): PveTarget => ({
+  ...target,
+  roles: { read: tier, provision: tier },
+});
+
+const NODE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const need = (ok: boolean, what: string) => {
+  if (!ok) throw new Error(`pveScoped: invalid ${what}`);
+};
+const node = (n: string) => (need(NODE.test(n), 'node name'), n);
+const vmid = (v: number) => (
+  need(Number.isInteger(v) && v >= 100 && v <= 999_999_999, 'vmid'),
+  String(v)
+);
+const osd = (o: number) => (
+  need(Number.isInteger(o) && o >= 0 && o < 100_000, 'osd id'),
+  String(o)
+);
+
+/** Flags an operator sets around maintenance. `pause`, `full` and friends are deliberately absent. */
+export const CEPH_FLAGS = [
+  'noout',
+  'norebalance',
+  'norecover',
+  'nobackfill',
+  'noscrub',
+  'nodeep-scrub',
+] as const;
+export type CephFlag = (typeof CEPH_FLAGS)[number];
+
+/** The CT config keys `ctSetConfig` may write: exactly what HFCTConfig's VM.Config.* privs cover. */
+export const CT_CONFIG_KEYS = [
+  'cores',
+  'cpulimit',
+  'memory',
+  'swap',
+  'onboot',
+  'description',
+  'tags',
+] as const;
+export type CtConfigPatch = Partial<
+  Record<(typeof CT_CONFIG_KEYS)[number], string | number | boolean>
+>;
+
+export const scopedCalls = {
+  cephStatus: (): ScopedCall => ({
+    tier: 'ceph-ops',
+    role: 'read',
+    method: 'GET',
+    path: '/cluster/ceph/status',
+  }),
+  cephFlags: (): ScopedCall => ({
+    tier: 'ceph-ops',
+    role: 'read',
+    method: 'GET',
+    path: '/cluster/ceph/flags',
+  }),
+  cephSetFlag: (flag: CephFlag, on: boolean): ScopedCall => {
+    need((CEPH_FLAGS as readonly string[]).includes(flag), 'ceph flag');
+    return {
+      tier: 'ceph-ops',
+      role: 'provision',
+      method: 'PUT',
+      path: `/cluster/ceph/flags/${flag}`,
+      form: { value: on ? '1' : '0' },
+    };
+  },
+  cephOsd: (n: string, id: number, to: 'in' | 'out'): ScopedCall => {
+    need(to === 'in' || to === 'out', 'osd direction');
+    return {
+      tier: 'ceph-ops',
+      role: 'provision',
+      method: 'POST',
+      path: `/nodes/${node(n)}/ceph/osd/${osd(id)}/${to}`,
+    };
+  },
+  ctConfig: (n: string, id: number): ScopedCall => ({
+    tier: 'ct-config',
+    role: 'read',
+    method: 'GET',
+    path: `/nodes/${node(n)}/lxc/${vmid(id)}/config`,
+  }),
+  ctSetConfig: (n: string, id: number, patch: CtConfigPatch): ScopedCall => {
+    const keys = Object.keys(patch);
+    need(keys.length > 0, 'empty config patch');
+    for (const k of keys)
+      need((CT_CONFIG_KEYS as readonly string[]).includes(k), `config key ${k}`);
+    const form: Record<string, string> = {};
+    for (const [k, v] of Object.entries(patch))
+      form[k] = typeof v === 'boolean' ? (v ? '1' : '0') : String(v);
+    return {
+      tier: 'ct-config',
+      role: 'provision',
+      method: 'PUT',
+      path: `/nodes/${node(n)}/lxc/${vmid(id)}/config`,
+      form,
+    };
+  },
+  ctPower: (n: string, id: number, action: 'start' | 'shutdown' | 'reboot'): ScopedCall => {
+    need(['start', 'shutdown', 'reboot'].includes(action), 'power action');
+    return {
+      tier: 'ct-config',
+      role: 'provision',
+      method: 'POST',
+      path: `/nodes/${node(n)}/lxc/${vmid(id)}/status/${action}`,
+    };
+  },
+} as const;
+
+/** Run one scoped call: mint its tier (only), call PVE, return `data`. */
+export const pveScoped = <T = unknown>(
+  target: PveTarget,
+  call: ScopedCall,
+): Effect.Effect<T | undefined, Error | PveCredentialDenied, HttpClient.HttpClient> =>
+  pve<T>(scopedTarget(target, call.tier), call.role, call.method, call.path, call.form);

package/src/talos/talosctl.test.ts

@@ -2,7 +2,7 @@
  * talosctl binary override. Fake spawner only — the named path is never executed (it only has to
  * exist and be a trusted file; the fake answers `version --client` with the pinned version).
  */
-import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterAll, expect, test } from 'bun:test';
@@ -26,6 +26,8 @@ trustBoundaryForTests(dir);
 const fixture = join(dir, 'talosctl');
 writeFileSync(fixture, '#!/bin/sh\n', { mode: 0o755 });
 chmodSync(fixture, 0o755);
+// macOS tmpdir is /var, a symlink to /private/var. The vetted command is the real path.
+const resolved = realpathSync(fixture);
 afterAll(() => rmSync(dir, { force: true, recursive: true }));
 
 const run = (binary: string | undefined, calls: FakeCall[]) =>
@@ -56,7 +58,7 @@ test('the binary option wins over HF_TALOSCTL', async () => {
   await withEnv('/definitely/not/here/talosctl', async () => {
     const calls: FakeCall[] = [];
     await run(fixture, calls);
-    expect(calls[0]?.command).toBe(fixture);
+    expect(calls[0]?.command).toBe(resolved);
   });
 });
 
@@ -64,7 +66,7 @@ test('HF_TALOSCTL selects the binary when the option is omitted', async () => {
   await withEnv(fixture, async () => {
     const calls: FakeCall[] = [];
     await run(undefined, calls);
-    expect(calls[0]?.command).toBe(fixture);
+    expect(calls[0]?.command).toBe(resolved);
   });
 });
 
@@ -84,7 +86,7 @@ test('the default talosctl is resolved on PATH, vetted and version-checked by ab
     withPath(dir, async () => {
       const calls: FakeCall[] = [];
       await run(undefined, calls);
-      expect(calls.map((call) => call.command)).toEqual([fixture, fixture]);
+      expect(calls.map((call) => call.command)).toEqual([resolved, resolved]);
     }),
   );
 });