@homeflare/alchemy 0.47.1 → 0.48.1

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

package/src/talos/talosctl.test.ts

@@ -0,0 +1,163 @@
+/**
+ * talosctl binary override. Fake spawner only — the named path is never executed (it only has to
+ * exist and be a trusted file; the fake answers `version --client` with the pinned version).
+ */
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, expect, test } from 'bun:test';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+import { trustBoundaryForTests } from './trust-boundary.seam.ts';
+import {
+  TALOSCTL_BINARY_ENV,
+  TalosBinaryRefused,
+  VERSION_PROBE_TIMEOUT,
+  talosctl,
+} from './talosctl.ts';
+
+// ⚠️ A real, vetted file in a private directory: the system `sh` or `bun` may be a symlink or live
+//   in a writable directory, which the vetting (correctly) refuses.
+const dir = mkdtempSync(join(tmpdir(), 'hf-talosctl-'));
+chmodSync(dir, 0o755);
+trustBoundaryForTests(dir);
+const fixture = join(dir, 'talosctl');
+writeFileSync(fixture, '#!/bin/sh\n', { mode: 0o755 });
+chmodSync(fixture, 0o755);
+afterAll(() => rmSync(dir, { force: true, recursive: true }));
+
+const run = (binary: string | undefined, calls: FakeCall[]) =>
+  Effect.runPromise(
+    Effect.provideService(
+      talosctl(['version'], {
+        talosconfigPath: 'unused-talosconfig.yaml',
+        ...(binary === undefined ? {} : { binary }),
+      }),
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(() => ({ stdout: 'Client: Tag: v1.14.2' }), calls),
+    ),
+  );
+
+const withEnv = async (value: string | undefined, body: () => Promise<void>) => {
+  const saved = process.env[TALOSCTL_BINARY_ENV];
+  if (value === undefined) delete process.env[TALOSCTL_BINARY_ENV];
+  else process.env[TALOSCTL_BINARY_ENV] = value;
+  try {
+    await body();
+  } finally {
+    if (saved === undefined) delete process.env[TALOSCTL_BINARY_ENV];
+    else process.env[TALOSCTL_BINARY_ENV] = saved;
+  }
+};
+
+test('the binary option wins over HF_TALOSCTL', async () => {
+  await withEnv('/definitely/not/here/talosctl', async () => {
+    const calls: FakeCall[] = [];
+    await run(fixture, calls);
+    expect(calls[0]?.command).toBe(fixture);
+  });
+});
+
+test('HF_TALOSCTL selects the binary when the option is omitted', async () => {
+  await withEnv(fixture, async () => {
+    const calls: FakeCall[] = [];
+    await run(undefined, calls);
+    expect(calls[0]?.command).toBe(fixture);
+  });
+});
+
+const withPath = async (value: string, body: () => Promise<void>) => {
+  const saved = process.env['PATH'];
+  process.env['PATH'] = value;
+  try {
+    await body();
+  } finally {
+    if (saved === undefined) delete process.env['PATH'];
+    else process.env['PATH'] = saved;
+  }
+};
+
+test('the default talosctl is resolved on PATH, vetted and version-checked by absolute path', async () => {
+  await withEnv(undefined, () =>
+    withPath(dir, async () => {
+      const calls: FakeCall[] = [];
+      await run(undefined, calls);
+      expect(calls.map((call) => call.command)).toEqual([fixture, fixture]);
+    }),
+  );
+});
+
+test('the default talosctl on PATH is refused when it reports another version', async () => {
+  await withEnv(undefined, () =>
+    withPath(dir, async () => {
+      const outcome = await Effect.runPromise(
+        Effect.provideService(
+          talosctl(['version'], { talosconfigPath: 'unused.yaml' }),
+          ChildProcessSpawner.ChildProcessSpawner,
+          fakeSpawner(() => ({ stdout: 'Client: Tag: v1.13.8' })),
+        ),
+      ).catch((e: unknown) => String(e));
+      expect(outcome).toContain('is not talosctl v1.14.2');
+    }),
+  );
+});
+
+test('a default talosctl that is not on PATH is refused, never run by bare name', async () => {
+  await withEnv(undefined, () =>
+    withPath(join(dir, 'empty'), async () => {
+      const calls: FakeCall[] = [];
+      const outcome = await run(undefined, calls).catch((e: unknown) => String(e));
+      expect(outcome).toContain('not found on PATH');
+      expect(calls).toEqual([]);
+    }),
+  );
+});
+
+test('a version probe that never answers is refused with a typed error, not awaited forever', async () => {
+  await withEnv(fixture, async () => {
+    const started = Date.now();
+    const outcome = await Effect.runPromise(
+      Effect.flip(
+        Effect.provideService(
+          // The default is 10 s (asserted below); a short override keeps the suite fast.
+          talosctl(['version'], {
+            talosconfigPath: 'unused.yaml',
+            versionProbeTimeout: '2 seconds',
+          }),
+          ChildProcessSpawner.ChildProcessSpawner,
+          ChildProcessSpawner.make(() => Effect.never),
+        ),
+      ),
+    );
+    expect(outcome).toBeInstanceOf(TalosBinaryRefused);
+    expect(outcome.message).toContain('did not answer within');
+    expect(Date.now() - started).toBeLessThan(4000);
+  });
+});
+
+test('the probe deadline is overridable per call and still fails closed', async () => {
+  await withEnv(fixture, async () => {
+    const started = Date.now();
+    const outcome = await Effect.runPromise(
+      Effect.flip(
+        Effect.provideService(
+          talosctl(['version'], {
+            talosconfigPath: 'unused.yaml',
+            versionProbeTimeout: '1 seconds',
+          }),
+          ChildProcessSpawner.ChildProcessSpawner,
+          ChildProcessSpawner.make(() => Effect.never),
+        ),
+      ),
+    );
+    expect(outcome).toBeInstanceOf(TalosBinaryRefused);
+    expect(outcome.message).toContain('did not answer within 1s');
+    expect(Date.now() - started).toBeLessThan(5000);
+  });
+});
+
+test('the default probe deadline is 10 s', () => {
+  expect(Duration.toSeconds(VERSION_PROBE_TIMEOUT)).toBe(10);
+});

