@homeflare/alchemy 0.47.0 → 0.48.0

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

@@ -0,0 +1,96 @@
+/**
+ * `Talos.ClusterIdentity` — publishes the physical cluster's uid for the operator to pin. Fake `bao` and fake apiserver only; nothing is written.
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { fakeApiServer } from './fake-apiserver.ts';
+import { fakeSpawner } from './fake-process.ts';
+import {
+  diffClusterIdentity,
+  readClusterIdentity,
+  reconcileClusterIdentity,
+} from './talos-cluster-identity.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 props = { context: 'admin@c1', target: { cluster: 'c1', mount: 'talos-c1' } };
+const run = <A, E>(effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>) =>
+  Effect.runPromise(
+    Effect.provideService(
+      effect,
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(() => ({ stdout: JSON.stringify({ data: { data: { kubeconfig } } }) })),
+    ),
+  );
+
+test('reads the kube-system uid and publishes { uid }', async () => {
+  const api = fakeApiServer({ 'c1.cluster.invalid': 'uid-c1' });
+  try {
+    const out = await run(readClusterIdentity(props));
+    expect(out).toEqual({ uid: 'uid-c1' });
+    expect(api.seen).toEqual(['GET c1.cluster.invalid/api/v1/namespaces/kube-system']);
+  } finally {
+    api.restore();
+  }
+});
+
+const prior = { uid: 'uid-c1' } as const;
+
+test('an unchanged uid is a noop', async () => {
+  const api = fakeApiServer({ 'c1.cluster.invalid': 'uid-c1' });
+  try {
+    expect((await run(diffClusterIdentity(props, prior)))?.action).toBe('noop');
+  } finally {
+    api.restore();
+  }
+});
+
+// ⛔ A changed uid must never be an `update`: downstream workloads would be force-applied onto the
+//   new cluster (see the header of talos-cluster-identity.ts).
+test('a changed uid is refused in diff AND reconcile, never an update', async () => {
+  const moved = fakeApiServer({ 'c1.cluster.invalid': 'uid-c2' });
+  try {
+    const inDiff = await run(diffClusterIdentity(props, prior)).catch((e: unknown) => String(e));
+    expect(inDiff).toContain('TalosClusterMoved');
+    expect(inDiff).toContain('uid-c2');
+    const inReconcile = await run(reconcileClusterIdentity(props, prior)).catch((e: unknown) =>
+      String(e),
+    );
+    expect(inReconcile).toContain('TalosClusterMoved');
+  } finally {
+    moved.restore();
+  }
+});
+
+test('reconcile with no saved output publishes the live uid', async () => {
+  const api = fakeApiServer({ 'c1.cluster.invalid': 'uid-c2' });
+  try {
+    const out = await run(reconcileClusterIdentity(props, undefined));
+    expect(out.uid).toBe('uid-c2');
+  } finally {
+    api.restore();
+  }
+});
+
+test('an apiserver answering without a uid fails closed', async () => {
+  const api = fakeApiServer({});
+  try {
+    const failure = await run(readClusterIdentity(props)).catch((e: unknown) => String(e));
+    expect(failure).toContain('TalosClusterIdentityUnreadable');
+  } finally {
+    api.restore();
+  }
+});

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

@@ -0,0 +1,130 @@
+/**
+ * `Talos.ClusterIdentity` — a read-only resource that reports WHICH physical cluster a name means.
+ *
+ * ★ It reads the vault kubeconfig and GETs the kube-system Namespace once (`cluster-identity.ts`),
+ *   and publishes `{ uid }`. That is the BOOTSTRAP-THEN-PIN step (cluster-adapter.ts header): the
+ *   first deploy creates the cluster and this row with no workloads, the operator copies the
+ *   printed uid into the adapter config, and workloads take `talosOpenBaoConnection(<literal>)`.
+ *   ⛔ It publishes NO `connection`: an Output uid in a workload's auth is unresolved at plan time
+ *   and hides a cluster change from the plan (`talosOpenBaoConnection` explains the DELETE on B).
+ * ⛔ DRIFT REPAIR CANNOT LAUNDER A MOVE: `read` receives the persisted output and compares it, so
+ *   `Drift.repair` fails with `TalosClusterMoved` instead of reconciling B against B.
+ * ⛔ IT MUTATES NOTHING: no vault write, no cluster write, `delete` is a no-op. Its only effect is
+ *   the value it reports. `after` must reach past Cilium/CNI only if the apiserver needs it; the
+ *   kube-system namespace exists as soon as the apiserver answers.
+ * ⛔ A CHANGED UID IS REFUSED, NEVER AN UPDATE (`TalosClusterMoved`, in diff AND reconcile). This
+ *   resource declares no `stables`, so downstream the engine sees an unresolved Output, every
+ *   workload `diff` returns undefined and the engine plans an UPDATE, not a replace (Plan.ts
+ *   resourceExpr, `isResolved(news)` in Manifest.ts and HelmChart.ts). Reconcile would then
+ *   connect with the NEW uid and force-apply onto the new cluster while the old cluster's objects
+ *   are orphaned (an earlier comment here claimed a replace and a refusal at cleanup: it cannot
+ *   happen). A real move is a NEW identity resource per physical cluster.
+ */
+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 { TalosClusterMoved } from './cluster-adapter-errors.ts';
+import { readClusterUid } from './cluster-identity.ts';
+import { openTransport, talosVaultLocation, withConnectDeadline } from './cluster-transport.ts';
+import type { KubeconfigProps } from './kubeconfig.ts';
+import type { TalosRequirements } from './resource.ts';
+
+type KubeconfigSource = Pick<KubeconfigProps, 'context' | 'kubeconfigKey' | 'target'>;
+
+export interface ClusterIdentityProps extends KubeconfigSource {
+  /** Ordering edge: after `Talos.Kubeconfig` (the vault key must exist) and the apiserver is up. */
+  after?: readonly unknown[];
+}
+
+export interface ClusterIdentityAttributes {
+  /**
+   * The cluster's kube-system `metadata.uid`. Public. ⛔ NOT A `connection`: these attributes are
+   * deliberately not `ClusterLike`. Pin this value as a literal in `TalosOpenBaoAdapter` and build
+   * workloads' connection from that literal (bootstrap-then-pin, cluster-adapter.ts header).
+   */
+  uid: string;
+}
+
+export interface TalosClusterIdentity extends Resource<
+  'Talos.ClusterIdentity',
+  ClusterIdentityProps,
+  ClusterIdentityAttributes,
+  never,
+  TalosRequirements
+> {}
+
+export const TalosClusterIdentity = Resource<TalosClusterIdentity>('Talos.ClusterIdentity');
+
+/**
+ * ★ EXPORTED for talos-cluster-identity.test.ts — see talos-bootstrap.ts's note on the pattern.
+ * ⛔ A PERSISTED OUTPUT IS COMPARED HERE TOO, not only in reconcile: `Drift.repair` hands `read`
+ *   the persisted attributes, then reconciles `news: old.props, output: <what read returned>`.
+ *   A read that ignored the output returned the NEW uid, so the reconcile guard compared B with B
+ *   and saved it. Failing in read stops that path with `TalosClusterMoved`.
+ */
+export const readClusterIdentity = (
+  props: ClusterIdentityProps,
+  output?: ClusterIdentityAttributes,
+) =>
+  Effect.gen(function* () {
+    const cluster = props.target.cluster;
+    // ⛔ Same single deadline as connect: a hung `bao` must not hang the plan.
+    const uid = yield* withConnectDeadline(
+      cluster,
+      Effect.gen(function* () {
+        const transport = yield* openTransport(talosVaultLocation(props));
+        return yield* readClusterUid(cluster, transport);
+      }),
+    );
+    if (output !== undefined && uid !== output.uid) {
+      return yield* Effect.fail(new TalosClusterMoved({ cluster, live: uid, saved: output.uid }));
+    }
+    return { uid };
+  });
+
+/** ⛔ Fails closed when a saved uid exists and the live one differs. See the header. */
+export const reconcileClusterIdentity = (
+  props: ClusterIdentityProps,
+  output: ClusterIdentityAttributes | undefined,
+) => readClusterIdentity(props, output);
+
+export const diffClusterIdentity = (
+  news: Input<ClusterIdentityProps>,
+  output: ClusterIdentityAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    yield* reconcileClusterIdentity(news, output);
+    return { action: 'noop' } as const;
+  });
+
+const handlers = {
+  delete: () => Effect.void,
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<ClusterIdentityProps>;
+    output: ClusterIdentityAttributes | undefined;
+  }) => diffClusterIdentity(news, output),
+  list: () => Effect.succeed([]),
+  read: ({
+    olds,
+    output,
+  }: {
+    olds: ClusterIdentityProps;
+    output: ClusterIdentityAttributes | undefined;
+  }) => readClusterIdentity(olds, output),
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: ClusterIdentityProps;
+    output: ClusterIdentityAttributes | undefined;
+  }) => reconcileClusterIdentity(news, output),
+};
+
+export const TalosClusterIdentityProvider = () =>
+  Provider.effect(TalosClusterIdentity, Effect.succeed(TalosClusterIdentity.Provider.of(handlers)));

