UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

422 lines (397 loc) • 16.9 kB
import { randomBytes } from "node:crypto"; import { hostname } from "node:os"; import { isPortAvailable } from "../server/ports"; import { scanListenPidsForAddress, type ListenPidScan } from "../server/port-reclaim"; 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, 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_TUNNEL_SPAWN_GRACE_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}$/; 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" | "remote_ocx_missing" | "join_tunnel_failed" | "admission_failed" | "join_connect_failed" | "join_rollback_failed" | "join_restart_failed"; export class ClientLinkJoinError extends Error { /** `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"; } } 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; /** * LISTEN-owner probe for the tunnel port; defaults to the netstat/lsof/ss scan. * Receives the loopback address the tunnel binds so listeners on unrelated * addresses do not confuse the readiness check. */ scanListenPids?: (port: number, address?: string) => ListenPidScan; 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, }; } /** * 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); 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: remoteOcxArgv(["link", "revoke", "--link-id", linkId]), knownHostsFile: deps.knownHostsFile, route: null, }), { 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); } } /** Wait for the live tunnel's authenticated readiness, retaining the deadline after failed ownership rechecks. */ async function waitForReady( deps: ClientLinkJoinDeps, tunnel: ClientLinkTunnelHandle, 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; const tunnelExited = tunnel.exited.then(() => { throw new ClientLinkJoinError("join_tunnel_failed"); }); await Promise.race([ tunnelExited, new Promise<void>(resolve => setTimeout(resolve, JOIN_TUNNEL_SPAWN_GRACE_MS)), ]); const listenPids = deps.scanListenPids ?? scanListenPidsForAddress; // The tunnel binds 127.0.0.1; a listener on a different loopback or interface address // never receives our requests, so ownership is only judged among sockets that serve it. const tunnelAddress = "127.0.0.1"; for (;;) { try { // A squatter answering the 401 challenge would otherwise collect the issued key: // the only listener allowed a keyed request is the ssh process we spawned — it owns // the port only after a successful bind, and ExitOnForwardFailure makes it exit when // it cannot take the port. An unverifiable scan stays "not ready", never a pass. const ownership = listenPids(port, tunnelAddress); if (ownership.ok && ownership.pids.length === 1 && ownership.pids[0] === tunnel.pid) { // Never follow redirects: a port occupant must not reroute the challenge, and a // redirected keyed request would carry the issued key to an unrelated listener. const probe = await Promise.race([ tunnelExited, fetchImpl(`http://127.0.0.1:${port}/readyz`, { redirect: "manual" }), ]); if (probe.status === 401) { // Ownership can flip between the probe and the keyed request (a squatter // takes the port after the tunnel dies). Re-scan in the same iteration and // skip only the keyed request on failure, not the deadline check and sleep. const recheck = listenPids(port, tunnelAddress); if (recheck.ok && recheck.pids.length === 1 && recheck.pids[0] === tunnel.pid) { const response = await Promise.race([ tunnelExited, fetchImpl(`http://127.0.0.1:${port}/readyz`, { headers: { "x-opencodex-api-key": key }, redirect: "manual", }), ]); 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 Promise.race([tunnelExited, 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; } /** Issue and enroll a confirmed Home link, compensating failures before committing the connection. */ 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 ?? (() => chooseJoinTunnelPort()))(); if (!isLinkPort(tunnelPort)) throw new Error("invalid link port"); } catch (error) { void error; throw new ClientLinkJoinError("join_port_failed"); } const thisAlias = localAlias(deps); let result: SshRunResult; try { const issue = (selectedClients?: OcxConnectedClientId[]) => deps.runner.run( buildExecArgv({ alias: input.alias, argv: remoteOcxArgv(["link", "issue", "--alias", thisAlias, "--tunnel-port", String(tunnelPort), ...(selectedClients ? ["--clients", selectedClients.join(",")] : []), "--json"]), knownHostsFile: deps.knownHostsFile, route: null, }), { timeoutMs: JOIN_REVOKE_TIMEOUT_MS }, ); result = await issue(deps.selectedClients); // The older CLI rejects unknown arguments before issuing a key. Retry only that // definite no-write result; keep the selection for the Child's existing fallback. if (deps.selectedClients && result.code === 2 && !result.stdout.trim() && /^(?:Error: )?Unexpected argument\(s\): --clients(?:\s|$)/m.test(result.stderr)) { result = await issue(); } } catch (error) { 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 { 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, tunnel, 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); } const enrollmentAbort = new AbortController(); let enrollmentFinished = false; try { if (!tunnel) throw new ClientLinkJoinError("join_tunnel_failed"); const connect = deps.connect ?? connectClient; // A tunnel exit cancels work; it is NOT a competing terminal result. The connect // transaction alone decides commit versus rollback, so an exit queued immediately // after commit cannot revoke a key that a connected client has already retained. void tunnel.exited.then(() => { if (!enrollmentFinished) enrollmentAbort.abort(new ClientLinkJoinError("join_tunnel_failed")); }); const signal = deps.connectDeps?.signal ? AbortSignal.any([enrollmentAbort.signal, deps.connectDeps.signal]) : enrollmentAbort.signal; // Observe a tunnel that exited after readiness before starting any enrollment write. await Promise.resolve(); signal.throwIfAborted(); 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"], selectedClientsExplicit: deps.selectedClients !== undefined, managementTransport: "direct", }, { fetchImpl: deps.fetchImpl, ...deps.connectDeps, signal, }); } catch (error) { // connectClient has drained its local rollback before rejecting. Only then can // the tunnel and the remote key be compensated without racing a late writer. const tunnelAborted = enrollmentAbort.signal.aborted; enrollmentFinished = true; await rollback(deps, issued.linkId, tunnel); throw new ClientLinkJoinError(tunnelAborted ? "join_tunnel_failed" : error instanceof ClientLinkJoinError ? error.code : "join_connect_failed"); } finally { enrollmentFinished = true; } await stopTunnel(tunnel); try { deps.scheduleRestart(); } catch { throw new ClientLinkJoinError("join_restart_failed", issued.linkId); } return { linkId: issued.linkId, apiKeyId: issued.apiKeyId }; }