@homeflare/alchemy 0.39.0 → 0.40.0

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');
+  });
+});

package/src/talos/credentials.ts

@@ -1,20 +1,38 @@
 /**
- * The Talos client credential a reconcile runs with: minted from OpenBao, written to a temp file.
+ * Talos client material minted from OpenBao, written to a session-temp file whose lifetime the
+ * CALLER owns — never this module.
  *
- * ⛔ TALOSCONFIG AND secrets.yaml HOLD CLIENT CERTIFICATES AND CLUSTER CA PRIVATE KEYS. Alchemy
- *   persists resource attributes WITHOUT encryption — StateEncoding.ts writes `Redacted` as
- *   `{"@redacted": <plaintext>}` — and this estate's state store is the `alchemy` Postgres that
- *   a nightly job dumps. Neither file may be a prop, an attribute, or a log line.
+ * ⛔ TALOSCONFIG, MACHINE CONFIG AND secrets.yaml CAN ALL HOLD CLIENT CERTIFICATES AND CLUSTER CA
+ *   PRIVATE KEYS. Alchemy persists resource attributes WITHOUT encryption — `StateEncoding.ts`
+ *   tags a `Redacted` value as `{ __redacted__: <plaintext> }` (`REDACTED_MARKER`), it does not
+ *   encrypt it — and this estate's state store is the shared Cloudflare HTTP state store, not a
+ *   database anyone forgets is world-legible. None of these three may ever be a prop, an
+ *   attribute or a log line; see docs/plans/2026-09-26-talos-secrets-flow.md for why the OLD
+ *   header here (Postgres, `{"@redacted": …}`) was wrong on both counts — the RULE survives the
+ *   correction either way.
  *
- * ★ MODELED ON <estate>/proxmox/src/credentials.ts: mint at call time through `ChildProcessSpawner`,
- *   use the material to build a client, drop it when the scope ends. The difference is Talos wants a
- *   FILE (`--talosconfig` / `TALOSCONFIG`), so mint writes a temp path and registers cleanup.
+ * ★ MODELED ON proxmox/credentials.ts + proxmox/mint.ts: mint at call time, use the material, drop
+ *   it when the scope ends. The difference is Talos wants a FILE (`--talosconfig` / `-f`), so
+ *   minting here writes a temp path and registers its own delete finalizer instead of just
+ *   building a header.
+ *
+ * ⛔ C1 FIX (2026-09-26, K-A3) — THE SHIPPED `mintTalosconfig` DELETED ITS OWN FILE BEFORE ANY
+ *   CALLER COULD USE IT. It wrapped its whole body in `Effect.scoped(...)` and registered the
+ *   delete finalizer inside that same scope, so the scope — and the file — closed the instant
+ *   `mintTalosconfig` RETURNED, before the caller ever got to pass the path to `talosctl`. Fixed
+ *   by `Effect.acquireRelease`: it still deletes on every exit path, but contributes `Scope.Scope`
+ *   to this module's own return type instead of discharging it, so the file survives until
+ *   whichever `Effect.scoped(...)` the CALLER wraps around its own use of the path (every
+ *   talos-*.ts resource file wraps its `read`/`reconcile` bodies for exactly this reason now).
  *
  * ⚠️ REASONED FROM THE PUBLISHED TALOS WORKFLOW, NOT MEASURED ON THIS ESTATE. There is no Talos
- *   cluster here yet; paths below follow the same `mount/data/…` shape other infra mounts use.
+ *   cluster here yet; KV paths below follow the `mount/<key>` shape O1 (the secrets-flow doc)
+ *   assigns, and `bao kv get` inserts the KV-v2 `data/` API segment itself — a key already
+ *   prefixed `data/` reads `<mount>/data/data/<key>`, which the OLD default did.
  */
 import { closeSync, openSync, writeFileSync } from 'node:fs';
 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';
@@ -26,10 +44,10 @@ export type TalosTarget = {
   /** Logical cluster name — safe to persist and log. */
   readonly cluster: string;
   /**
-   * Path under the mount for the talosconfig YAML.
-   *
-   * ⚠️ DEFAULT IS REASONED. The first real deploy will confirm or correct the path; a wrong path
-   *   fails closed with a bao error rather than writing an empty talosconfig.
+   * Path under the mount for the talosconfig YAML. Default `'talosconfig'` — FIXED 2026-09-26;
+   * the shipped default was `'data/talosconfig'`, which `bao kv get` turned into
+   * `<mount>/data/data/talosconfig` (see the ⚠️ above). It failed closed rather than reading an
+   * empty talosconfig, but it would have blocked the very first deploy.
    */
   readonly talosconfigKey?: string;
 };
@@ -39,98 +57,150 @@ export type TalosCredential = {
   readonly talosconfigPath: string;
 };
 
