@homeflare/alchemy 0.39.0 → 0.41.0

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

package/src/talos/fake-process.ts

@@ -0,0 +1,94 @@
+/**
+ * A fake `ChildProcessSpawner` for offline Talos tests — no real `bao` or `talosctl` process ever
+ * starts. Shared by credentials.test.ts and talos-machine-config.test.ts (2026-09-26, K-A3);
+ * this package had NO process-level test fake before this file — every Talos resource file spawns
+ * a real binary in production and none of that was previously exercised offline.
+ *
+ * ★ A FULL FAKE SERVICE, NOT A REAL SPAWN WITH A FIXTURE EXECUTABLE ON `PATH`. The alternative —
+ *   a tiny fake `bao`/`talosctl` script and a mutated `process.env.PATH` — spawns a REAL OS
+ *   process and mutates process-global state for the test's duration, which is exactly the kind
+ *   of cross-test interference the house rules ask tests to avoid. `ChildProcessSpawner.make`
+ *   takes just a `spawn` function and derives everything else, so a fake `spawn` is the whole cost.
+ */
+import * as Effect from 'effect/Effect';
+import * as Sink from 'effect/Sink';
+import * as Stream from 'effect/Stream';
+import type { Command } from 'effect/unstable/process/ChildProcess';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+
+export type FakeResult = {
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly exitCode?: number;
+};
+export type FakeCall = {
+  readonly command: string;
+  readonly args: readonly string[];
+  /**
+   * Decoded stdin text, present only when the real caller piped a `Stream` in (K-talos-first-boot,
+   * `credentials-write.ts`'s `writeKvValue`) — the whole reason this fake exists is to prove a
+   * value went in via stdin and never via argv, so a test needs to see it.
+   */
+  readonly stdin?: string;
+};
+export type FakeHandler = (call: FakeCall) => FakeResult;
+
+const encode = (text: string) => new TextEncoder().encode(text);
+
+const fakeHandle = (result: FakeResult): ChildProcessSpawner.ChildProcessHandle =>
+  ChildProcessSpawner.makeHandle({
+    all: Stream.fromIterable([encode((result.stdout ?? '') + (result.stderr ?? ''))]),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(result.exitCode ?? 0)),
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    pid: ChildProcessSpawner.ProcessId(1),
+    stderr: Stream.fromIterable([encode(result.stderr ?? '')]),
+    stdin: Sink.drain,
+    stdout: Stream.fromIterable([encode(result.stdout ?? '')]),
+    unref: Effect.succeed(Effect.void),
+  });
+
+/**
+ * Decode a `StandardCommand`'s `options.stdin` into text, or `undefined` when there was none to
+ * decode. Only `"pipe" | "inherit" | "ignore" | "overlapped"` (no bytes) and a raw `Stream` (the
+ * only two shapes anything in this package ever passes — `credentials-write.ts`'s `writeKvValue`
+ * uses `Stream.fromIterable`, matching `alchemy`'s own `Cloudflare/Workers/ViteChild.ts` usage) are
+ * handled; a `StdinConfig` wrapper is unwrapped to its own `.stream` field first.
+ */
+const stdinText = (stdin: unknown) =>
+  Effect.gen(function* () {
+    if (stdin === undefined || typeof stdin === 'string') return undefined;
+    const stream =
+      typeof stdin === 'object' && stdin !== null && 'stream' in stdin
+        ? (stdin as { stream: unknown }).stream
+        : stdin;
+    if (stream === undefined || typeof stream === 'string') return undefined;
+    const chunks = yield* Stream.runCollect(stream as Stream.Stream<Uint8Array>);
+    return chunks.map((chunk) => new TextDecoder().decode(chunk)).join('');
+  }).pipe(Effect.orDie);
+
+/**
+ * Build a fake `ChildProcessSpawner.Service` from `handler`, which sees every command's
+ * executable + argv (+ decoded stdin, when piped) and returns canned stdout/stderr/exitCode.
+ * `credentials.ts` and `talosctl.ts` only ever build `StandardCommand`s (never a piped command),
+ * so that is the only shape this fake accepts — a `PipedCommand` is a test-authoring mistake, not
+ * something to fake.
+ */
+export const fakeSpawner = (handler: FakeHandler, calls: FakeCall[] = []) =>
+  ChildProcessSpawner.make((command: Command) =>
+    Effect.gen(function* () {
+      if (command._tag !== 'StandardCommand') {
+        return yield* Effect.die(new Error('fake-process: only StandardCommand is supported'));
+      }
+      const stdin = yield* stdinText(command.options.stdin);
+      const call: FakeCall = {
+        args: command.args,
+        command: command.command,
+        ...(stdin === undefined ? {} : { stdin }),
+      };
+      calls.push(call);
+      return fakeHandle(handler(call));
+    }),
+  );

package/src/talos/index.ts

@@ -5,10 +5,45 @@
  *   These are the symbols a real stack consumes; the rest of the files are internals a
  *   provider needs but a consumer should not depend on. An `export *` here would publish
  *   every helper as API and make the next refactor a breaking change.
