@homeflare/alchemy 0.54.0 → 0.55.0

package/src/ceph/ceph-config-options.test.ts

@@ -1,19 +1,32 @@
 /**
  * Structural guard on the named config-option list itself (mon-transport doc acceptance test #3):
- * the list contains none of the lockout classes, and it starts empty (D-C1).
+ * the list contains none of the lockout classes, and each entry is one reviewed line (D-C1).
  */
 import { describe, expect, test } from 'bun:test';
-import { NAMED_CONFIG_OPTIONS, isLockoutConfigOption } from './ceph-config-options.ts';
+import {
+  NAMED_CONFIG_OPTIONS,
+  allowedWhoFor,
+  isLockoutConfigOption,
+} from './ceph-config-options.ts';
 
 describe('NAMED_CONFIG_OPTIONS', () => {
-  test('starts empty', () => {
-    expect(NAMED_CONFIG_OPTIONS.size).toBe(0);
+  test('the first reviewed entry is the mgr prometheus perf-counter switch, for mgr only', () => {
+    expect(NAMED_CONFIG_OPTIONS.get('mgr/prometheus/exclude_perf_counters')).toEqual(['mgr']);
+    expect(allowedWhoFor('mgr/prometheus/exclude_perf_counters')).toEqual(['mgr']);
+    expect(allowedWhoFor('mon_allow_pool_delete')).toEqual([]);
   });
 
   test('contains none of the lockout classes, whatever gets added later', () => {
-    const bad = [...NAMED_CONFIG_OPTIONS].filter((name) => isLockoutConfigOption(name));
+    const bad = [...NAMED_CONFIG_OPTIONS.keys()].filter((name) => isLockoutConfigOption(name));
     expect(bad).toEqual([]);
   });
+
+  test('every entry names at least one bounded <who>', () => {
+    for (const [name, whos] of NAMED_CONFIG_OPTIONS) {
+      expect([name, whos.length > 0]).toEqual([name, true]);
+      for (const who of whos) expect(who).toMatch(/^(global|mon|osd|mgr|mds|client)(\.[\w-]+)?$/);
+    }
+  });
 });
 
 describe('isLockoutConfigOption', () => {
@@ -31,14 +44,18 @@ describe('isLockoutConfigOption', () => {
     'keyring_path',
     'key',
     'mon_data_key',
+    'mgr/dashboard/key',
+    'mgr/restful/keyring',
   ])('flags %s', (name) => {
     expect(isLockoutConfigOption(name)).toBe(true);
   });
 
-  test.each(['mon_allow_pool_delete', 'osd_pool_default_size', 'mon_max_pg_per_osd'])(
-    'does not flag an ordinary tuning option like %s',
-    (name) => {
-      expect(isLockoutConfigOption(name)).toBe(false);
-    },
-  );
+  test.each([
+    'mgr/prometheus/exclude_perf_counters',
+    'mon_allow_pool_delete',
+    'osd_pool_default_size',
+    'mon_max_pg_per_osd',
+  ])('does not flag an ordinary tuning option like %s', (name) => {
+    expect(isLockoutConfigOption(name)).toBe(false);
+  });
 });

package/src/ceph/ceph-config-options.ts

@@ -3,10 +3,14 @@
  * through the mon-command transport (ceph-argv.ts's `configProblem`). Design:
  * docs/plans/2026-09-26-ceph-config-options.md, D-C1.
  *
- * ⛔ THE LIST STARTS EMPTY, AND EACH ADDITION IS ITS OWN REVIEWED PR LINE. Nothing in K-A4 adds to
- *   it — `CephConfigOption` (K-D) is a separate, later family; this file exists now only so the
- *   transport's allowlist has something to bound `config` against from day one, per the accepted
- *   design ("config get/set for the named option list which starts EMPTY").
+ * ⛔ THE LIST STARTED EMPTY, AND EACH ADDITION IS ITS OWN REVIEWED PR LINE. `Ceph.ConfigOption`
+ *   (K-D, config-option.ts) is the only declarer; it refuses any `{who, name}` this map does not
+ *   carry before planning, and the transport's allowlist (ceph-argv-config.ts) refuses it again
+ *   before anything dials. One entry per line, each with a comment saying what it does and why it
+ *   is managed — never a batch.
+ * ★ EACH ENTRY ALSO NAMES THE `<who>` IT MAY BE SET FOR. This is the config-options design's
+ *   acceptance test #1 ("`<who>` bounded to the declared daemons"): an option listed for `mgr`
+ *   can never be written to `global`, `client.admin` or any other section through this transport.
  * ⛔ NEVER ADD ONE OF THE LOCKOUT CLASSES BELOW. `mon_host`, `public_network`, `cluster_network`,
  *   `public_addr`, `cluster_addr`, every `auth_*_required` and every `key`/`keyring`-bearing
  *   option re-address the mons or de-authenticate the whole cluster — cutting every VM disk — and
@@ -17,8 +21,22 @@
  *   never a `ceph config set` argv, which lands in the runner's log and the node's sudo journal.
  */
 
-/** Starts empty. Add one reviewed option name per PR line, never a batch. */
-export const NAMED_CONFIG_OPTIONS: ReadonlySet<string> = new Set([]);
+/**
+ * option name -> the `<who>` sections it may be set for. Add one reviewed line per PR, never a
+ * batch; the structural test (ceph-config-options.test.ts) runs the lockout guard over every key.
+ */
+export const NAMED_CONFIG_OPTIONS: ReadonlyMap<string, readonly string[]> = new Map<
+  string,
+  readonly string[]
+>([
+  // mgr prometheus module: `false` makes it export per-daemon perf counters (ceph_osd_op_*,
+  // ceph_rgw_* …) instead of omitting them. Set live 2026-10, codified here so plan reconciles it.
+  ['mgr/prometheus/exclude_perf_counters', ['mgr']],
+]);
+
+/** The `<who>` sections `name` may be set for — empty when the option is not on the list. */
+export const allowedWhoFor = (name: string): readonly string[] =>
+  NAMED_CONFIG_OPTIONS.get(name) ?? [];
 
 const LOCKOUT_EXACT: ReadonlySet<string> = new Set([
   'mon_host',
@@ -28,8 +46,11 @@ const LOCKOUT_EXACT: ReadonlySet<string> = new Set([
   'cluster_addr',
 ]);
 
-/** `auth_*_required` (cephx enforcement) and anything key/keyring-shaped, either side of `_`. */
-const LOCKOUT_PATTERN = /^auth_\w*_required$|(^|_)key(ring)?($|_)/;
+/**
+ * `auth_*_required` (cephx enforcement) and anything key/keyring-shaped, bounded by `_` or by the
+ * `/` that separates an mgr module option (`mgr/<module>/<option>`) — so `mgr/x/key` is caught too.
+ */
+const LOCKOUT_PATTERN = /^auth_\w*_required$|(^|[_/])key(ring)?($|[_/])/;
 
 /** Whether `name` is a class this transport must never read a value for, adopt, or write. */
 export const isLockoutConfigOption = (name: string): boolean =>

package/src/ceph/config-option.ts

@@ -0,0 +1,112 @@
+/**
+ * `Ceph.ConfigOption` (K-D) — one `{who, name} = value` row of the Ceph mon config db, declared.
+ * Design: docs/plans/2026-09-26-ceph-config-options.md. Pure helpers: ceph-config-option-form.ts;
+ * the loop: ceph-config-option-reconcile.ts; the allowlist: ceph-argv-config.ts.
+ *
+ * ★ ONE RESOURCE PER OPTION, AND ONLY OPTIONS ON THE NAMED LIST. `NAMED_CONFIG_OPTIONS`
+ *   (ceph-config-options.ts) is the gate: each entry is its own reviewed PR line and names the
+ *   `<who>` it may be set for. Anything else is refused at `diff` (so the plan fails loudly) and
+ *   again by the transport before anything dials.
+ * ★ PLAN READS OVER THE PVE API, NEVER SSH. `read`/`diff` call `GET /nodes/{node}/ceph/cfg/db`
+ *   (read lease only — "a plan never elevates"). Only `reconcile`/`delete` reach ssh, through
+ *   ceph-transport.ts — the existing mon-command transport `Ceph.AuthEntity` uses, not a new one.
+ * ★ ADOPTION OF AN ALREADY-SET OPTION IS A ZERO-WRITE NO-OP. A cold `read` of a live row answers
+ *   `Unowned(attrs)` (the house rule for a marker-less API, H1), so a live option needs
+ *   `adopt(true)` on its row; `reconcile` then observes the matching value and writes nothing.
+ *   ⛔ Fix-live-then-codify is fine for this family exactly because of that: the plan proves it.
+ * ⚠️ PRECONDITION BEFORE DECLARING THE WHOLE CONFIG DB: the dead `public_addr` entries
+ *   (homeflare-proxmox docs/completeness-tb4-sdn-ceph.md, T3) must be removed by hand with
+ *   `ceph config rm` first, so fossils are never adopted. `public_addr` is a lockout class and can
+ *   never be declared here; a single named option (like the first one) is not blocked by it.
+ * ⚠️ THE COMPARED VALUE IS THE MON DB's, not the effective one: a ceph.conf override or a compiled
+ *   default is out of scope (CephConf is its own family).
+ * ⚠️ `defaultRemovalPolicy: 'retain'`: removing a row stops managing it; `config rm` runs only when
+ *   a removal policy of `destroy` is chosen deliberately for that row.
+ */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { mintTier } from '../proxmox/credentials.ts';
+import { runPve } from '../proxmox/distilled-pve.ts';
+import type { PveRequirements } from '../proxmox/resource-spec.ts';
+import { UNREADABLE, readOrUnreadable, unreadableWarning } from '../proxmox/unreadable-read.ts';
+import {
+  type CephConfigOptionAttributes,
+  type CephConfigOptionProps,
+  configOptionProblem,
+  findLive,
+  matches,
+} from './ceph-config-option-form.ts';
+import {
+  deleteCephConfigOption,
+  reconcileCephConfigOption,
+} from './ceph-config-option-reconcile.ts';
+
+export type {
+  CephConfigOptionAttributes,
+  CephConfigOptionProps,
+} from './ceph-config-option-form.ts';
+
+export interface CephConfigOption extends Resource<
+  'Ceph.ConfigOption',
+  CephConfigOptionProps,
+  CephConfigOptionAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const CephConfigOption = Resource<CephConfigOption>('Ceph.ConfigOption', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** The whole mon config db, over the PVE API, on a read lease. */
+const readRows = (props: Pick<CephConfigOptionProps, 'target' | 'node'>) =>
+  runPve(props.target, 'read', false, nodes.listNodeCephCfgDb({ node: props.node }));
+
+const refuse = (props: CephConfigOptionProps) => {
+  const problem = configOptionProblem(props);
+  return problem === undefined ? Effect.void : Effect.fail(new Error(problem));
+};
+
+export const CephConfigOptionProvider = () =>
+  Provider.effect(
+    CephConfigOption,
+    Effect.succeed(
+      CephConfigOption.Provider.of({
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds, output }) {
+          const live = findLive(yield* readRows(olds), olds.who, olds.name);
+          if (live === undefined) return undefined;
+          return output !== undefined ? live : Unowned(live);
+        }),
+
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* refuse(news);
+          if (output === undefined) return undefined;
+          if (output.who !== news.who || output.name !== news.name)
+            return { action: 'replace' } as const;
+          const rows = yield* readOrUnreadable(readRows(news));
+          if (rows === UNREADABLE) {
+            yield* unreadableWarning(
+              'Ceph.ConfigOption',
+              `${news.who}/${news.name}`,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
+            return { action: 'noop' } as const;
+          }
+          const live = findLive(rows, news.who, news.name);
+          return { action: matches(live, news) ? 'noop' : 'update' } as const;
+        }),
+
+        reconcile: ({ news }) => reconcileCephConfigOption(news, readRows(news), {}),
+
+        delete: ({ olds }) => deleteCephConfigOption(olds, readRows(olds), {}),
+      }),
+    ),
+  );

package/src/ceph/index.ts

@@ -1,12 +1,16 @@
 /**
- * Ceph providers for Alchemy — the mon-command transport and `Ceph.AuthEntity` (K-A4).
+ * Ceph providers for Alchemy — the mon-command transport, `Ceph.AuthEntity` (K-A4) and
+ * `Ceph.ConfigOption` (K-D).
  *
  * ⛔ THIS BARREL IS THE PUBLIC API, DELIBERATELY SMALLER THAN THE DIRECTORY — see
  *   `../openbao/index.ts`'s header for why. The allowlist internals (ceph-argv.ts), the parsing
- *   (ceph-auth-parse.ts) and the reconcile loop (ceph-auth-reconcile.ts) are exported by path for
- *   a future `CephConfigOption` (K-D) or a test to reach directly, not published here.
+ *   (ceph-auth-parse.ts) and the reconcile loops (ceph-auth-reconcile.ts,
+ *   ceph-config-option-reconcile.ts) are reached by path from tests, not published here.
  */
 export type { CephAuthEntityAttributes, CephAuthEntityProps, CephCaps } from './auth-entity.ts';
 export { CephAuthEntity, CephAuthEntityProvider } from './auth-entity.ts';
 export type { CephDial, CephExecResult, CephTransportOptions } from './ceph-transport.ts';
 export { assertFreshQuorum, runCephCommand, sshCephDial } from './ceph-transport.ts';
+export type { CephConfigOptionAttributes, CephConfigOptionProps } from './config-option.ts';
+export { CephConfigOption, CephConfigOptionProvider } from './config-option.ts';
+export { NAMED_CONFIG_OPTIONS } from './ceph-config-options.ts';

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

@@ -0,0 +1,92 @@
+/**
+ * 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 { SUDO } from './sudo-allowlist.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);
+  });
+});

package/src/linux/sudo-runner.ts

@@ -44,6 +44,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 +60,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 +101,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. */
@@ -103,7 +135,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)
@@ -157,6 +209,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/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);