@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
text/typescript
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;
}