package/src/talos/talosctl-binary.ts

@@ -0,0 +1,150 @@
+/**
+ * Which `talosctl` runs, and whether that file may be trusted with the vault-minted talosconfig.
+ * Extracted from talosctl.ts (250-line cap).
+ *
+ * ⛔ A VETTING REFUSAL IS NOT A TalosError. `TalosError` means a `talosctl` run completed and
+ *   exited non-zero — the one outcome `Talos.ClusterHealth` may call "not healthy", and the one
+ *   `talosctlOrAlready` pattern-matches. A refused binary never ran, so it is its own class and
+ *   propagates through both untouched (hunt round 6: it read as `healthy: false`).
+ */
+import { accessSync, constants, lstatSync, realpathSync } from 'node:fs';
+import { basename, delimiter, dirname, isAbsolute, join } from 'node:path';
+import * as Effect from 'effect/Effect';
+import { isTrustedBoundary } from './trust-boundary.ts';
+
+/** `talosctl` on `PATH`. A lane pins another build with {@link TALOSCTL_BINARY_ENV} or `binary`. */
+export const DEFAULT_TALOSCTL_BINARY = 'talosctl';
+
+/**
+ * Executable override, read at call time. The Mac PATH measured 2026-10-05 has v1.13.8; the
+ * cluster is v1.14.2. Set this to the v1.14.2 binary. A per-call `binary` option wins.
+ */
+export const TALOSCTL_BINARY_ENV = 'HF_TALOSCTL';
+
+/** `bao` on `PATH` — the OpenBao CLI that fetches the cluster credentials at connect time. */
+export const DEFAULT_BAO_BINARY = 'bao';
+
+/** `bao` executable override, read at call time and vetted exactly like {@link TALOSCTL_BINARY_ENV}. */
+export const BAO_BINARY_ENV = 'HF_BAO';
+
+export class TalosBinaryRefused extends Error {
+  readonly command: string;
+  readonly binary: string;
+
+  constructor(command: string, detail: string, binary = DEFAULT_TALOSCTL_BINARY) {
+    super(`${binary} ${command} refused: ${detail}`);
+    this.name = 'TalosBinaryRefused';
+    this.command = command;
+    this.binary = binary;
+  }
+}
+
+/**
+ * ⛔ THE DEFAULT IS VETTED TOO (hunt round 5): a bare `talosctl` is resolved against `PATH` here
+ *   (not `Bun.which` — the published dist runs on Node, where that global is missing), symlinks are
+ *   followed, and the REAL file is vetted, version-checked and executed by absolute path.
+ */
+export const resolveDefault = (binary: string) =>
+  Effect.try({
+    try: () => {
+      for (const entry of (process.env['PATH'] ?? '').split(delimiter)) {
+        if (!isAbsolute(entry)) continue;
+        try {
+          const candidate = join(entry, binary);
+          accessSync(candidate, constants.X_OK);
+          return realpathSync(candidate);
+        } catch {
+          // not in this PATH entry — try the next
+        }
+      }
+      throw new Error('not found');
+    },
+    catch: () => new TalosBinaryRefused('binary check', `${binary} was not found on PATH`, binary),
+  });
+
+/**
+ * ⛔ EVERY DIRECTORY ON THE CANONICAL PATH must belong to the current user or root and must not be
+ *   group/world-writable (unless sticky: a sticky directory's entries cannot be renamed by others).
+ *   Round 5 checked only the immediate parent's mode, so an attacker-owned 0755 parent, or a
+ *   writable ancestor, could swap the file after the check. Returns the refusal reason, or
+ *   undefined when the whole chain is trusted.
+ */
+const untrustedAncestor = (file: string, uid: number | undefined): string | undefined => {
+  let dir = realpathSync(dirname(file));
+  for (;;) {
+    const stat = lstatSync(dir);
+    // The boundary directory itself is still vetted; only what lies ABOVE it is not (test seam,
+    // trust-boundary.seam.ts, which the published tarball does not carry).
+    const isBoundary = isTrustedBoundary(dir);
+    if (uid !== undefined && stat.uid !== uid && stat.uid !== 0) {
+      return `lives under a directory owned by another user (${dir})`;
+    }
+    const sticky = (stat.mode & 0o1000) !== 0;
+    if ((stat.mode & 0o022) !== 0 && !sticky) {
+      return `lives in a group- or world-writable directory (${dir})`;
+    }
+    const up = dirname(dir);
+    if (up === dir || isBoundary) return undefined;
+    dir = up;
+  }
+};
+
+/**
+ * ⛔ THE BINARY GETS THE VAULT-MINTED TALOSCONFIG: absolute, owned, not writable, executable, trusted
+ *   path. ⛔ RETURNS THE CANONICAL PATH (round 7): the override's directory is resolved ONCE
+ *   (realpath), that path and every ancestor of it are vetted, and the caller must launch exactly
+ *   the returned path for the version probe AND the credential-bearing call. Vetting the given path
+ *   and executing it again let a symlinked ancestor be repointed between the two launches. The leaf
+ *   itself is still lstat'd, so a symlink leaf is refused rather than followed.
+ */
+export const checkBinaryPath = (binary: string, source: string) => {
+  const refuse = (why: string) =>
+    Effect.fail(new TalosBinaryRefused('binary check', `${source} ${why}`, binary));
+  if (!isAbsolute(binary)) return refuse('must be an absolute path');
+  return Effect.try({
+    try: () => {
+      const canonical = join(realpathSync(dirname(binary)), basename(binary));
+      const file = lstatSync(canonical);
+      const uid = process.getuid?.();
+      return { canonical, file, uid, ancestor: untrustedAncestor(canonical, uid) };
+    },
+    catch: () => new TalosBinaryRefused('binary check', `${source} is not a readable file`, binary),
+  }).pipe(
+    Effect.flatMap(({ canonical, file, uid, ancestor }) => {
+      // ★ lstat, not stat: a symlink can be re-pointed by whoever owns the link, so none is accepted.
+      if (file.isSymbolicLink()) return refuse('must not be a symlink');
+      if (!file.isFile()) return refuse('is not a regular file');
+      // ⛔ FAIL CLOSED: with no process uid (a platform lacking getuid) ownership cannot be checked.
+      if (uid === undefined) return refuse('cannot be vetted: no process uid to check ownership');
+      if (ancestor !== undefined) return refuse(ancestor);
+      if (uid !== undefined && file.uid !== uid && file.uid !== 0) {
+        return refuse('must be owned by the current user or root');
+      }
+      if ((file.mode & 0o022) !== 0) return refuse('is group- or world-writable');
+      try {
+        accessSync(canonical, constants.X_OK);
+      } catch {
+        return refuse('is not executable');
+      }
+      return Effect.succeed(canonical);
+    }),
+  );
+};
+
+/**
+ * Resolve and vet the `bao` binary: {@link BAO_BINARY_ENV} wins over `bao` on `PATH`, and either is
+ * checked exactly like talosctl (absolute, owned, not writable, executable, not a symlink, every
+ * ancestor trusted). Returns the canonical path to launch.
+ *
+ * ⛔ `bao` FETCHES THE CLUSTER CREDENTIALS (`readKvValue` / `writeKvValue`), so an un-vetted `bao`
+ *   on a group/world-writable PATH folder (umask 002, the round-10 incident) could answer with an
+ *   attacker's kubeconfig. The same walk that vets `talosctl` must gate every `bao` launch.
+ */
+export const resolveBao = (): Effect.Effect<string, TalosBinaryRefused> => {
+  const override = process.env[BAO_BINARY_ENV]?.trim();
+  const requested = override !== undefined && override !== '' ? override : DEFAULT_BAO_BINARY;
+  const source = requested === DEFAULT_BAO_BINARY ? 'bao on PATH' : BAO_BINARY_ENV;
+  const resolved =
+    requested === DEFAULT_BAO_BINARY ? resolveDefault(requested) : Effect.succeed(requested);
+  return Effect.flatMap(resolved, (path) => checkBinaryPath(path, source));
+};

