UNPKG

@bitkyc08/opencodex

Version:

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

620 lines (576 loc) • 33.6 kB
import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { mkdtempSync } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { assertSshAlias, buildExecArgv, buildFingerprintArgv, buildProbeArgv, REMOTE_COMMAND_NOT_FOUND, remoteOcxArgv } from "../../link/ssh-argv"; import { parseFingerprintLine } from "../../link/fingerprint"; import { awaitFirstAdmission } from "../../link/admission-wait"; import { linkKnownHostsPath, linkStorePath } from "../../link/paths"; import { clearCompensationFailed, compensationPath, markCompensationFailed, readCompensation } from "../../link/compensation"; import { loadHostCandidates } from "../../link/ssh-config"; import { newLinkId, readLinkStore, writeLinkStore, type LinkStore } from "../../link/store"; import { boundHint, createSshRunner, sshFailureHint, sshRunnerErrorHint, type SshRunner, type SshRunResult } from "../../link/ssh-runner"; import { projectLinkStatus, type LinkStatusDto } from "../../link/status-projection"; import { isLinkPort } from "../../link/ports"; import { joinHome, type ClientLinkJoinDeps } from "../../client/link-join"; import { clientLinkTunnelStatus } from "../../client/link-tunnel"; import type { ManagementContext } from "./context"; import { readManagementJsonBodyOr } from "./body"; import { issueApiKeyInProcess, revokeApiKeyInProcess, type IssuedApiKey } from "./oauth-account-routes"; import { acceptSystemRestart, resolveListenPort } from "./system-restart"; const PROBE_TTL_MS = 5 * 60_000; const APPLY_ADMISSION_TIMEOUT_MS = 15_000; const LINK_ID = /^lnk_[0-9a-f]{16}$/; // `ocx link` and `ocx connect --link` first shipped in 2.66.0; an older remote passes --version // and then fails at apply with remote_port_failed. const MIN_REMOTE_OCX = [2, 66, 0] as const; // A bounded semver shape: the parsed version reaches the confirm-host body and the outdated hint, // so the tail admits only a pre-release and build of semver identifier characters and must end // the token. Anything else attached to the version makes the output unrecognized. const REMOTE_OCX_VERSION = /^opencodex (\d{1,9})\.(\d{1,9})\.(\d{1,9})(-[0-9A-Za-z.-]{1,64})?(\+[0-9A-Za-z.-]{1,64})?(?=\s|$)/; const isLinkPath = (path: string): boolean => path === "/api/link" || path.startsWith("/api/link/"); export interface PendingLinkHost { alias: string; fingerprint: string; keyType: string; knownHostLine: string; probedAt: number; } export interface ConfirmedLinkHost extends PendingLinkHost { ocxVersion: string; } export interface LinkRouteListener { ensureStarted(): Promise<void>; status(): { state: "off" | "listening" | "failed"; port: number | null; reason: string | null }; close(): Promise<void>; onAuthenticatedCatalog(listener: (apiKeyId: string) => void): () => void; } export interface LinkRouteState { pendingHosts: Map<string, PendingLinkHost>; confirmedHosts?: Map<string, ConfirmedLinkHost>; compensationFailures?: Map<string, { since: string; reason: "compensation_failed" }>; supervisor: import("../../link/supervisor").LinkSupervisor; listener: LinkRouteListener; } const states = new WeakMap<object, LinkRouteState>(); // One process runs at most one join: a join ends by restarting this process as a client. let joinInProgress = false; /** * `hint` is one line bounded by `boundHint`: from ssh stderr (`sshFailureHint`), from the ssh * runner's own failure (`sshRunnerErrorHint`), or the parsed remote version for * `remote_ocx_outdated`. It is returned, never logged. */ function fail(code: string, message: string, status: number, hint?: string): Response { return Response.json({ error: { code, message, ...(hint ? { hint } : {}) } }, { status, headers: { "cache-control": "no-store" } }); } function isRecord(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); } function exactBody(body: unknown, keys: readonly string[]): Record<string, unknown> | null { if (!isRecord(body)) return null; const actual = Object.keys(body).sort(); const expected = [...keys].sort(); return actual.length === expected.length && actual.every((key, index) => key === expected[index]) ? body : null; } function port(value: unknown): value is number { return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535; } /** A paired GUI session. Only hub runtimes issue these. */ function pairedSession(ctx: ManagementContext): boolean { return ctx.principal === "gui-session" && ctx.sessionControl?.isPaired(ctx.req, ctx.config) === true; } /** * A paired session, or on a standalone runtime the current loopback-issued session that reached * the public listener bound to a loopback hostname. The loopback bootstrap mints that session * without a credential, so this is casual-path protection like POST /api/github/star, not a * secret-backed boundary like the admin token. Hubs keep the paired-only rule. Join admits this * session too: turning a Child on from its own dashboard is the point of the route, and the * dashboard warns first that the restart briefly interrupts running Codex turns. */ function dashboardSession(ctx: ManagementContext): boolean { if (pairedSession(ctx)) return true; return ctx.principal === "gui-session" && (ctx.config.runtimeRole ?? "standalone") === "standalone" && ctx.guiSessionIssuance === "loopback" && ctx.trustedLoopbackIngress && ctx.sessionControl?.isCurrent(ctx.req, ctx.config) === true; } function adminLoopback(ctx: ManagementContext): boolean { return ctx.principal === "admin-token" && ctx.trustedLoopbackIngress; } function auth(ctx: ManagementContext, kind: "dashboard" | "admin" | "either"): Response | null { if (ctx.guiSessionIssuance === "tailscale-identity") return fail("tailscale_session_refused", "Tailscale identity sessions cannot use link routes.", 403); const allowed = kind === "dashboard" ? dashboardSession(ctx) : kind === "admin" ? adminLoopback(ctx) : dashboardSession(ctx) || adminLoopback(ctx); return allowed ? null : fail("forbidden", "The required link authorization was not present.", 403); } /** * The client runtime a join restarts into binds exactly the configured port, with no fallback. * A standalone that runs elsewhere (`ocx start --port`, or a port fallback) would restart into a * proxy that cannot bind where Codex is routed, so it may not join. */ function joinPortMatches(ctx: ManagementContext): boolean { const live = (ctx.deps.liveListenPort ?? resolveListenPort)(); return live !== undefined && live === ctx.config.port; } /** Whether `POST /api/link/join` would pass its admission, role and port gates for this caller. */ function joinAvailable(ctx: ManagementContext): boolean { return dashboardSession(ctx) && (ctx.config.runtimeRole ?? "standalone") === "standalone" && joinPortMatches(ctx); } function runnerFor(ctx: ManagementContext): SshRunner { return ctx.deps.sshRunner ?? createSshRunner(); } function readStoreFor(ctx: ManagementContext): LinkStore { return ctx.deps.readLinkStore?.() ?? readLinkStore(linkStorePath()); } function writeStoreFor(ctx: ManagementContext, store: LinkStore): void { (ctx.deps.writeLinkStore ?? (value => writeLinkStore(linkStorePath(), value)))(store); } function stateFor(ctx: ManagementContext): LinkRouteState | null { const supervisor = ctx.deps.linkSupervisor?.(); const listener = ctx.deps.linkListener?.(); if (!supervisor || !listener) return null; const key = ctx.config as object; const existing = states.get(key); if (existing) return existing; const state: LinkRouteState = { pendingHosts: new Map(), confirmedHosts: new Map(), compensationFailures: new Map(), supervisor, listener, }; states.set(key, state); return state; } function knownHostsFile(ctx: ManagementContext): string { return ctx.deps.linkKnownHostsPath?.() ?? linkKnownHostsPath(); } function putKnownHost(path: string, alias: string, line: string): string { const before = (() => { try { return readFileSync(path, "utf8"); } catch { return ""; } })(); const lines = before.split(/\r?\n/).filter(value => value && !value.startsWith(`${alias} `) && !value.startsWith(`${alias},`)); lines.push(line.trim()); mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); writeFileSync(path, `${lines.join("\n")}\n`, { mode: 0o600 }); try { chmodSync(path, 0o600); } catch { /* best effort on Windows */ } return before; } function restoreKnownHost(path: string, before: string): void { if (!before) { try { rmSync(path, { force: true }); } catch { /* best effort compensation */ } return; } writeFileSync(path, before, { mode: 0o600 }); } function issueKey(ctx: ManagementContext, name: string): IssuedApiKey { return (ctx.deps.issueApiKey ?? issueApiKeyInProcess)(ctx.config, name); } function revokeKey(ctx: ManagementContext, id: string): boolean { return (ctx.deps.revokeApiKey ?? revokeApiKeyInProcess)(ctx.config, id); } /** * Revocation that a retry can repeat. A key that is no longer in the live config is already * revoked, which is exactly the state a partially completed cleanup leaves behind; without this * a retried DELETE would fail forever on the key it removed the first time. */ function revokeKeyIdempotent(ctx: ManagementContext, id: string): boolean { let revoked = false; try { revoked = revokeKey(ctx, id); } catch { revoked = false; } if (revoked) return true; return !(ctx.config.apiKeys ?? []).some(entry => entry.id === id); } function compensationFailure(ctx: ManagementContext, state: LinkRouteState, record: LinkStore["links"][number], phase: string): Response { const since = new Date((ctx.deps.now ?? Date.now)()).toISOString(); (state.compensationFailures ??= new Map()).set(record.id, { since, reason: "compensation_failed" }); try { markCompensationFailed(record.id, since, compensationPath()); } catch (error) { console.warn(`[link] compensation marker persistence failed linkId=${record.id}: ${error instanceof Error ? error.message : String(error)}`); } console.warn(`[link] compensation_failed linkId=${record.id} phase=${phase}`); return fail("compensation_failed", "The link compensation could not be completed.", 500); } async function compensateNewLink(ctx: ManagementContext, state: LinkRouteState, record: LinkStore["links"][number]): Promise<Response | null> { const revoked = revokeKeyIdempotent(ctx, record.apiKeyId); if (!revoked) { try { await state.supervisor.stopLink(record.id); } catch { /* retain the record and failure marker */ } try { const current = readStoreFor(ctx); if (!current.links.some(link => link.id === record.id)) { writeStoreFor(ctx, { ...current, links: [...current.links, record] }); } } catch { // The in-memory marker still makes the residual visible when persistence is unavailable. } return compensationFailure(ctx, state, record, "revoke"); } try { await state.supervisor.stopLink(record.id); } catch { return compensationFailure(ctx, state, record, "stop"); } try { const current = readStoreFor(ctx); const next = { ...current, links: current.links.filter(link => link.id !== record.id) }; if (next.links.length !== current.links.length) { writeStoreFor(ctx, next); } clearCompensationFailed(record.id, compensationPath()); state.compensationFailures?.delete(record.id); if (next.links.length === 0) await state.listener.close(); return null; } catch { return compensationFailure(ctx, state, record, "store"); } } async function candidates(ctx: ManagementContext): Promise<Response> { const values = ctx.deps.loadLinkCandidates?.() ?? loadHostCandidates(); return Response.json({ candidates: values.map(value => ({ alias: value.alias, source: value.source })) }); } async function probe(ctx: ManagementContext, state: LinkRouteState): Promise<Response> { const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias"]); if (!body || typeof body.alias !== "string") return fail("invalid_body", "alias is required.", 400); try { assertSshAlias(body.alias); } catch { return fail("invalid_alias", "alias must be a valid SSH host alias.", 400); } const dir = mkdtempSync(join(tmpdir(), "ocx-link-probe-")); const tempKnownHosts = join(dir, "known_hosts"); writeFileSync(tempKnownHosts, "", { mode: 0o600 }); const runner = runnerFor(ctx); try { const result = await runner.run(buildProbeArgv({ alias: body.alias, tempKnownHostsFile: tempKnownHosts }), { timeoutMs: 30_000 }); if (result.code !== 0) return fail("probe_failed", "SSH host probing failed.", 502, sshFailureHint(result.stderr)); const fingerprintResult = await runner.run(buildFingerprintArgv(tempKnownHosts), { timeoutMs: 10_000 }); if (fingerprintResult.code !== 0) return fail("fingerprint_failed", "The SSH host fingerprint could not be read.", 502, sshFailureHint(fingerprintResult.stderr)); const parsed = parseFingerprintLine(fingerprintResult.stdout.trim()); const knownHostLine = readFileSync(tempKnownHosts, "utf8").trim().split(/\r?\n/).filter(Boolean).at(-1); if (!knownHostLine) return fail("fingerprint_failed", "The SSH probe did not record a host key.", 502); state.pendingHosts.set(body.alias, { alias: body.alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, knownHostLine, probedAt: (ctx.deps.now ?? Date.now)() }); return Response.json({ alias: body.alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType }); } catch (error) { return fail("probe_failed", "SSH host probing failed.", 502, sshRunnerErrorHint(error)); } finally { try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } } } async function confirmHost(ctx: ManagementContext, state: LinkRouteState): Promise<Response> { const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias", "fingerprint"]); if (!body || typeof body.alias !== "string" || typeof body.fingerprint !== "string") return fail("invalid_body", "alias and fingerprint are required.", 400); const pending = state.pendingHosts.get(body.alias); const now = (ctx.deps.now ?? Date.now)(); if (!pending || now - pending.probedAt > PROBE_TTL_MS) return fail("host_confirmation_expired", "The SSH host probe has expired.", 409); if (pending.fingerprint !== body.fingerprint) return fail("host_fingerprint_mismatch", "The confirmed fingerprint does not match the probe.", 409); const path = knownHostsFile(ctx); const before = putKnownHost(path, pending.alias, pending.knownHostLine); // Every refusal restores known_hosts and keeps the pending probe, so a retry within its TTL works. const refuse = (response: Response): Response => { restoreKnownHost(path, before); return response; }; let result: SshRunResult; try { result = await runnerFor(ctx).run(buildExecArgv({ alias: pending.alias, argv: remoteOcxArgv(["--version"]), knownHostsFile: path }), { timeoutMs: 30_000 }); } catch (error) { return refuse(fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502, sshRunnerErrorHint(error))); } if (result.code === REMOTE_COMMAND_NOT_FOUND) return refuse(fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr))); if (result.code !== 0) return refuse(fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502, sshFailureHint(result.stderr))); const version = parseRemoteOcxVersion(result.stdout); if (!version) return refuse(fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502)); if (!meetsRemoteOcxFloor(version.parts)) { return refuse(fail("remote_ocx_outdated", `The remote OpenCodex is older than ${MIN_REMOTE_OCX.join(".")}.`, 409, boundHint(`opencodex ${version.version}`))); } const confirmed = { ...pending, ocxVersion: version.version }; state.confirmedHosts ??= new Map(); state.confirmedHosts.set(pending.alias, confirmed); state.pendingHosts.delete(pending.alias); return Response.json({ alias: pending.alias, fingerprint: pending.fingerprint, ocxVersion: confirmed.ocxVersion }); } /** * `ocx --version` prints `opencodex <version>` first; a usage banner, an unbounded version tail or * other output is refused. */ function parseRemoteOcxVersion(stdout: string): { version: string; parts: [number, number, number] } | null { const match = REMOTE_OCX_VERSION.exec(stdout.trim().split(/\r?\n/)[0] ?? ""); if (!match) return null; return { version: `${match[1]}.${match[2]}.${match[3]}${match[4] ?? ""}${match[5] ?? ""}`, parts: [Number(match[1]), Number(match[2]), Number(match[3])] }; } function meetsRemoteOcxFloor(parts: readonly [number, number, number]): boolean { for (let index = 0; index < MIN_REMOTE_OCX.length; index += 1) { if (parts[index] !== MIN_REMOTE_OCX[index]) return parts[index]! > MIN_REMOTE_OCX[index]!; } return true; } function parsePortOutput(stdout: string): number | null { try { const value: unknown = JSON.parse(stdout.trim()); if (!isRecord(value) || Object.keys(value).length !== 1 || !port(value.port)) return null; return value.port; } catch { return null; } } async function apply(ctx: ManagementContext, state: LinkRouteState): Promise<Response> { const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias"]); if (!body || typeof body.alias !== "string") return fail("invalid_body", "alias is required.", 400); const confirmed = state.confirmedHosts?.get(body.alias); if (!confirmed) return fail("host_not_confirmed", "Confirm the SSH host before applying the link.", 409); const knownHosts = knownHostsFile(ctx); const runner = runnerFor(ctx); let remotePort: number; let portHint: string | undefined; try { const result = await runner.run(buildExecArgv({ alias: body.alias, argv: remoteOcxArgv(["link", "port"]), knownHostsFile: knownHosts }), { timeoutMs: 30_000 }); if (result.code === REMOTE_COMMAND_NOT_FOUND) return fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr)); remotePort = result.code === 0 ? parsePortOutput(result.stdout) ?? 0 : 0; if (result.code !== 0) portHint = sshFailureHint(result.stderr); } catch (error) { remotePort = 0; portHint = sshRunnerErrorHint(error); } if (!port(remotePort)) return fail("remote_port_failed", "The remote link port could not be determined.", 502, portHint); let issued: IssuedApiKey; try { issued = issueKey(ctx, `link:${body.alias}`); } catch { return fail("key_issue_failed", "The link key could not be issued.", 503); } const id = newLinkId(); const record = { id, alias: body.alias, direction: "hub-initiated" as const, hostKeyFingerprint: confirmed.fingerprint, tunnelPort: remotePort, apiKeyId: issued.id, createdAt: new Date((ctx.deps.now ?? Date.now)()).toISOString() }; let store: LinkStore; try { const current = readStoreFor(ctx); if (current.links.some(link => link.alias === body.alias && link.direction === "hub-initiated")) { const compensation = await compensateNewLink(ctx, state, record); if (compensation) return compensation; return fail("link_exists", "A link for this alias already exists.", 409); } store = { ...current, links: [...current.links, record] }; writeStoreFor(ctx, store); await state.listener.ensureStarted(); if (state.listener.status().state !== "listening") { const compensation = await compensateNewLink(ctx, state, record); return compensation ?? fail("listener_unavailable", "The link listener is unavailable.", 503); } await state.supervisor.ensureStarted(); await state.supervisor.reload(); } catch { const compensation = await compensateNewLink(ctx, state, record); if (compensation) return compensation; return fail("link_apply_failed", "The link could not be started.", 503); } const admission = awaitFirstAdmission(issued.id, APPLY_ADMISSION_TIMEOUT_MS, state.listener.onAuthenticatedCatalog); const input = new TextEncoder().encode(JSON.stringify({ apiKeyId: issued.id, key: issued.key })); try { const result = await runner.run(buildExecArgv({ alias: body.alias, argv: remoteOcxArgv(["connect", "--link", "--key-stdin", "--tunnel-port", String(remotePort), "--link-id", id]), knownHostsFile: knownHosts }), { stdin: input, timeoutMs: APPLY_ADMISSION_TIMEOUT_MS }); if (result.code !== 0) { void admission.catch(() => {}); const compensation = await compensateNewLink(ctx, state, record); if (compensation) return compensation; const hint = sshFailureHint(result.stderr); return result.code === REMOTE_COMMAND_NOT_FOUND ? fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, hint) : fail("remote_connect_failed", "The remote link connection failed.", 502, hint); } try { await admission; } catch { const compensation = await compensateNewLink(ctx, state, record); return compensation ?? fail("admission_timeout", "The remote link did not authenticate a catalog request in time.", 502); } return Response.json({ linkId: id }, { status: 202 }); } catch (error) { void admission.catch(() => {}); const compensation = await compensateNewLink(ctx, state, record); return compensation ?? fail("remote_connect_failed", "The remote link connection failed.", 502, sshRunnerErrorHint(error)); } finally { input.fill(0); } } async function issue(ctx: ManagementContext): Promise<Response> { const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias", "tunnelPort"]); if (!body || typeof body.alias !== "string" || !isLinkPort(body.tunnelPort)) return fail("invalid_body", "alias and tunnelPort are required.", 400); try { assertSshAlias(body.alias); } catch { return fail("invalid_alias", "alias must be a valid SSH host alias.", 400); } let issued: IssuedApiKey; try { issued = issueKey(ctx, `link:${body.alias}`); } catch { return fail("key_issue_failed", "The link key could not be issued.", 503); } const id = newLinkId(); const state = stateFor(ctx); if (!state) { if (!revokeKeyIdempotent(ctx, issued.id)) { console.warn(`[link] compensation_failed apiKeyId=${issued.id} phase=revoke-without-lifecycle`); return fail("compensation_failed", "The link compensation could not be completed.", 500); } return fail("link_unavailable", "The link lifecycle is unavailable.", 503); } const record = { id, alias: body.alias, direction: "client-initiated" as const, hostKeyFingerprint: null, tunnelPort: body.tunnelPort, apiKeyId: issued.id, createdAt: new Date((ctx.deps.now ?? Date.now)()).toISOString() }; let failureCode = "link_issue_failed"; try { const current = readStoreFor(ctx); if (current.links.some(link => link.id === id)) throw new Error("link id collision"); if (current.links.some(link => link.alias === body.alias && link.direction === "client-initiated")) { const compensation = await compensateNewLink(ctx, state, record); return compensation ?? fail("link_exists", "A link for this alias already exists.", 409); } writeStoreFor(ctx, { ...current, links: [...current.links, record] }); await state.listener.ensureStarted(); if (state.listener.status().state !== "listening") { failureCode = "listener_unavailable"; throw new Error("link listener unavailable"); } await state.supervisor.ensureStarted(); const boundStore = readStoreFor(ctx); if (!port(boundStore.listenerPort)) throw new Error("link listener did not bind"); return Response.json({ linkId: id, apiKeyId: issued.id, key: issued.key, listenerPort: boundStore.listenerPort }); } catch { const compensation = await compensateNewLink(ctx, state, record); return compensation ?? fail(failureCode, failureCode === "listener_unavailable" ? "The link listener is unavailable." : "The link could not be issued.", 503); } } type LinkJoinRouteOverrides = { joinHome?: typeof joinHome; }; function joinRouteOverrides(ctx: ManagementContext): LinkJoinRouteOverrides { return ctx.deps as ManagementApiDepsWithJoinOverrides; } type ManagementApiDepsWithJoinOverrides = ManagementContext["deps"] & LinkJoinRouteOverrides; function joinFailure(error: unknown): Response { const code = error && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : ""; const hint = error && typeof error === "object" && "hint" in error && typeof error.hint === "string" ? error.hint : undefined; switch (code) { case "host_not_confirmed": return fail("host_not_confirmed", "Confirm the SSH host before joining the link.", 409); case "host_confirmation_expired": return fail("host_confirmation_expired", "The SSH host confirmation has expired.", 409); case "join_port_failed": return fail("join_port_failed", "No local port is available for the link tunnel.", 503); case "join_issue_failed": return fail("join_issue_failed", "The home could not issue a link.", 502, hint); case "remote_ocx_missing": return fail("remote_ocx_missing", "ocx was not found on the home.", 502, hint); case "join_tunnel_failed": return fail("join_tunnel_failed", "The SSH tunnel to the home did not become ready.", 502); case "admission_failed": return fail("admission_failed", "The home refused the issued link key.", 502); case "join_rollback_failed": { const linkId = error && typeof error === "object" && "linkId" in error && typeof error.linkId === "string" ? error.linkId : "unknown"; return fail("join_rollback_failed", `The join failed and the home link could not be revoked; run ocx link revoke --link-id ${linkId} on the home.`, 502); } case "join_restart_failed": return fail("join_restart_failed", "The link is ready; restart OpenCodex to finish connecting as a Child.", 500); default: return fail("join_connect_failed", "The client link join could not be completed.", 502); } } async function handleJoin(ctx: ManagementContext, state: LinkRouteState): Promise<Response> { const body = exactBody(await readManagementJsonBodyOr(ctx.req, null), ["alias"]); if (!body || typeof body.alias !== "string") return fail("invalid_body", "alias is required.", 400); try { assertSshAlias(body.alias); } catch { return fail("invalid_alias", "alias must be a valid SSH host alias.", 400); } if (joinInProgress) return fail("join_in_progress", "A link join is already in progress.", 409); joinInProgress = true; try { const confirmed = state.confirmedHosts?.get(body.alias); const overrides = joinRouteOverrides(ctx); const deps: ClientLinkJoinDeps = { runner: runnerFor(ctx), knownHostsFile: knownHostsFile(ctx), scheduleRestart: () => { acceptSystemRestart(); }, ...(confirmed ? { confirmedHost: confirmed } : {}), }; const result = await (overrides.joinHome ?? joinHome)(deps, { alias: body.alias }); return Response.json({ linkId: result.linkId, alias: body.alias, restarting: true }, { status: 202 }); } catch (error) { return joinFailure(error); } finally { joinInProgress = false; } } async function remove(ctx: ManagementContext, state: LinkRouteState, id: string): Promise<Response> { if (!LINK_ID.test(id)) return fail("invalid_link_id", "The link id is invalid.", 400); const current = readStoreFor(ctx); const record = current.links.find(link => link.id === id); if (!record) return fail("link_not_found", "The link was not found.", 404); const body = await readManagementJsonBodyOr(ctx.req, {}); if (!isRecord(body) || Object.keys(body).some(key => key !== "force") || (body.force !== undefined && typeof body.force !== "boolean")) return fail("invalid_body", "force must be a boolean.", 400); const force = body.force === true; await state.supervisor.stopLink(id); const restartTunnel = async (): Promise<void> => { try { await state.supervisor.ensureStarted(); await state.supervisor.reload(); } catch (error) { console.warn(`[link] tunnel restart failed linkId=${id}: ${error instanceof Error ? error.message : String(error)}`); } }; if (!force && record.direction === "hub-initiated") { try { const result = await runnerFor(ctx).run(buildExecArgv({ alias: record.alias, argv: remoteOcxArgv(["disconnect"]), knownHostsFile: knownHostsFile(ctx) }), { timeoutMs: 30_000 }); if (result.code !== 0) { await restartTunnel(); return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502, sshFailureHint(result.stderr)); } } catch (error) { await restartTunnel(); return fail("remote_disconnect_failed", "The remote client could not be disconnected.", 502, sshRunnerErrorHint(error)); } } if (!revokeKeyIdempotent(ctx, record.apiKeyId)) return fail("key_revoke_failed", "The link key could not be revoked.", 502); let next: LinkStore; try { const latest = readStoreFor(ctx); next = { ...latest, links: latest.links.filter(link => link.id !== id) }; if (next.links.length !== latest.links.length) writeStoreFor(ctx, next); clearCompensationFailed(id, compensationPath()); } catch { return fail("link_remove_failed", "The link record could not be removed.", 503); } state.compensationFailures?.delete(id); if (next.links.length === 0) await state.listener.close(); return Response.json({ linkId: id }); } export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: LinkRouteState): Promise<Response | null> { const { url, req } = ctx; const path = url.pathname; if (!isLinkPath(path)) return null; if (ctx.guiSessionIssuance === "tailscale-identity") return fail("tailscale_session_refused", "Tailscale identity sessions cannot use link routes.", 403); if (url.pathname === "/api/link/join" && req.method === "POST") { // The same dashboard admission as the Home side. Every refusal below runs before link state // is read and before any SSH. const denied = auth(ctx, "dashboard"); if (denied) return denied; if ((ctx.config.runtimeRole ?? "standalone") !== "standalone") return fail("standalone_required", "Client initiated links require standalone runtime mode.", 409); if (!joinPortMatches(ctx)) return fail("join_port_mismatch", "OpenCodex is not running on its configured port, so it cannot restart as a Child.", 409); const state = suppliedState ?? stateFor(ctx); if (!state) return fail("link_unavailable", "The link lifecycle is unavailable.", 503); return handleJoin(ctx, state); } const state = suppliedState ?? stateFor(ctx); if (!state) return fail("link_unavailable", "The link lifecycle is unavailable.", 503); if (url.pathname === "/api/link/status" && req.method === "GET") { const denied = auth(ctx, "either"); if (denied) return denied; const store = readStoreFor(ctx); const listenerStatus = state.listener.status(); const dto: LinkStatusDto = projectLinkStatus( store, state.supervisor.status(), listenerStatus, ctx.config, readCompensation(), ctx.config.runtimeRole === "client" ? clientLinkTunnelStatus() : null, ); for (const link of dto.links) { const failure = state.compensationFailures?.get(link.id); if (failure) Object.assign(link, { state: "failed" as const, since: failure.since, reason: failure.reason }); } if (dto.child && store.links[0]) { const failure = state.compensationFailures?.get(store.links[0].id); if (failure) Object.assign(dto.child, { state: "failed" as const, since: failure.since, reason: failure.reason }); } // A dashboard session also learns whether it may join as a Child. The admin-token answer stays // the exact K16 document that `ocx link status` validates key by key. const body: LinkStatusDto & { joinAvailable?: boolean } = ctx.principal === "gui-session" ? { ...dto, joinAvailable: joinAvailable(ctx) } : dto; return Response.json(body, { headers: { "cache-control": "no-store" } }); } if (url.pathname === "/api/link/candidates" && req.method === "GET") { const denied = auth(ctx, "dashboard"); if (denied) return denied; return candidates(ctx); } if (url.pathname === "/api/link/probe" && req.method === "POST") { const denied = auth(ctx, "dashboard"); if (denied) return denied; return probe(ctx, state); } if (url.pathname === "/api/link/confirm-host" && req.method === "POST") { const denied = auth(ctx, "dashboard"); if (denied) return denied; return confirmHost(ctx, state); } if (url.pathname === "/api/link/apply" && req.method === "POST") { const denied = auth(ctx, "dashboard"); if (denied) return denied; return apply(ctx, state); } if (url.pathname === "/api/link/issue" && req.method === "POST") { const denied = auth(ctx, "admin"); if (denied) return denied; return issue(ctx); } if (req.method === "DELETE" && path.startsWith("/api/link/")) { const denied = auth(ctx, "either"); if (denied) return denied; let id: string; try { id = decodeURIComponent(path.slice("/api/link/".length)); } catch { return fail("invalid_link_id", "The link id is invalid.", 400); } return remove(ctx, state, id); } return null; }