@bitkyc08/opencodex 2.39.0 → 2.40.0

package/src/client/hub-relay.ts

@@ -0,0 +1,288 @@
+import { stripMachineAuthHeaders } from "./machine-auth";
+
+export interface HubRelayTarget {
+  managementUrl: string;
+  browserOrigin: string;
+}
+
+export const HUB_RELAY_REQUEST_BODY_MAX_BYTES = 4 * 1024 * 1024;
+export const HUB_RELAY_RESPONSE_BODY_MAX_BYTES = 16 * 1024 * 1024;
+export const HUB_RELAY_DEFAULT_TIMEOUT_MS = 15_000;
+export const HUB_RELAY_HEADER_MAX_BYTES = 64 * 1024;
+
+const ALLOWED_METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+const REQUEST_HEADERS = new Set([
+  "accept",
+  "accept-language",
+  "cache-control",
+  "content-type",
+  "if-match",
+  "if-modified-since",
+  "if-none-match",
+  "if-unmodified-since",
+  "origin",
+  "x-opencodex-api-key",
+  "x-opencodex-csrf-token",
+  "x-opencodex-gui-origin",
+]);
+const RESPONSE_HEADERS = new Set([
+  "cache-control",
+  "content-language",
+  "content-type",
+  "etag",
+  "expires",
+  "last-modified",
+  "pragma",
+  "retry-after",
+  "vary",
+]);
+const HOP_BY_HOP_HEADERS = new Set([
+  "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+  "te", "trailer", "transfer-encoding", "upgrade",
+]);
+
+export type HubRelayRawHeaderValidation =
+  | { ok: true; connectionNamed: Set<string> }
+  | { ok: false; reason: "smuggling" | "invalid" };
+
+export function validateHubRelayRequestHeaders(raw: readonly (readonly [string, string])[]): HubRelayRawHeaderValidation {
+  let contentLengths = 0;
+  let transferEncoding = false;
+  const connectionNamed = new Set<string>();
+  for (const [rawName, value] of raw) {
+    const name = rawName.trim().toLowerCase();
+    if (!name || /[\r\n]/.test(rawName) || /[\r\n]/.test(value)) return { ok: false, reason: "invalid" };
+    if (name === "content-length") {
+      contentLengths += 1;
+      if (!/^\d+$/.test(value.trim())) return { ok: false, reason: "smuggling" };
+    }
+    if (name === "transfer-encoding") transferEncoding = true;
+    if (name === "upgrade") return { ok: false, reason: "smuggling" };
+    if (name === "connection") {
+      for (const token of value.split(",")) {
+        const normalized = token.trim().toLowerCase();
+        if (normalized) connectionNamed.add(normalized);
+      }
+    }
+  }
+  if (transferEncoding || contentLengths > 1) return { ok: false, reason: "smuggling" };
+  return { ok: true, connectionNamed };
+}
+
+function relayError(status: number, error: string): Response {
+  return Response.json({ error }, { status });
+}
+
+function canonicalOrigin(value: string): string | null {
+  try {
+    const url = new URL(value);
+    if ((url.protocol !== "http:" && url.protocol !== "https:")
+      || url.username || url.password || url.pathname !== "/" || url.search || url.hash) return null;
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
+function relayDestination(suffix: string, target: HubRelayTarget, method: string): URL | null {
+  const origin = canonicalOrigin(target.managementUrl);
+  const browserOrigin = canonicalOrigin(target.browserOrigin);
+  if (!origin || !browserOrigin || !ALLOWED_METHODS.has(method)) return null;
+  if (!suffix.startsWith("/") || suffix.startsWith("//") || suffix.includes("\\") || suffix.includes("#")) return null;
+  if (/%(?:2f|5c)/i.test(suffix) || /%(?:2e)(?:%2e|\.)?/i.test(suffix)) return null;
+  const rawPath = suffix.split("?", 1)[0]!;
+  for (const segment of rawPath.split("/")) {
+    let decoded: string;
+    try { decoded = decodeURIComponent(segment); } catch { return null; }
+    if (decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\")) return null;
+  }
+  if (rawPath === "/opencodex-session") {
+    if (suffix !== rawPath || (method !== "GET" && method !== "POST")) return null;
+  } else if (!rawPath.startsWith("/api/")) {
+    return null;
+  }
+  let destination: URL;
+  try { destination = new URL(suffix, `${origin}/`); } catch { return null; }
+  if (destination.origin !== origin || destination.username || destination.password || destination.hash) return null;
+  if (destination.pathname !== rawPath) return null;
+  return destination;
+}
+
+async function boundedBody(
+  stream: ReadableStream<Uint8Array> | null,
+  declared: string | null,
+  limit: number,
+): Promise<Uint8Array<ArrayBuffer> | null> {
+  if (!stream) return null;
+  const contentLength = declared === null ? null : Number(declared);
+  if (contentLength !== null && (!Number.isSafeInteger(contentLength) || contentLength < 0 || contentLength > limit)) {
+    throw new RangeError("body_too_large");
+  }
+  const reader = stream.getReader();
+  const chunks: Uint8Array<ArrayBufferLike>[] = [];
+  let length = 0;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      length += next.value.byteLength;
+      if (length > limit) throw new RangeError("body_too_large");
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  // BodyInit requires an ArrayBuffer-backed view, not a SharedArrayBuffer-capable view.
+  const body: Uint8Array<ArrayBuffer> = new Uint8Array(new ArrayBuffer(length));
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+
+function filteredHeaders(source: Headers, allowlist: Set<string>, omitted: ReadonlySet<string> = new Set()): Headers {
+  const headers = new Headers();
+  for (const [name, value] of source) {
+    const normalized = name.toLowerCase();
+    if (allowlist.has(normalized) && !HOP_BY_HOP_HEADERS.has(normalized) && !omitted.has(normalized)) headers.append(name, value);
+  }
+  return headers;
+}
+
+function headersWithinLimit(headers: Headers): boolean {
+  let bytes = 0;
+  for (const [name, value] of headers) {
+    bytes += name.length + value.length + 4;
+    if (bytes > HUB_RELAY_HEADER_MAX_BYTES) return false;
+  }
+  return true;
+}
+
+function boundedRelayResponseStream(
+  body: ReadableStream<Uint8Array>,
+  limit: number,
+  signal: AbortSignal,
+): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  let bytes = 0;
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    signal.removeEventListener("abort", onAbort);
+    try { reader.releaseLock(); } catch { /* a pending read may still own it */ }
+  };
+  const onAbort = () => {
+    if (finished) return;
+    try { void reader.cancel(signal.reason).catch(() => undefined).finally(finish); }
+    catch { finish(); }
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  if (signal.aborted) onAbort();
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const next = await reader.read();
+        if (next.done) {
+          finish();
+          controller.close();
+          return;
+        }
+        bytes += next.value.byteLength;
+        if (bytes > limit) {
+          try { await reader.cancel(new RangeError("hub relay response body too large")); } catch { /* best effort */ }
+          finish();
+          controller.error(new RangeError("hub relay response body too large"));
+          return;
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        finish();
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      try { await reader.cancel(reason); } catch { /* best effort */ }
+      finish();
+    },
+  });
+}
+
+export async function relayHubManagementRequest(
+  req: Request,
+  suffix: string,
+  target: HubRelayTarget,
+  deps: { fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<Response> {
+  const method = req.method.toUpperCase();
+  const destination = relayDestination(suffix, target, method);
+  if (!destination) return relayError(404, "hub relay path refused");
+  const requestHeaderValidation = validateHubRelayRequestHeaders([...req.headers]);
+  if (!requestHeaderValidation.ok) return relayError(400, "hub relay request headers refused");
+
+  let body: Uint8Array<ArrayBuffer> | null;
+  try {
+    body = method === "GET" || method === "HEAD"
+      ? null
+      : await boundedBody(req.body, req.headers.get("content-length"), HUB_RELAY_REQUEST_BODY_MAX_BYTES);
+  } catch {
+    return relayError(413, "hub relay request body too large");
+  }
+
+  const stripped = stripMachineAuthHeaders(req.headers);
+  const headers = filteredHeaders(stripped, REQUEST_HEADERS, requestHeaderValidation.connectionNamed);
+  if (!headersWithinLimit(headers)) return relayError(431, "hub relay request headers too large");
+  const browserOrigin = canonicalOrigin(target.browserOrigin);
+  const mutation = method !== "GET" && method !== "HEAD";
+  const suppliedOrigin = headers.get("origin");
+  if (!browserOrigin || (mutation ? suppliedOrigin !== browserOrigin : suppliedOrigin !== null && suppliedOrigin !== browserOrigin)) {
+    return relayError(403, "hub relay browser origin refused");
+  }
+
+  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 signal = req.signal
+    ? AbortSignal.any([req.signal, timeoutSignal])
+    : timeoutSignal;
+  let upstream: Response;
+  try {
+    upstream = await (deps.fetchImpl ?? fetch)(destination, {
+      method,
+      headers,
+      ...(body ? { body } : {}),
+      redirect: "manual",
+      signal,
+    });
+  } catch {
+    return relayError(502, "hub relay unavailable");
+  }
+  if (upstream.status >= 300 && upstream.status < 400) {
+    try { await upstream.body?.cancel(); } catch { /* best effort */ }
+    return relayError(502, "hub relay redirect refused");
+  }
+
+  const responseConnectionNamed = new Set((upstream.headers.get("connection") ?? "").split(",").map(value => value.trim().toLowerCase()).filter(Boolean));
+  const responseHeaders = filteredHeaders(upstream.headers, RESPONSE_HEADERS, responseConnectionNamed);
+  if (!headersWithinLimit(responseHeaders)) {
+    try { await upstream.body?.cancel(); } catch { /* best effort */ }
+    return relayError(502, "hub relay response headers too large");
+  }
+  const declaredResponseLength = upstream.headers.get("content-length");
+  if (declaredResponseLength !== null && (!/^\d+$/.test(declaredResponseLength)
+    || Number(declaredResponseLength) > HUB_RELAY_RESPONSE_BODY_MAX_BYTES)) {
+    try { await upstream.body?.cancel(); } catch { /* best effort */ }
+    return relayError(502, "hub relay response body too large");
+  }
+  const responseBody = method === "HEAD" || !upstream.body
+    ? null
+    : boundedRelayResponseStream(upstream.body, HUB_RELAY_RESPONSE_BODY_MAX_BYTES, signal);
+  return new Response(responseBody, {
+    status: upstream.status,
+    statusText: upstream.statusText,
+    headers: responseHeaders,
+  });
+}

package/src/client/machine-api.ts

@@ -0,0 +1,139 @@
+import { journalOwner } from "../codex/journal";
+import { diagnoseCodexShim, installCodexShim, uninstallCodexShim } from "../codex/shim";
+import { readManagementJsonBody } from "../server/management/body";
+import type { OcxClientConnectionConfig } from "../types";
+import { disconnectClient, syncConnectedClient } from "./connect";
+
+export type HubReachability = "unknown" | "online" | "offline" | "unauthorized";
+
+export interface MachineStatusV1 {
+  mode: "client";
+  connected: true;
+  machineBase: string;
+  sharedBase: string;
+  sharedServerOrigin: string;
+  managementTransport: "direct" | "relay";
+  apiKeyId: string;
+  protocolVersion: 1;
+  connectedAt: string;
+  catalogSyncedAt?: string;
+  hubReachability: HubReachability;
+}
+
+export interface MachineApiDeps {
+  sync: typeof syncConnectedClient;
+  disconnect: typeof disconnectClient;
+  scheduleStandaloneRecycle: () => void;
+  hubReachability?: () => HubReachability;
+  setHubReachability?: (value: HubReachability) => void;
+}
+
+const defaultDeps: MachineApiDeps = {
+  sync: syncConnectedClient,
+  disconnect: disconnectClient,
+  scheduleStandaloneRecycle: () => {},
+};
+
+function strictObject(value: unknown, allowed: readonly string[]): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  return Object.keys(record).every(key => allowed.includes(key)) ? record : null;
+}
+
+async function jsonBody(req: Request): Promise<unknown | Response> {
+  try {
+    return await readManagementJsonBody(req);
+  } catch {
+    return Response.json({ error: "invalid JSON body" }, { status: 400 });
+  }
+}
+
+function statusPayload(req: Request, state: OcxClientConnectionConfig, deps: MachineApiDeps): MachineStatusV1 {
+  const machineBase = new URL(req.url).origin;
+  return {
+    mode: "client",
+    connected: true,
+    machineBase,
+    sharedBase: state.managementTransport === "relay"
+      ? `${machineBase}/api/machine/hub-relay`
+      : state.managementUrl,
+    sharedServerOrigin: state.managementUrl,
+    managementTransport: state.managementTransport,
+    apiKeyId: state.apiKeyId,
+    protocolVersion: state.protocolVersion,
+    connectedAt: state.connectedAt,
+    ...(state.catalogSyncedAt ? { catalogSyncedAt: state.catalogSyncedAt } : {}),
+    hubReachability: deps.hubReachability?.() ?? "unknown",
+  };
+}
+
+export async function handleMachineApi(
+  req: Request,
+  url: URL,
+  state: OcxClientConnectionConfig,
+  injected: MachineApiDeps = defaultDeps,
+): Promise<Response | null> {
+  const deps = { ...defaultDeps, ...injected };
+  if (url.pathname === "/api/machine/status" && req.method === "GET") {
+    return Response.json(statusPayload(req, state, deps), { headers: { "Cache-Control": "no-store" } });
+  }
+  if (url.pathname === "/api/machine/clients" && req.method === "GET") {
+    return Response.json({
+      selectedClients: [...state.selectedClients],
+      journalOwner: journalOwner(),
+      shim: diagnoseCodexShim(),
+    }, { headers: { "Cache-Control": "no-store" } });
+  }
+  if (url.pathname === "/api/machine/sync" && req.method === "POST") {
+    const body = await jsonBody(req);
+    if (body instanceof Response) return body;
+    const input = strictObject(body, ["restartCodex"]);
+    if (!input || (input.restartCodex !== undefined && typeof input.restartCodex !== "boolean")) {
+      return Response.json({ error: "invalid sync request" }, { status: 400 });
+    }
+    try {
+      const result = await deps.sync(
+        input.restartCodex === undefined ? {} : { restartCodex: input.restartCodex },
+      );
+      deps.setHubReachability?.("online");
+      return Response.json({ success: true, ...result });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "client sync failed";
+      deps.setHubReachability?.(/unauthor/i.test(message) ? "unauthorized" : "offline");
+      return Response.json({ success: false, error: message }, { status: 502 });
+    }
+  }
+  if (url.pathname === "/api/machine/shim" && req.method === "GET") {
+    return Response.json(diagnoseCodexShim(), { headers: { "Cache-Control": "no-store" } });
+  }
+  if (url.pathname === "/api/machine/shim" && req.method === "POST") {
+    const body = await jsonBody(req);
+    if (body instanceof Response) return body;
+    const input = strictObject(body, ["action"]);
+    if (!input || (input.action !== "install" && input.action !== "repair" && input.action !== "uninstall")) {
+      return Response.json({ error: "action must be install, repair, or uninstall" }, { status: 400 });
+    }
+    try {
+      const result = input.action === "uninstall" ? uninstallCodexShim() : installCodexShim();
+      return Response.json({ success: true, action: input.action, result, shim: diagnoseCodexShim() });
+    } catch (error) {
+      return Response.json({ success: false, error: error instanceof Error ? error.message : "shim action failed" }, { status: 409 });
+    }
+  }
+  if (url.pathname === "/api/machine/disconnect" && req.method === "POST") {
+    const body = await jsonBody(req);
+    if (body instanceof Response) return body;
+    const input = strictObject(body, ["keepCatalog"]);
+    if (!input || (input.keepCatalog !== undefined && typeof input.keepCatalog !== "boolean")) {
+      return Response.json({ error: "invalid disconnect request" }, { status: 400 });
+    }
+    try {
+      const result = await deps.disconnect(input.keepCatalog === undefined ? {} : { keepCatalog: input.keepCatalog });
+      deps.scheduleStandaloneRecycle();
+      return Response.json({ success: true, ...result }, { status: 202 });
+    } catch (error) {
+      return Response.json({ success: false, error: error instanceof Error ? error.message : "disconnect failed" }, { status: 409 });
+    }
+  }
+  return null;
+}

package/src/client/machine-auth.ts

@@ -0,0 +1,54 @@
+import type { OcxConfig } from "../types";
+import {
+  managementPrincipal,
+  requireManagementAuth,
+  type ManagementAuthState,
+} from "../server/management-auth";
+
+export const MACHINE_SESSION_HEADER = "x-opencodex-machine-session";
+export const MACHINE_GUI_ORIGIN_HEADER = "x-opencodex-machine-gui-origin";
+export const MACHINE_CSRF_HEADER = "x-opencodex-machine-csrf-token";
+
+const MACHINE_AUTH_HEADERS = [
+  MACHINE_SESSION_HEADER,
+  MACHINE_GUI_ORIGIN_HEADER,
+  MACHINE_CSRF_HEADER,
+] as const;
+
+function machinePrincipalRequest(req: Request): Request {
+  const headers = new Headers(req.headers);
+  const token = headers.get(MACHINE_SESSION_HEADER);
+  const browserOrigin = headers.get(MACHINE_GUI_ORIGIN_HEADER);
+  const csrf = headers.get(MACHINE_CSRF_HEADER);
+  headers.delete("authorization");
+  headers.delete("x-api-key");
+  headers.delete("x-opencodex-api-key");
+  headers.delete("x-opencodex-gui-origin");
+  headers.delete("x-opencodex-csrf-token");
+  if (token) headers.set("x-opencodex-api-key", token);
+  if (browserOrigin) {
+    headers.set("x-opencodex-gui-origin", browserOrigin);
+    headers.set("Origin", browserOrigin);
+  }
+  if (csrf) headers.set("x-opencodex-csrf-token", csrf);
+  return new Request(req.url, { method: req.method, headers, signal: req.signal });
+}
+
+export function requireMachineAuth(
+  req: Request,
+  state: ManagementAuthState,
+  config: OcxConfig,
+): Response | null {
+  const synthetic = machinePrincipalRequest(req);
+  const error = requireManagementAuth(synthetic, state, config);
+  if (error) return error;
+  return managementPrincipal(synthetic, state, config) === "gui-session"
+    ? null
+    : Response.json({ error: "opencodex machine GUI session required" }, { status: 401 });
+}
+
+export function stripMachineAuthHeaders(headers: Headers): Headers {
+  const stripped = new Headers(headers);
+  for (const name of MACHINE_AUTH_HEADERS) stripped.delete(name);
+  return stripped;
+}

package/src/client/machine-listener.ts

@@ -0,0 +1,143 @@
+import { readFileSync } from "node:fs";
+import type { Server } from "bun";
+import { loadConfig } from "../config";
+import { browserSecurityHeaders } from "../server/auth-cors";
+import { serveGuiFile, serveSessionBootstrap } from "../server/gui-static";
+import {
+  initializeManagementAuthState,
+  issueGuiSession,
+  managementPrincipal,
+  requireManagementAuth,
+  type ManagementAuthState,
+} from "../server/management-auth";
+import type { OcxClientConnectionConfig, OcxConfig } from "../types";
+import { disconnectClient, syncConnectedClient } from "./connect";
+import { readClientConnectionState } from "./state";
+import { handleMachineApi, type HubReachability, type MachineApiDeps } from "./machine-api";
+import { MACHINE_GUI_ORIGIN_HEADER, requireMachineAuth } from "./machine-auth";
+import { relayHubManagementRequest } from "./hub-relay";
+
+const VERSION = (() => {
+  try { return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string; }
+  catch { return "0.0.0"; }
+})();
+const GUI_SPA_PATHS = new Set([
+  "/dashboard", "/startup", "/providers", "/models", "/subagents",
+  "/logs", "/usage", "/storage", "/codex-set", "/integrations",
+]);
+
+export interface MachineListenerDeps {
+  state?: OcxClientConnectionConfig;
+  managementAuthState?: ManagementAuthState;
+  fetchImpl?: typeof fetch;
+  machineApi?: Partial<MachineApiDeps>;
+}
+
+function json404(req: Request): Response {
+  const url = new URL(req.url);
+  return Response.json({ error: "not_found", method: req.method, path: url.pathname }, { status: 404 });
+}
+
+function machinePolicyConfig(config: OcxConfig): OcxConfig {
+  return { ...config, hostname: "127.0.0.1" };
+}
+
+export function machineRouteAllowed(url: URL, req: Request, relayEnabled: boolean): boolean {
+  if (req.headers.get("upgrade")) return false;
+  const path = url.pathname;
+  if (req.method === "GET" && (path === "/healthz" || path === "/readyz" || path === "/" || path === "/opencodex-session")) return true;
+  if (req.method === "GET" && (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim")) return true;
+  if (req.method === "POST" && (path === "/api/machine/sync" || path === "/api/machine/shim" || path === "/api/machine/disconnect")) return true;
+  if (relayEnabled && path.startsWith("/api/machine/hub-relay/")) return true;
+  if (req.method !== "GET" || path.startsWith("/api/") || path.startsWith("/v1/")) return false;
+  return GUI_SPA_PATHS.has(path)
+    || path.startsWith("/integrations/")
+    || /\.(?:css|gif|ico|jpe?g|js|json|map|png|svg|webp|woff2?)$/i.test(path);
+}
+
+export function startMachineListener(
+  port?: number,
+  deps: MachineListenerDeps = {},
+): Server<unknown> {
+  const config = machinePolicyConfig(loadConfig());
+  const connection = deps.state ?? (() => {
+    const state = readClientConnectionState();
+    if (state.kind !== "connected") throw new Error(`machine listener requires connected client state, got ${state.kind}`);
+    return state.value;
+  })();
+  const managementAuth = deps.managementAuthState ?? initializeManagementAuthState(config);
+  let hubReachability: HubReachability = "unknown";
+  const machineApiDeps: MachineApiDeps = {
+    sync: deps.machineApi?.sync ?? syncConnectedClient,
+    disconnect: deps.machineApi?.disconnect ?? disconnectClient,
+    scheduleStandaloneRecycle: deps.machineApi?.scheduleStandaloneRecycle ?? (() => {
+      void import("./runtime").then(module => module.scheduleStandaloneRecycle());
+    }),
+    hubReachability: deps.machineApi?.hubReachability ?? (() => hubReachability),
+    setHubReachability: deps.machineApi?.setHubReachability ?? (value => { hubReachability = value; }),
+  };
+  const relayEnabled = connection.managementTransport === "relay";
+
+  return Bun.serve({
+    port: port ?? config.port ?? 10100,
+    hostname: "127.0.0.1",
+    async fetch(req, server) {
+      const url = new URL(req.url);
+      if (!machineRouteAllowed(url, req, relayEnabled)) return json404(req);
+      if (url.pathname === "/healthz" && req.method === "GET") {
+        return Response.json({ service: "opencodex", version: VERSION, role: "client", uptime: process.uptime(), pid: process.pid, port: server.port });
+      }
+      if (url.pathname === "/readyz" && req.method === "GET") {
+        return Response.json({ service: "opencodex", version: VERSION, role: "client", status: "ready", uptime: process.uptime(), pid: process.pid, port: server.port, protocolVersion: 1 });
+      }
+      if (url.pathname.startsWith("/api/machine/hub-relay/")) {
+        if (!relayEnabled) return json404(req);
+        const authError = requireMachineAuth(req, managementAuth, config);
+        if (authError) return authError;
+        const prefix = "/api/machine/hub-relay";
+        const suffix = `${url.pathname.slice(prefix.length)}${url.search}`;
+        const response = await relayHubManagementRequest(req, suffix, {
+          managementUrl: connection.managementUrl,
+          browserOrigin: req.headers.get(MACHINE_GUI_ORIGIN_HEADER) ?? req.headers.get("Origin") ?? "",
+        }, { fetchImpl: deps.fetchImpl });
+        if (response.status === 401) hubReachability = "unauthorized";
+        else if (response.status >= 500) hubReachability = "offline";
+        else hubReachability = "online";
+        return response;
+      }
+      if (url.pathname.startsWith("/api/machine/")) {
+        const authError = requireManagementAuth(req, managementAuth, config);
+        if (authError) return authError;
+        if (managementPrincipal(req, managementAuth, config) !== "gui-session") {
+          return Response.json({ error: "opencodex machine GUI session required" }, { status: 401 });
+        }
+        return await handleMachineApi(req, url, connection, machineApiDeps) ?? json404(req);
+      }
+
+      const session = (url.pathname === "/" || url.pathname === "/opencodex-session")
+        ? issueGuiSession(req, config, managementAuth, { trustedTailscaleIngress: false })
+        : null;
+      if (url.pathname === "/opencodex-session" && session) return serveSessionBootstrap(session);
+      // State the role, exactly as the standalone/hub server does (src/server/index.ts).
+      // The GUI decides whether a machine plane exists from this tag alone
+      // (gui/src/api-targets.ts `isConnectedRuntime`): without it `discoverApiTargets`
+      // returns standalone targets and never queries /api/machine/status, so a connected
+      // client renders as a plain install — no hub usage scope, no "this machine" panel,
+      // no connected-client list. This listener only ever serves a connected client, so
+      // the role is a constant here rather than a config read.
+      const gui = serveGuiFile(url.pathname, undefined, session ?? undefined, "client");
+      if (gui) return gui;
+      if (url.pathname === "/") {
+        return Response.json({
+          status: "ok",
+          service: "opencodex",
+          version: VERSION,
+          role: "client",
+          dashboard: { available: false, reason: "GUI build not found" },
+          endpoints: { health: "/healthz", ready: "/readyz", machine: "/api/machine/*" },
+        }, { headers: browserSecurityHeaders() });
+      }
+      return json404(req);
+    },
+  });
+}