@homeflare/alchemy 0.38.0 → 0.40.0

package/src/proxmox/storage-download.test.ts

@@ -0,0 +1,216 @@
+/**
+ * `Proxmox.StorageDownload` engine tests over a stub fetch. No live host, no live cluster.
+ * ⚠️ The exact `import/` volid segment is REASONED, not measured — see storage-download-props.ts.
+ *   These fixtures spell it that way for readability only; `readDownload` matches by filename
+ *   suffix, so the tests below would pass with any segment spelling PVE actually uses.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, type FakePve, fakePve, withoutBao } from './fake-pve.ts';
+import type { StorageDownloadProps } from './storage-download-props.ts';
+import { ProxmoxStorageDownload, ProxmoxStorageDownloadProvider } from './storage-download.ts';
+
+const NODE = 'pve1';
+const STORAGE = 'cephfs-tb4';
+const FILENAME = 'talos-v1.13.0-metal-amd64.qcow2';
+const UPID = `UPID:${NODE}:00000002:0:0:imgdownload:${STORAGE}:test@pve!fake:`;
+const row = (over: Partial<Record<string, unknown>> = {}) => ({
+  format: 'qcow2',
+  size: 123_456,
+  volid: `${STORAGE}:import/${FILENAME}`,
+  ...over,
+});
+
+const declare = (over: Partial<StorageDownloadProps> = {}): StorageDownloadProps => ({
+  checksum: 'a'.repeat(64),
+  checksumAlgorithm: 'sha256',
+  filename: FILENAME,
+  node: NODE,
+  storage: STORAGE,
+  target: FAKE_TARGET,
+  url: 'https://images.example.test/talos.qcow2',
+  ...over,
+});
+
+const engine = (fake: FakePve) =>
+  engineOver(ProxmoxStorageDownloadProvider().pipe(Layer.provideMerge(fake.layer)));
+
+const isTaskStatus = (call: { method: string; path: string }) =>
+  call.path.includes('/tasks/') && call.path.endsWith('/status');
+const isList = (call: { method: string; path: string }) =>
+  call.method === 'GET' && call.path.includes('/content?');
+const isDownload = (call: { method: string; path: string }) =>
+  call.method === 'POST' && call.path.endsWith('/download-url');
+
+describe('creating a download', () => {
+  test('one POST to download-url, a task wait, then the next plan is noop', async () => {
+    let downloaded = false;
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return downloaded ? [row()] : [];
+      if (isDownload(call)) {
+        downloaded = true;
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      expect(await stack.deploy(ProxmoxStorageDownload('image', declare()))).toEqual({
+        image: 'create',
+      });
+      expect(
+        (await stack.verify(ProxmoxStorageDownload('image', declare()), { all: true })).rows[0],
+      ).toMatchObject({ diff: 'noop' });
+    });
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/storage/${STORAGE}/download-url`]);
+    const posted = fake.calls.find((call) => call.method === 'POST')?.form;
+    expect(posted?.['checksum']).toBe('a'.repeat(64));
+    expect(posted?.['checksum-algorithm']).toBe('sha256');
+    expect(posted?.['content']).toBe('import');
+    expect(fake.calls.some((call) => call.path.includes('/tasks/'))).toBe(true);
+  });
+
+  test('⛔ checksum is required: an empty one is refused before any write ("checksum-pinned")', async () => {
+    const fake = fakePve((call) => (isList(call) ? [] : null));
+    await withoutBao(async () => {
+      await expect(
+        engine(fake).deploy(ProxmoxStorageDownload('image', declare({ checksum: '  ' }))),
+      ).rejects.toThrow(/checksum is required/);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('a failed download task refuses the plan — the checksum-mismatch refusal', async () => {
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { exitstatus: 'checksum mismatch', status: 'stopped' };
+      if (isList(call)) return [];
+      if (isDownload(call)) return UPID;
+      return null;
+    });
+    await withoutBao(async () => {
+      await expect(engine(fake).deploy(ProxmoxStorageDownload('image', declare()))).rejects.toThrow(
+        /checksum mismatch/,
+      );
+    });
+  });
+});
+
+describe('removing a download', () => {
+  test('not retain by default: dropping the declaration deletes the file and waits for its task', async () => {
+    let exists = false;
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return exists ? [row()] : [];
+      if (isDownload(call)) {
+        exists = true;
+        return UPID;
+      }
+      if (call.method === 'DELETE') {
+        exists = false;
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxStorageDownload('image', declare()));
+      await stack.deploy(Effect.void);
+    });
+    expect(fake.writes()).toHaveLength(2);
+    expect(fake.writes()[0]).toBe(`POST nodes/${NODE}/storage/${STORAGE}/download-url`);
+    expect(fake.writes()[1]).toMatch(
+      new RegExp(`^DELETE nodes/${NODE}/storage/${STORAGE}/content/`),
+    );
+  });
+
+  test('⛔ idempotent delete: a volume already gone by removal time sends no DELETE', async () => {
+    let created = false;
+    let vanished = false;
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return created && !vanished ? [row()] : [];
+      if (isDownload(call)) {
+        created = true;
+        return UPID;
+      }
+      return null; // a DELETE here would fail the test below by never answering it
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxStorageDownload('image', declare()));
+      vanished = true; // out-of-band: something else already removed the file
+      await stack.deploy(Effect.void);
+    });
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/storage/${STORAGE}/download-url`]);
+  });
+});
+
+describe('identity (red-team I1/I2 on PR 297)', () => {
+  test('a changed filename replaces: the old file is deleted, the new one downloaded', async () => {
+    const NEW_FILENAME = 'talos-v1.14.0-metal-amd64.qcow2';
+    // ⚠️ ALCHEMY REPLACES CREATE-FIRST (acl.test.ts's own note): the new file exists alongside the
+    //   old one for a moment, so the fixture tracks a SET of files, not one current name.
+    const files = new Set<string>();
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return [...files].map((f) => row({ volid: `${STORAGE}:import/${f}` }));
+      if (isDownload(call)) {
+        files.add(call.form['filename'] ?? '');
+        return UPID;
+      }
+      if (call.method === 'DELETE') {
+        // ⚠️ The volid path segment may arrive percent-encoded (its own `:` and `/`) — match by
+        //   decoded suffix, the same way readDownload matches a listed row (storage-download-props.ts).
+        const decoded = decodeURIComponent(call.path);
+        const gone = [...files].find((f) => decoded.endsWith(f));
+        if (gone !== undefined) files.delete(gone);
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxStorageDownload('image', declare()));
+      expect(
+        await stack.deploy(ProxmoxStorageDownload('image', declare({ filename: NEW_FILENAME }))),
+      ).toEqual({ image: 'replace' });
+    });
+    const [download1, download2] = fake.writes().filter((w) => w.includes('download-url'));
+    expect(download1).toBeDefined();
+    expect(download2).toBeDefined();
+    expect(fake.writes().some((w) => w.startsWith('DELETE') && w.endsWith(FILENAME))).toBe(true);
+    expect(files).toEqual(new Set([NEW_FILENAME]));
+  });
+
+  test('a changed checksum on the same filename is refused, never silently planned noop', async () => {
+    let downloaded = false;
+    const fake = fakePve((call) => {
+      if (isTaskStatus(call)) return { status: 'stopped', exitstatus: 'OK' };
+      if (isList(call)) return downloaded ? [row()] : [];
+      if (isDownload(call)) {
+        downloaded = true;
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxStorageDownload('image', declare()));
+      await expect(
+        stack.deploy(ProxmoxStorageDownload('image', declare({ checksum: 'b'.repeat(64) }))),
+      ).rejects.toThrow(/checksum changed but filename did not/);
+    });
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/storage/${STORAGE}/download-url`]);
+  });
+});
+
+describe('no secret prop', () => {
+  test('every declared field is a public identity or download parameter, never a credential', () => {
+    for (const key of Object.keys(declare())) {
+      expect(key).not.toMatch(/pass|secret|token|key$|credential/i);
+    }
+  });
+});

package/src/proxmox/storage-download.ts

@@ -0,0 +1,58 @@
+/**
+ * `Proxmox.StorageDownload` — one `download-url` fetch of an image onto a named storage's
+ * `import` content, declared. Joined 2026-09-26 for Talos: a node needs a boot image on shared
+ * storage (`cephtb4`/`cephfs-tb4`) before `Proxmox.Vm` can reference it as a disk source.
+ *
+ * ★ A CREATE-ORIENTED FAMILY, NOT A GENERAL DOWNLOADER. `content` is fixed to `import` — never a
+ *   prop — because that is the one content type a VM disk import consumes; an ISO or a container
+ *   template already has its own path (`upload`, or an out-of-band copy) and does not belong here.
+ *
+ * ⛔ `checksum` AND `checksumAlgorithm` ARE REQUIRED, NOT OPTIONAL, EVEN THOUGH PVE'S OWN SCHEMA
+ *   MARKS BOTH OPTIONAL (`generated/pve/nodes-node-storage-storage.ts`). An unpinned download is
+ *   not a declaration — it is a promise that whatever the URL answers today is what a Talos node
+ *   boots from, silently, on every future adopt. This resource narrows the vendor's own contract
+ *   on purpose; `storage-download-lifecycle.ts`'s `createRefusals` is the runtime backstop for a
+ *   caller that casts around the type.
+ *
+ * ⛔ THERE IS NO UPDATE PATH. PVE does not remember the `url` or `checksum` a volume was created
+ *   from — `GET .../content` reports only `format`/`size`/`volid` — so once the file exists on
+ *   `storage`, this resource has nothing left to compare a new declaration against except the
+ *   PREVIOUS one (storage-download-identity.ts). A DIFFERENT `checksum`/`url` on the SAME `filename`
+ *   is REFUSED, never silently written or silently `noop` (2026-09-26, red-team I2 on PR 297):
+ *   change `filename` to force a new download, which plans a `replace` — the old file is deleted and
+ *   the new one downloaded under its own name — exactly as an immutable artifact should be.
+ *
+ * ⛔ NO SECRET IS A PROP. Every field here — `node`, `storage`, `filename`, `url`, the checksum
+ *   pair, `compression`, `verifyCertificates` — is either an identity or a public download
+ *   parameter; none is a credential, matching the "no secret prop" rule every PVE family here
+ *   carries (see qemu-props.ts's `cipassword`/`machine` for the family that has one to guard).
+ *
+ * ★ NOT `retain` BY DEFAULT, UNLIKE `Proxmox.Vm`/`Proxmox.Lxc`. A downloaded image is reproducible
+ *   from its own declaration (the same `url` and `checksum` rebuild it byte-for-byte); a VM's
+ *   disk state or a container's data is not. Dropping this declaration deletes the file — an
+ *   operator who wants to keep an unreferenced image around pins its own `RemovalPolicy.retain()`.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { PveRequirements } from './resource.ts';
+import { storageDownloadHandlers } from './storage-download-lifecycle.ts';
+import type { StorageDownloadAttributes, StorageDownloadProps } from './storage-download-props.ts';
+
+export type { StorageDownloadAttributes, StorageDownloadProps } from './storage-download-props.ts';
+
+export interface ProxmoxStorageDownload extends Resource<
+  'Proxmox.StorageDownload',
+  StorageDownloadProps,
+  StorageDownloadAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxStorageDownload = Resource<ProxmoxStorageDownload>('Proxmox.StorageDownload');
+
+export const ProxmoxStorageDownloadProvider = () =>
+  Provider.effect(
+    ProxmoxStorageDownload,
+    Effect.succeed(ProxmoxStorageDownload.Provider.of(storageDownloadHandlers)),
+  );

package/src/talos/credentials-write.test.ts

@@ -0,0 +1,81 @@
+/**
+ * `credentials-write.ts` — offline, fake `bao`, no real process ever spawns. Fixtures only.
+ */
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import { reservedTempPath, writeKvValue } from './credentials-write.ts';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+
+const run = <A, E>(
+  effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
+  handler: (c: FakeCall) => { stdout?: string; stderr?: string; exitCode?: number },
+  calls: FakeCall[] = [],
+) =>
+  Effect.runPromise(
+    Effect.provideService(
+      effect,
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(handler, calls),
+    ),
+  );
+
+describe('writeKvValue', () => {
+  it('sends the value on stdin, never in argv', async () => {
+    const calls: FakeCall[] = [];
+    await run(
+      writeKvValue('talos-c1', 'kubeconfig', 'kubeconfig', 'super-secret-kubeconfig-body'),
+      () => ({}),
+      calls,
+    );
+    assert.equal(calls.length, 1);
+    // ⛔ C2 (LAND red team): `=-`, never `=@-` — `@` means "read a file at this literal path",
+    // which OpenBao's own CLI rejects (or, worse, silently reads a file named `-` if one exists).
+    assert.deepEqual(calls[0]?.args, ['kv', 'put', 'talos-c1/kubeconfig', 'kubeconfig=-']);
+    assert.equal(calls[0]?.stdin, 'super-secret-kubeconfig-body');
+    // ⛔ THE POINT OF THE TEST: the value appears nowhere in argv.
+    assert.ok(!calls[0]?.args.some((arg) => arg.includes('super-secret-kubeconfig-body')));
+  });
+
+  it('fails on a non-zero exit and never echoes stdin in the error', async () => {
+    await assert.rejects(
+      run(writeKvValue('talos-c1', 'kubeconfig', 'kubeconfig', 'secret-body'), () => ({
+        exitCode: 2,
+        stderr: 'permission denied',
+      })),
+      (error: unknown) =>
+        error instanceof Error &&
+        error.message.includes('permission denied') &&
+        !error.message.includes('secret-body'),
+    );
+  });
+});
+
+describe('reservedTempPath', () => {
+  it('does not pre-create the file, and cleans up if something else wrote there', async () => {
+    let path = '';
+    await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const reserved = yield* reservedTempPath('c1-node-kubeconfig-out');
+          path = reserved.path;
+          assert.equal(existsSync(path), false, 'nothing has written here yet');
+          yield* Effect.promise(() =>
+            Bun.write(path, 'written by the caller, like talosctl would'),
+          );
+          assert.ok(existsSync(path));
+        }),
+      ),
+    );
+    assert.equal(existsSync(path), false, 'must be gone once the caller scope closed');
+  });
+
+  it('two calls never collide on the same path', async () => {
+    const [a, b] = await Effect.runPromise(
+      Effect.scoped(Effect.all([reservedTempPath('same-label'), reservedTempPath('same-label')])),
+    );
+    assert.notEqual(a.path, b.path);
+  });
+});