package/src/talos/talosctl.ts

@@ -10,24 +10,65 @@
  * ⛔ DO NOT LOG STDOUT ON FAILURE. `talosctl kubeconfig` and error paths have been observed in the
  *   wild to include credential material; stderr is the safe diagnostic channel.
  */
+import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 import * as Stream from 'effect/Stream';
 import * as ChildProcess from 'effect/process/ChildProcess';
 import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
+import {
+  DEFAULT_TALOSCTL_BINARY,
+  TALOSCTL_BINARY_ENV,
+  TalosBinaryRefused,
+  checkBinaryPath,
+  resolveDefault,
+} from './talosctl-binary.ts';
+
+export { DEFAULT_TALOSCTL_BINARY, TALOSCTL_BINARY_ENV, TalosBinaryRefused };
 
 export class TalosError extends Error {
   constructor(
     readonly command: string,
     readonly exitCode: number,
     detail: string,
+    binary = DEFAULT_TALOSCTL_BINARY,
   ) {
-    super(`talosctl ${command} -> ${String(exitCode)}: ${detail}`);
+    super(`${binary} ${command} -> ${String(exitCode)}: ${detail}`);
     this.name = 'TalosError';
   }
 }
 
+/** The Talos client version this family is written against (`--client` of the pinned binary). */
+export const TALOSCTL_PINNED_VERSION = 'v1.14.2';
+
+const talosctlBinary = (override: string | undefined): string => {
+  const fromOption = override?.trim();
+  if (fromOption !== undefined && fromOption !== '') return fromOption;
+  const fromEnv = process.env[TALOSCTL_BINARY_ENV]?.trim();
+  if (fromEnv !== undefined && fromEnv !== '') return fromEnv;
+  return DEFAULT_TALOSCTL_BINARY;
+};
+
+/**
+ * ⛔ THE CHILD GETS A MINIMAL ENV, NOT `process.env`: BAO_TOKEN and every other credential in the
+ *   caller's environment stay out of an override that is only vetted by path and version. The
+ *   talosconfig travels as a file argument, so the binary needs nothing else but `PATH`/`HOME`.
+ */
+const talosctlEnv = (): Record<string, string> => {
+  const env: Record<string, string> = {};
+  for (const name of ['PATH', 'HOME', 'TMPDIR']) {
+    const value = process.env[name];
+    if (value !== undefined && value !== '') env[name] = value;
+  }
+  return env;
+};
+
 export type TalosRunOptions = {
   readonly talosconfigPath: string;
+  /**
+   * `talosctl` executable. Wins over {@link TALOSCTL_BINARY_ENV}.
+   * @default `talosctl` on `PATH`, or `HF_TALOSCTL` when that variable is set.
+   */
+  readonly binary?: string;
   readonly nodes?: readonly string[];
   readonly endpoints?: readonly string[];
   /**
@@ -37,23 +78,25 @@ export type TalosRunOptions = {
    * since insecure mode ignores the file's certs rather than requiring their absence.
    */
   readonly insecure?: boolean;
+  /**
+   * Deadline for the `version --client` probe of the binary; past it the binary is refused (fails
+   * closed, never skipped). A cold first run of the Go binary under CI load can exceed a tight
+   * limit, so a caller may raise it.
+   * @default {@link VERSION_PROBE_TIMEOUT} (10 s)
+   */
+  readonly versionProbeTimeout?: Duration.Input;
 };
 
