@homeflare/alchemy 0.53.1 → 0.55.0

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);