@bitkyc08/opencodex 2.65.0-preview.20260925 → 2.66.0-preview.20260925

package/src/client/link-join.ts

@@ -0,0 +1,323 @@
+import { randomBytes } from "node:crypto";
+import { hostname } from "node:os";
+import { findAvailablePort } from "../server/ports";
+import { isLinkPort } from "../link/ports";
+import { buildExecArgv } from "../link/ssh-argv";
+import type { SshRunner } from "../link/ssh-runner";
+import { connectClient, type ClientConnectDeps } from "./connect";
+import {
+  clearClientLinkState,
+  clientLinkStatePath,
+  readClientLinkState,
+  writeClientLinkState,
+  type ClientLinkState,
+} from "./link-state";
+import { isLinkConnection, readClientConnectionState, type ClientConnectionState } from "./state";
+import {
+  spawnClientLinkTunnel,
+  type ClientLinkTunnelDeps,
+  type ClientLinkTunnelHandle,
+} from "./link-tunnel";
+import type { OcxConnectedClientId } from "../types";
+
+const JOIN_TUNNEL_READY_TIMEOUT_MS = 15_000;
+const JOIN_TUNNEL_POLL_MS = 100;
+const JOIN_REVOKE_TIMEOUT_MS = 30_000;
+const JOIN_CONFIRM_TTL_MS = 5 * 60_000;
+const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+const API_KEY_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/;
+const DATA_KEY = /^ocx_data_[0-9a-f]{40}$/;
+const VALID_ALIAS = /^[A-Za-z0-9_][A-Za-z0-9._@%+:\[\]-]{0,252}$/;
+
+export interface JoinConfirmedHost {
+  alias: string;
+  fingerprint: string;
+  probedAt: number;
+}
+
+export type JoinFailureCode =
+  | "host_not_confirmed"
+  | "host_confirmation_expired"
+  | "join_port_failed"
+  | "join_issue_failed"
+  | "join_tunnel_failed"
+  | "admission_failed"
+  | "join_connect_failed"
+  | "join_rollback_failed"
+  | "join_restart_failed";
+
+export class ClientLinkJoinError extends Error {
+  constructor(readonly code: JoinFailureCode, readonly linkId?: string) {
+    super(linkId ? `${code}: ${linkId}` : code);
+    this.name = "ClientLinkJoinError";
+  }
+}
+
+interface IssuedLink {
+  linkId: string;
+  apiKeyId: string;
+  key: string;
+  listenerPort: number;
+}
+
+export interface ClientLinkJoinDeps {
+  runner: SshRunner;
+  knownHostsFile: string;
+  confirmedHost?: JoinConfirmedHost;
+  configDir?: string;
+  choosePort?: () => Promise<number>;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  hostname?: () => string;
+  randomBytes?: (size: number) => Uint8Array;
+  fetchImpl?: typeof fetch;
+  spawnTunnel?: (spec: {
+    linkId: string;
+    alias: string;
+    tunnelPort: number;
+    peerListenerPort: number;
+  }, deps?: ClientLinkTunnelDeps) => ClientLinkTunnelHandle;
+  writeState?: (state: ClientLinkState) => void;
+  clearState?: (linkId: string) => void;
+  readSidecar?: () => ClientLinkState | null;
+  readConnectionState?: () => ClientConnectionState;
+  connect?: typeof connectClient;
+  connectDeps?: ClientConnectDeps;
+  selectedClients?: OcxConnectedClientId[];
+  /** Hands the standalone process to the client runtime once the join has committed. */
+  scheduleRestart: () => void;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validPort(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
+}
+
+function parseIssuedLink(stdout: string): IssuedLink | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout.trim());
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || Object.keys(parsed).length !== 4
+    || typeof parsed.linkId !== "string" || !LINK_ID.test(parsed.linkId)
+    || typeof parsed.apiKeyId !== "string" || !API_KEY_ID.test(parsed.apiKeyId)
+    || typeof parsed.key !== "string" || !DATA_KEY.test(parsed.key)
+    || !validPort(parsed.listenerPort)) {
+    return null;
+  }
+  return {
+    linkId: parsed.linkId,
+    apiKeyId: parsed.apiKeyId,
+    key: parsed.key,
+    listenerPort: parsed.listenerPort,
+  };
+}
+
+function localAlias(deps: ClientLinkJoinDeps): string {
+  const raw = (deps.hostname ?? hostname)().trim();
+  const normalized = raw.replace(/[^A-Za-z0-9_\.\-]/g, "-").replace(/^-+/, "").slice(0, 253);
+  if (VALID_ALIAS.test(normalized)) return normalized;
+  const bytes = (deps.randomBytes ?? randomBytes)(4);
+  return `client-${Buffer.from(bytes).toString("hex")}`;
+}
+
+function defaultWriteState(configDir: string | undefined, state: ClientLinkState): void {
+  writeClientLinkState(state, clientLinkStatePath(configDir));
+}
+
+function defaultClearState(configDir: string | undefined, linkId: string): void {
+  clearClientLinkState(linkId, clientLinkStatePath(configDir));
+}
+
+async function stopTunnel(tunnel: ClientLinkTunnelHandle | null): Promise<void> {
+  if (!tunnel) return;
+  try {
+    await tunnel.stop();
+  } catch (error) {
+    void error;
+  }
+}
+
+async function revokeIssuedLink(deps: ClientLinkJoinDeps, linkId: string, alias = deps.confirmedHost?.alias ?? ""): Promise<boolean> {
+  try {
+    const result = await deps.runner.run(
+      buildExecArgv({
+        alias,
+        argv: ["ocx", "link", "revoke", "--link-id", linkId],
+        knownHostsFile: deps.knownHostsFile,
+      }),
+      { timeoutMs: JOIN_REVOKE_TIMEOUT_MS },
+    );
+    return result.code === 0;
+  } catch (error) {
+    void error;
+    return false;
+  }
+}
+
+async function rollback(
+  deps: ClientLinkJoinDeps,
+  linkId: string,
+  tunnel: ClientLinkTunnelHandle | null,
+): Promise<void> {
+  await stopTunnel(tunnel);
+  if (!await revokeIssuedLink(deps, linkId)) throw new ClientLinkJoinError("join_rollback_failed", linkId);
+  try {
+    (deps.clearState ?? (id => defaultClearState(deps.configDir, id)))(linkId);
+  } catch (error) {
+    void error;
+  }
+}
+
+async function compensateStaleSidecar(deps: ClientLinkJoinDeps): Promise<void> {
+  let sidecar: ClientLinkState | null;
+  try {
+    sidecar = (deps.readSidecar ?? (() => readClientLinkState(clientLinkStatePath(deps.configDir))))();
+  } catch {
+    // A corrupt sidecar is overwritten by the next successful join.
+    return;
+  }
+  if (!sidecar) return;
+  let connection: ClientConnectionState;
+  try {
+    connection = (deps.readConnectionState ?? readClientConnectionState)();
+  } catch {
+    connection = { kind: "invalid", reason: "client connection state could not be read" };
+  }
+  if (connection.kind === "connected" && isLinkConnection(connection.value)
+    && connection.value.link?.linkId === sidecar.linkId) return;
+  if (!await revokeIssuedLink(deps, sidecar.linkId, sidecar.alias)) {
+    throw new ClientLinkJoinError("join_rollback_failed", sidecar.linkId);
+  }
+  try {
+    (deps.clearState ?? (linkId => defaultClearState(deps.configDir, linkId)))(sidecar.linkId);
+  } catch {
+    throw new ClientLinkJoinError("join_rollback_failed", sidecar.linkId);
+  }
+}
+
+async function waitForReady(
+  deps: ClientLinkJoinDeps,
+  port: number,
+  key: string,
+): Promise<void> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
+  const deadline = now() + JOIN_TUNNEL_READY_TIMEOUT_MS;
+  for (;;) {
+    try {
+      const response = await fetchImpl(`http://127.0.0.1:${port}/readyz`, {
+        headers: { "x-opencodex-api-key": key },
+      });
+      if (response.status === 200) return;
+      if (response.status === 401) throw new ClientLinkJoinError("admission_failed");
+    } catch (error) {
+      if (error instanceof ClientLinkJoinError) throw error;
+    }
+    const remaining = deadline - now();
+    if (remaining <= 0) throw new ClientLinkJoinError("join_tunnel_failed");
+    await sleep(Math.min(JOIN_TUNNEL_POLL_MS, remaining));
+  }
+}
+
+function requireConfirmedHost(deps: ClientLinkJoinDeps, alias: string): JoinConfirmedHost {
+  const confirmed = deps.confirmedHost;
+  if (!confirmed || confirmed.alias !== alias) throw new ClientLinkJoinError("host_not_confirmed");
+  if ((deps.now ?? Date.now)() - confirmed.probedAt > JOIN_CONFIRM_TTL_MS) {
+    throw new ClientLinkJoinError("host_confirmation_expired");
+  }
+  return confirmed;
+}
+
+export async function joinHome(deps: ClientLinkJoinDeps, input: { alias: string }): Promise<{ linkId: string; apiKeyId: string }> {
+  const confirmed = requireConfirmedHost(deps, input.alias);
+  await compensateStaleSidecar(deps);
+  let tunnelPort: number;
+  try {
+    tunnelPort = await (deps.choosePort ?? (() => findAvailablePort(0, "127.0.0.1")))();
+    if (!isLinkPort(tunnelPort)) throw new Error("invalid link port");
+  } catch (error) {
+    void error;
+    throw new ClientLinkJoinError("join_port_failed");
+  }
+
+  const thisAlias = localAlias(deps);
+  let issued: IssuedLink;
+  try {
+    const result = await deps.runner.run(
+      buildExecArgv({
+        alias: input.alias,
+        argv: ["ocx", "link", "issue", "--alias", thisAlias, "--tunnel-port", String(tunnelPort), "--json"],
+        knownHostsFile: deps.knownHostsFile,
+      }),
+      { timeoutMs: JOIN_REVOKE_TIMEOUT_MS },
+    );
+    if (result.code !== 0) throw new Error("issue failed");
+    const parsed = parseIssuedLink(result.stdout);
+    if (!parsed) throw new Error("invalid issue response");
+    issued = parsed;
+  } catch (error) {
+    void error;
+    throw new ClientLinkJoinError("join_issue_failed");
+  }
+
+  let tunnel: ClientLinkTunnelHandle | null = null;
+  try {
+    const state: ClientLinkState = {
+      linkId: issued.linkId,
+      alias: input.alias,
+      hubHostKeyFingerprint: confirmed.fingerprint,
+      peerListenerPort: issued.listenerPort,
+      tunnelPort,
+    };
+    (deps.writeState ?? (value => defaultWriteState(deps.configDir, value)))(state);
+    tunnel = (deps.spawnTunnel ?? spawnClientLinkTunnel)({
+      linkId: issued.linkId,
+      alias: input.alias,
+      tunnelPort,
+      peerListenerPort: issued.listenerPort,
+    }, {
+      runner: deps.runner,
+      configDir: deps.configDir,
+      knownHostsFile: deps.knownHostsFile,
+    });
+    await waitForReady(deps, tunnelPort, issued.key);
+  } catch (error) {
+    const code = error instanceof ClientLinkJoinError ? error.code : "join_tunnel_failed";
+    await rollback(deps, issued.linkId, tunnel);
+    throw new ClientLinkJoinError(code);
+  }
+
+  try {
+    const connect = deps.connect ?? connectClient;
+    await connect({
+      serverUrl: `http://127.0.0.1:${tunnelPort}`,
+      managementUrl: `http://127.0.0.1:${tunnelPort}`,
+      credential: { kind: "link", apiKeyId: issued.apiKeyId, key: issued.key },
+      transport: "link",
+      link: { tunnelPort, linkId: issued.linkId },
+      selectedClients: deps.selectedClients ?? ["codex", "claude"],
+      managementTransport: "direct",
+    }, {
+      fetchImpl: deps.fetchImpl,
+      ...deps.connectDeps,
+    });
+  } catch {
+    await rollback(deps, issued.linkId, tunnel);
+    throw new ClientLinkJoinError("join_connect_failed");
+  }
+
+  await stopTunnel(tunnel);
+  try {
+    deps.scheduleRestart();
+  } catch {
+    throw new ClientLinkJoinError("join_restart_failed", issued.linkId);
+  }
+  return { linkId: issued.linkId, apiKeyId: issued.apiKeyId };
+}

