@homeflare/alchemy 0.47.1 → 0.48.0

package/src/talos/mint-temp-file.ts

@@ -0,0 +1,56 @@
+/**
+ * `mintKvTempFile` — the 0600 session-temp file `readKvValue`'s material lands in. Extracted from
+ * credentials.ts (2026-10-06, red team PR 355) once the Node-runtime fix pushed that file past the
+ * 250-line cap; the split mirrors credentials-write.ts, which was split out for its own header.
+ */
+import { closeSync, openSync, writeFileSync } from 'node:fs';
+import { unlink } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
+
+/**
+ * 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 credentials.ts.
+ *
+ * ⛔ 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 UUID 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* () {
+    // ⛔ NODE, NOT BUN (red team, PR 355): the published dist runs on Node, where `Bun.env` and
+    //   `Bun.randomUUIDv7` are missing globals — a `Talos.ClusterHealth` check would hit a
+    //   `ReferenceError` before `talosctl` ever ran. `os.tmpdir()` and `node:crypto` `randomUUID`
+    //   are the portable equivalents.
+    const path = join(tmpdir(), `hf-talos-${label}-${randomUUID()}.yaml`);
+    yield* Effect.acquireRelease(
+      Effect.try({
+        try: () => {
+          const fd = openSync(path, 'wx', 0o600);
+          try {
+            writeFileSync(fd, raw);
+          } finally {
+            closeSync(fd);
+          }
+        },
+        catch: (cause) => new Error(`writing ${label} temp file: ${String(cause)}`),
+      }),
+      () =>
+        Effect.tryPromise({ try: () => unlink(path), catch: () => undefined }).pipe(
+          Effect.orElseSucceed(() => undefined),
+        ),
+    );
+    return { path };
+  });

package/src/talos/node-connect.harness.ts

@@ -0,0 +1,78 @@
+/**
+ * Run UNDER NODE by `node-connect.test.ts` (never imported by bun): a successful `talos-openbao`
+ * connect with a fake `bao` and a fake apiserver, so any Bun-only API on the connect path (the
+ * `Bun.YAML` that once made every kubeconfig "unreadable" on Node) fails CI.
+ *
+ * ★ The apiserver fake patches `node:https`'s `request` and calls `syncBuiltinESMExports`, which is
+ *   how a Node program changes what `import * as https` sees. Prints one JSON line, no secrets.
+ */
+import { EventEmitter } from 'node:events';
+import https from 'node:https';
+import { syncBuiltinESMExports } from 'node:module';
+import { ClusterAdapter } from 'alchemy/Kubernetes/ClusterAdapter';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { TalosOpenBaoAdapter, talosOpenBaoConnection } from './cluster-adapter.ts';
+import { fakeSpawner } from './fake-process.ts';
+
+const b64 = (text: string) => Buffer.from(text).toString('base64');
+const pem = (label: string) => `-----${'BEGIN'} ${label}-----\n${b64(label)}\n`;
+const kubeconfig = `apiVersion: v1
+kind: Config
+clusters:
+  - name: c1
+    cluster: { server: 'https://c1.cluster.invalid:6443', certificate-authority-data: ${b64(pem('CERTIFICATE'))} }
+contexts:
+  - name: admin@c1
+    context: { cluster: c1, user: admin@c1 }
+users:
+  - name: admin@c1
+    user: { client-certificate-data: ${b64(pem('CERTIFICATE'))}, client-key-data: ${b64(pem('PRIVATE KEY'))} }
+`;
+
+const seen: string[] = [];
+const fakeRequest = (
+  options: { hostname: string; method: string; path: string },
+  callback: (response: EventEmitter & { statusCode?: number }) => void,
+) => {
+  seen.push(`${options.method} ${options.hostname}${options.path}`);
+  const request = new EventEmitter() as EventEmitter & { write: () => void; end: () => void };
+  request.write = () => undefined;
+  request.end = () => {
+    const response = new EventEmitter() as EventEmitter & { statusCode?: number };
+    response.statusCode = 200;
+    callback(response);
+    response.emit('data', Buffer.from('{"metadata":{"uid":"uid-c1"}}'));
+    response.emit('end');
+  };
+  return request;
+};
+(https as unknown as { request: unknown }).request = fakeRequest;
+syncBuiltinESMExports();
+
+process.env['BAO_ADDR'] ??= 'https://bao.invalid';
+process.env['BAO_TOKEN'] ??= 'fake-test-token';
+
+// ⚠️ The trust-boundary seam registers the fixtures dir ASYNC (trust-boundary.ts's computed
+//   dynamic import). `readKvValue` now vets `bao`, so the walk must see the boundary before it
+//   runs. Awaiting the seam here flushes that registration; without it a bare `node` run can walk
+//   past the (755) fixtures dir into a group-writable ancestor and refuse a trusted stub.
+await import('./trust-boundary.seam.ts');
+
+const spawner = Layer.succeed(
+  ChildProcessSpawner.ChildProcessSpawner,
+  fakeSpawner(() => ({ stdout: JSON.stringify({ data: { data: { kubeconfig } } }) })),
+);
+const config = {
+  c1: { context: 'admin@c1', key: 'kubeconfig', mount: 'talos-c1', uid: 'uid-c1' },
+};
+
+const transport = await Effect.runPromise(
+  Effect.gen(function* () {
+    const adapter = yield* ClusterAdapter('talos-openbao');
+    return yield* adapter.connect(talosOpenBaoConnection('uid-c1'));
+  }).pipe(Effect.provide(TalosOpenBaoAdapter(config).pipe(Layer.provide(spawner)))),
+);
+const hasCert = transport.clientCert !== undefined;
+process.stdout.write(`${JSON.stringify({ endpoint: transport.endpoint, hasCert, seen })}\n`);