package/src/talos/credentials-write.ts

@@ -0,0 +1,95 @@
+/**
+ * The write half of Talos's OpenBao KV access — split out of credentials.ts (2026-09-26,
+ * K-talos-first-boot) once it needed its own header, the same reason machine-config-read.ts,
+ * machine-config-poll.ts and talos-errors.ts were split out of talos-machine-config.ts before it.
+ * `credentials.ts` stays the read side (mint a talosconfig, read a KV value); this file is the one
+ * place anything in this package ever writes TO OpenBao.
+ *
+ * ★ FIRST CALLER: `Talos.Kubeconfig` (kubeconfig.ts) writing the admin kubeconfig it generates at
+ *   cluster bring-up into the vault instead of an un-vaulted host `runtimePath` — see that file's
+ *   own header. `Ceph.AuthEntity` (K-A4, a separate design/PR) is expected to need the same shape
+ *   for its own vault-written entity keys; this is not yet shared with it on purpose — two callers
+ *   is the point at which sharing stops being speculative.
+ */
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
+import * as Stream from 'effect/Stream';
+import * as ChildProcess from 'effect/unstable/process/ChildProcess';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+
+/**
+ * A fresh, unguessable temp path for SOME OTHER PROCESS (talosctl) to create — unlike
+ * `credentials.ts`'s `mintKvTempFile`, this does NOT pre-create the file with `wx`, because the
+ * caller here is capturing a command's OWN output rather than writing known content itself. The
+ * random UUIDv7 name is the only pre-fabrication guard (an attacker cannot pre-plant a symlink at a
+ * path it cannot predict) — first used by `kubeconfig.ts` to capture `talosctl kubeconfig`'s
+ * generated file before reading it back and writing it into the vault.
+ */
+export const reservedTempPath = (
+  label: string,
+): Effect.Effect<{ readonly path: string }, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const path = `${Bun.env['TMPDIR'] ?? '/tmp'}/hf-talos-${label}-${Bun.randomUUIDv7()}.yaml`;
+    yield* Effect.addFinalizer(() =>
+      Effect.tryPromise({ try: () => Bun.file(path).delete(), catch: () => undefined }).pipe(
+        Effect.orElseSucceed(() => undefined),
+      ),
+    );
+    return { path };
+  });
+
+/**
+ * Write one field of an OpenBao KV-v2 value from `value` — never argv, the mirror image of
+ * `credentials.ts`'s `readKvValue`.
+ *
+ * ⛔ C2 FIX (LAND red team, 2026-09-26) — `field=@-` IS WRONG AND WAS NEVER MEASURED. `@value` means
+ *   "read a file at this path"; a literal path of `-` is not the stdin convention for `@` — it is
+ *   just a file named `-`. MEASURED against the estate's OpenBao v2.6.2 binary (isolated in-memory
+ *   dev server, `env -i`, scratch HOME, no estate credentials involved; server removed after):
+ *   `field=@-` exits 1 with `invalid key/value pair "field=@-": error reading file: open -: no
+ *   such file or directory`, and if a file literally named `-` exists in the working directory it
+ *   silently stores THAT file's bytes instead. `field=-` (no `@`) is Vault/OpenBao's own stdin
+ *   convention and was confirmed against the same binary to read the piped bytes correctly. Every
+ *   `Talos.Kubeconfig` create failed here — AFTER `talosctl kubeconfig` had already issued a fresh
+ *   admin client certificate, which cannot be revoked.
+ * ⛔ stderr ONLY ON FAILURE — same rule as `readKvValue`: never echo what was being written, on
+ *   success or failure.
+ */
+export const writeKvValue = (
+  mount: string,
+  key: string,
+  field: string,
+  value: string,
+): Effect.Effect<void, Error, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const result = yield* ChildProcess.make('bao', ['kv', 'put', `${mount}/${key}`, `${field}=-`], {
+      detached: false,
+      extendEnv: true,
+      stderr: 'pipe',
+      stdin: Stream.fromIterable([new TextEncoder().encode(value)]),
+      stdout: 'pipe',
+    }).pipe(
+      spawner.spawn,
+      Effect.flatMap((child) =>
+        Effect.all(
+          {
+            exitCode: child.exitCode,
+            stderr: child.stderr.pipe(
+              Stream.decodeText,
+              Stream.mkString,
+              Effect.map((text) => text.trim()),
+            ),
+          },
+          { concurrency: 'unbounded' },
+        ),
+      ),
+      Effect.scoped,
+    );
+
+    if (result.exitCode !== 0) {
+      return yield* Effect.fail(
+        new Error(`bao kv put ${mount}/${key} exited ${String(result.exitCode)}: ${result.stderr}`),
+      );
+    }
+  });