package/src/client/link-relay.ts

@@ -0,0 +1,241 @@
+import {
+  boundedRelayResponseStream,
+  filterRelayHeaders,
+  headersWithinLimit,
+  HUB_RELAY_DEFAULT_TIMEOUT_MS,
+  HUB_RELAY_REQUEST_BODY_MAX_BYTES,
+  HUB_RELAY_RESPONSE_BODY_MAX_BYTES,
+  readBoundedRelayRequestBody,
+  validateHubRelayRequestHeaders,
+} from "./hub-relay";
+import { linkRouteAllowed } from "../link/routes";
+import { isLinkPort } from "../link/ports";
+
+export interface LinkRelayTarget {
+  tunnelPort: number;
+}
+
+export interface LinkRelayClock {
+  setTimeout: typeof setTimeout;
+  clearTimeout: typeof clearTimeout;
+}
+
+export interface LinkRelayDeps {
+  fetchImpl?: typeof fetch;
+  clock?: LinkRelayClock;
+  timeoutMs?: number;
+  sseIdleTimeoutMs?: number;
+}
+
+export const LINK_RELAY_RETRY_AFTER_SECONDS = 1;
+export const LINK_RELAY_SSE_IDLE_TIMEOUT_MS = 300_000;
+
+const defaultClock: LinkRelayClock = {
+  setTimeout: globalThis.setTimeout,
+  clearTimeout: globalThis.clearTimeout,
+};
+const REQUEST_OMITTED_HEADERS = new Set(["content-length", "host"]);
+const RESPONSE_OMITTED_HEADERS = new Set(["content-encoding", "content-length"]);
+
+function jsonError(status: number, error: string, retry = false): Response {
+  const headers = retry ? { "Retry-After": String(LINK_RELAY_RETRY_AFTER_SECONDS) } : undefined;
+  return Response.json({ error }, { status, headers });
+}
+
+export function linkRelayDestination(url: URL, target: LinkRelayTarget): string {
+  if (!isLinkPort(target.tunnelPort)) {
+    throw new RangeError("invalid link tunnel port");
+  }
+  return `http://127.0.0.1:${target.tunnelPort}${url.pathname}${url.search}`;
+}
+
+export function forwardLinkRequestHeaders(source: Headers): Headers {
+  const validation = validateHubRelayRequestHeaders([...source]);
+  if (!validation.ok) return new Headers();
+  const omitted = new Set([...REQUEST_OMITTED_HEADERS, ...validation.connectionNamed]);
+  return filterRelayHeaders(source, undefined, omitted);
+}
+
+export function sanitizeLinkResponseHeaders(source: Headers): Headers {
+  const connectionNamed = new Set((source.get("connection") ?? "")
+    .split(",").map(value => value.trim().toLowerCase()).filter(Boolean));
+  return filterRelayHeaders(source, undefined, new Set([...RESPONSE_OMITTED_HEADERS, ...connectionNamed]));
+}
+
+function isSse(headers: Headers): boolean {
+  return headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() === "text/event-stream";
+}
+
+function idleBoundedStream(
+  body: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+  clock: LinkRelayClock,
+  idleTimeoutMs: number,
+  onIdle: () => void,
+  cleanup: () => void,
+): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let finished = false;
+  let closed = false;
+  let controllerRef: ReadableStreamDefaultController<Uint8Array> | undefined;
+  const clearIdleTimer = () => {
+    if (timer !== undefined) clock.clearTimeout(timer);
+    timer = undefined;
+  };
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    clearIdleTimer();
+    signal.removeEventListener("abort", onAbort);
+    cleanup();
+    try { reader.releaseLock(); } catch { /* a pending read may still own it */ }
+  };
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    try { controllerRef?.close(); } catch { /* the consumer may have cancelled */ }
+  };
+  const cancelUpstream = (reason: unknown, closeResponse: boolean) => {
+    if (finished) return;
+    clearIdleTimer();
+    try {
+      void reader.cancel(reason).catch(() => undefined).finally(() => {
+        finish();
+        if (closeResponse) close();
+      });
+    } catch {
+      finish();
+      if (closeResponse) close();
+    }
+  };
+  const onAbort = () => cancelUpstream(signal.reason, true);
+  const armIdleTimer = () => {
+    clearIdleTimer();
+    timer = clock.setTimeout(() => {
+      onIdle();
+      cancelUpstream(new DOMException("link relay SSE idle timeout", "TimeoutError"), true);
+    }, idleTimeoutMs);
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controllerRef = controller;
+      if (signal.aborted) onAbort();
+      else armIdleTimer();
+    },
+    async pull(controller) {
+      if (closed) return;
+      try {
+        const next = await reader.read();
+        if (next.done) {
+          finish();
+          closed = true;
+          controller.close();
+          return;
+        }
+        if (next.value.byteLength > 0) armIdleTimer();
+        controller.enqueue(next.value);
+      } catch (error) {
+        finish();
+        if (!closed) {
+          closed = true;
+          controller.error(error);
+        }
+      }
+    },
+    async cancel(reason) {
+      cancelUpstream(reason, false);
+    },
+  });
+}
+
+export async function relayLinkDataRequest(
+  req: Request,
+  target: LinkRelayTarget,
+  deps: LinkRelayDeps = {},
+): Promise<Response> {
+  const url = new URL(req.url);
+  if (!linkRouteAllowed(url, req)) return jsonError(404, "not_found");
+  let destination: string;
+  try { destination = linkRelayDestination(url, target); } catch { return jsonError(404, "not_found"); }
+  const validation = validateHubRelayRequestHeaders([...req.headers]);
+  if (!validation.ok) return jsonError(400, "link relay request headers refused");
+
+  let body: Uint8Array<ArrayBuffer> | null;
+  try {
+    body = req.method === "GET" || req.method === "HEAD"
+      ? null
+      : await readBoundedRelayRequestBody(req.body, req.headers.get("content-length"), HUB_RELAY_REQUEST_BODY_MAX_BYTES);
+  } catch {
+    return jsonError(413, "link relay request body too large");
+  }
+  const headers = forwardLinkRequestHeaders(req.headers);
+  if (!headersWithinLimit(headers)) {
+    return jsonError(431, "link relay request headers too large");
+  }
+
+  const relayAbort = new AbortController();
+  const timeoutMs = typeof deps.timeoutMs === "number" && Number.isFinite(deps.timeoutMs) && deps.timeoutMs > 0
+    ? Math.min(Math.floor(deps.timeoutMs), 120_000)
+    : HUB_RELAY_DEFAULT_TIMEOUT_MS;
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const onTimeout = () => relayAbort.abort(timeoutSignal.reason);
+  const onClientAbort = () => relayAbort.abort(req.signal.reason);
+  timeoutSignal.addEventListener("abort", onTimeout, { once: true });
+  req.signal.addEventListener("abort", onClientAbort, { once: true });
+  const cleanup = () => {
+    timeoutSignal.removeEventListener("abort", onTimeout);
+    req.signal.removeEventListener("abort", onClientAbort);
+  };
+  if (req.signal.aborted) onClientAbort();
+  else if (timeoutSignal.aborted) onTimeout();
+
+  let upstream: Response;
+  try {
+    const init: RequestInit & { duplex?: "half" } = {
+      method: req.method,
+      headers,
+      redirect: "manual",
+      signal: relayAbort.signal,
+      ...(body ? { body, duplex: "half" } : {}),
+    };
+    upstream = await (deps.fetchImpl ?? fetch)(destination, init);
+  } catch {
+    cleanup();
+    return jsonError(503, "link tunnel unavailable", true);
+  }
+  if (relayAbort.signal.aborted) {
+    cleanup();
+    try { await upstream.body?.cancel(); } catch { /* best effort */ }
+    return jsonError(503, "link tunnel unavailable", true);
+  }
+
+  const sse = isSse(upstream.headers);
+  const responseHeaders = sanitizeLinkResponseHeaders(upstream.headers);
+  if (!headersWithinLimit(responseHeaders)) {
+    cleanup();
+    try { await upstream.body?.cancel(); } catch { /* best effort */ }
+    return jsonError(502, "link relay response headers too large");
+  }
+  const declaredLength = upstream.headers.get("content-length");
+  if (!sse && declaredLength !== null && (!/^\d+$/.test(declaredLength)
+    || Number(declaredLength) > HUB_RELAY_RESPONSE_BODY_MAX_BYTES)) {
+    cleanup();
+    try { await upstream.body?.cancel(); } catch { /* best effort */ }
+    return jsonError(502, "link relay response body too large");
+  }
+  if (req.method === "HEAD" || !upstream.body) {
+    cleanup();
+    try { await upstream.body?.cancel(); } catch { /* best effort */ }
+    return new Response(null, { status: upstream.status, statusText: upstream.statusText, headers: responseHeaders });
+  }
+
+  // The handshake deadline ends once a response exists. The body owns cleanup after that.
+  timeoutSignal.removeEventListener("abort", onTimeout);
+  const responseBody = sse
+    ? idleBoundedStream(upstream.body, relayAbort.signal, deps.clock ?? defaultClock,
+      deps.sseIdleTimeoutMs ?? LINK_RELAY_SSE_IDLE_TIMEOUT_MS, () => relayAbort.abort(new DOMException("link relay SSE idle timeout", "TimeoutError")), cleanup)
+    : boundedRelayResponseStream(upstream.body, HUB_RELAY_RESPONSE_BODY_MAX_BYTES, relayAbort.signal, cleanup);
+  return new Response(responseBody, { status: upstream.status, statusText: upstream.statusText, headers: responseHeaders });
+}