package/src/talos/node-connect.test.ts

@@ -0,0 +1,27 @@
+/**
+ * ⛔ THE PUBLISHED CODE RUNS ON NODE. A successful adapter connect is run under a real `node`
+ * process (`node-connect.harness.ts`, type stripping), so a Bun-only API on the connect path fails
+ * here. Reproduced before the fix: on Node 22 `Bun.YAML` was a missing global, swallowed into
+ * "unreadable kubeconfig", and the adapter returned no transport. Bun's own test run cannot see
+ * that, which is why this spawns node instead of importing the module.
+ */
+import { expect, test } from 'bun:test';
+
+test('a successful connect works under node, with no Bun globals', async () => {
+  const harness = new URL('./node-connect.harness.ts', import.meta.url).pathname;
+  const proc = Bun.spawn(['node', '--experimental-strip-types', '--no-warnings', harness], {
+    stderr: 'pipe',
+    stdout: 'pipe',
+  });
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  expect({ code, err: err.slice(0, 500) }).toEqual({ code: 0, err: '' });
+  expect(JSON.parse(out.trim())).toEqual({
+    endpoint: 'https://c1.cluster.invalid:6443',
+    hasCert: true,
+    seen: ['GET c1.cluster.invalid/api/v1/namespaces/kube-system'],
+  });
+});

package/src/talos/node-temp.harness.ts