package/src/talos/credentials.test.ts

@@ -0,0 +1,157 @@
+/**
+ * The C1 lifetime fix — pins that `mintTalosconfig`'s temp file survives until the CALLER's own
+ * `Effect.scoped` closes, not until `mintTalosconfig` itself returns (the shipped defect,
+ * credentials.ts's own header). Fully offline: fake-process.ts fakes `bao`, nothing real spawns.
+ *
+ * ⚠️ FIXTURES ONLY. No real OpenBao, no real talosconfig material — every "talosconfig" body
+ *   below is a plain marker string, not YAML that could be mistaken for the real shape.
+ */
+import assert from 'node:assert/strict';
+import { existsSync, statSync } from 'node:fs';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import { mintKubeconfig, mintKvTempFile, mintTalosconfig, readKvValue } from './credentials.ts';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+
+const bao =
+  (data: Record<string, unknown>, exitCode = 0) =>
+  (call: FakeCall) => {
+    assert.equal(call.command, 'bao');
+    return exitCode === 0
+      ? { stdout: JSON.stringify({ data: { data } }) }
+      : { exitCode, stderr: 'permission denied' };
+  };
+
+const run = <A, E>(
+  effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
+  handler: (c: FakeCall) => ReturnType<ReturnType<typeof bao>>,
+  calls: FakeCall[] = [],
+) =>
+  Effect.runPromise(
+    Effect.provideService(
+      effect,
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(handler, calls),
+    ),
+  );
+
+describe('mintTalosconfig — C1 lifetime fix', () => {
+  it('reads talosconfig/<mount> — the FIXED default key, not the doubled data/data path', async () => {
+    const calls: FakeCall[] = [];
+    let capturedPath = '';
+    await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const credential = yield* mintTalosconfig({ cluster: 'c1', mount: 'talos-c1' });
+          capturedPath = credential.talosconfigPath;
+          assert.ok(existsSync(capturedPath), 'file must exist while the caller scope is open');
+        }),
+      ).pipe(
+        Effect.provideService(
+          ChildProcessSpawner.ChildProcessSpawner,
+          fakeSpawner(bao({ talosconfig: 'fake-talosconfig-body' }), calls),
+        ),
+      ),
+    );
+    assert.equal(calls.length, 1);
+    assert.deepEqual(calls[0]?.args, ['kv', 'get', '-format=json', 'talos-c1/talosconfig']);
+    assert.equal(existsSync(capturedPath), false, 'must be gone once the caller scope closed');
+  });
+
+  it('is gone even when the caller scope is closed by a later failure (finalizers always run)', async () => {
+    let capturedPath = '';
+    const failing = Effect.scoped(
+      Effect.gen(function* () {
+        const credential = yield* mintTalosconfig({ cluster: 'c1', mount: 'talos-c1' });
+        capturedPath = credential.talosconfigPath;
+        return yield* Effect.fail(new Error('downstream talosctl call failed'));
+      }),
+    ).pipe(
+      Effect.provideService(
+        ChildProcessSpawner.ChildProcessSpawner,
+        fakeSpawner(bao({ talosconfig: 'fake-body' })),
+      ),
+    );
+    await assert.rejects(Effect.runPromise(failing));
+    assert.equal(existsSync(capturedPath), false);
+  });
+
+  it('honors a custom talosconfigKey without adding a data/ prefix', async () => {
+    const calls: FakeCall[] = [];
+    await run(
+      Effect.scoped(
+        mintTalosconfig({ cluster: 'c1', mount: 'talos-c1', talosconfigKey: 'context/admin' }),
+      ),
+      bao({ config: 'fallback-field-body' }),
+      calls,
+    );
+    assert.deepEqual(calls[0]?.args, ['kv', 'get', '-format=json', 'talos-c1/context/admin']);
+  });
+
+  it('fails without spawning talosctl or leaving a file when bao denies the read', async () => {
+    await assert.rejects(
+      run(Effect.scoped(mintTalosconfig({ cluster: 'c1', mount: 'talos-c1' })), bao({}, 1)),
+    );
+  });
+
+  it('fails when the KV entry has neither a talosconfig nor a config field', async () => {
+    await assert.rejects(
+      run(
+        Effect.scoped(mintTalosconfig({ cluster: 'c1', mount: 'talos-c1' })),
+        bao({ unrelated: 'x' }),
+      ),
+    );
+  });
+});
+
+describe('mintKvTempFile', () => {
+  it('writes exactly the given content at mode 0600', async () => {
+    let path = '';
+    await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const file = yield* mintKvTempFile('exact body\n', 'c1-node-config');
+          path = file.path;
+          const text = yield* Effect.promise(() => Bun.file(path).text());
+          assert.equal(text, 'exact body\n');
+          assert.equal(statSync(path).mode & 0o777, 0o600);
+        }),
+      ),
+    );
+    assert.equal(existsSync(path), false);
+  });
+});
+
+describe('mintKubeconfig — the consumer-side seam, same lifetime shape as mintTalosconfig', () => {
+  it('reads the default kubeconfig key and the file survives only within the caller scope', async () => {
+    const calls: FakeCall[] = [];
+    let capturedPath = '';
+    await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const file = yield* mintKubeconfig({ cluster: 'c1', mount: 'talos-c1' });
+          capturedPath = file.path;
+          assert.ok(existsSync(capturedPath));
+        }),
+      ).pipe(
+        Effect.provideService(
+          ChildProcessSpawner.ChildProcessSpawner,
+          fakeSpawner(bao({ kubeconfig: 'fake-kubeconfig-body' }), calls),
+        ),
+      ),
+    );
+    assert.deepEqual(calls[0]?.args, ['kv', 'get', '-format=json', 'talos-c1/kubeconfig']);
+    assert.equal(existsSync(capturedPath), false);
+  });
+});
+
+describe('readKvValue', () => {
+  it('tries fields in order and returns the first non-empty match', async () => {
+    const value = await run(
+      readKvValue('talos-c1', 'nodes/10001', ['config', 'legacyConfig']),
+      bao({ legacyConfig: 'second-field-body' }),
+    );
+    assert.equal(value, 'second-field-body');
+  });
+});