UNPKG

@bitkyc08/opencodex

Version:

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

517 lines (503 loc) • 38.1 kB
import { seedRouteDeviceClients } from "../../routing/home-route-intent"; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { assertSshAlias, buildExecArgv, buildFingerprintArgv, buildProbeArgv, REMOTE_COMMAND_NOT_FOUND, remoteOcxArgv } from "../../link/ssh-argv"; import { plantUnavailableGuidance, resolveChildBinarySource } from "../../link/child-binary-source"; import { parseFingerprintLine } from "../../link/fingerprint"; import { confirmedLineTrust as confirmedLineTrustIn, type ConfirmedLineTrust } from "../../link/route-trust"; import { isDetachedEphemeralChildConfig } from "../../link/ephemeral-child"; import { classifyChildAttachConflict, classifyPlantFailure, inspectRemoteChildRuntime, parseFullInstallCensus, remoteFullInstallCensusArgv, remotePlantChildArgv, remotePurgePlantedChildArgv } from "../../link/remote-plant"; import { requireRemotePlatform } from "../../link/remote-platform"; import { LINK_CATALOG_MAX_BYTES, LINK_RELAY_VERIFY_MS, isChildHealth, linkCommandBudget, linkRestartBudget, parseChildHttp, remoteChildHttpArgv, REMOTE_CURL_PREFLIGHT } from "../../link/remote-probe"; import { newLinkId, type LinkStore } from "../../link/store"; import { residualRecovery } from "../../link/residual-recovery"; import { SshRunnerError, boundHint, sshFailureHint, sshRunnerErrorHint, type SshRunResult } from "../../link/ssh-runner"; import { withConfigMutationLockSync } from "../../config/mutation-lock"; import type { ManagementContext } from "./context"; import { readManagementJsonBodyOr } from "./body"; import { fail, exactBody, port, isRecord, runnerFor, readStoreFor, writeStoreFor, knownHostsFile, putConfirmedKnownHost, issueKey, compensateNewLink, keyCleanupFailed, revokeKeyIdempotent, type LinkRouteState } from "./link-route-state"; import { identityFileRefusal, routeFields, routeMismatch, routeOf, sameRouteRequest, splitRouteRequest } from "./link-route-request"; import { enrollOperationDigest, journalInUse, journalOpenFailure, NO_ENROLL_JOURNAL, openEnrollJournal, openEnrollmentConflict, replayOperation, underAliasLock, type EnrollJournal } from "./link-operation"; import { tombstoneNamesAlias } from "../../link/tombstones"; import { isOperationId } from "../../link/operations-journal"; import { CHILD_CONFIG_TOO_LARGE_HINT, CHILD_CONFIG_TOO_LARGE_MESSAGE, CHILD_CONFIG_VALIDATE_MAX_OUTPUT_BYTES, CHILD_PREFLIGHT_MAX_OUTPUT_BYTES, childConfigFailureReason, childHealthRefusalHint, childRoleRefusalHint } from "./link-child-preflight"; const PROBE_TTL_MS = 5 * 60_000; const MIN_REMOTE_OCX = [2, 66, 0] as const; 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|$)/; /** * What a refused apply that may have left the Child connected answers: the closed words a client maps to its own guidance * (residualKind: plant, only the managed binary's purge removes it, or enrollment; residualInstall for the latter, when the * apply knew it), the attempt's link id and the Child's platform when known, and a recovery line bound to that id * (src/link/residual-recovery.ts), which journalled replies share. */ export function liveResidual(kind: "plant" | "ephemeral" | "full", platform: "posix" | "windows" | undefined, linkId: string): { residualKind: "plant" | "enrollment"; residualInstall?: "ephemeral" | "full"; linkId: string; recovery: string; remotePlatform?: "posix" | "windows" } { return { residualKind: kind === "plant" ? "plant" : "enrollment", ...(kind === "plant" ? {} : { residualInstall: kind }), ...(platform ? { remotePlatform: platform } : {}), linkId, recovery: residualRecovery(kind, linkId, platform), }; } /** * Same-alias operations refuse overlap rather than overwrite a confirmed generation. Keyed without case, as OpenSSH * matches known_hosts names and as the alias lock and the operation journal match aliases. */ export async function serialized(state: LinkRouteState, alias: string, action: () => Promise<Response>): Promise<Response> { const operations = state.operations ??= new Set(); const key = alias.toLowerCase(); if (operations.has(key)) return fail("link_operation_in_progress", "A link operation for this alias is already running.", 409); operations.add(key); try { return await action(); } finally { operations.delete(key); } } function remoteFailure(result: SshRunResult, code: string, message: string): Response | null { if (result.code === REMOTE_COMMAND_NOT_FOUND) return fail("remote_ocx_missing", "ocx was not found on the remote host.", 502, sshFailureHint(result.stderr)); return result.code === 0 ? null : fail(code, message, 502, sshFailureHint(result.stderr)); } function parseVersion(stdout: string): { version: string; parts: number[] } | null { const match = REMOTE_OCX_VERSION.exec(stdout.trim().split(/\r?\n/)[0] ?? ""); return match ? { version: match.slice(1, 4).join(".") + (match[4] ?? "") + (match[5] ?? ""), parts: match.slice(1, 4).map(Number) } : null; } function isOutdatedVersion(parts: readonly number[]): boolean { const cmp = parts.findIndex((part, i) => part !== MIN_REMOTE_OCX[i]); return cmp >= 0 && parts[cmp]! < MIN_REMOTE_OCX[cmp]!; } export async function probe(ctx: ManagementContext, state: LinkRouteState): Promise<Response> { const split = splitRouteRequest(await readManagementJsonBodyOr(ctx.req, null), ctx); if ("error" in split) return split.error; const keyRefusal = identityFileRefusal(split.route.explicitRoute); if (keyRefusal) return keyRefusal; const value = split.body, wanted = split.route, route = wanted.explicitRoute, bound = routeFields(wanted); const body = exactBody(value, ["alias"]) ?? exactBody(value, ["alias", "includeVersion"]) ?? exactBody(value, ["alias", "includeVersion", "allowMissing"]); if (!body || typeof body.alias !== "string" || (body.includeVersion !== undefined && body.includeVersion !== true) || (body.allowMissing !== undefined && (typeof body.allowMissing !== "boolean" || body.includeVersion !== true))) { return fail("invalid_body", "alias is required.", 400); } const alias = body.alias; try { assertSshAlias(alias); } catch { return fail("invalid_alias", "alias must be a valid SSH host alias.", 400); } const resolveBinary = ctx.deps.resolveChildBinarySource ?? resolveChildBinarySource; return serialized(state, alias, async () => { const dir = mkdtempSync(join(tmpdir(), "ocx-link-probe-")); const path = join(dir, "known_hosts"); writeFileSync(path, "", { mode: 0o600 }); const runner = runnerFor(ctx), now = ctx.deps.now ?? Date.now; try { const started = now(); const result = await runner.run(buildProbeArgv({ alias, tempKnownHostsFile: path, route }), { timeoutMs: 30_000 }); const latency = Math.max(0, now() - started); if (result.code !== 0 || result.stdout.trim() !== "ocx-link-probe") return fail("probe_failed", "SSH host probing failed.", 502, sshFailureHint(result.stderr)); const fp = await runner.run(buildFingerprintArgv(path), { timeoutMs: 10_000 }); if (fp.code !== 0) return fail("fingerprint_failed", "The SSH host fingerprint could not be read.", 502, sshFailureHint(fp.stderr)); const parsed = parseFingerprintLine(fp.stdout.trim()); const line = readFileSync(path, "utf8").trim().split(/\r?\n/).filter(Boolean).at(-1); if (!line) return fail("fingerprint_failed", "The SSH probe did not record a host key.", 502); const remotePlatform = await requireRemotePlatform(runner, alias, route, path); if (body.includeVersion === true && body.allowMissing === true) { const inspected = await inspectRemoteChildRuntime(runner, alias, route, path, remotePlatform); if (!inspected) return fail("version_probe_failed", "The remote OpenCodex runtime could not be inspected.", 502); if (inspected.runtimeKind === "missing") { const source = resolveBinary(inspected.targetTriple); state.pendingHosts.set(alias, { alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, knownHostLine: line, probedAt: now(), sshLatencyMs: latency, remotePlatform, runtimeKind: "missing", targetTriple: inspected.targetTriple, ...bound }); state.confirmedHosts?.delete(alias); return Response.json({ alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, ocxVersion: null, runtimeKind: "missing", targetTriple: inspected.targetTriple, plantable: source.ok, ...(source.ok ? { binarySizeBytes: source.artifact.sizeBytes } : { plantUnavailableReason: source.reason }), }); } const parsedVersion = parseVersion(inspected.ocxVersionLine ?? ""); if (!parsedVersion) return fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502); state.pendingHosts.set(alias, { alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, knownHostLine: line, probedAt: now(), sshLatencyMs: latency, remotePlatform, runtimeKind: inspected.runtimeKind, targetTriple: inspected.targetTriple, ...bound }); state.confirmedHosts?.delete(alias); return Response.json({ alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, ocxVersion: parsedVersion.version, runtimeKind: inspected.runtimeKind, targetTriple: inspected.targetTriple, plantable: false, }); } let ocxVersion: string | undefined; if (body.includeVersion === true) { const versionResult = await runner.run(buildExecArgv({ alias, argv: remoteOcxArgv(["--version"], remotePlatform), knownHostsFile: path, route }), { timeoutMs: 30_000 }); const denied = remoteFailure(versionResult, "version_probe_failed", "The remote ocx version could not be read."); if (denied) return denied; const parsedVersion = parseVersion(versionResult.stdout); if (!parsedVersion) return fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502); ocxVersion = parsedVersion.version; } state.pendingHosts.set(alias, { alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, knownHostLine: line, probedAt: now(), sshLatencyMs: latency, remotePlatform, ...bound }); state.confirmedHosts?.delete(alias); return Response.json({ alias, fingerprint: parsed.fingerprint, keyType: parsed.keyType, ...(ocxVersion === undefined ? {} : { ocxVersion }) }); } catch (error) { return fail("probe_failed", "SSH host probing failed.", 502, sshRunnerErrorHint(error)); } finally { rmSync(dir, { recursive: true, force: true }); } }); } export async function confirmHost(ctx: ManagementContext, state: LinkRouteState): Promise<Response> { const split = splitRouteRequest(await readManagementJsonBodyOr(ctx.req, null), ctx); if ("error" in split) return split.error; const keyRefusal = identityFileRefusal(split.route.explicitRoute); if (keyRefusal) return keyRefusal; const value = split.body, wanted = split.route; const body = exactBody(value, ["alias", "fingerprint"]) ?? exactBody(value, ["alias", "fingerprint", "allowMissing"]); if (!body || typeof body.alias !== "string" || typeof body.fingerprint !== "string" || (body.allowMissing !== undefined && typeof body.allowMissing !== "boolean")) { return fail("invalid_body", "alias and fingerprint are required.", 400); } const alias = body.alias; const resolveBinary = ctx.deps.resolveChildBinarySource ?? resolveChildBinarySource; return serialized(state, alias, async () => { const pending = state.pendingHosts.get(alias), 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); if (!sameRouteRequest(routeOf(pending), wanted)) return routeMismatch(); const route = pending.explicitRoute ?? null; const dir = mkdtempSync(join(tmpdir(), "ocx-link-confirm-")), path = join(dir, "known_hosts"); writeFileSync(path, pending.knownHostLine + "\n", { mode: 0o600 }); try { const started = now(); const runner = runnerFor(ctx); const remotePlatform = pending.remotePlatform ?? await requireRemotePlatform(runner, alias, route, path); if (body.allowMissing === true) { const inspected = await inspectRemoteChildRuntime(runner, alias, route, path, remotePlatform); if (!inspected) return fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502); if (inspected.runtimeKind === "missing") { const source = resolveBinary(inspected.targetTriple); if (state.pendingHosts.get(alias) !== pending || now() - pending.probedAt > PROBE_TTL_MS) return fail("host_confirmation_expired", "The SSH host probe changed or expired.", 409); if (!putConfirmedKnownHost(ctx, alias, pending.knownHostLine, pending.fingerprint)) return linkPinConflict(); const confirmed = { ...pending, remotePlatform, sshLatencyMs: Math.max(pending.sshLatencyMs ?? 0, now() - started), ocxVersion: null, runtimeKind: "missing" as const, targetTriple: inspected.targetTriple, plantable: source.ok, ...(source.ok ? { binarySizeBytes: source.artifact.sizeBytes } : { plantUnavailableReason: source.reason }), }; (state.confirmedHosts ??= new Map()).set(alias, confirmed); state.pendingHosts.delete(alias); return Response.json({ alias, fingerprint: pending.fingerprint, ocxVersion: null, runtimeKind: "missing", targetTriple: inspected.targetTriple, plantable: source.ok, ...(source.ok ? { binarySizeBytes: source.artifact.sizeBytes } : { plantUnavailableReason: source.reason }), }); } const version = parseVersion(inspected.ocxVersionLine ?? ""); if (!version) return fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502); if (isOutdatedVersion(version.parts)) return fail("remote_ocx_outdated", "The remote OpenCodex is older than 2.66.0.", 409, boundHint("opencodex " + version.version)); if (state.pendingHosts.get(alias) !== pending || now() - pending.probedAt > PROBE_TTL_MS) return fail("host_confirmation_expired", "The SSH host probe changed or expired.", 409); if (!putConfirmedKnownHost(ctx, alias, pending.knownHostLine, pending.fingerprint)) return linkPinConflict(); const confirmed = { ...pending, remotePlatform, sshLatencyMs: Math.max(pending.sshLatencyMs ?? 0, now() - started), ocxVersion: version.version, runtimeKind: inspected.runtimeKind, targetTriple: inspected.targetTriple, plantable: false }; (state.confirmedHosts ??= new Map()).set(alias, confirmed); state.pendingHosts.delete(alias); return Response.json({ alias, fingerprint: pending.fingerprint, ocxVersion: version.version, runtimeKind: inspected.runtimeKind, targetTriple: inspected.targetTriple, plantable: false, }); } const result = await runner.run(buildExecArgv({ alias, argv: remoteOcxArgv(["--version"], remotePlatform), knownHostsFile: path, route }), { timeoutMs: 30_000 }); const denied = remoteFailure(result, "version_probe_failed", "The remote ocx version could not be confirmed."); if (denied) return denied; const version = parseVersion(result.stdout); if (!version) return fail("remote_ocx_unrecognized", "The remote ocx did not report an OpenCodex version.", 502); if (isOutdatedVersion(version.parts)) return fail("remote_ocx_outdated", "The remote OpenCodex is older than 2.66.0.", 409, boundHint("opencodex " + version.version)); if (state.pendingHosts.get(alias) !== pending || now() - pending.probedAt > PROBE_TTL_MS) return fail("host_confirmation_expired", "The SSH host probe changed or expired.", 409); if (!putConfirmedKnownHost(ctx, alias, pending.knownHostLine, pending.fingerprint)) return linkPinConflict(); const confirmed = { ...pending, remotePlatform, sshLatencyMs: Math.max(pending.sshLatencyMs ?? 0, now() - started), ocxVersion: version.version }; (state.confirmedHosts ??= new Map()).set(alias, confirmed); state.pendingHosts.delete(alias); return Response.json({ alias, fingerprint: pending.fingerprint, ocxVersion: version.version }); } catch (error) { return fail("version_probe_failed", "The remote ocx version could not be confirmed.", 502, sshRunnerErrorHint(error)); } finally { rmSync(dir, { recursive: true, force: true }); } }); } function confirmedLineTrust(path: string, alias: string, line: string): ConfirmedLineTrust { let text = ""; try { text = readFileSync(path, "utf8"); } catch { return "key_changed"; } return confirmedLineTrustIn(text, alias, line); } function linkPinConflict(): Response { return fail("link_pin_conflict", "A Home-initiated link already pins another key for this alias; remove that link before trusting another key.", 409); } const APPLY_KEYS = new Set(["alias", "fingerprint", "plant", "operationId", "requireEphemeral"]); function parsePort(stdout: string): number | null { try { const value: unknown = JSON.parse(stdout.trim()); return isRecord(value) && Object.keys(value).length === 1 && port(value.port) ? value.port : null; } catch { return null; } } export async function apply(ctx: ManagementContext, state: LinkRouteState): Promise<Response> { const split = splitRouteRequest(await readManagementJsonBodyOr(ctx.req, null), ctx); if ("error" in split) return split.error; const value = split.body, wanted = split.route; const body = isRecord(value) && Object.keys(value).every(key => APPLY_KEYS.has(key)) ? value : null; if (!body || typeof body.alias !== "string" || (body.fingerprint !== undefined && typeof body.fingerprint !== "string") || (body.plant !== undefined && typeof body.plant !== "boolean") || (body.operationId !== undefined && !isOperationId(body.operationId)) || (body.requireEphemeral !== undefined && body.requireEphemeral !== true)) { return fail("invalid_body", "alias and optional fingerprint/plant are required.", 400); } const alias = body.alias; // A repeat replays without probing, so the fingerprint is what names the operation (the CLI requires it too). if (body.operationId !== undefined && typeof body.fingerprint !== "string") return fail("invalid_body", "operationId requires fingerprint.", 400); const resolveBinary = ctx.deps.resolveChildBinarySource ?? resolveChildBinarySource; // ocx link add --operation-id (structure/remote-link.md, "Operation journal"): replay, recovery and the reserved ids. const operation = typeof body.operationId === "string" ? { id: body.operationId, digest: enrollOperationDigest({ alias, ...(typeof body.fingerprint === "string" ? { fingerprint: body.fingerprint } : {}), route: wanted, requireEphemeral: body.requireEphemeral === true }) } : null; // A tombstone for this alias means recover can run against the machine; it holds the alias lock, so this does too. return underAliasLock(ctx, alias, operation !== null || journalInUse(ctx) || tombstoneNamesAlias(alias), async () => { if (operation) { const replay = await replayOperation(ctx, state, operation, "enroll"); if (replay) return replay; } const open = openEnrollmentConflict(ctx, alias, operation?.id); if (open) return open; return serialized(state, alias, async () => { const confirmed = state.confirmedHosts?.get(alias), now = ctx.deps.now ?? Date.now; if (!confirmed) return fail("host_not_confirmed", "Confirm the SSH host before applying the link.", 409); if (now() - confirmed.probedAt > PROBE_TTL_MS) return fail("host_confirmation_expired", "The SSH host confirmation has expired.", 409); if (body.fingerprint !== undefined && body.fingerprint !== confirmed.fingerprint) return fail("host_fingerprint_mismatch", "The apply fingerprint does not match the confirmed host.", 409); if (!sameRouteRequest(routeOf(confirmed), wanted)) return routeMismatch(); const route = confirmed.explicitRoute ?? null; // After the replay above, before the journal entry and any SSH: a new operation needs a key ssh can use. const keyRefusal = identityFileRefusal(route); if (keyRefusal) return keyRefusal; if (readStoreFor(ctx).links.some(link => link.alias === alias && link.direction === "hub-initiated")) return fail("link_exists", "A link for this alias already exists.", 409); if (confirmed.runtimeKind === "missing" && body.plant !== true) { return fail("remote_ocx_missing", "ocx was not found on the remote host; confirm planting ocx-child before applying.", 409); } let journal: EnrollJournal = NO_ENROLL_JOURNAL; if (operation) { try { journal = openEnrollJournal(ctx, operation, alias, routeFields(routeOf(confirmed))); } catch (error) { return journalOpenFailure(error); } } // The attempt's link id, fixed before anything changes on the Child: a residual answer binds the Child's step to it, even // for a plant whose rollback failed before the link was stored. const attemptLinkId = journal.reservedLinkId ?? newLinkId(); return journal.finish(await (async (): Promise<Response> => { const dir = mkdtempSync(join(tmpdir(), "ocx-link-apply-")), knownHosts = join(dir, "known_hosts"); writeFileSync(knownHosts, confirmed.knownHostLine + "\n", { mode: 0o600 }); const runner = runnerFor(ctx), budget = linkCommandBudget(confirmed.sshLatencyMs); const run = (argv: readonly string[], timeoutMs = budget, maxOutputBytes?: number) => runner.run(buildExecArgv({ alias, argv, knownHostsFile: knownHosts, route }), { timeoutMs, ...(maxOutputBytes === undefined ? {} : { maxOutputBytes }) }); let remotePlatform: "posix" | "windows" | undefined; const knownPlatform = (): "posix" | "windows" | undefined => remotePlatform; const ocx = (args: readonly string[]) => remoteOcxArgv(args, remotePlatform); let record: LinkStore["links"][number] | undefined, input: Uint8Array | undefined; // A key issued for a record that has not passed the locked alias and trust checks. Until then a // failure revokes only the key: compensation, which may store its record, is for a validated one. let unvalidatedKeyId: string | undefined; // The alias and trust checks a new record must pass under the mutation lock, both when it is // first written and when compensation would store it again: no other Home-initiated link owns // the alias in any case, and the live known_hosts still trusts exactly the confirmed key. const linkCheck = (current: LinkStore, self?: string): "exists" | ConfirmedLineTrust => { const wanted = alias.toLowerCase(); if (current.links.some(link => link.id !== self && link.alias.toLowerCase() === wanted && link.direction === "hub-initiated")) return "exists"; return confirmedLineTrust(knownHostsFile(ctx), alias, confirmed.knownHostLine); }; let ephemeralChild = confirmed.runtimeKind === "ephemeral", plantedFreshBinary = false, purgeRollbackFailed = false, remoteMayBeConnected = false, phase = "remote_port"; const failed = async (response: Response): Promise<Response> => { const own = record; let compensation = own ? await compensateNewLink(ctx, state, own, current => linkCheck(current, own.id) === "trusted") : null; if (!record && unvalidatedKeyId !== undefined) { const keyId = unvalidatedKeyId; unvalidatedKeyId = undefined; if (!revokeKeyIdempotent(ctx, keyId)) { console.warn("[link] apply failed before storing the link; its issued key could not be revoked"); compensation = keyCleanupFailed(); } } if (plantedFreshBinary) { plantedFreshBinary = false; try { const purged = await run(remotePurgePlantedChildArgv(remotePlatform)); if (purged.code === 0) remoteMayBeConnected = false; else { remoteMayBeConnected = true; purgeRollbackFailed = true; } } catch { remoteMayBeConnected = true; purgeRollbackFailed = true; } } const outcome = compensation ?? response; if (!remoteMayBeConnected) return outcome; const payload = await outcome.json() as Record<string, unknown>; const residual = liveResidual(purgeRollbackFailed ? "plant" : ephemeralChild ? "ephemeral" : "full", knownPlatform(), attemptLinkId); return Response.json({ ...payload, residual: true, ...residual }, { status: outcome.status }); }; try { remotePlatform = confirmed.remotePlatform ?? await requireRemotePlatform(runner, alias, route, knownHosts); if (body.requireEphemeral === true) { // Before any plant, key or Child change: a runnable full ocx anywhere the gated argv looks refuses. phase = "full_install_census"; if (remotePlatform === "windows") return fail("require_ephemeral_unsupported", "--require-ephemeral is not supported for a Windows Child.", 409); const census = await run(remoteFullInstallCensusArgv()); const verdict = census.code === 0 ? parseFullInstallCensus(census.stdout) : null; if (verdict === null) return fail("full_install_census_failed", "The Child could not be checked for a full OpenCodex install.", 502, sshFailureHint(census.stderr)); if (verdict === "present") return fail("full_install_present", "A full OpenCodex install is on the Child; --require-ephemeral refuses it before any change.", 409); } if (body.plant === true && confirmed.runtimeKind === "missing") { phase = "remote_plant"; const source = resolveBinary(confirmed.targetTriple ?? null); if (!source.ok) return fail("remote_plant_unavailable", plantUnavailableGuidance(source.reason, confirmed.targetTriple ?? null), 409, source.reason); let planted: SshRunResult; journal.intent("plant"); try { planted = await runner.run( buildExecArgv({ alias, argv: remotePlantChildArgv(remotePlatform, source.artifact.sizeBytes, source.artifact.sha256), knownHostsFile: knownHosts, route }), { stdin: source.artifact.bytes, timeoutMs: Math.max(budget, 60_000) }, ); } catch (plantErr) { if (plantErr instanceof SshRunnerError && plantErr.code === "timeout") { return fail("remote_plant_timeout", "Planting ocx-child on the remote host timed out.", 502, sshRunnerErrorHint(plantErr)); } return fail("remote_plant_failed", "Could not plant ocx-child on the remote host.", 502, sshRunnerErrorHint(plantErr)); } if (planted.code !== 0) { const reason = classifyPlantFailure(planted.stderr); if (reason) return fail("remote_plant_failed", "The Child has no sha256sum, shasum, or openssl to verify the ocx-child binary, so it was not installed.", 502, reason); return fail("remote_plant_failed", "Could not plant ocx-child on the remote host.", 502, sshFailureHint(planted.stderr)); } plantedFreshBinary = true; journal.done("plant"); ephemeralChild = true; } phase = "remote_port"; const chosen = await run(ocx(["link", "port"])); const denied = remoteFailure(chosen, "remote_port_failed", "The remote link port could not be determined."); if (denied) return await failed(denied); const remotePort = parsePort(chosen.stdout); if (!remotePort) return await failed(fail("remote_port_failed", "The remote link port could not be determined.", 502)); journal.port(remotePort); phase = "child_preflight"; const configured = await run(ocx(["config", "show", "--json"]), budget, CHILD_PREFLIGHT_MAX_OUTPUT_BYTES); let childConfig: unknown = null; try { if (configured.code === 0) childConfig = JSON.parse(configured.stdout); } catch { /* fail closed */ } if (!isRecord(childConfig) || !port(childConfig.port)) { const hint = await childConfigFailureReason(configured, () => run(ocx(["config", "validate", "--json"]), budget, CHILD_CONFIG_VALIDATE_MAX_OUTPUT_BYTES)); return await failed(fail("child_preflight_failed", "The Child effective configuration could not be read.", 502, hint)); } if ((childConfig.runtimeRole ?? "standalone") !== "standalone") return await failed(fail("child_restart_unsupported", "The Child must run standalone OpenCodex; an existing Hub or Child cannot be converted by Add Child.", 409, childRoleRefusalHint(childConfig.runtimeRole))); const childPort = childConfig.port; if (remotePlatform === "posix" && (await run(REMOTE_CURL_PREFLIGHT)).code !== 0) return await failed(fail("child_curl_missing", "Install curl on the Child before connecting a Remote Link.", 409)); const before = await run(remoteChildHttpArgv(childPort, "healthz", LINK_RELAY_VERIFY_MS, remotePlatform)); ephemeralChild = isDetachedEphemeralChildConfig(childConfig); if (ephemeralChild) { if (before.code === 255) return await failed(fail("child_preflight_failed", "The Child loopback port could not be inspected.", 502, sshFailureHint(before.stderr))); if (before.code === 0) return await failed(fail("child_port_busy", "The Child's target port is already in use; no Child files were modified.", 409)); } else { let beforeHealth: unknown = null; try { if (before.code === 0) beforeHealth = parseChildHttp(before.stdout); } catch { /* reported as nothing answering */ } if (!isChildHealth(beforeHealth, "standalone", childPort)) return await failed(fail("child_restart_unsupported", "The Child must run a standalone OpenCodex with bound restart support; update or disconnect it before linking.", 409, childHealthRefusalHint(beforeHealth, childPort))); } state.confirmedHosts?.delete(alias); phase = "home_setup"; const id = attemptLinkId; journal.intent("key_issued"); let issued: ReturnType<typeof issueKey>; if (journal.reservedKeyId === undefined) issued = issueKey(ctx, "link:" + alias); else { // The config may be saved before issuing throws (a reconcile that fails afterwards), leaving the reserved key // durable while memory says it is absent: never settle that as clean. // failed() still rolls back a binary this apply planted; the key's own outcome stays unknown. try { issued = issueKey(ctx, "link:" + alias, journal.reservedKeyId); } catch { return await failed(fail("key_issue_uncertain", "Issuing the link key failed after it may have been saved; whether the reserved key exists is unknown.", 500)); } } unvalidatedKeyId = issued.id; if (journal.reservedKeyId !== undefined && issued.id !== journal.reservedKeyId) return await failed(fail("key_reservation_failed", "The link key was not issued under its reserved id.", 500)); journal.done("key_issued"); const candidate: LinkStore["links"][number] = { id, alias, direction: "hub-initiated", hostKeyFingerprint: confirmed.fingerprint, tunnelPort: remotePort, apiKeyId: issued.id, createdAt: new Date(now()).toISOString(), remotePlatform, childKind: ephemeralChild ? "ephemeral" : "full", ...routeFields(routeOf(confirmed)) }; // Under the same lock as the store write: no Home-initiated link may own this alias in any // case, and the live known_hosts must still trust exactly the confirmed key for it (another // confirmation, under any spelling, may have replaced it since this one). Only a record that // passed both becomes `record`, the one compensation handles; any earlier failure, an // exception included, leaves it unset and revokes the key alone. A write that throws leaves // its outcome unknown: compensation re-runs the same checks before it would store the record. journal.intent("link_recorded"); const created = withConfigMutationLockSync((): "written" | "exists" | ConfirmedLineTrust => { const current = readStoreFor(ctx); const check = linkCheck(current); if (check !== "trusted") return check; record = candidate; unvalidatedKeyId = undefined; writeStoreFor(ctx, { ...current, links: [...current.links, candidate] }); return "written"; }); if (created !== "written") { // The record failed validation and was never stored; failed() revokes its key alone. return await failed(created === "exists" ? fail("link_exists", "A link for this alias already exists.", 409) : created === "trust_file_unexpected" ? fail("trust_file_unexpected", "The link known_hosts file has a pattern, host-list, marker or malformed line; remove that line, then probe and confirm the host again.", 409) : fail("host_key_changed", "The confirmed host key is no longer the one trusted for this alias; probe and confirm the host again.", 409)); } // An ephemeral ocx-child never reads route intent, so its enrollment saves none: seeding would // also start ocx sync applying route intent to every Home client. if (!ephemeralChild) withConfigMutationLockSync(() => seedRouteDeviceClients(ctx.config, ctx.version, id, undefined, readStoreFor(ctx).links.map(link => link.id))); journal.done("link_recorded"); await state.listener.ensureStarted(); if (state.listener.status().state !== "listening") return await failed(fail("listener_unavailable", "The link listener is unavailable.", 503)); await state.supervisor.ensureStarted(); await state.supervisor.reload(); phase = "remote_connect"; input = new TextEncoder().encode(JSON.stringify({ apiKeyId: issued.id, key: issued.key })); journal.intent("child_enrolled"); remoteMayBeConnected = true; const connected = await runner.run(buildExecArgv({ alias, argv: ocx(["connect", "--link", "--key-stdin", "--tunnel-port", String(remotePort), "--link-id", id]), knownHostsFile: knownHosts, route }), { stdin: input, timeoutMs: budget }); if (connected.code !== 0) { const conflict = classifyChildAttachConflict(connected.stderr); if (conflict === "child_port_busy") { remoteMayBeConnected = false; return await failed(fail("child_port_busy", "The Child's target port is already in use; no Child files were modified.", 409, sshFailureHint(connected.stderr))); } if (conflict === "child_external_provider_conflict") { remoteMayBeConnected = false; return await failed(fail("child_external_provider_conflict", "The Child's ~/.codex/config.toml is already managed by another model provider or custom base URL; no Child files were modified.", 409, sshFailureHint(connected.stderr))); } } const connectDenied = remoteFailure(connected, "remote_connect_failed", "The Child enrollment command failed."); if (connectDenied) return await failed(connectDenied); input.fill(0); journal.done("child_enrolled"); journal.intent("relay_verified"); phase = "child_restart"; const restarted = await run(ocx(["restart"]), linkRestartBudget(confirmed.sshLatencyMs)); if (restarted.code !== 0) return await failed(fail("child_restart_failed", "The Child restart could not be verified.", 502, sshFailureHint(restarted.stderr))); phase = "child_relay"; const deadline = now() + LINK_RELAY_VERIFY_MS, remaining = () => Math.max(1, deadline - now()); const health = await run(remoteChildHttpArgv(childPort, "healthz", remaining(), remotePlatform), remaining()); if (!isChildHealth(health.code === 0 ? parseChildHttp(health.stdout) : null, "client", childPort)) return await failed(fail("child_runtime_not_client", "The Child is not serving the client runtime after restart.", 502)); let admitted = false; const unsubscribe = state.listener.onAuthenticatedCatalog(keyId => { if (keyId === issued.id) admitted = true; }); try { if (now() >= deadline) return await failed(fail("child_relay_timeout", "The Child relay verification deadline expired.", 502)); const catalog = await run(remoteChildHttpArgv(childPort, "v1/catalog", remaining(), remotePlatform), remaining(), LINK_CATALOG_MAX_BYTES); let data: unknown = null; try { if (catalog.code === 0) data = parseChildHttp(catalog.stdout); } catch { /* malformed is not a completed catalog */ } if (!isRecord(data) || !Array.isArray(data.models) || !admitted || now() > deadline) return await failed(fail("child_relay_failed", "The Child did not relay a complete authenticated catalog through this Home.", 502)); journal.done("relay_verified"); return Response.json({ linkId: id }, { status: 202 }); } finally { unsubscribe(); } } catch (error) { if (phase === "child_preflight" && error instanceof SshRunnerError && error.code === "output_limit") { return await failed(fail("child_preflight_output_limit", CHILD_CONFIG_TOO_LARGE_MESSAGE, 502, CHILD_CONFIG_TOO_LARGE_HINT)); } return await failed(fail(phase + (error instanceof SshRunnerError && error.code === "timeout" ? "_timeout" : "_failed"), "Remote Link failed during " + phase.replaceAll("_", " ") + ".", 502, sshRunnerErrorHint(error))); } finally { input?.fill(0); rmSync(dir, { recursive: true, force: true }); } })()); }); }); }