-const defaultKey = (target: TalosTarget) => target.talosconfigKey ?? 'data/talosconfig';
+const DEFAULT_TALOSCONFIG_KEY = 'talosconfig';
 
 /**
- * Mint one talosconfig file for `target`.
+ * Default OpenBao KV path (under `target.mount`) for the admin kubeconfig `Talos.Kubeconfig`
+ * writes once at cluster bring-up. See kubeconfig.ts's own header (K-talos-first-boot, 2026-09-26)
+ * and docs/plans/2026-09-26-talos-secrets-flow.md's O1 key list.
+ */
+export const DEFAULT_KUBECONFIG_KEY = 'kubeconfig';
+
+/**
+ * Read one OpenBao KV-v2 value and return the first of `fields` that is a non-empty string.
  *
- * ★ SHELLS OUT TO `bao` RATHER THAN SPEAKING THE HTTP API — same reasoning as proxmox credentials.
- *   The estate's BAO_ADDR / BAO_NAMESPACE / approle contract already lives in that binary.
+ * ★ THE ONE PLACE THIS PACKAGE SHELLS TO `bao` — talosconfig, per-node machine config and any
+ *   future KV-backed Talos material (secrets.yaml, ceph entity keys) all read through this,
+ *   so there is exactly one spot that must never echo a KV value on failure.
+ * ⛔ stderr ONLY ON FAILURE. stdout may hold the very secret this call exists to fetch.
  */
-export const mintTalosconfig = (target: TalosTarget) =>
-  Effect.scoped(
-    Effect.gen(function* () {
-      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-      const key = defaultKey(target);
-      const result = yield* ChildProcess.make(
-        'bao',
-        ['kv', 'get', '-format=json', `${target.mount}/${key}`],
-        { detached: false, extendEnv: true, stderr: 'pipe', stdin: 'ignore', 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()),
-              ),
-              stdout: child.stdout.pipe(
-                Stream.decodeText,
-                Stream.mkString,
-                Effect.map((text) => text.trim()),
-              ),
-            },
-            { concurrency: 'unbounded' },
-          ),
+export const readKvValue = (
+  mount: string,
+  key: string,
+  fields: readonly string[],
+): Effect.Effect<string, Error, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const result = yield* ChildProcess.make(
+      'bao',
+      ['kv', 'get', '-format=json', `${mount}/${key}`],
+      { detached: false, extendEnv: true, stderr: 'pipe', stdin: 'ignore', 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()),
+            ),
+            stdout: child.stdout.pipe(
+              Stream.decodeText,
+              Stream.mkString,
+              Effect.map((text) => text.trim()),
+            ),
+          },
+          { concurrency: 'unbounded' },
         ),
-        Effect.scoped,
-      );
+      ),
+      Effect.scoped,
+    );
 
-      if (result.exitCode !== 0) {
-        // ⛔ stderr ONLY — stdout may hold talosconfig YAML with client credentials.
-        return yield* Effect.fail(
-          new Error(
-            `bao kv get ${target.mount}/${key} exited ${String(result.exitCode)}: ${result.stderr}`,
-          ),
-        );
-      }
+    if (result.exitCode !== 0) {
+      return yield* Effect.fail(
+        new Error(`bao kv get ${mount}/${key} exited ${String(result.exitCode)}: ${result.stderr}`),
+      );
+    }
 
-      const parsed = JSON.parse(result.stdout) as { data?: { data?: Record<string, unknown> } };
-      const data = parsed.data?.data;
-      const raw = data?.['talosconfig'] ?? data?.['config'];
-      if (typeof raw !== 'string' || raw.trim() === '') {
-        return yield* Effect.fail(
-          new Error(
-            `${target.mount}/${key} returned no talosconfig field. Expected a KV key named 'talosconfig' or 'config' — never store the value in Alchemy props.`,
-          ),
-        );
-      }
+    const parsed = JSON.parse(result.stdout) as { data?: { data?: Record<string, unknown> } };
+    const data = parsed.data?.data;
+    for (const field of fields) {
+      const raw = data?.[field];
+      if (typeof raw === 'string' && raw.trim() !== '') return raw;
+    }
+    return yield* Effect.fail(
+      new Error(
+        `${mount}/${key} returned no ${fields.join('/')} field. Never store the value itself in ` +
+          'an Alchemy prop or attribute — fix the KV entry, not the caller.',
+      ),
+    );
+  });
 
