@linzumi/cli 0.0.4-beta → 0.0.6-beta

package/src/index.ts

@@ -13,13 +13,42 @@
   Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
   Relationship: Keeps default local runner identity collision-resistant for
   concurrent local starts.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Exposes the live stream flush interval as a runner option so
+  local users can tune Kandan persistence batching without changing the Codex
+  transcript protocol, and exposes explicit local preview forwarding ports as
+  capability metadata without creating an implicit tunnel.
 */
 import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
 import { runLocalCodexRunner, type RunnerOptions } from "./runner";
 import { writeCachedLocalRunnerToken } from "./authCache";
 import { resolveLocalRunnerToken } from "./authResolution";
 import { identityFromAccessToken } from "./channelSessionSupport";
-import { acquireLocalRunnerTokenDetails } from "./oauth";
+import {
+  assertConfiguredAllowedCwds,
+  parseAllowedCwdList,
+  parseAllowedPortList,
+} from "./localCapabilities";
+import {
+  acquireLocalRunnerTokenDetails,
+  fetchLocalRunnerStartTarget,
+  type LocalRunnerStartTarget,
+  validateLocalRunnerToken,
+} from "./oauth";
+import {
+  assertStartDependencies,
+  buildRunnerDependencyStatus,
+} from "./dependencyStatus";
+import { resolveEditorRuntime } from "./localEditorRuntime";
+import {
+  kandanTlsTrustFromEnv,
+  trustedFetch,
+  trustedWebSocketFactory,
+} from "./kandanTls";
 
 type FlagDefinition = {
   readonly kind: "value" | "boolean";
@@ -42,6 +71,10 @@ const flagDefinitions = new Map<string, FlagDefinition>([
   ["reasoning-effort", { kind: "value" }],
   ["sandbox", { kind: "value" }],
   ["approval-policy", { kind: "value" }],
+  ["stream-flush-ms", { kind: "value" }],
+  ["allowed-cwd", { kind: "value" }],
+  ["forward-port", { kind: "value" }],
+  ["code-server-bin", { kind: "value" }],
   ["fast", { kind: "boolean" }],
   ["log-file", { kind: "value" }],
   ["auth-file", { kind: "value" }],
@@ -53,7 +86,9 @@ if (import.meta.main) {
   try {
     await main(process.argv.slice(2));
   } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`,
+    );
     process.exit(1);
   }
 }
@@ -66,11 +101,16 @@ async function main(args: readonly string[]): Promise<void> {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write("linzumi 0.0.4-beta\n");
+      process.stdout.write("linzumi 0.0.6-beta\n");
       return;
     case "auth":
       await runAuthCommand(parsed.args);
       return;
+    case "start": {
+      const options = await parseStartRunnerArgs(parsed.args);
+      await runLocalCodexRunner(options);
+      return;
+    }
     case "run": {
       const options = await parseRunnerArgs(parsed.args);
       await runLocalCodexRunner(options);
@@ -83,6 +123,7 @@ type ParsedCommand =
   | { readonly command: "guide"; readonly args: readonly string[] }
   | { readonly command: "version"; readonly args: readonly string[] }
   | { readonly command: "auth"; readonly args: readonly string[] }
+  | { readonly command: "start"; readonly args: readonly string[] }
   | { readonly command: "run"; readonly args: readonly string[] };
 
 function parseCommand(args: readonly string[]): ParsedCommand {
@@ -102,6 +143,8 @@ function parseCommand(args: readonly string[]): ParsedCommand {
       return { command: "run", args: ["--help"] };
     case "auth":
       return { command: "auth", args: rest };
+    case "start":
+      return { command: "start", args: rest };
     case "run":
       return { command: "run", args: rest };
     default:
@@ -132,10 +175,170 @@ async function runAuthCommand(args: readonly string[]): Promise<void> {
     authFilePath: stringValue(values, "auth-file"),
   });
 
-  process.stdout.write(`Saved Kandan local runner auth for ${cached.kandanBaseUrl}\n`);
+  process.stdout.write(
+    `Saved Kandan local runner auth for ${cached.kandanBaseUrl}\n`,
+  );
+}
+
+type StartRunnerDeps = {
+  readonly resolveToken: typeof resolveLocalRunnerToken;
+  readonly fetchStartTarget: typeof fetchLocalRunnerStartTarget;
+  readonly validateToken: typeof validateLocalRunnerToken;
+  readonly buildDependencyStatus: typeof buildRunnerDependencyStatus;
+  readonly resolveEditorRuntime: typeof resolveEditorRuntime;
+};
+
+export async function parseStartRunnerArgs(
+  args: readonly string[],
+  deps: StartRunnerDeps = {
+    resolveToken: resolveLocalRunnerToken,
+    fetchStartTarget: fetchLocalRunnerStartTarget,
+    validateToken: validateLocalRunnerToken,
+    buildDependencyStatus: buildRunnerDependencyStatus,
+    resolveEditorRuntime,
+  },
+): Promise<RunnerOptions> {
+  const { cwdArg, flagArgs } = splitStartArgs(args);
+  const values = strictFlagValues(flagArgs);
+
+  if (values.get("help") === true) {
+    process.stdout.write(startHelpText());
+    process.exit(0);
+  }
+
+  rejectStartTargetingFlags(values);
+
+  const kandanUrl = stringValue(values, "kandan-url") ?? "wss://serve.kandanai.com";
+  const requestedCwd = resolveUserPath(cwdArg ?? process.cwd());
+  const allowedCwds = assertConfiguredAllowedCwds([requestedCwd]);
+  const cwd = allowedCwds[0] ?? requestedCwd;
+  const codexBin = stringValue(values, "codex-bin") ?? "codex";
+  const customCodeServerBin = stringValue(values, "code-server-bin");
+  const initialDependencyStatus = await deps.buildDependencyStatus({
+    cwd,
+    codexBin,
+    codeServerBin: customCodeServerBin,
+  });
+  assertStartDependencies(initialDependencyStatus);
+  const explicitToken = stringValue(values, "token");
+  const authFilePath = stringValue(values, "auth-file");
+  const callbackHost = stringValue(values, "oauth-callback-host");
+  const reportRejectedCachedToken = () => {
+    process.stderr.write(
+      "Cached Kandan local runner auth was rejected; starting OAuth.\n",
+    );
+  };
+  const token = await deps.resolveToken({
+    kandanUrl,
+    explicitToken,
+    onboarding: "start",
+    authFilePath,
+    callbackHost,
+    reportRejectedCachedToken,
+  });
+  const target = await deps.fetchStartTarget({ kandanUrl, accessToken: token });
+  const tokenMatchesTarget = await deps.validateToken({
+    kandanUrl,
+    accessToken: token,
+    workspaceSlug: target.workspaceSlug,
+    channelSlug: target.channelSlug,
+  });
+  const targetToken = tokenMatchesTarget
+    ? token
+    : await resolveStartTargetToken({
+        kandanUrl,
+        explicitToken,
+        target,
+        authFilePath,
+        callbackHost,
+        resolveToken: deps.resolveToken,
+        reportRejectedCachedToken,
+      });
+  const editorRuntime = await deps.resolveEditorRuntime({
+    kandanUrl,
+    token: targetToken,
+    customCodeServerBin,
+    fetchImpl: trustedFetch(kandanTlsTrustFromEnv()),
+  });
+  const dependencyStatus = await deps.buildDependencyStatus({
+    cwd,
+    codexBin,
+    codeServerBin: editorRuntime.codeServerBin,
+    editorRuntime: editorRuntime.status,
+  });
+  assertStartDependencies(dependencyStatus);
+
+  return {
+    kandanUrl,
+    token: targetToken,
+    runnerId: stringValue(values, "runner-id") ?? `runner-${randomUUID()}`,
+    cwd,
+    codexBin,
+    codexUrl: stringValue(values, "codex-url"),
+    launchTui: values.get("launch-tui") === true,
+    fast: values.get("fast") === true,
+    logFile: stringValue(values, "log-file"),
+    allowedCwds,
+    allowedForwardPorts: parseAllowedPortList(
+      stringValue(values, "forward-port"),
+    ),
+    codeServerBin: editorRuntime.codeServerBin,
+    editorRuntime: editorRuntime.runtime,
+    socketFactory: trustedWebSocketFactory(kandanTlsTrustFromEnv()),
+    dependencyStatus,
+    channelSession: {
+      workspaceSlug: target.workspaceSlug,
+      channelSlug: target.channelSlug,
+      kandanThreadId: stringValue(values, "kandan-thread-id"),
+      listenUser: stringValue(values, "listen-user") ?? defaultListenUserFromToken(targetToken),
+      model: stringValue(values, "model"),
+      reasoningEffort: stringValue(values, "reasoning-effort"),
+      sandbox: stringValue(values, "sandbox"),
+      approvalPolicy: stringValue(values, "approval-policy"),
+      streamFlushMs: positiveIntegerValue(values, "stream-flush-ms"),
+    },
+  };
+}
+
+async function resolveStartTargetToken(args: {
+  readonly kandanUrl: string;
+  readonly explicitToken?: string | undefined;
+  readonly target: LocalRunnerStartTarget;
+  readonly authFilePath?: string | undefined;
+  readonly callbackHost?: string | undefined;
+  readonly resolveToken: typeof resolveLocalRunnerToken;
+  readonly reportRejectedCachedToken: () => void;
+}): Promise<string> {
+  if (args.explicitToken !== undefined) {
+    throw new Error(
+      `provided local runner token is not scoped to ${args.target.workspaceSlug}/${args.target.channelSlug}`,
+    );
+  }
+
+  return await args.resolveToken({
+    kandanUrl: args.kandanUrl,
+    workspaceSlug: args.target.workspaceSlug,
+    channelSlug: args.target.channelSlug,
+    authFilePath: args.authFilePath,
+    callbackHost: args.callbackHost,
+    reportRejectedCachedToken: args.reportRejectedCachedToken,
+  });
 }
 
-export async function parseRunnerArgs(args: readonly string[]): Promise<RunnerOptions> {
+type RunnerArgsDeps = {
+  readonly resolveToken: typeof resolveLocalRunnerToken;
+  readonly buildDependencyStatus: typeof buildRunnerDependencyStatus;
+  readonly resolveEditorRuntime: typeof resolveEditorRuntime;
+};
+
+export async function parseRunnerArgs(
+  args: readonly string[],
+  deps: RunnerArgsDeps = {
+    resolveToken: resolveLocalRunnerToken,
+    buildDependencyStatus: buildRunnerDependencyStatus,
+    resolveEditorRuntime,
+  },
+): Promise<RunnerOptions> {
   const values = strictFlagValues(args);
 
   if (values.get("help") === true) {
@@ -144,37 +347,65 @@ export async function parseRunnerArgs(args: readonly string[]): Promise<RunnerOp
   }
 
   if (values.get("version") === true) {
-    process.stdout.write("linzumi 0.0.4-beta\n");
+    process.stdout.write("linzumi 0.0.6-beta\n");
     process.exit(0);
   }
 
   const channelTarget = parseChannelSessionTarget(values);
   const kandanUrl = required(values, "kandan-url");
+  const cwd = stringValue(values, "cwd") ?? process.cwd();
+  const codexBin = stringValue(values, "codex-bin") ?? "codex";
+  const customCodeServerBin = stringValue(values, "code-server-bin");
   const explicitToken = stringValue(values, "token");
-  const token = await resolveLocalRunnerToken({
-      kandanUrl,
-      explicitToken,
-      workspaceSlug: channelTarget?.workspaceSlug,
-      channelSlug: channelTarget?.channelSlug,
-      authFilePath: stringValue(values, "auth-file"),
-      callbackHost: stringValue(values, "oauth-callback-host"),
-      reportRejectedCachedToken: () => {
-        process.stderr.write("Cached Kandan local runner auth was rejected; starting OAuth.\n");
-      },
-    });
+  const token = await deps.resolveToken({
+    kandanUrl,
+    explicitToken,
+    workspaceSlug: channelTarget?.workspaceSlug,
+    channelSlug: channelTarget?.channelSlug,
+    authFilePath: stringValue(values, "auth-file"),
+    callbackHost: stringValue(values, "oauth-callback-host"),
+    reportRejectedCachedToken: () => {
+      process.stderr.write(
+        "Cached Kandan local runner auth was rejected; starting OAuth.\n",
+      );
+    },
+  });
   const channelSession = parseChannelSession(values, token, channelTarget);
+  const editorRuntime = await deps.resolveEditorRuntime({
+    kandanUrl,
+    token,
+    customCodeServerBin,
+    fetchImpl: trustedFetch(kandanTlsTrustFromEnv()),
+  });
+  const dependencyStatus = await deps.buildDependencyStatus({
+    cwd,
+    codexBin,
+    codeServerBin: editorRuntime.codeServerBin,
+    editorRuntime: editorRuntime.status,
+  });
+  assertStartDependencies(dependencyStatus);
 
   return {
     kandanUrl,
     token,
     runnerId: stringValue(values, "runner-id") ?? `runner-${randomUUID()}`,
-    cwd: stringValue(values, "cwd") ?? process.cwd(),
-    codexBin: stringValue(values, "codex-bin") ?? "codex",
+    cwd,
+    codexBin,
     codexUrl: stringValue(values, "codex-url"),
     launchTui: values.get("launch-tui") === true,
     fast: values.get("fast") === true,
     logFile: stringValue(values, "log-file"),
-    channelSession
+    allowedCwds: assertConfiguredAllowedCwds(
+      parseAllowedCwdList(stringValue(values, "allowed-cwd")),
+    ),
+    allowedForwardPorts: parseAllowedPortList(
+      stringValue(values, "forward-port"),
+    ),
+    codeServerBin: editorRuntime.codeServerBin,
+    editorRuntime: editorRuntime.runtime,
+    socketFactory: trustedWebSocketFactory(kandanTlsTrustFromEnv()),
+    dependencyStatus,
+    channelSession,
   };
 }
 
@@ -213,10 +444,78 @@ function strictFlagValues(args: readonly string[]): Map<string, string | true> {
   return values;
 }
 
+function splitStartArgs(args: readonly string[]): {
+  readonly cwdArg: string | undefined;
+  readonly flagArgs: readonly string[];
+} {
+  let cwdArg: string | undefined;
+  const flagArgs: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === undefined) {
+      continue;
+    }
+
+    if (!arg.startsWith("--")) {
+      if (cwdArg !== undefined) {
+        throw new Error("linzumi start accepts at most one folder path");
+      }
+
+      cwdArg = arg;
+      continue;
+    }
+
+    flagArgs.push(arg);
+    const key = arg.slice(2);
+    const definition = flagDefinitions.get(key);
+
+    if (definition?.kind === "value") {
+      const next = args[index + 1];
+
+      if (next !== undefined) {
+        flagArgs.push(next);
+        index += 1;
+      }
+    }
+  }
+
+  return { cwdArg, flagArgs };
+}
+
+function rejectStartTargetingFlags(values: Map<string, string | true>): void {
+  const unsupportedFlags = ["workspace", "channel"].filter((flag) =>
+    values.has(flag),
+  );
+
+  if (unsupportedFlags.length > 0) {
+    throw new Error(
+      `linzumi start chooses its workspace during browser onboarding; remove ${unsupportedFlags
+        .map((flag) => `--${flag}`)
+        .join(", ")} or use linzumi connect for an explicit workspace/channel.`,
+    );
+  }
+}
+
+function resolveUserPath(pathValue: string): string {
+  if (pathValue === "~") {
+    return homedir();
+  }
+
+  if (pathValue.startsWith("~/")) {
+    return resolve(homedir(), pathValue.slice(2));
+  }
+
+  return resolve(pathValue);
+}
+
 function parseChannelSession(
   values: Map<string, string | true>,
   token: string,
-  target: { readonly workspaceSlug: string; readonly channelSlug: string } | undefined,
+  target:
+    | { readonly workspaceSlug: string; readonly channelSlug: string }
+    | undefined,
 ): RunnerOptions["channelSession"] {
   if (target === undefined) {
     return undefined;
@@ -234,12 +533,15 @@ function parseChannelSession(
     reasoningEffort: stringValue(values, "reasoning-effort"),
     sandbox: stringValue(values, "sandbox"),
     approvalPolicy: stringValue(values, "approval-policy"),
+    streamFlushMs: positiveIntegerValue(values, "stream-flush-ms"),
   };
 }
 
 function parseChannelSessionTarget(
-  values: Map<string, string | true>
-): { readonly workspaceSlug: string; readonly channelSlug: string } | undefined {
+  values: Map<string, string | true>,
+):
+  | { readonly workspaceSlug: string; readonly channelSlug: string }
+  | undefined {
   return parseOptionalChannelTarget(values);
 }
 
@@ -250,12 +552,16 @@ function defaultListenUserFromToken(token: string): string {
     return username;
   }
 
-  throw new Error("missing --listen-user and authenticated user is unavailable");
+  throw new Error(
+    "missing --listen-user and authenticated user is unavailable",
+  );
 }
 
 function parseOptionalChannelTarget(
-  values: Map<string, string | true>
-): { readonly workspaceSlug: string; readonly channelSlug: string } | undefined {
+  values: Map<string, string | true>,
+):
+  | { readonly workspaceSlug: string; readonly channelSlug: string }
+  | undefined {
   const channel = stringValue(values, "channel");
   const workspace = stringValue(values, "workspace");
 
@@ -267,7 +573,7 @@ function parseOptionalChannelTarget(
     ? parseChannelPath(channel)
     : {
         workspaceSlug: workspace ?? required(values, "workspace"),
-        channelSlug: channel ?? required(values, "channel")
+        channelSlug: channel ?? required(values, "channel"),
       };
 }
 
@@ -289,7 +595,7 @@ function parseChannelPath(channel: string): {
 
   return {
     workspaceSlug: workspaceSlug.trim(),
-    channelSlug: channelSlug.trim()
+    channelSlug: channelSlug.trim(),
   };
 }
 
@@ -303,7 +609,10 @@ function required(values: Map<string, string | true>, key: string): string {
   return value;
 }
 
-function stringValue(values: Map<string, string | true>, key: string): string | undefined {
+function stringValue(
+  values: Map<string, string | true>,
+  key: string,
+): string | undefined {
   const value = values.get(key);
 
   if (typeof value === "string" && value.trim() !== "") {
@@ -313,11 +622,31 @@ function stringValue(values: Map<string, string | true>, key: string): string |
   return undefined;
 }
 
+function positiveIntegerValue(
+  values: Map<string, string | true>,
+  key: string,
+): number | undefined {
+  const value = stringValue(values, key);
+
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number(value);
+
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+
+  throw new Error(`--${key} must be a positive integer`);
+}
+
 function helpText(): string {
   return `Kandan local Codex runner
 
 Usage:
   linzumi
+  linzumi start <folder> [options]
   linzumi connect --kandan-url <ws-url> --workspace <slug> --channel <slug> [options]
   linzumi auth --kandan-url <ws-url> [--workspace <slug> --channel <slug>]
 
@@ -342,11 +671,17 @@ Codex:
   --reasoning-effort <value>  Reasoning effort requested for Codex and shown in Kandan
   --sandbox <value>           Sandbox metadata shown in Kandan
   --approval-policy <value>   Approval-policy metadata shown in Kandan
+  --stream-flush-ms <ms>      Batch live Codex deltas before Kandan persistence, default 150
   --fast                      Mark this runner as low-latency/fast in the availability message
   --log-file <path>           JSONL event log path, default <cwd>/.kandan-local-codex-runner.log
+  --allowed-cwd <paths>       Comma-separated roots where Kandan may start new local Codex sessions
+  --forward-port <ports>      Comma-separated local TCP ports Kandan may expose as authenticated previews
+  --code-server-bin <path>    Custom development code-server executable. The default editor runtime is downloaded from Kandan.
 
 Examples:
   Good:
+    linzumi start ~/
+    linzumi start ~/code/my-app --kandan-url wss://serve.kandanai.com
     linzumi connect --kandan-url wss://serve.kandanai.com --workspace linzumi --channel seans-playground --codex-bin codex --launch-tui
     linzumi connect --kandan-url wss://serve.kandanai.com --workspace linzumi --channel seans-playground --codex-bin codex --model gpt-5.5 --reasoning-effort low --fast --launch-tui
     linzumi auth --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground
@@ -354,17 +689,66 @@ Examples:
     linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --workspace default --channel seans-playground --cwd /tmp/kandan-runner-a
     linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground
     linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --channel default/seans-playground --listen-user all --launch-tui
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --allowed-cwd ~/code/linzumi,~/scratch
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --forward-port 3000,5173
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --allowed-cwd ~/code/linzumi
 
   Bad:
     linzumi connect --kandan-url ws://127.0.0.1:4160 --token not-a-jwt --workspace default --channel seans-playground
       Missing --listen-user and authenticated user is unavailable.
     linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --listen-users sean
       Invalid flag: use --listen-user.
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --allowed-cwd /does/not/exist
+      Invalid --allowed-cwd: allowed cwd roots must exist locally.
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --forward-port vite
+      Invalid --forward-port: value must be a TCP port from 1 to 65535.
+`;
+}
+
+function startHelpText(): string {
+  return `Linzumi one-command local runner
+
+Usage:
+  linzumi start <folder> [options]
+
+What it does:
+  Opens Kandan in your browser, creates or reuses your personal coding space,
+  grants a scoped local-runner token, and starts this computer as a runner for
+  Codex sessions, local previews, and the Kandan editor.
+
+Options:
+  --kandan-url <ws-url>       Kandan websocket base URL, default wss://serve.kandanai.com
+  --token <jwt>               Optional scoped local-runner token override
+  --auth-file <path>          Auth cache path, default ~/.kandan/auth.json
+  --oauth-callback-host <ip>  Callback host reachable by your browser
+  --runner-id <id>            Stable local runner id
+  --codex-bin <path>          Codex executable, default codex
+  --code-server-bin <path>    Custom development code-server executable. By default Kandan installs the approved editor runtime.
+  --listen-user <user|all>    User whose replies are accepted, default authenticated user
+  --model <name>              Model requested for Codex sessions
+  --reasoning-effort <value>  Reasoning effort requested for Codex sessions
+  --sandbox <value>           Sandbox metadata shown in Kandan
+  --approval-policy <value>   Approval-policy metadata shown in Kandan
+  --forward-port <ports>      Comma-separated local TCP ports Kandan may expose as previews
+  --fast                      Mark this runner as low-latency/fast in Kandan
+
+Examples:
+  linzumi start ~/
+  linzumi start ~/code/my-app --kandan-url ws://100.71.192.98:4162 --oauth-callback-host 100.71.192.98
 `;
 }
 
 function connectGuideText(): string {
-  return `linzumi connect
+  return `linzumi start
+
+Fastest path:
+  linzumi start ~/
+
+This opens Kandan in your browser, creates or reuses your personal coding
+space, and starts this computer as a local Codex runner.
+
+Advanced:
+  linzumi connect
 
 Connect this computer to Kandan as a local Codex runner.
 

package/src/kandanTls.ts

@@ -0,0 +1,86 @@
+/*
+- Date: 2026-04-29
+  Spec: kandan/server_v2/plans/2026-04-29-local-runner-editor-runtime-distribution-note.md
+  Relationship: Lets local proof and development runners trust a specific
+  Kandan CA certificate without disabling TLS verification globally.
+*/
+import { existsSync } from "node:fs";
+
+type BunRuntime = {
+  readonly file: (path: string) => unknown;
+};
+
+type TlsFetchInit = RequestInit & {
+  readonly tls?: {
+    readonly ca: unknown;
+  };
+};
+
+type TlsWebSocketOptions = {
+  readonly tls?: {
+    readonly ca: unknown;
+  };
+};
+
+export type KandanTlsTrust = {
+  readonly caFile: string;
+  readonly ca: unknown;
+};
+
+export function kandanTlsTrustFromEnv(): KandanTlsTrust | undefined {
+  return kandanTlsTrustFromCaFile(process.env.KANDAN_TLS_CA_FILE);
+}
+
+export function kandanTlsTrustFromCaFile(caFile: string | undefined): KandanTlsTrust | undefined {
+  if (caFile === undefined || caFile.trim() === "") {
+    return undefined;
+  }
+
+  const trimmed = caFile.trim();
+  if (!existsSync(trimmed)) {
+    throw new Error(`KANDAN_TLS_CA_FILE does not exist: ${trimmed}`);
+  }
+
+  const bun = (globalThis as unknown as { readonly Bun?: BunRuntime }).Bun;
+  if (bun === undefined) {
+    throw new Error("KANDAN_TLS_CA_FILE requires the Bun runtime");
+  }
+
+  return {
+    caFile: trimmed,
+    ca: bun.file(trimmed),
+  };
+}
+
+export function trustedFetch(
+  trust: KandanTlsTrust | undefined,
+): typeof fetch {
+  if (trust === undefined) {
+    return fetch;
+  }
+
+  return ((input: URL | RequestInfo, init?: RequestInit) => {
+    const request = {
+      ...(init ?? {}),
+      tls: {
+        ca: trust.ca,
+      },
+    } satisfies TlsFetchInit;
+    return fetch(input, request);
+  }) as typeof fetch;
+}
+
+export function trustedWebSocketFactory(
+  trust: KandanTlsTrust | undefined,
+): ((url: string) => WebSocket) | undefined {
+  if (trust === undefined) {
+    return undefined;
+  }
+
+  return (url) =>
+    new WebSocket(url, {
+      tls: {
+        ca: trust.ca,
+      },
+    } as TlsWebSocketOptions);
+}