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