package/src/talos/talosctl-vetting.test.ts

@@ -0,0 +1,212 @@
+/**
+ * `HF_TALOSCTL` vetting: path (absolute, lstat, owner, parent directory, mode), exact version, and
+ * the minimal child env. Fake spawner only — the named file is never executed.
+ */
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { type FakeHandler, fakeSpawner } from './fake-process.ts';
+import { trustBoundaryForTests } from './trust-boundary.seam.ts';
+import { TalosBinaryRefused, TalosError, talosctl } from './talosctl.ts';
+
+const run = (binary: string, handler: FakeHandler = () => ({}), envs: unknown[] = []) =>
+  Effect.runPromise(
+    Effect.provideService(
+      talosctl(['version'], { binary, talosconfigPath: 'unused.yaml' }),
+      ChildProcessSpawner.ChildProcessSpawner,
+      ChildProcessSpawner.make((cmd) => {
+        if (cmd._tag === 'StandardCommand') envs.push(cmd.options);
+        return fakeSpawner(handler).spawn(cmd);
+      }),
+    ),
+  ).catch((e: unknown) => String(e));
+
+const dir = mkdtempSync(join(tmpdir(), 'hf-talosctl-vet-'));
+chmodSync(dir, 0o755);
+trustBoundaryForTests(dir);
+afterAll(() => rmSync(dir, { force: true, recursive: true }));
+const trusted = (name: string) => {
+  const path = join(dir, name);
+  writeFileSync(path, '#!/bin/sh\n', { mode: 0o755 });
+  chmodSync(path, 0o755);
+  return path;
+};
+const pinned =
+  (tag: string): FakeHandler =>
+  () => ({ stdout: `Client: Tag: ${tag}` });
+
+test('relative, missing, group/world-writable and symlinked overrides are refused', async () => {
+  expect(await run('relative/talosctl')).toContain('absolute');
+  expect(await run(join(dir, 'missing'))).toContain('not a readable file');
+  const bin = trusted('writable');
+  chmodSync(bin, 0o777);
+  expect(await run(bin)).toContain('group- or world-writable');
+  const link = join(dir, 'link');
+  symlinkSync(trusted('target'), link);
+  expect(await run(link)).toContain('symlink');
+});
+
+test('an override in a group- or world-writable directory is refused', async () => {
+  const open = join(dir, 'open');
+  mkdirSync(open);
+  const bin = join(open, 'talosctl');
+  writeFileSync(bin, '#!/bin/sh\n', { mode: 0o755 });
+  chmodSync(open, 0o777);
+  expect(await run(bin)).toContain('writable directory');
+});
+
+test('a writable ancestor of the override is refused (fails on 37d835a: only the parent was checked)', async () => {
+  const outer = join(dir, 'outer');
+  mkdirSync(join(outer, 'inner'), { recursive: true });
+  const bin = join(outer, 'inner', 'talosctl');
+  writeFileSync(bin, '#!/bin/sh\n', { mode: 0o755 });
+  chmodSync(join(outer, 'inner'), 0o755);
+  chmodSync(outer, 0o777);
+  expect(await run(bin, pinned('v1.14.2'))).toContain('writable directory');
+});
+
+test('the walk stops at a registered boundary but not above an unregistered one (guards the trust-boundary.seam wiring: if the seam is missing or the pull fails, the jailed shape is refused too)', async () => {
+  // Two identical shapes: `jailed/inner` is registered as a boundary, `free/inner` is not. The
+  // wrapper above each is group/world-writable, so only the registered one can pass: the
+  // boundary directory itself is still vetted (755), and its wrapper is never reached.
+  const jailed = join(dir, 'jailed');
+  const free = join(dir, 'free');
+  for (const wrapper of [jailed, free]) {
+    mkdirSync(join(wrapper, 'inner', 'bin'), { recursive: true });
+    // ⚠️ The BOUNDARY DIRECTORY is vetted too, so it must be 755 — not the umask default. Measured
+    //   2026-10-06 at umask 002 (CT100's default): `mkdirSync(…, { recursive: true })` creates the
+    //   intermediate `inner` group-writable (775), and the walk rightly refused the boundary itself
+    //   before ever reaching the 777 wrapper the test means to probe.
+    chmodSync(join(wrapper, 'inner'), 0o755);
+    chmodSync(join(wrapper, 'inner', 'bin'), 0o755);
+    writeFileSync(join(wrapper, 'inner', 'bin', 'talosctl'), '#!/bin/sh\n', { mode: 0o755 });
+    chmodSync(join(wrapper, 'inner', 'bin', 'talosctl'), 0o755);
+  }
+  trustBoundaryForTests(join(jailed, 'inner'));
+  chmodSync(jailed, 0o777);
+  chmodSync(free, 0o777);
+  expect(await run(join(jailed, 'inner', 'bin', 'talosctl'), pinned('v1.14.2'))).toBe(
+    'Client: Tag: v1.14.2',
+  );
+  expect(await run(join(free, 'inner', 'bin', 'talosctl'), pinned('v1.14.2'))).toContain(
+    'writable directory',
+  );
+});
+
+test('an ancestor owned by another user is refused (fails on 37d835a: parent owner never read)', async () => {
+  const owner = join(dir, 'foreign');
+  mkdirSync(owner);
+  const bin = join(owner, 'talosctl');
+  writeFileSync(bin, '#!/bin/sh\n', { mode: 0o755 });
+  chmodSync(owner, 0o755);
+  expect(await run(bin, pinned('v1.14.2'))).toBe('Client: Tag: v1.14.2');
+  const real = process.getuid;
+  // Everything here is ours; pretending to be another uid makes every directory foreign.
+  Object.defineProperty(process, 'getuid', { configurable: true, value: () => 4242 });
+  try {
+    expect(await run(bin, pinned('v1.14.2'))).toContain('directory owned by another user');
+  } finally {
+    Object.defineProperty(process, 'getuid', { configurable: true, value: real });
+  }
+});
+
+test('a non-executable override is refused', async () => {
+  const bin = join(dir, 'noexec');
+  writeFileSync(bin, '#!/bin/sh\n', { mode: 0o644 });
+  chmodSync(bin, 0o644);
+  expect(await run(bin, pinned('v1.14.2'))).toContain('not executable');
+});
+
+test('both launches use the canonical path even if an ancestor symlink is swapped (fails on ede1f6f)', async () => {
+  const real = join(dir, 'real-bin');
+  const evil = join(dir, 'evil-bin');
+  for (const d of [real, evil]) {
+    mkdirSync(d);
+    chmodSync(d, 0o755);
+    writeFileSync(join(d, 'talosctl'), '#!/bin/sh\n', { mode: 0o755 });
+    chmodSync(join(d, 'talosctl'), 0o755);
+  }
+  const via = join(dir, 'via');
+  symlinkSync(real, via);
+  const launched: string[] = [];
+  const out = await Effect.runPromise(
+    Effect.provideService(
+      talosctl(['version'], { binary: join(via, 'talosctl'), talosconfigPath: 'unused.yaml' }),
+      ChildProcessSpawner.ChildProcessSpawner,
+      ChildProcessSpawner.make((cmd) => {
+        if (cmd._tag === 'StandardCommand') launched.push(cmd.command);
+        // The attacker repoints the link right after the version probe.
+        rmSync(via);
+        symlinkSync(evil, via);
+        return fakeSpawner(pinned('v1.14.2')).spawn(cmd);
+      }),
+    ),
+  );
+  expect(out).toBe('Client: Tag: v1.14.2');
+  expect(launched.length).toBe(2);
+  expect(launched[0]).toBe(join(realpathSync(real), 'talosctl'));
+  expect(launched[1]).toBe(launched[0]);
+});
+
+test('a refusal is a TalosBinaryRefused naming its source, never a TalosError', async () => {
+  const outcome = await Effect.runPromise(
+    Effect.flip(
+      Effect.provideService(
+        talosctl(['version'], { binary: 'relative/talosctl', talosconfigPath: 'x' }),
+        ChildProcessSpawner.ChildProcessSpawner,
+        fakeSpawner(() => ({})),
+      ),
+    ),
+  );
+  expect(outcome).toBeInstanceOf(TalosBinaryRefused);
+  expect(outcome).not.toBeInstanceOf(TalosError);
+  expect(String(outcome)).toContain('the `binary` option');
+  expect(String(outcome)).not.toContain('HF_TALOSCTL');
+});
+
+test('no process uid means ownership cannot be checked: refused (fails on 19502c6: passed)', async () => {
+  const bin = trusted('no-getuid');
+  const real = process.getuid;
+  Object.defineProperty(process, 'getuid', { configurable: true, value: undefined });
+  try {
+    expect(await run(bin, pinned('v1.14.2'))).toContain('no process uid');
+  } finally {
+    Object.defineProperty(process, 'getuid', { configurable: true, value: real });
+  }
+});
+
+test('the version must match exactly: v1.14.20 and v1.13.8 fail, v1.14.2 passes', async () => {
+  const bin = trusted('versions');
+  expect(await run(bin, pinned('v1.14.20'))).toContain('v1.14.2');
+  expect(await run(bin, pinned('v1.13.8'))).toContain('v1.14.2');
+  expect(await run(bin, pinned('v1.14.2'))).toBe('Client: Tag: v1.14.2');
+});
+
+test('the child gets a minimal env: BAO_TOKEN never reaches the binary, even the version probe', async () => {
+  const saved = process.env['BAO_TOKEN'];
+  process.env['BAO_TOKEN'] = 'fake-test-token';
+  const options: unknown[] = [];
+  try {
+    await run(trusted('env'), pinned('v1.14.2'), options);
+  } finally {
+    if (saved === undefined) delete process.env['BAO_TOKEN'];
+    else process.env['BAO_TOKEN'] = saved;
+  }
+  expect(options.length).toBe(2);
+  for (const option of options as { env?: Record<string, string>; extendEnv?: boolean }[]) {
+    expect(option.extendEnv).toBe(false);
+    expect(Object.keys(option.env ?? {})).not.toContain('BAO_TOKEN');
+    expect(Object.keys(option.env ?? {})).not.toContain('BAO_ADDR');
+  }
+});