@@ -0,0 +1,40 @@
+/**
+ * ⛔ THE PUBLISHED CODE RUNS ON NODE. `mintKvTempFile` (credentials.ts) and `reservedTempPath`
+ *   (credentials-write.ts) once built their path from `Bun.env`/`Bun.randomUUIDv7` — missing globals
+ *   on Node, where a `Talos.ClusterHealth` check would hit a `ReferenceError` before `talosctl` ran.
+ *   Run under a real `node` process (type stripping) so a Bun-only API here fails CI.
+ */
+import { existsSync, statSync } from 'node:fs';
+import * as Effect from 'effect/Effect';
+import { mintKvTempFile } from './credentials.ts';
+import { reservedTempPath } from './credentials-write.ts';
+
+const report = (label: string, value: unknown) =>
+  process.stdout.write(`${JSON.stringify({ label, value })}\n`);
+
+let tempCreated = false;
+let tempMode = -1;
+let tempGone = false;
+const mintedPath = await Effect.runPromise(
+  Effect.scoped(
+    Effect.gen(function* () {
+      const file = yield* mintKvTempFile('node-body\n', 'c1-node-check');
+      tempCreated = existsSync(file.path);
+      tempMode = statSync(file.path).mode & 0o777;
+      return file.path;
+    }),
+  ),
+);
+tempGone = !existsSync(mintedPath);
+
+let reservedPath = '';
+const reservedGone = await Effect.runPromise(
+  Effect.scoped(
+    Effect.gen(function* () {
+      const reserved = yield* reservedTempPath('c1-node-reserve');
+      reservedPath = reserved.path;
+    }),
+  ),
+).then(() => !existsSync(reservedPath));
+
+report('temp', { tempCreated, tempMode, tempGone, reservedGone });

package/src/talos/node-temp.test.ts

@@ -0,0 +1,26 @@
+/**
+ * ⛔ The temp-file minters (credentials.ts `mintKvTempFile`, credentials-write.ts `reservedTempPath`)
+ *   run on Node in production. They once read `Bun.env`/`Bun.randomUUIDv7`; a Node process would
+ *   throw `ReferenceError: Bun is not defined`. This spawns a real `node` process (type stripping) so
+ *   a Bun-only API on that path fails here rather than in a consumer's deploy.
+ */
+import { expect, test } from 'bun:test';
+
+test('the temp-file minters work under node, with no Bun globals', async () => {
+  const harness = new URL('./node-temp.harness.ts', import.meta.url).pathname;
+  const proc = Bun.spawn(['node', '--experimental-strip-types', '--no-warnings', harness], {
+    stderr: 'pipe',
+    stdout: 'pipe',
+  });
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  expect({ code, err: err.slice(0, 500) }).toEqual({ code: 0, err: '' });
+  const line = out.trim().split('\n').pop() ?? '';
+  expect(JSON.parse(line)).toEqual({
+    label: 'temp',
+    value: { tempCreated: true, tempMode: 0o600, tempGone: true, reservedGone: true },
+  });
+});

package/src/talos/talos-cluster-health-declare.test.ts

@@ -0,0 +1,54 @@
+/**
+ * A FRESH `Talos.ClusterHealth` skips `diff` while its inputs are unresolved, so the literal-uid
+ * refusal must already have happened when the resource is DECLARED. Driven through a real
+ * `Alchemy.Stack` (the engine's own declaration path, no handler called directly): an Output uid
+ * fails the stack before any plan exists, and a literal one still declares.
+ */
+import { expect, test } from 'bun:test';
+import * as Alchemy from 'alchemy';
+import * as Effect from 'effect/Effect';
+import { talosOpenBaoConnection } from './cluster-adapter.ts';
+import { TalosClusterHealth, TalosClusterHealthProvider } from './talos-cluster-health.ts';
+import './fake-process.ts';
+
+const base = { controlPlaneNodes: ['198.51.100.10'], target: { cluster: 'c1', mount: 'talos-c1' } };
+
+const compile = (body: unknown) => {
+  const stack = Alchemy.Stack as unknown as (
+    name: string,
+    options: { providers: unknown; state: unknown },
+    body: unknown,
+  ) => Effect.Effect<unknown, unknown, never>;
+  return stack(
+    'talos-health-declare',
+    { providers: TalosClusterHealthProvider(), state: Alchemy.inMemoryState() },
+    body,
+  ).pipe(Effect.provideService(Alchemy.Stage, 'test'), Effect.scoped);
+};
+
+test('declaring a fresh health resource whose uid is an Output fails the stack', async () => {
+  const failure = await Effect.runPromise(
+    compile(
+      Effect.gen(function* () {
+        const first = yield* TalosClusterHealth('First', {
+          ...base,
+          connection: talosOpenBaoConnection('uid-c1'),
+        });
+        // A real Output: an attribute of another resource, unresolved until it deploys.
+        const uid = (first as unknown as { controlPlaneNodes: unknown }).controlPlaneNodes;
+        yield* TalosClusterHealth('Second', {
+          ...base,
+          connection: { auth: { kind: 'talos-openbao', uid } },
+        } as never);
+      }),
+    ).pipe(Effect.flip),
+  );
+  expect((failure as { _tag: string })._tag).toBe('TalosUidNotLiteral');
+});
+
+test('a literal uid declares fine', async () => {
+  const compiled = await Effect.runPromise(
+    compile(TalosClusterHealth('Only', { ...base, connection: talosOpenBaoConnection('uid-c1') })),
+  );
+  expect(compiled).toBeDefined();
+});

