@bitkyc08/opencodex 2.67.0 → 2.68.0-preview.20260927

package/src/client/connect.ts

@@ -8,6 +8,7 @@ import {
 import { hostname } from "node:os";
 import { atomicWriteFile, loadConfig, withConfigMutationLockSync } from "../config";
 import { claudeDesktopIntegrationEnabledNow } from "../codex/desired-state";
+import { siblingOfLivePort, siblingSkipMessage } from "../codex/sibling-start";
 import {
   inspectRemoteDesktopStore, readDesktopDisconnectReceipt, writeDesktopDisconnectReceipt,
   replaceRemoteDesktopCredential, restoreRemoteDesktopStore, finishRemoteDesktopCleanup,
@@ -22,6 +23,7 @@ import {
   injectCodexConfig,
   currentExternalCodexModelProvider,
   isCodexRoutingInjected,
+  standaloneCodexRoutingTarget,
   type CodexRoutingTarget,
 } from "../codex/inject";
 import {
@@ -44,6 +46,7 @@ import {
 import { MAX_REMOTE_CATALOG_BYTES } from "../server/catalog-download";
 import type {
   OcxClientConnectionConfig,
+  OcxConfig,
   OcxConnectedClientId,
 } from "../types";
 import {
@@ -169,20 +172,31 @@ function catalogMatchesFingerprint(body: string, fingerprint: string | undefined
   return createHash("sha256").update(body).digest("base64url") === fingerprint;
 }
 
-export function routingTarget(serverUrl: string, localPort?: number): CodexRoutingTarget & { link?: true } {
-  const baseUrl = localPort === undefined
-    ? `${serverUrl}/v1`
-    : (() => {
-      if (!Number.isInteger(localPort) || localPort < 1 || localPort > 65535) {
-        throw new Error("link mode requires a valid local config port");
-      }
-      return `http://localhost:${localPort}/v1`;
-    })();
+/**
+ * Codex routing for a connected client. A hub client points Codex at the hub with the admission
+ * token in `env_key`. A link Child (`localPort` given) keeps exactly the standalone loopback form,
+ * root `openai_base_url = "http://127.0.0.1:<port>/v1"` with no provider table and no `env_key`:
+ * its own listener relays to the Home and attaches the link key itself, so a GUI-launched Codex
+ * that never saw the key's environment variable still works, and joining changes no Codex bytes.
+ */
+export function routingTarget(
+  serverUrl: string,
+  localPort?: number,
+  config?: Pick<OcxConfig, "codexDesktopAuthless" | "codexClientCompaction">,
+): CodexRoutingTarget & { link?: true } {
+  if (localPort === undefined) {
+    return { baseUrl: `${serverUrl}/v1`, requiresAdmissionToken: true, tokenEnv: "OPENCODEX_API_AUTH_TOKEN" };
+  }
+  if (!Number.isInteger(localPort) || localPort < 1 || localPort > 65535) {
+    throw new Error("link mode requires a valid local config port");
+  }
   return {
-    baseUrl,
-    requiresAdmissionToken: true,
-    tokenEnv: "OPENCODEX_API_AUTH_TOKEN",
-    ...(localPort === undefined ? {} : { link: true as const }),
+    ...standaloneCodexRoutingTarget(localPort, {
+      hostname: "127.0.0.1",
+      codexDesktopAuthless: config?.codexDesktopAuthless,
+      codexClientCompaction: config?.codexClientCompaction,
+    }),
+    link: true as const,
   };
 }
 
@@ -538,6 +552,9 @@ export async function connectClient(
   let writtenCatalogFingerprint: string | null = null;
   let injectionCommitted = false;
   let committed = false;
+  // Before any catalog, journal, client-state or credential write: `CODEX_HOME` is shared with the
+  // live proxy a sibling instance runs beside, and connecting re-points it (`sibling-start.ts`).
+  if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
   try {
     linkMode = (options.transport ?? "hub") === "link";
     if (linkMode) {
@@ -655,7 +672,7 @@ export async function connectClient(
     }), deps.lifecycleLockDeps);
 
     const config = earlyConfig ?? loadConfig();
-    const target = routingTarget(serverUrl, linkMode ? config.port : undefined);
+    const target = routingTarget(serverUrl, linkMode ? config.port : undefined, config);
     const injectConfig = { ...config, syncResumeHistory: false };
     const preflight = await injectCodexConfig(config.port, injectConfig, {
       validateOnly: true,
@@ -750,6 +767,7 @@ export async function syncConnectedClient(
   _options: { restartCodex?: boolean } = {},
   deps: ClientConnectDeps = {},
 ): Promise<{ catalogWritten: boolean; cacheSynced: boolean; injected: boolean; stale: boolean }> {
+  if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
   const initial = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
     assertNoClientDisconnectPending();
     const state = readClientConnectionState();
@@ -796,7 +814,7 @@ export async function syncConnectedClient(
   if (next.selectedClients.includes("codex")) {
     const config = loadConfig();
     const result = await injectCodexConfig(config.port, { ...config, syncResumeHistory: false }, {
-      routingTarget: routingTarget(next.serverUrl, isLinkConnection(next) ? config.port : undefined), catalogPath: DEFAULT_CATALOG_PATH,
+      routingTarget: routingTarget(next.serverUrl, isLinkConnection(next) ? config.port : undefined, config), catalogPath: DEFAULT_CATALOG_PATH,
       journalOwner: { kind: "client", apiKeyId: next.apiKeyId }, beforeClientWrite,
     });
     if (!result.success || result.status === "skipped") throw new Error(result.message);
@@ -891,6 +909,7 @@ export async function disconnectClient(
   desktopRestoration?: "owned_projection" | "standard_fallback" | "selection_preserved";
   restartRequired: boolean;
 }> {
+  if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
   const keepCatalog = options.keepCatalog === true;
   const prepared = withClientLifecycleSync(held => withConfigMutationLockSync(() => {
     const read = readDesktopDisconnectReceipt();

package/src/client/link-ingress.ts

@@ -0,0 +1,102 @@
+import type { Server } from "bun";
+import { formatErrorResponse } from "../bridge";
+import { readServiceApiTokenState, type ServiceApiTokenState } from "../lib/service-secrets";
+import { linkRouteAllowed } from "../link/routes";
+import { isAllowedRequestOrigin, type RequestPolicyView } from "../server/auth-cors";
+import { relayLinkDataRequest, type LinkRelayDeps } from "./link-relay";
+
+/** How often an unavailable link key is looked for again. A valid key is never re-read. */
+export const LINK_KEY_RETRY_MS = 1_000;
+
+export interface LinkKeySourceDeps {
+  readToken?: () => ServiceApiTokenState;
+  now?: () => number;
+}
+
+/**
+ * The link key for relayed requests, read from the service token file once and then held in
+ * memory, so no data-plane request touches the disk. The file must still hold the key this
+ * connection committed (`tokenFingerprint`); anything else yields null. Only while the key is
+ * unavailable is the file read again, at most once per `LINK_KEY_RETRY_MS`. The key is never
+ * logged, returned in a response, or written anywhere.
+ */
+export function createLinkKeySource(expectedFingerprint: string, deps: LinkKeySourceDeps = {}): () => string | null {
+  const readToken = deps.readToken ?? readServiceApiTokenState;
+  const now = deps.now ?? Date.now;
+  let key: string | null = null;
+  let lastRead = 0;
+  const load = (): void => {
+    lastRead = now();
+    try {
+      const state = readToken();
+      key = state.kind === "present" && state.fingerprint === expectedFingerprint ? state.token : null;
+    } catch {
+      key = null;
+    }
+  };
+  load();
+  return () => {
+    if (key === null && now() - lastRead >= LINK_KEY_RETRY_MS) load();
+    return key;
+  };
+}
+
+export interface LinkIngress {
+  tunnelPort: number;
+  /** The listener's loopback policy: the standalone Host and Origin anti-rebinding gate. */
+  policy: RequestPolicyView;
+  linkKey: () => string | null;
+  relay?: LinkRelayDeps;
+}
+
+const RESPONSES_WEBSOCKET_DISABLED = "Responses WebSocket transport is disabled; use HTTP";
+
+/**
+ * Lift Bun's per-request idle timer for a relayed request, as the standalone does on its data
+ * routes (`disableResponsesRequestTimeout`). Without it the listener's idle limit cuts a quiet
+ * stretch of a long generation: an SSE gap between events, or a Home that holds a turn after
+ * its headers. The relay bounds the wait itself (header deadline, SSE idle limit, caller abort).
+ * It is a local call rather than the standalone helper's import, which would load the Responses
+ * WebSocket upstream modules into every Child.
+ */
+function liftRequestIdleTimer(req: Request, server: Pick<Server<unknown>, "timeout"> | undefined): void {
+  if (!server) return;
+  try { server.timeout(req, 0); } catch { /* the request may already be closed */ }
+}
+
+/**
+ * The link-mode data plane of the client machine listener. It answers only the requests it
+ * owns and returns null for everything else, which the listener handles as before.
+ *
+ * - A `/v1/responses` WebSocket upgrade gets 426, the answer codex-rs turns into an HTTP
+ *   fallback; the link never carries a WebSocket.
+ * - Every relayed route passes the standalone loopback Host/Origin gate before any upstream
+ *   fetch, so a rebinding or cross-site browser page cannot reach the Home through this port.
+ * - Without the committed link key nothing is fetched, and the caller gets
+ *   `503 link_credential_unavailable`.
+ * - `/readyz` stays local: it reports this listener, not the tunnel.
+ * - A relayed request is exempt from the listener's idle limit, like a standalone data route.
+ */
+export function handleLinkIngress(
+  req: Request,
+  url: URL,
+  ingress: LinkIngress,
+  server?: Pick<Server<unknown>, "timeout">,
+): Response | Promise<Response> | null {
+  const upgrade = req.headers.get("upgrade");
+  if (upgrade !== null) {
+    if (url.pathname !== "/v1/responses" || upgrade.trim().toLowerCase() !== "websocket") return null;
+    if (!isAllowedRequestOrigin(req, ingress.policy)) {
+      return formatErrorResponse(403, "origin_rejected", "WebSocket upgrade blocked: non-local Origin");
+    }
+    return formatErrorResponse(426, "upgrade_required", RESPONSES_WEBSOCKET_DISABLED);
+  }
+  if (url.pathname === "/readyz" || !linkRouteAllowed(url, req)) return null;
+  if (!isAllowedRequestOrigin(req, ingress.policy)) {
+    return formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked");
+  }
+  const admissionKey = ingress.linkKey();
+  if (!admissionKey) return Response.json({ error: "link_credential_unavailable" }, { status: 503 });
+  liftRequestIdleTimer(req, server);
+  return relayLinkDataRequest(req, { tunnelPort: ingress.tunnelPort, admissionKey }, ingress.relay);
+}

package/src/client/link-join.ts

@@ -1,9 +1,9 @@
 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 { isPortAvailable } from "../server/ports";
+import { isLinkPort, JOIN_TUNNEL_PORT_MAX, JOIN_TUNNEL_PORT_MIN } from "../link/ports";
+import { buildExecArgv, REMOTE_COMMAND_NOT_FOUND, remoteOcxArgv } from "../link/ssh-argv";
+import { sshFailureHint, sshRunnerErrorHint, type SshRunner, type SshRunResult } from "../link/ssh-runner";
 import { connectClient, type ClientConnectDeps } from "./connect";
 import {
   clearClientLinkState,
@@ -24,6 +24,7 @@ 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 JOIN_PORT_ATTEMPTS = 32;
 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}$/;
@@ -40,6 +41,7 @@ export type JoinFailureCode =
   | "host_confirmation_expired"
   | "join_port_failed"
   | "join_issue_failed"
+  | "remote_ocx_missing"
   | "join_tunnel_failed"
   | "admission_failed"
   | "join_connect_failed"
@@ -47,7 +49,8 @@ export type JoinFailureCode =
   | "join_restart_failed";
 
 export class ClientLinkJoinError extends Error {
-  constructor(readonly code: JoinFailureCode, readonly linkId?: string) {
+  /** `hint` is a bounded line from ssh stderr or the ssh runner's own failure, for the dashboard; it is not part of the message. */
+  constructor(readonly code: JoinFailureCode, readonly linkId?: string, readonly hint?: string) {
     super(linkId ? `${code}: ${linkId}` : code);
     this.name = "ClientLinkJoinError";
   }
@@ -118,6 +121,24 @@ function parseIssuedLink(stdout: string): IssuedLink | null {
   };
 }
 
+/**
+ * A free loopback port in the join range (`JOIN_TUNNEL_PORT_MIN`-`JOIN_TUNNEL_PORT_MAX`), tried at
+ * random so a fixed-port service on this computer is not hit every time.
+ */
+export async function chooseJoinTunnelPort(deps: {
+  isAvailable?: (port: number) => Promise<boolean>;
+  random?: () => number;
+} = {}): Promise<number> {
+  const isAvailable = deps.isAvailable ?? (port => isPortAvailable(port, "127.0.0.1"));
+  const random = deps.random ?? Math.random;
+  const span = JOIN_TUNNEL_PORT_MAX - JOIN_TUNNEL_PORT_MIN + 1;
+  for (let attempt = 0; attempt < JOIN_PORT_ATTEMPTS; attempt += 1) {
+    const port = JOIN_TUNNEL_PORT_MIN + Math.min(span - 1, Math.floor(random() * span));
+    if (await isAvailable(port)) return port;
+  }
+  throw new Error("no free port in the join tunnel range");
+}
+
 function localAlias(deps: ClientLinkJoinDeps): string {
   const raw = (deps.hostname ?? hostname)().trim();
   const normalized = raw.replace(/[^A-Za-z0-9_\.\-]/g, "-").replace(/^-+/, "").slice(0, 253);
@@ -148,7 +169,7 @@ async function revokeIssuedLink(deps: ClientLinkJoinDeps, linkId: string, alias
     const result = await deps.runner.run(
       buildExecArgv({
         alias,
-        argv: ["ocx", "link", "revoke", "--link-id", linkId],
+        argv: remoteOcxArgv(["link", "revoke", "--link-id", linkId]),
         knownHostsFile: deps.knownHostsFile,
       }),
       { timeoutMs: JOIN_REVOKE_TIMEOUT_MS },
@@ -240,7 +261,7 @@ export async function joinHome(deps: ClientLinkJoinDeps, input: { alias: string
   await compensateStaleSidecar(deps);
   let tunnelPort: number;
   try {
-    tunnelPort = await (deps.choosePort ?? (() => findAvailablePort(0, "127.0.0.1")))();
+    tunnelPort = await (deps.choosePort ?? (() => chooseJoinTunnelPort()))();
     if (!isLinkPort(tunnelPort)) throw new Error("invalid link port");
   } catch (error) {
     void error;
@@ -248,24 +269,24 @@ export async function joinHome(deps: ClientLinkJoinDeps, input: { alias: string
   }
 
   const thisAlias = localAlias(deps);
-  let issued: IssuedLink;
+  let result: SshRunResult;
   try {
-    const result = await deps.runner.run(
+    result = await deps.runner.run(
       buildExecArgv({
         alias: input.alias,
-        argv: ["ocx", "link", "issue", "--alias", thisAlias, "--tunnel-port", String(tunnelPort), "--json"],
+        argv: remoteOcxArgv(["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");
+    throw new ClientLinkJoinError("join_issue_failed", undefined, sshRunnerErrorHint(error));
   }
+  // Hints come from stderr only: a successful issue prints the new data key on stdout.
+  if (result.code === REMOTE_COMMAND_NOT_FOUND) throw new ClientLinkJoinError("remote_ocx_missing", undefined, sshFailureHint(result.stderr));
+  const parsed = result.code === 0 ? parseIssuedLink(result.stdout) : null;
+  if (!parsed) throw new ClientLinkJoinError("join_issue_failed", undefined, result.code === 0 ? undefined : sshFailureHint(result.stderr));
+  const issued: IssuedLink = parsed;
 
   let tunnel: ClientLinkTunnelHandle | null = null;
   try {