-      const talosconfigPath = `${Bun.env['TMPDIR'] ?? '/tmp'}/hf-talos-${target.cluster}-${Bun.randomUUIDv7()}.yaml`;
-      /**
-       * ⛔ 0600, CREATED EXCLUSIVELY, AND `Bun.write` CANNOT DO EITHER. This file holds the
-       *   cluster's admin client certificate — everything talosctl needs to reconfigure or wipe a
-       *   node. `Bun.write` takes no mode, so it lands at the process umask, which on this estate
-       *   is 0644: world-readable, in a world-readable directory, for as long as the resource
-       *   runs. The name is unguessable, and "unguessable" is not a permission.
-       * ⚠️ `wx` IS THE OTHER HALF. Opening with O_EXCL means this cannot be made to write through
-       *   a path an attacker pre-created — the classic /tmp symlink race — and with a UUIDv7 name
-       *   a collision is a genuine error rather than something to paper over.
-       * ⚠️ THE FINALIZER BELOW REMOVES IT ON EVERY EXIT PATH, but a hard kill (SIGKILL, power
-       *   loss) leaves it behind. 0600 is what makes that survivable rather than a disclosure.
-       */
-      yield* Effect.try({
+/**
+ * Write `raw` to a session-temp, 0600, exclusively-created file whose lifetime is the CALLER's
+ * `Effect.scoped`, not this call's. See the ⛔ C1 FIX note at the top of this file.
+ *
+ * ⛔ 0600, CREATED EXCLUSIVELY, AND `Bun.write` CANNOT DO EITHER. This file can hold a cluster
+ *   admin client certificate or a machine config's bootstrap token. `Bun.write` takes no mode, so
+ *   it lands at the process umask — world-readable on this estate — for as long as the resource
+ *   runs. The name is unguessable, and "unguessable" is not a permission.
+ * ⚠️ `wx` IS THE OTHER HALF. `O_EXCL` means this cannot be made to write through a path an
+ *   attacker pre-created (the classic /tmp symlink race), and with a UUIDv7 name a collision is a
+ *   genuine error rather than something to paper over.
+ * ⚠️ A HARD KILL (SIGKILL, power loss) skips the finalizer and leaves the file behind. 0600 is
+ *   what makes that survivable rather than a disclosure.
+ */
+export const mintKvTempFile = (
+  raw: string,
+  label: string,
+): Effect.Effect<{ readonly path: string }, Error, Scope.Scope> =>
+  Effect.gen(function* () {
+    const path = `${Bun.env['TMPDIR'] ?? '/tmp'}/hf-talos-${label}-${Bun.randomUUIDv7()}.yaml`;
+    yield* Effect.acquireRelease(
+      Effect.try({
         try: () => {
-          const fd = openSync(talosconfigPath, 'wx', 0o600);
+          const fd = openSync(path, 'wx', 0o600);
           try {
             writeFileSync(fd, raw);
           } finally {
             closeSync(fd);
           }
         },
-        catch: (cause) => new Error(`writing temp talosconfig: ${String(cause)}`),
-      });
+        catch: (cause) => new Error(`writing ${label} temp file: ${String(cause)}`),
+      }),
+      () =>
+        Effect.tryPromise({ try: () => Bun.file(path).delete(), catch: () => undefined }).pipe(
+          Effect.orElseSucceed(() => undefined),
+        ),
+    );
+    return { path };
+  });
 
-      yield* Effect.addFinalizer(() =>
-        Effect.tryPromise({
-          try: () => Bun.file(talosconfigPath).delete(),
-          catch: () => undefined,
-        }).pipe(Effect.orElseSucceed(() => undefined)),
-      );
+/**
+ * Mint one talosconfig file for `target`.
+ *
+ * ⛔ CALLERS MUST WRAP THEIR WHOLE USE OF `credential.talosconfigPath` — not just this call — in
+ *   `Effect.scoped(...)`. This function's own `Scope.Scope` requirement is what makes that the
+ *   caller's job instead of a lie this function tells itself; see the header above.
+ */
+export const mintTalosconfig = (
+  target: TalosTarget,
+): Effect.Effect<TalosCredential, Error, ChildProcessSpawner.ChildProcessSpawner | Scope.Scope> =>
+  readKvValue(target.mount, target.talosconfigKey ?? DEFAULT_TALOSCONFIG_KEY, [
+    'talosconfig',
+    'config',
+  ]).pipe(
+    Effect.flatMap((raw) => mintKvTempFile(raw, `${target.cluster}-talosconfig`)),
+    Effect.map(({ path }): TalosCredential => ({ talosconfigPath: path })),
+  );
 
-      return { talosconfigPath } satisfies TalosCredential;
-    }),
+/**
+ * Mint one temp kubeconfig file from the vault copy `Talos.Kubeconfig` writes at bring-up
+ * (K-talos-first-boot, 2026-09-26) — the consumer-side counterpart to {@link mintTalosconfig},
+ * named as the future seam for `Kubernetes.ClusterAdapter` in
+ * docs/plans/2026-09-26-talos-secrets-flow.md ("consumers mint it the way the talosconfig is
+ * minted"). Not yet wired to that adapter — this only makes the read+materialize step exist.
+ */
+export const mintKubeconfig = (
+  target: TalosTarget,
+  key = DEFAULT_KUBECONFIG_KEY,
+): Effect.Effect<
+  { readonly path: string },
+  Error,
+  ChildProcessSpawner.ChildProcessSpawner | Scope.Scope
+> =>
+  readKvValue(target.mount, key, ['kubeconfig', 'config']).pipe(
+    Effect.flatMap((raw) => mintKvTempFile(raw, `${target.cluster}-kubeconfig`)),
   );