package/src/client/link-state.ts

@@ -0,0 +1,110 @@
+import { chmodSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteFile, isMissingPathError } from "../config/atomic-write";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { hardenSecretDir } from "../lib/windows-secret-acl";
+import { linkDir } from "../link/paths";
+import { isLinkPort } from "../link/ports";
+import { assertSshAlias } from "../link/ssh-argv";
+
+/**
+ * The client-owned half of a client-initiated link, stored beside the hub-side `links.json`
+ * as `<configDir>/link/client-link.json` (directory 0700, file 0600). It holds no key: the
+ * data key lives only in the client connection config, which already owns it.
+ */
+export interface ClientLinkState {
+  linkId: string;
+  alias: string;
+  hubHostKeyFingerprint: string;
+  peerListenerPort: number;
+  tunnelPort: number;
+}
+
+export class ClientLinkStateError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ClientLinkStateError";
+  }
+}
+
+const FIELDS = new Set(["linkId", "alias", "hubHostKeyFingerprint", "peerListenerPort", "tunnelPort"]);
+const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+const FINGERPRINT = /^[A-Z0-9]+:[A-Za-z0-9+/=]{16,128}$/;
+
+const isPort = (value: unknown): value is number =>
+  typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
+
+export function clientLinkStatePath(configDir?: string): string {
+  return join(linkDir(configDir), "client-link.json");
+}
+
+export function parseClientLinkState(value: unknown): ClientLinkState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ClientLinkStateError("client-link.json is not an object");
+  const raw = value as Record<string, unknown>;
+  const fail = (field: string): never => { throw new ClientLinkStateError(`client-link.${field} is invalid`); };
+  for (const field of Object.keys(raw)) if (!FIELDS.has(field)) fail(field);
+  if (typeof raw.linkId !== "string" || !LINK_ID.test(raw.linkId)) fail("linkId");
+  if (typeof raw.alias !== "string") fail("alias");
+  try {
+    assertSshAlias(raw.alias as string);
+  } catch {
+    fail("alias");
+  }
+  if (typeof raw.hubHostKeyFingerprint !== "string" || !FINGERPRINT.test(raw.hubHostKeyFingerprint)) fail("hubHostKeyFingerprint");
+  if (!isPort(raw.peerListenerPort)) fail("peerListenerPort");
+  if (!isLinkPort(raw.tunnelPort)) fail("tunnelPort");
+  return {
+    linkId: raw.linkId as string,
+    alias: raw.alias as string,
+    hubHostKeyFingerprint: raw.hubHostKeyFingerprint as string,
+    peerListenerPort: raw.peerListenerPort as number,
+    tunnelPort: raw.tunnelPort as number,
+  };
+}
+
+/** `null` when no sidecar exists. A present but unreadable or malformed sidecar throws. */
+export function readClientLinkState(path: string = clientLinkStatePath()): ClientLinkState | null {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if (isMissingPathError(error)) return null;
+    throw error;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new ClientLinkStateError("client-link.json is not valid JSON", { cause: error });
+  }
+  return parseClientLinkState(raw);
+}
+
+export function writeClientLinkState(state: ClientLinkState, path: string = clientLinkStatePath()): void {
+  const normalized = parseClientLinkState(state);
+  const dir = dirname(path);
+  assertNotRealHomeUnderTest(dirname(dir));
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") hardenSecretDir(dir, { required: true });
+  else chmodSync(dir, 0o700);
+  // atomicWriteFile hardens its private temp on Windows before the rename, so only POSIX needs
+  // the explicit mode on the final path.
+  atomicWriteFile(path, `${JSON.stringify(normalized, null, 2)}\n`);
+  if (process.platform !== "win32") chmodSync(path, 0o600);
+}
+
+/**
+ * Deletes the sidecar only while it still names `expectedLinkId`. Returns false when there was
+ * nothing to delete or it belongs to a different link, which callers treat as "not ours".
+ */
+export function clearClientLinkState(expectedLinkId: string, path: string = clientLinkStatePath()): boolean {
+  const current = readClientLinkState(path);
+  if (!current || current.linkId !== expectedLinkId) return false;
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    if (isMissingPathError(error)) return false;
+    throw error;
+  }
+  return true;
+}