+ * ★ `Talos.MachineConfig`'S RESOURCE CLASS JOINED ITS PROVIDER 2026-09-26 (K-A3) — until now this
+ *   barrel exported only `Talos*Provider`, which builds the provider but gives a consuming stack
+ *   nothing to `new` or call to actually DECLARE a row (the same gap proxmox/index.ts's own header
+ *   calls out for `ProxmoxVm`). MachineConfig is safe to declare today: it fails closed on a digest
+ *   mismatch before touching a node, and its cold-start read never silently adopts (PR 307 fix-first
+ *   #1, machine-config-read.ts's own header).
+ * ★ BOOTSTRAP, CLUSTERHEALTH AND KUBECONFIG JOIN THEM (K-talos-first-boot, 2026-09-26) — PR 307's
+ *   red team (fix-first #3) held these back because `Talos.Bootstrap` could re-run `talosctl
+ *   bootstrap` against an already-bootstrapped cluster and `Talos.Kubeconfig` wrote a cluster-admin
+ *   kubeconfig to un-vaulted host disk. Both are fixed now: bootstrap's "once means once" invariant
+ *   (talos-bootstrap.ts's own header) and kubeconfig landing in OpenBao, written once at bring-up
+ *   (kubeconfig.ts's own header) — plus `Talos.ClusterHealth`'s error handling no longer conflates a
+ *   vault/transport failure with "cluster not healthy yet" (talos-cluster-health.ts's own header).
  * ★ Anything unlisted is still reachable by path if you genuinely need it — that is a
  *   deliberate, visible act rather than an accident of barrelling.
  */
-export { TalosKubeconfigProvider } from './kubeconfig.ts';
-export { TalosBootstrapProvider } from './talos-bootstrap.ts';
-export { TalosClusterHealthProvider } from './talos-cluster-health.ts';
-export { TalosMachineConfigProvider } from './talos-machine-config.ts';
+export type { TalosCredential, TalosTarget } from './credentials.ts';
+export {
+  type KubeconfigAttributes,
+  type KubeconfigProps,
+  TalosKubeconfig,
+  TalosKubeconfigProvider,
+} from './kubeconfig.ts';
+export type { ApplyMode, WithTarget } from './resource.ts';
+export {
+  type BootstrapAttributes,
+  type BootstrapProps,
+  TalosBootstrap,
+  TalosBootstrapProvider,
+} from './talos-bootstrap.ts';
+export {
+  type ClusterHealthAttributes,
+  type ClusterHealthProps,
+  TalosClusterHealth,
+  TalosClusterHealthProvider,
+} from './talos-cluster-health.ts';
+export {
+  type MachineConfigAttributes,
+  type MachineConfigProps,
+  TalosMachineConfig,
+  TalosMachineConfigProvider,
+} from './talos-machine-config.ts';

package/src/talos/kubeconfig-attrs.ts

@@ -0,0 +1,55 @@
+/**
+ * `Talos.Kubeconfig`'s attribute builder and its `Kubernetes.Connection` — split out of
+ * kubeconfig.ts (LAND, 2026-09-26, C1/I2 fixes) once fixing those findings pushed the file over the
+ * 250-line cap, the same reason machine-config-read.ts/machine-config-poll.ts/talos-errors.ts were
+ * split out of talos-machine-config.ts before it. Only `import type` comes back from kubeconfig.ts,
+ * so there is no runtime cycle between the two files.
+ */
+import type { Connection } from 'alchemy/Kubernetes/Connection';
+import type { KubeconfigAttributes, KubeconfigProps } from './kubeconfig.ts';
+import { kubeconfigMetadata, sha256 } from './values.ts';
+
+const generation = (meta: {
+  endpoint: string;
+  caFingerprint: string;
+  clientFingerprint: string;
+  context: string;
+}) => sha256(`${meta.context}\n${meta.endpoint}\n${meta.caFingerprint}\n${meta.clientFingerprint}`);
+
+/**
+ * ⛔ I2 FIX (LAND red team, 2026-09-26) — NEVER LEAVE `path` UNDEFINED. An undefined `path` here
+ *   made the stock `Kubernetes.KubeConfigAdapter` fall back to `$KUBECONFIG`/`~/.kube/config`
+ *   (alchemy `Kubernetes/internal/kubeconfig.ts`'s `resolveKubeConfigPath`, wired in
+ *   `BuiltinAdapters.ts`) — exactly the un-vaulted, possibly-stale-context exposure this whole
+ *   family exists to remove. A consumer wiring `Kubernetes.*` to `kube.connection` (this
+ *   attribute's own doc invites exactly that) would silently connect through whatever
+ *   `admin@<cluster>` context happens to be on the operator's machine. `Kubernetes.ClusterAdapter`
+ *   is not yet wired to `mintKubeconfig` (kubeconfig.ts's own header) — no real path exists for
+ *   this connection to use — so it must fail LOUDLY instead of silently succeeding against a
+ *   stranger's cluster. A path that can never resolve does that: `resolveKubeContext` fails at
+ *   `fs.readFileString` naming this exact sentinel, instead of reading whatever real file happens
+ *   to be on `$KUBECONFIG`.
+ */
+const UNWIRED_KUBECONFIG_PATH =
+  '/talos-first-boot-unwired/wire-Kubernetes.ClusterAdapter-to-mintKubeconfig';
+
+const toConnection = (props: KubeconfigProps): Connection => ({
+  auth: { context: props.context, kind: 'kubeconfig', path: UNWIRED_KUBECONFIG_PATH },
+});
+
+/** Parse `raw` kubeconfig YAML into public, persistable attributes, or `undefined` if it fails to. */
+export const buildAttrs = (
+  raw: string,
+  props: KubeconfigProps,
+): KubeconfigAttributes | undefined => {
+  const meta = kubeconfigMetadata(raw, props.context);
+  if (meta === undefined) return undefined;
+  return {
+    certificateAuthorityFingerprint: meta.caFingerprint,
+    clientCertificateFingerprint: meta.clientFingerprint,
+    connection: toConnection(props),
+    context: props.context,
+    credentialGeneration: generation({ ...meta, context: props.context }),
+    endpoint: meta.endpoint,
+  };
+};