package/src/talos/talos-cluster-health-literal.test.ts

@@ -0,0 +1,69 @@
+/**
+ * `Talos.ClusterHealth` hands its `connection` to workloads through `cluster: health`, so an
+ * Output there reintroduces the unresolved-uid hole `talosOpenBaoConnection` closes. `diff` still
+ * sees the Input, so that is where the refusal happens. Offline: fake-process.ts fakes everything.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as Output from 'alchemy/Output';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { talosOpenBaoConnection } from './cluster-adapter.ts';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+import { diffClusterHealth } from './talos-cluster-health.ts';
+
+const connection = talosOpenBaoConnection('uid-c1');
+const prior = {
+  connection,
+  controlPlaneNodes: '198.51.100.10',
+  healthy: true,
+  workerNodes: '',
+};
+const base = {
+  controlPlaneNodes: ['198.51.100.10'],
+  target: { cluster: 'c1', mount: 'talos-c1' },
+};
+
+const diffWith = (given: unknown, calls: FakeCall[]) =>
+  Effect.runPromise(
+    Effect.provideService(
+      diffClusterHealth({ ...base, connection: given } as never, prior),
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(
+        () => ({ stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) }),
+        calls,
+      ),
+    ),
+  );
+
+describe('diffClusterHealth — literal connection', () => {
+  it('plans noop for a literal connection (the guard does not refuse good input)', async () => {
+    const calls: FakeCall[] = [];
+    assert.equal((await diffWith(connection, calls))?.action, 'noop');
+  });
+
+  it('refuses an Output uid before any vault or talosctl call', async () => {
+    const calls: FakeCall[] = [];
+    const uid = Output.literal('uid-c1');
+    await assert.rejects(
+      diffWith({ auth: { kind: 'talos-openbao', uid } }, calls),
+      (error: unknown) => String(error).includes('literal string'),
+    );
+    assert.deepEqual(calls, []);
+  });
+
+  it('refuses a connection that is itself an Output', async () => {
+    const calls: FakeCall[] = [];
+    await assert.rejects(diffWith(Output.literal(connection), calls));
+    assert.deepEqual(calls, []);
+  });
+
+  it('refuses a stock kubeconfig connection at diff time (never reaches $KUBECONFIG)', async () => {
+    const calls: FakeCall[] = [];
+    await assert.rejects(
+      diffWith({ auth: { kind: 'kubeconfig', context: 'admin@hf-c1' } }, calls),
+      (error: unknown) => String(error).includes('literal string'),
+    );
+    assert.deepEqual(calls, []);
+  });
+});

package/src/talos/talos-cluster-health.test.ts

@@ -4,9 +4,11 @@
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
+import * as Output from 'alchemy/Output';
 import * as Effect from 'effect/Effect';
 import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
 import { type FakeCall, fakeSpawner } from './fake-process.ts';
+import { talosOpenBaoConnection } from './cluster-adapter.ts';
 import {
   diffClusterHealth,
   readClusterHealth,
@@ -14,7 +16,14 @@ import {
 } from './talos-cluster-health.ts';
 
 const TARGET = { cluster: 'c1', mount: 'talos-c1' };
-const props = () => ({ controlPlaneNodes: ['198.51.100.10'], target: TARGET });
+const connection = talosOpenBaoConnection('uid-c1');
+const props = () => ({ connection, controlPlaneNodes: ['198.51.100.10'], target: TARGET });
+const prior = (healthy: boolean) => ({
+  connection,
+  controlPlaneNodes: '198.51.100.10',
+  healthy,
+  workerNodes: '',
+});
 
 const run = <A, E>(
   effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
@@ -54,6 +63,7 @@ describe('readClusterHealth', () => {
   it('reports healthy:true when talosctl health exits zero', async () => {
     const result = await run(readClusterHealth(props()), healthy);
     assert.equal(result.healthy, true);
+    assert.deepEqual(result.connection, connection);
   });
 
   it('propagates a vault/transport failure instead of reporting healthy:false', async () => {
@@ -64,30 +74,105 @@ describe('readClusterHealth', () => {
   });
 });
 
+/** A talosctl vetting refusal (relative HF_TALOSCTL): the binary never runs, so it is no verdict. */
+const withRefusedBinary = async <A>(body: () => Promise<A>): Promise<A> => {
+  const saved = process.env['HF_TALOSCTL'];
+  process.env['HF_TALOSCTL'] = 'relative/talosctl';
+  try {
+    return await body();
+  } finally {
+    if (saved === undefined) delete process.env['HF_TALOSCTL'];
+    else process.env['HF_TALOSCTL'] = saved;
+  }
+};
+const refusal = (error: unknown) =>
+  error instanceof Error &&
+  error.name === 'TalosBinaryRefused' &&
+  error.message.includes('absolute');
+
+describe('a talosctl vetting refusal is never a health verdict (fails on 37d835a: healthy:false)', () => {
+  it('read propagates it', async () => {
+    await withRefusedBinary(() =>
+      assert.rejects(run(readClusterHealth(props()), healthy), refusal),
+    );
+  });
+
+  it('diff propagates it instead of planning an update', async () => {
+    await withRefusedBinary(() =>
+      assert.rejects(run(diffClusterHealth(props(), prior(true)), healthy), refusal),
+    );
+  });
+
+  it('reconcile propagates it without the "cluster not healthy" mislabel', async () => {
+    await withRefusedBinary(() =>
+      assert.rejects(
+        run(reconcileClusterHealth(props()), healthy),
+        (error: unknown) => refusal(error) && !String(error).includes('cluster not healthy'),
+      ),
+    );
+  });
+});
+
 describe('diffClusterHealth', () => {
   it('plans update when the cluster genuinely reports unhealthy', async () => {
+    const result = await run(diffClusterHealth(props(), prior(false)), unhealthy);
+    assert.equal(result?.action, 'update');
+  });
+
+  it('propagates a vault/transport failure rather than planning update silently', async () => {
+    await assert.rejects(run(diffClusterHealth(props(), prior(false)), vaultDown));
+  });
+
+  it('plans noop when the cluster is healthy and the connection is unchanged', async () => {
+    const result = await run(diffClusterHealth(props(), prior(true)), healthy);
+    assert.equal(result?.action, 'noop');
+  });
+
+  it('plans update when the cluster is healthy but the connection changed', async () => {
+    const drifted = talosOpenBaoConnection('uid-other');
     const result = await run(
-      diffClusterHealth(props(), {
-        controlPlaneNodes: '198.51.100.10',
-        healthy: false,
-        workerNodes: '',
-      }),
-      unhealthy,
+      diffClusterHealth(props(), { ...prior(true), connection: drifted }),
+      healthy,
     );
     assert.equal(result?.action, 'update');
   });
 
-  it('propagates a vault/transport failure rather than planning update silently', async () => {
-    await assert.rejects(
-      run(
-        diffClusterHealth(props(), {
-          controlPlaneNodes: '198.51.100.10',
-          healthy: false,
-          workerNodes: '',
-        }),
-        vaultDown,
-      ),
+  it('plans update when only the cluster uid changed (a real move)', async () => {
+    const moved = talosOpenBaoConnection('uid-c2');
+    const result = await run(
+      diffClusterHealth(props(), { ...prior(true), connection: moved }),
+      healthy,
+    );
+    assert.equal(result?.action, 'update');
+  });
+
+  it('plans update, not a throw, for a row saved before `connection` existed', async () => {
+    const { connection: _dropped, ...old } = prior(true);
+    const result = await run(
+      diffClusterHealth(props(), old as unknown as ReturnType<typeof prior>),
+      healthy,
     );
+    assert.equal(result?.action, 'update');
+  });
+});
+
+describe('diffClusterHealth — a legacy auth.cluster row (fails if the hasOwn guard is deleted)', () => {
+  it('plans update for a healthy cluster whose saved row still carries auth.cluster', async () => {
+    const legacy = { auth: { ...talosOpenBaoConnection('uid-c1').auth, cluster: 'c1' } };
+    const result = await run(
+      diffClusterHealth(props(), { ...prior(true), connection: legacy as never }),
+      healthy,
+    );
+    assert.equal(result?.action, 'update');
+  });
+});
+
+describe('diffClusterHealth — a non-literal connection is a TYPED failure', () => {
+  it('fails (flip would reject on a defect) with TalosUidNotLiteral for an Output uid', async () => {
+    const output = Output.literal('uid-c1') as unknown as string;
+    const bad = { ...props(), connection: { auth: { kind: 'talos-openbao', uid: output } } };
+    const error = await run(Effect.flip(diffClusterHealth(bad as never, prior(true))), healthy);
+    assert.equal((error as { _tag: string })._tag, 'TalosUidNotLiteral');
   });
 });
 
@@ -96,6 +181,7 @@ describe('check — I1 fix: --nodes names ONE contact node, not the whole cluste
     const calls: FakeCall[] = [];
     await run(
       readClusterHealth({
+        connection,
         controlPlaneNodes: ['198.51.100.10', '198.51.100.11', '198.51.100.12'],
         target: TARGET,
       }),
@@ -116,7 +202,7 @@ describe('check — I1 fix: --nodes names ONE contact node, not the whole cluste
 
   it('fails closed instead of spawning talosctl when controlPlaneNodes is empty', async () => {
     await assert.rejects(
-      run(readClusterHealth({ controlPlaneNodes: [], target: TARGET }), healthy),
+      run(readClusterHealth({ connection, controlPlaneNodes: [], target: TARGET }), healthy),
       (error: unknown) =>
         error instanceof Error && error.message.includes('controlPlaneNodes is empty'),
     );

package/src/talos/talos-cluster-health.ts

@@ -22,13 +22,19 @@
  *   rollout would never learn the real problem was vault. Both `read` and `reconcile` now only
  *   catch `TalosError` (`talosctl health` itself ran and exited non-zero — the one case this
  *   family may honestly call "not healthy"); anything else propagates untouched.
+ * ★ `connection` IS A PASS-THROUGH so this resource is `ClusterLike`. Later rows take
+ *   `cluster: health`. The health check itself still uses `target` and `talosctl`; the field is
+ *   copied onto attributes and is not a credential. It is required: an optional field would not
+ *   satisfy `{ connection: Connection }`.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
+import type { TalosOpenBaoConnection } from './cluster-adapter.ts';
 import { mintTalosconfig } from './credentials.ts';
+import { literalConnectionRefusal, withLiteralConnection } from './literal-connection.ts';
 import type { TalosRequirements, WithTarget } from './resource.ts';
 import { TalosError, talosctl } from './talosctl.ts';
 
@@ -49,12 +55,19 @@ export interface ClusterHealthProps extends WithTarget {
    * on kube-proxy and CoreDNS, both of which wait on a CNI that does not exist yet at bootstrap.
    */
   after?: readonly unknown[];
+  /**
+   * Kubernetes connection copied onto attributes so a later row can take `cluster: this`.
+   * Not read by the health check. Persist only a secret-free connection (`talos-openbao`).
+   */
+  connection: TalosOpenBaoConnection;
 }
 
 export interface ClusterHealthAttributes {
   healthy: boolean;
   controlPlaneNodes: string;
   workerNodes: string;
+  /** Same object as the prop. Makes these attributes `ClusterLike`. */
+  connection: TalosOpenBaoConnection;
 }
 
 export interface TalosClusterHealth extends Resource<
@@ -65,11 +78,34 @@ export interface TalosClusterHealth extends Resource<
   TalosRequirements
 > {}
 
-export const TalosClusterHealth = Resource<TalosClusterHealth>('Talos.ClusterHealth');
+// ⛔ Declaration-time literal guard: a fresh resource skips `diff` (see `withLiteralConnection`).
+export const TalosClusterHealth = withLiteralConnection(
+  Resource<TalosClusterHealth>('Talos.ClusterHealth'),
+);
 
 const nodeCsv = (nodes: readonly string[] | undefined) =>
   nodes === undefined || nodes.length === 0 ? '' : nodes.join(',');
 
+const attributes = (props: ClusterHealthProps, healthy: boolean): ClusterHealthAttributes => ({
+  connection: props.connection,
+  controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
+  healthy,
+  workerNodes: nodeCsv(props.workerNodes),
+});
+
+/**
+ * ⚠️ A ROW SAVED BEFORE `connection` EXISTED HAS NONE — `right` is `undefined` at runtime despite
+ *   the type, and reading `right.auth` threw on a healthy cluster. Missing means "update".
+ */
+const sameConnection = (
+  left: TalosOpenBaoConnection,
+  right: TalosOpenBaoConnection | undefined,
+): boolean =>
+  right?.auth?.kind === left.auth.kind &&
+  right.auth.uid === left.auth.uid &&
+  // ⚠️ A row that still carries the legacy `auth.cluster` alias must update, so it leaves state.
+  !Object.hasOwn(right.auth, 'cluster');
+
 const healthArgs = (props: ClusterHealthProps, waitTimeout: string) => {
   const args = ['health', '--wait-timeout', waitTimeout];
   const cp = nodeCsv(props.controlPlaneNodes);
@@ -113,11 +149,7 @@ const check = (props: ClusterHealthProps, waitTimeout: string) =>
         nodes: [contact],
         talosconfigPath: credential.talosconfigPath,
       });
-      return {
-        controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
-        healthy: true,
-        workerNodes: nodeCsv(props.workerNodes),
-      };
+      return attributes(props, true);
     }),
   );
 
@@ -132,13 +164,7 @@ const isTalosError = (cause: unknown): cause is TalosError => cause instanceof T
 /** ★ EXPORTED for talos-cluster-health.test.ts — see talos-bootstrap.ts's own note on the pattern. */
 export const readClusterHealth = (props: ClusterHealthProps) =>
   check(props, '5s').pipe(
-    Effect.catchIf(isTalosError, () =>
-      Effect.succeed({
-        controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
-        healthy: false,
-        workerNodes: nodeCsv(props.workerNodes),
-      }),
-    ),
+    Effect.catchIf(isTalosError, () => Effect.succeed(attributes(props, false))),
   );
 
 export const diffClusterHealth = (
@@ -146,9 +172,15 @@ export const diffClusterHealth = (
   output: ClusterHealthAttributes | undefined,
 ) =>
   Effect.gen(function* () {
+    // ⛔ `cluster: health` hands this connection to workloads: refuse an Output here, while it is
+    //   still an Input (`literal-connection.ts`).
+    const refused = literalConnectionRefusal((news as { connection?: unknown }).connection);
+    if (refused !== undefined) return yield* Effect.fail(refused);
     if (output === undefined || !isResolved(news)) return undefined;
     const live = yield* readClusterHealth(news);
-    if (live.healthy) return { action: 'noop' } as const;
+    if (live.healthy && sameConnection(live.connection, output.connection)) {
+      return { action: 'noop' } as const;
+    }
     return { action: 'update' } as const;
   });