-/** Run `talosctl <args…>`. Returns trimmed stdout, or '' when empty. */
-export const talosctl = (args: readonly string[], options: TalosRunOptions) =>
+const capture = (binary: string, argv: readonly string[]) =>
   Effect.gen(function* () {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-    const argv = [
-      ...args,
-      '--talosconfig',
-      options.talosconfigPath,
-      ...(options.nodes === undefined ? [] : ['--nodes', options.nodes.join(',')]),
-      ...(options.endpoints === undefined ? [] : ['--endpoints', options.endpoints.join(',')]),
-      ...(options.insecure === true ? ['--insecure'] : []),
-    ];
-    const result = yield* ChildProcess.make('talosctl', argv, {
-      detached: false,
-      extendEnv: true,
+    return yield* ChildProcess.make(binary, argv, {
+      // ⛔ No `detached: false`, plus `forceKillAfter`, as credentials.ts's bao spawn: the child
+      //   leads its own process group (killed whole on interrupt) and a SIGTERM-ignoring talosctl
+      //   is SIGKILLed 1 s later instead of blocking interruption.
+      env: talosctlEnv(),
+      extendEnv: false,
+      forceKillAfter: Duration.seconds(1),
       stderr: 'pipe',
       stdin: 'ignore',
       stdout: 'pipe',
@@ -79,11 +122,86 @@ export const talosctl = (args: readonly string[], options: TalosRunOptions) =>
       ),
       Effect.scoped,
     );
+  });
+
+/**
+ * ⛔ THE VERSION PROBE IS BOUNDED. `talosctl version --client` talks to no cluster and answers in
+ *   milliseconds, so a probe silent for this long is a hung or hostile binary: it is refused
+ *   (failed closed, typed) instead of parking the caller forever. Interrupting the scope kills the
+ *   child with its process group (proved against a real hanging child by talosctl-probe-kill.test.ts).
+ * ⚠️ 10 s, not 3 s: a cold first run of the Go binary under CI load can take seconds, and a
+ *   refusal there is a false alarm. Override per call with `TalosRunOptions.versionProbeTimeout`.
+ */
+export const VERSION_PROBE_TIMEOUT = Duration.seconds(10);
+
+/** ⚠️ EXACT TOKEN MATCH: `includes` would accept v1.14.20 for v1.14.2. */
+const reportsPinnedVersion = (stdout: string) =>
+  stdout.split(/[^\w.+-]+/).includes(TALOSCTL_PINNED_VERSION);
+
+/**
+ * ⛔ AN OVERRIDE MUST REPORT THE PINNED CLIENT VERSION (`version --client`, no talosconfig, so
+ *   nothing secret reaches an untrusted binary before it is vetted).
+ */
+const checkOverrideVersion = (
+  binary: string,
+  source: string,
+  timeout: Duration.Input = VERSION_PROBE_TIMEOUT,
+) =>
+  capture(binary, ['version', '--client']).pipe(
+    Effect.timeoutOrElse({
+      duration: timeout,
+      orElse: () =>
+        Effect.fail(
+          new TalosBinaryRefused(
+            'version --client',
+            `${source} did not answer within ${String(Duration.toSeconds(timeout))}s`,
+            binary,
+          ),
+        ),
+    }),
+    Effect.flatMap((out) =>
+      out.exitCode === 0 && reportsPinnedVersion(out.stdout)
+        ? Effect.void
+        : Effect.fail(
+            new TalosBinaryRefused(
+              'version --client',
+              `${source} is not talosctl ${TALOSCTL_PINNED_VERSION} (exit ${String(out.exitCode)})`,
+              binary,
+            ),
+          ),
+    ),
+  );
+
+/** Run `talosctl <args…>`. Returns trimmed stdout, or '' when empty. */
+export const talosctl = (args: readonly string[], options: TalosRunOptions) =>
+  Effect.gen(function* () {
+    const requested = talosctlBinary(options.binary);
+    const resolved =
+      requested === DEFAULT_TALOSCTL_BINARY ? yield* resolveDefault(requested) : requested;
+    const fromOption = options.binary?.trim();
+    const source =
+      requested === DEFAULT_TALOSCTL_BINARY
+        ? 'talosctl on PATH'
+        : fromOption !== undefined && fromOption !== ''
+          ? 'the `binary` option'
+          : TALOSCTL_BINARY_ENV;
+    // ⛔ Launch exactly the vetted canonical path, for the probe and the credentialed call alike.
+    const binary = yield* checkBinaryPath(resolved, source);
+    yield* checkOverrideVersion(binary, source, options.versionProbeTimeout);
+    const argv = [
+      ...args,
+      '--talosconfig',
+      options.talosconfigPath,
+      ...(options.nodes === undefined ? [] : ['--nodes', options.nodes.join(',')]),
+      ...(options.endpoints === undefined ? [] : ['--endpoints', options.endpoints.join(',')]),
+      ...(options.insecure === true ? ['--insecure'] : []),
+    ];
+    const result = yield* capture(binary, argv);
 
     const command = args.join(' ');
     if (result.exitCode !== 0) {
       return yield* Effect.fail(
-        new TalosError(command, result.exitCode, result.stderr.slice(0, 300)),
+        new TalosError(command, result.exitCode, result.stderr.slice(0, 300), binary),
       );
     }
     return result.stdout;

package/src/talos/trust-boundary.test.ts

@@ -0,0 +1,17 @@
+/**
+ * The shipped trust-boundary surface. ⛔ The talosctl ancestor walk stops early above a
+ * registered directory, so anything that can register a directory can switch that vetting off —
+ * the module a consumer imports must therefore offer no way to register one. The register
+ * function lives in trust-boundary.seam.ts, which the published tarball excludes (package.json
+ * `files`, asserted by scripts/smoke.ts), so a non-test import of this module cannot reach it.
+ */
+import { expect, test } from 'bun:test';
+import * as shipped from './trust-boundary.ts';
+
+test('the shipped module exposes only the read-only boundary query', () => {
+  expect(Object.keys(shipped).sort()).toEqual(['isTrustedBoundary']);
+});
+
+test('isTrustedBoundary answers false for an unregistered directory', () => {
+  expect(shipped.isTrustedBoundary('/definitely/not/registered')).toBe(false);
+});

package/src/talos/trust-boundary.ts

@@ -0,0 +1,45 @@
+/**
+ * Which directories the talosctl ancestor walk (talosctl-binary.ts) may stop above.
+ *
+ * ⛔ READ-ONLY SHIPPED SURFACE, TEST-ONLY BY CONSTRUCTION. This is the only module the walk
+ *   consults, and its only export is the query below — the register function lives in
+ *   `trust-boundary.seam.ts`, which the published tarball does not contain (package.json `files`
+ *   excludes it; scripts/smoke.ts asserts that). A non-test import of this module therefore
+ *   cannot stop the walk early: `trustBoundaryForTests` is unreachable, the set it feeds is not
+ *   exported, and in a consumer install the dynamic pull below finds no seam, keeps the empty
+ *   set and every ancestor of a binary is vetted (fail closed). The seam is pulled with a
+ *   COMPUTED specifier so no bundler inlines it into the shipped module.
+ *
+ *   Plain syntax on purpose: fake-process.ts's graph is loaded under Node's strip-only
+ *   TypeScript (node-connect.harness.ts), which cannot load talosctl-binary.ts (parameter
+ *   properties). Not exported from the subpath index.
+ */
+import { realpathSync } from 'node:fs';
+
+let boundaries: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Canonical compare: the walk hands over a real path, but the boundary is a security decision —
+ * resolving again makes it independent of what a caller (now or future) cached. ⛔ A directory
+ * that cannot be resolved is answered FALSE, never thrown: it is certainly not a registered
+ * boundary, and the walk must treat "no boundary" as "vet everything" (fail closed).
+ */
+export const isTrustedBoundary = (dir: string): boolean => {
+  try {
+    return boundaries.has(realpathSync(dir));
+  } catch {
+    return false;
+  }
+};
+
+const seamSpecifier = './trust-boundary' + '.seam.ts';
+void import(seamSpecifier).then(
+  (seam: { boundaries: ReadonlySet<string> }) => {
+    boundaries = seam.boundaries;
+  },
+  () => {
+    // Published package: no seam in the tarball — the set stays empty and the walk is never
+    // shortened. In-repo this only fires if the seam file was deleted; boundary-dependent tests
+    // then fail loudly instead of passing short-handed.
+  },
+);

package/src/talos/values.ts

@@ -6,6 +6,7 @@
  *   reconcile time; tests use fixtures only.
  */
 import { createHash } from 'node:crypto';
+import { parseYaml } from './yaml-parse.ts';
 
 /** Trim trailing whitespace only — leading space in YAML is meaningful. */
 export const canonicalText = (text: string) => text.trimEnd();
@@ -39,12 +40,7 @@ export const configDigest = (text: string) => sha256(text);
  *   silently picking one would repeat the exact shipped bug.
  */
 export const extractMachineConfigSpec = (wrapperYaml: string): string | undefined => {
-  let doc: unknown;
-  try {
-    doc = Bun.YAML.parse(wrapperYaml);
-  } catch {
-    return undefined;
-  }
+  let doc = parseYaml(wrapperYaml);
   if (Array.isArray(doc)) {
     if (doc.length !== 1) return undefined;
     doc = doc[0];
@@ -77,12 +73,9 @@ export const kubeconfigMetadata = (
   yamlText: string,
   contextName: string,
 ): { endpoint: string; caFingerprint: string; clientFingerprint: string } | undefined => {
-  let doc: KubeconfigDoc;
-  try {
-    doc = Bun.YAML.parse(yamlText) as KubeconfigDoc;
-  } catch {
-    return undefined;
-  }
+  const parsed = parseYaml(yamlText);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+  const doc = parsed as KubeconfigDoc;
 
   const ctx = doc.contexts?.find((row) => row.name === contextName)?.context;
   const clusterName = ctx?.cluster;