@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,660 lines • 88.9 kB
text/typescript
import { createHash } from "node:crypto";
import {
existsSync,
lstatSync,
mkdirSync,
readFileSync,
unlinkSync,
} from "node:fs";
import { hostname } from "node:os";
import { dirname } from "node:path";
import { atomicWriteFile, loadConfig, withConfigMutationLockSync } from "../config";
import { getConfigDir, withConfigDirHardeningSettled } from "../config/paths";
import { claudeDesktopIntegrationEnabledNow } from "../codex/desired-state";
import { siblingOfLivePort, siblingSkipMessage } from "../codex/sibling-start";
import {
inspectRemoteDesktopStore, readDesktopDisconnectReceipt, writeDesktopDisconnectReceipt, removeDesktopDisconnectReceipt,
replaceRemoteDesktopCredential, restoreRemoteDesktopStore, finishRemoteDesktopCleanup,
type DesktopDisconnectReceipt, type DesktopRemoteOwner, type DesktopStoreResult,
} from "../claude/desktop-remote-store";
import {
withClientDisconnectAttempt, withClientLifecycle, withClientLifecycleSync,
type ClientLifecycleHeld, type ClientLifecycleLockDeps,
} from "./lifecycle-lock";
import { invalidateCodexModelsCache, invalidateCodexModelsCacheWithPermit } from "../codex/catalog/sync";
import { desktopLifecycleRefusal } from "./desktop-refusal";
import { withCatalogWriteSerialization } from "../codex/catalog-write-serialization";
import {
injectCodexConfig,
currentExternalCodexModelProvider,
isCodexRoutingInjected,
standaloneCodexRoutingTarget,
type CodexRoutingTarget,
} from "../codex/inject";
import {
JOURNAL_PATH,
adoptJournalForClient,
journalHandoverIncomplete,
journalOwner,
restoreJournalState,
} from "../codex/journal";
import { ConfigWriteContentChanged } from "../codex/config-write-lock";
import { readCodexHomeJournal } from "../codex/codex-home-owner";
import { DEFAULT_CATALOG_PATH, getCodexHome } from "../codex/paths";
import {
readServiceApiTokenState,
readTokenBackupState,
removeServiceApiTokenFileIfOwned,
removeOrphanTokenBackup,
replaceServiceApiTokenFile,
restoreTokenBackup,
serviceApiTokenBackupPath,
serviceApiTokenFingerprint,
writeTokenBackup,
writeServiceApiTokenFile,
} from "../lib/service-secrets";
import { MAX_REMOTE_CATALOG_BYTES } from "../server/catalog-download";
import { readHubCredential, removeHubCredential, writeHubCredential, type HubRelayCredential } from "./hub-session";
import type {
OcxClientConnectionConfig,
OcxConfig,
OcxConnectedClientId,
} from "../types";
import {
downloadClientCatalog,
abortClientKeyRotation,
commitClientKeyRotation,
exchangeConnectPairingGrant,
fetchHubReady,
HubClientError,
issueClientKey,
normalizeHubOrigin,
probeClientKeyId,
requestHubRelayCredential,
revokeClientKey,
revokeHubRelayLease,
startClientKeyRotation,
type ConnectGuiSession,
type IssuedClientKey,
type OneTimeConnectCredential,
} from "./hub-client";
import {
clearClientConnection,
commitClientConnection,
readClientConnectionState,
isLinkConnection,
markClientConnectPending, clearClientConnectPending, pendingClientConnectMayOwnToken,
assertNoClientDisconnectPending, assertClientConnectionUnchanged, sameClientConnectionOwner,
} from "./state";
import { assertClientCatalogCompatible, type CatalogCompatibilityDeps } from "./catalog-compatibility";
import {
assertClientSyncExpectation, assertDisconnectLinkExpectation, ClientSyncExpectationError, isClientSyncLockBusy, type ClientSyncExpectation,
} from "./sync-expectation";
import { overlayHomeCodexSettings } from "../link/codex-settings";
import {
clearHomeCodexSettingsRecord,
fetchHomeCodexSettings,
homeCodexSettingsReceipt,
readHomeCodexSettingsRecord,
resolveHomeCodexSettings,
recordHomeCodexSettings,
withLinkApply,
withdrawChangingHomeCodexSettingsRecord,
writeHomeCodexSettingsRecord,
type HomeCodexSettingsRecord,
type HomeCodexSettingsSource,
type LinkHomeDeps,
} from "./link-home";
import { hubStateCachePath } from "./hub-state";
import { ClientLinkStateError, clearClientLinkState, readChildLinkMarker, readClientLinkState } from "./link-state";
import { isLinkPort } from "../link/ports";
import { assertRouteIntentPort, clientSyncRuntimeGuard, ClientSyncRuntimeError } from "./sync-runtime";
import { prepareConnectedRouteIntent, initialConnectRouteIntent, connectedRouteSelectedClients, applyConnectedRouteIntent } from "../integrations/route-intent-connected";
import { clearRouteIntentReceipt, clearRouteIntentUnappliedProof, readRouteIntentReceiptStrict, writeRouteIntentUnappliedProof } from "../integrations/route-intent-state";
import type { RouteIntentReceipt } from "../integrations/route-intent-contract";
import { clearHomeRouteIntentRecord } from "./link-home";
import { clearInitialRouteIntent, recordInitialRouteIntent } from "../integrations/route-intent-initial";
import { cleanupConnectedRouteIntent } from "../integrations/route-intent-disconnect";
import { nativeIntentOriginalsPath, readNativeIntentOriginals, restoreNativeIntentOriginals } from "./route-intent-native-originals";
import { clearFileIntentOriginals } from "./route-intent-file-originals";
class RotationRecoveryRequiredError extends Error {
constructor(message: string, options?: ErrorOptions) {
super(message, options);
this.name = "RotationRecoveryRequiredError";
}
}
export interface ConnectOptions {
serverUrl: string;
managementUrl?: string;
credential: OneTimeConnectCredential | LinkClientCredential;
selectedClients: OcxConnectedClientId[];
/** Provisioning selection retained until Home revises that client's device policy. */
selectedClientsExplicit?: boolean;
managementTransport: "direct" | "relay";
transport?: "hub" | "link";
link?: { tunnelPort: number; linkId: string };
noSync?: boolean;
catalogTimeoutMs?: number;
}
export interface LinkClientCredential {
kind: "link";
apiKeyId: string;
key: string;
}
export interface ClientConnectDeps {
/** Abort enrollment network work and refuse subsequent writes; rollback still drains. */
signal?: AbortSignal;
fetchImpl?: typeof fetch;
now?: () => Date;
lifecycleLockDeps?: ClientLifecycleLockDeps;
catalogCompatibility?: CatalogCompatibilityDeps;
/** Link mode: how the Home's Codex settings are read (#6957). */
linkHome?: LinkHomeDeps;
/** Link mode: the apply lock's path (OCX-6); defaults to `<configDir>/link/apply-lock.sqlite`. */
linkApplyLockPath?: string;
}
export interface RotateClientOptions {
credential: OneTimeConnectCredential;
}
type CatalogSnapshot =
| { kind: "absent" }
| { kind: "file"; body: string; fingerprint: string };
function sha256(value: string): string {
return createHash("sha256").update(value).digest("hex");
}
function catalogSnapshot(): CatalogSnapshot {
if (!existsSync(DEFAULT_CATALOG_PATH)) return { kind: "absent" };
const stat = lstatSync(DEFAULT_CATALOG_PATH);
if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_REMOTE_CATALOG_BYTES) {
throw new Error("existing OpenCodex catalog is not a bounded regular file");
}
const body = readFileSync(DEFAULT_CATALOG_PATH, "utf8");
return { kind: "file", body, fingerprint: sha256(body) };
}
function restoreCatalogSnapshot(snapshot: CatalogSnapshot, writtenFingerprint: string): boolean {
try {
if (!existsSync(DEFAULT_CATALOG_PATH)) return snapshot.kind === "absent";
const stat = lstatSync(DEFAULT_CATALOG_PATH);
if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_REMOTE_CATALOG_BYTES) return false;
const current = readFileSync(DEFAULT_CATALOG_PATH, "utf8");
if (sha256(current) !== writtenFingerprint) return false;
if (snapshot.kind === "absent") unlinkSync(DEFAULT_CATALOG_PATH);
else atomicWriteFile(DEFAULT_CATALOG_PATH, snapshot.body);
return true;
} catch {
return false;
}
}
function validLocalCatalog(): string {
const snapshot = catalogSnapshot();
if (snapshot.kind !== "file") throw new Error("connected catalog is missing");
try {
const parsed = JSON.parse(snapshot.body) as unknown;
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid");
} catch {
throw new Error("connected catalog is malformed");
}
return snapshot.body;
}
/**
* Is the on-disk catalog still the one this connection wrote?
*
* Recorded as our own hash rather than the hub's ETag: /v1/catalog emits no validator
* (Phase 1, D2), so there is no server-supplied tag to keep. This is an ownership check on
* local bytes, which never needed the hub's participation — the previous spelling only
* looked like a cache concern because it reused the ETag string.
*/
function catalogMatchesFingerprint(body: string, fingerprint: string | undefined): boolean {
if (!fingerprint) return false;
return createHash("sha256").update(body).digest("base64url") === fingerprint;
}
/**
* Codex routing for a connected client. A hub client points Codex at the hub with the admission
* token in `env_key`. A link Child (`localPort` given) keeps exactly the standalone loopback form,
* root `openai_base_url = "http://127.0.0.1:<port>/v1"` with no provider table and no `env_key`:
* its own listener relays to the Home and attaches the link key itself, so a GUI-launched Codex
* that never saw the key's environment variable still works, and joining changes no Codex bytes.
*/
export function routingTarget(
serverUrl: string,
localPort?: number,
config?: Pick<OcxConfig, "codexDesktopAuthless" | "codexClientCompaction">,
): CodexRoutingTarget & { link?: true } {
if (localPort === undefined) {
return { baseUrl: `${serverUrl}/v1`, requiresAdmissionToken: true, tokenEnv: "OPENCODEX_API_AUTH_TOKEN" };
}
if (!Number.isInteger(localPort) || localPort < 1 || localPort > 65535) {
throw new Error("link mode requires a valid local config port");
}
return {
...standaloneCodexRoutingTarget(localPort, {
hostname: "127.0.0.1",
codexDesktopAuthless: config?.codexDesktopAuthless,
codexClientCompaction: config?.codexClientCompaction,
}),
link: true as const,
};
}
function localGuiOrigin(): string {
const port = loadConfig().port;
return `http://localhost:${Number.isInteger(port) && port > 0 ? port : 10100}`;
}
type ConnectCredential = { kind: "admin"; value: Uint8Array } | { kind: "gui-session"; value: ConnectGuiSession };
async function provisionHubRelay(
connection: OcxClientConnectionConfig, authority: ConnectCredential, key: string, fetchImpl?: typeof fetch,
): Promise<HubRelayCredential | null> {
try {
return await requestHubRelayCredential(connection.managementUrl, authority, connection.apiKeyId, key, fetchImpl);
} catch {
console.warn("Warning: Hub relay credential unavailable. Local management reads require a current Hub relay credential.");
return null;
}
}
/** The caller holds the configuration mutation lock for this connection generation. */
function persistHubRelay(connection: OcxClientConnectionConfig, credential: HubRelayCredential | null): void {
try {
if (credential) writeHubCredential(credential, connection);
else removeHubCredential();
} catch {
console.warn("Warning: could not update the local Hub relay credential.");
}
}
function clientKeyName(): string {
const raw = `ocx connect ${hostname() || "client"}`;
return raw.slice(0, 80);
}
function releaseCredential(credential: OneTimeConnectCredential): void {
credential.value.fill(0);
}
function releaseConnectCredential(credential: ConnectOptions["credential"]): void {
if (credential.kind !== "link") releaseCredential(credential);
}
async function rotationAuthority(
connection: OcxClientConnectionConfig,
options: RotateClientOptions,
deps: ClientConnectDeps,
): Promise<ConnectCredential> {
if (options.credential.kind === "admin") return { kind: "admin", value: options.credential.value };
const session = await exchangeConnectPairingGrant(
connection.managementUrl,
localGuiOrigin(),
options.credential.value,
{ fetchImpl: deps.fetchImpl },
);
return { kind: "gui-session", value: session };
}
async function replaceHubRelayCredential(
connection: ClientRotationResult, authority: ConnectCredential, key: string, deps: ClientConnectDeps,
): Promise<ClientRotationResult> {
const credential = await provisionHubRelay(connection, authority, key, deps.fetchImpl);
const { rotationOutcome: _rotationOutcome, ...committed } = connection;
try {
withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(committed);
persistHubRelay(committed, credential);
});
} catch {
console.warn("Warning: the Hub key rotated but the local relay credential could not be published.");
}
return connection;
}
export type ClientRotationResult = OcxClientConnectionConfig & {
rotationOutcome: "committed" | "rolled_back";
};
function desktopOwner(connection: OcxClientConnectionConfig): DesktopRemoteOwner {
return { serverUrl: connection.serverUrl, apiKeyId: connection.apiKeyId, connectedAt: connection.connectedAt };
}
function requireDesktopResult(result: DesktopStoreResult): Extract<DesktopStoreResult, { ok: true }> {
if (!result.ok) throw new Error(`desktop_lifecycle_${result.reason}`);
return result;
}
function assertRotationCandidates(
connection: OcxClientConnectionConfig,
currentFingerprint: string,
backupFingerprint: string,
): void {
assertClientConnectionUnchanged(connection);
const current = readServiceApiTokenState();
const backup = readTokenBackupState();
if (current.kind !== "present" || backup.kind !== "present"
|| current.fingerprint !== currentFingerprint || backup.fingerprint !== backupFingerprint) {
throw new RotationRecoveryRequiredError("rotation token generations changed; preserve recovery files");
}
}
function alignDesktopCredential(
held: ClientLifecycleHeld,
connection: OcxClientConnectionConfig,
previousFingerprint: string,
token: { token: string; fingerprint: string },
): void {
withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(connection);
const current = readServiceApiTokenState();
if (current.kind !== "present" || current.fingerprint !== token.fingerprint) {
throw new Error("client_token_changed");
}
if (inspectRemoteDesktopStore(desktopOwner(connection)).kind === "absent") return;
let result: DesktopStoreResult;
if (!claudeDesktopIntegrationEnabledNow()) {
result = restoreRemoteDesktopStore(held, {
owner: desktopOwner(connection), knownTokenFingerprints: [connection.tokenFingerprint, current.fingerprint],
});
} else {
result = replaceRemoteDesktopCredential(held, {
owner: desktopOwner(connection), expectedTokenFingerprint: previousFingerprint, replacementKey: current.token,
});
if (!result.ok && !result.changed && result.reason === "conflict" && previousFingerprint !== current.fingerprint) {
// Recovery may find Desktop already on the chosen generation while only
// service-api-token needed rollback. Retry that exact, freshly proven
// current generation; never retry a partial write or an unsafe artifact.
result = replaceRemoteDesktopCredential(held, {
owner: desktopOwner(connection), expectedTokenFingerprint: current.fingerprint, replacementKey: current.token,
});
}
}
requireDesktopResult(result);
});
}
function finalizeRotation(
held: ClientLifecycleHeld,
connection: OcxClientConnectionConfig,
previousFingerprint: string,
token: { token: string; fingerprint: string },
rotationOutcome: ClientRotationResult["rotationOutcome"],
): ClientRotationResult {
try {
alignDesktopCredential(held, connection, previousFingerprint, token);
return withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(connection);
const current = readServiceApiTokenState();
if (current.kind !== "present" || current.fingerprint !== token.fingerprint) throw new Error("client_token_changed");
const next = { ...connection, tokenFingerprint: token.fingerprint };
delete next.pendingOperation;
commitClientConnection(next);
removeOrphanTokenBackup();
// Outcome is an API result only, never a persisted client configuration field.
return { ...next, rotationOutcome };
});
} catch {
throw new RotationRecoveryRequiredError("rotation local finalization is incomplete; preserve recovery files");
}
}
async function recoverRotationWithAuthority(
held: ClientLifecycleHeld,
connection: OcxClientConnectionConfig,
authority: ConnectCredential,
deps: ClientConnectDeps,
): Promise<ClientRotationResult> {
try {
const pending = connection.pendingOperation;
if (!pending || pending.oldKeyBackupPath !== serviceApiTokenBackupPath()) throw new Error("invalid rotation marker");
const current = readServiceApiTokenState();
const backup = readTokenBackupState();
if (current.kind !== "present" || backup.kind !== "present" || backup.fingerprint !== connection.tokenFingerprint) {
throw new Error("rotation recovery generations are unavailable");
}
const assertFresh = () => withConfigMutationLockSync(() => assertRotationCandidates(connection, current.fingerprint, backup.fingerprint));
assertFresh();
if (current.fingerprint === backup.fingerprint) {
// A crash after the marker but before replacement leaves two copies of OLD.
// Their equal successful probes must never commit an uninstalled new hub key.
if (!await probeClientKeyId(connection.serverUrl, backup.token, connection.apiKeyId, { fetchImpl: deps.fetchImpl })) {
throw new Error("old generation not admitted");
}
assertFresh();
await abortClientKeyRotation(connection.managementUrl, authority, connection.apiKeyId, pending.rotationId, { fetchImpl: deps.fetchImpl });
if (!await probeClientKeyId(connection.serverUrl, backup.token, connection.apiKeyId, { fetchImpl: deps.fetchImpl })) {
throw new Error("old generation not admitted after abort");
}
assertFresh();
return finalizeRotation(held, connection, backup.fingerprint, backup, "rolled_back");
}
const [currentAccepted, backupAccepted] = await Promise.all([
probeClientKeyId(connection.serverUrl, current.token, connection.apiKeyId, { fetchImpl: deps.fetchImpl }),
probeClientKeyId(connection.serverUrl, backup.token, connection.apiKeyId, { fetchImpl: deps.fetchImpl }),
]);
assertFresh();
if (currentAccepted && backupAccepted) {
alignDesktopCredential(held, connection, backup.fingerprint, current);
await commitClientKeyRotation(connection.managementUrl, authority, connection.apiKeyId, pending.rotationId, { fetchImpl: deps.fetchImpl });
assertFresh();
return await replaceHubRelayCredential(finalizeRotation(held, connection, backup.fingerprint, current, "committed"), authority, current.token, deps);
}
if (currentAccepted && !backupAccepted) {
return await replaceHubRelayCredential(finalizeRotation(held, connection, backup.fingerprint, current, "committed"), authority, current.token, deps);
}
if (!currentAccepted && backupAccepted) {
// Remote abort is confirmed before either local credential is rolled back.
await abortClientKeyRotation(connection.managementUrl, authority, connection.apiKeyId, pending.rotationId, { fetchImpl: deps.fetchImpl });
assertFresh();
const restored = withConfigMutationLockSync(() => restoreTokenBackup(pending.oldKeyBackupPath));
return finalizeRotation(held, connection, current.fingerprint, { token: backup.token, fingerprint: restored.fingerprint }, "rolled_back");
}
throw new Error("both generations rejected");
} catch (error) {
if (error instanceof RotationRecoveryRequiredError) throw error;
throw new RotationRecoveryRequiredError("rotation recovery could not settle admission and Desktop state; preserve current and backup tokens");
}
}
export async function recoverPendingClientRotation(
options: RotateClientOptions,
deps: ClientConnectDeps = {},
): Promise<ClientRotationResult> {
try {
return await withClientLifecycle(async held => {
assertNoClientDisconnectPending();
const state = readClientConnectionState();
if (state.kind !== "connected" || !state.value.pendingOperation) throw new Error("no pending client key rotation to recover");
if (isLinkConnection(state.value)) throw new Error("connect rotate is unavailable in link mode");
const authority = await rotationAuthority(state.value, options, deps);
return recoverRotationWithAuthority(held, state.value, authority, deps);
}, deps.lifecycleLockDeps);
} finally { releaseCredential(options.credential); }
}
export async function rotateConnectedClientKey(
options: RotateClientOptions,
deps: ClientConnectDeps = {},
): Promise<ClientRotationResult> {
try {
return await withClientLifecycle(held => rotateConnectedClientKeyHeld(held, options, deps), deps.lifecycleLockDeps);
} finally { releaseCredential(options.credential); }
}
async function rotateConnectedClientKeyHeld(
held: ClientLifecycleHeld,
options: RotateClientOptions,
deps: ClientConnectDeps,
): Promise<ClientRotationResult> {
let connection: OcxClientConnectionConfig | null = null;
let authority: ConnectCredential | null = null;
let started: { rotationId: string; key: string; createdAt: string } | null = null;
let markerPersisted = false;
let backupCreated = false;
let hubCommitted = false;
try {
assertNoClientDisconnectPending();
const state = readClientConnectionState();
if (state.kind !== "connected") throw new Error("connect rotate is available only while connected");
connection = state.value;
if (isLinkConnection(connection)) throw new Error("connect rotate is unavailable in link mode");
const current = readServiceApiTokenState();
if (current.kind !== "present") throw new Error("connected service token unavailable");
if (!connection.pendingOperation) {
if (current.fingerprint !== connection.tokenFingerprint) throw new Error("connected service token ownership changed");
const desktop = inspectRemoteDesktopStore(desktopOwner(connection));
if (["conflict", "unsafe", "pending"].includes(desktop.kind)) throw new Error("desktop_lifecycle_recovery_required");
// Establish legacy fallback ownership and reject edited projections BEFORE hub issuance.
// The remote Desktop store writes under the config root with required ACLs, so it admits
// after overlapping config-root ACL work (#7815); a timeout here refuses before the hub.
const unchanged = connection;
await withConfigDirHardeningSettled(getConfigDir(), () => alignDesktopCredential(held, unchanged, current.fingerprint, current));
withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(connection!);
const orphan = readTokenBackupState();
if (orphan.kind === "unsafe") throw new Error("service token backup is unsafe");
if (orphan.kind === "present") removeOrphanTokenBackup();
});
}
authority = await rotationAuthority(connection, options, deps);
if (connection.pendingOperation) return recoverRotationWithAuthority(held, connection, authority, deps);
withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(connection!);
writeTokenBackup(current.fingerprint);
});
backupCreated = true;
const rotation = await startClientKeyRotation(connection.managementUrl, authority, connection.apiKeyId, { fetchImpl: deps.fetchImpl });
started = { rotationId: rotation.rotationId, key: rotation.key, createdAt: rotation.createdAt };
const marked: OcxClientConnectionConfig = {
...connection,
pendingOperation: { kind: "rotate", rotationId: rotation.rotationId, newKeyIssuedAt: rotation.createdAt, oldKeyBackupPath: serviceApiTokenBackupPath() },
};
withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(connection!);
commitClientConnection(marked);
});
connection = marked;
markerPersisted = true;
const replacement = withConfigMutationLockSync(() => {
assertRotationCandidates(connection!, current.fingerprint, current.fingerprint);
return replaceServiceApiTokenFile(rotation.key);
});
// Still before the hub commit: an admission timeout takes the ordinary rollback below.
const marking = connection;
await withConfigDirHardeningSettled(getConfigDir(), () =>
alignDesktopCredential(held, marking, current.fingerprint, { token: rotation.key, fingerprint: replacement.fingerprint }));
if (!await probeClientKeyId(connection.serverUrl, rotation.key, connection.apiKeyId, { fetchImpl: deps.fetchImpl })) {
throw new Error("new client key admission probe was refused");
}
withConfigMutationLockSync(() => assertRotationCandidates(connection!, replacement.fingerprint, current.fingerprint));
try {
await commitClientKeyRotation(connection.managementUrl, authority, connection.apiKeyId, rotation.rotationId, { fetchImpl: deps.fetchImpl });
} catch {
return await recoverRotationWithAuthority(held, connection, authority, deps);
}
hubCommitted = true;
const finalized = finalizeRotation(held, connection, current.fingerprint, { token: rotation.key, fingerprint: replacement.fingerprint }, "committed");
return await replaceHubRelayCredential(finalized, authority, rotation.key, deps);
} catch (error) {
if (error instanceof RotationRecoveryRequiredError || hubCommitted) {
throw error instanceof RotationRecoveryRequiredError ? error : new RotationRecoveryRequiredError("committed rotation requires local recovery");
}
if (connection && authority && started) {
try {
await abortClientKeyRotation(connection.managementUrl, authority, connection.apiKeyId, started.rotationId, { fetchImpl: deps.fetchImpl });
if (markerPersisted && connection.pendingOperation) {
const beforeRestore = readServiceApiTokenState();
const backup = readTokenBackupState();
if (beforeRestore.kind !== "present" || backup.kind !== "present") throw new Error("rotation rollback token unavailable");
withConfigMutationLockSync(() => {
assertRotationCandidates(connection!, beforeRestore.fingerprint, backup.fingerprint);
restoreTokenBackup(connection!.pendingOperation!.oldKeyBackupPath);
});
finalizeRotation(held, connection, beforeRestore.fingerprint, backup, "rolled_back");
} else {
withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(connection!);
if (backupCreated) removeOrphanTokenBackup();
});
}
} catch {
throw new RotationRecoveryRequiredError("rotation rollback was incomplete; preserve current and backup tokens");
}
} else if (backupCreated && connection) {
withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(connection!);
removeOrphanTokenBackup();
});
}
throw error;
} finally {
if (started) started.key = "";
authority = null;
}
}
async function cleanupIssuedKey(
managementUrl: string,
credential: ConnectCredential,
issuedId: string,
deps: ClientConnectDeps,
): Promise<string | null> {
try {
await revokeClientKey(managementUrl, credential, issuedId, { fetchImpl: deps.fetchImpl });
return null;
} catch {
return `Hub cleanup could not revoke client key ${issuedId}; revoke it from Integrations → API Keys.`;
}
}
function assertConnectingState(expectedTokenFingerprint?: string): void {
assertNoClientDisconnectPending();
if (readClientConnectionState().kind !== "disconnected") throw new Error("client_connection_changed");
const token = readServiceApiTokenState();
if (expectedTokenFingerprint === undefined ? token.kind !== "absent"
: token.kind !== "present" || token.fingerprint !== expectedTokenFingerprint) {
if (expectedTokenFingerprint === undefined && token.kind === "present") {
throw new Error("client_token_changed: if this is not a Hub and no admission secret or installed service uses the token, inspect it and use ocx disconnect --orphaned-token --yes before retrying");
}
throw new Error("client_token_changed");
}
}
/** Enroll a client key, keeping its pending ownership visible until commit or rollback. */
/**
* Connect this machine to a hub or, with `transport: "link"`, to a Remote Link Home. A link
* connect holds the apply lock throughout (OCX-6), because it applies the Home's Codex settings
* and records that apply exactly as `ocx sync` does.
*/
export async function connectClient(
options: ConnectOptions,
deps: ClientConnectDeps = {},
): Promise<OcxClientConnectionConfig> {
if ((options.transport ?? "hub") !== "link") return connectClientUnlocked(options, deps);
return withLinkApply(() => connectClientUnlocked(options, deps), deps.linkApplyLockPath);
}
async function connectClientUnlocked(
options: ConnectOptions,
deps: ClientConnectDeps = {},
): Promise<OcxClientConnectionConfig> {
deps.signal?.throwIfAborted();
const rawFetch = deps.fetchImpl ?? fetch;
const fetchImpl: typeof fetch = deps.signal ? Object.assign(async (...[input, init = {}]: Parameters<typeof fetch>) => {
deps.signal!.throwIfAborted();
const signals = [deps.signal, init.signal, input instanceof Request ? input.signal : undefined]
.filter((signal): signal is AbortSignal => signal != null);
return rawFetch(input, { ...init, signal: AbortSignal.any(signals), redirect: "manual" });
}, { preconnect: rawFetch.preconnect }) : rawFetch;
const assertActiveConnectingState = (fingerprint?: string) => {
deps.signal?.throwIfAborted();
assertConnectingState(fingerprint);
};
let serverUrl = "";
let managementUrl = "";
let linkAdmissionToken: string | null = null;
let linkMode = false;
let linkMetadata: { tunnelPort: number; linkId: string } | undefined;
let issued: IssuedClientKey | null = null;
let cleanupCredential: ConnectCredential | null = null;
let tokenFingerprint: string | null = null;
let pendingConnectFingerprint: string | null = null;
let priorCatalog: CatalogSnapshot | null = null;
let writtenCatalogFingerprint: string | null = null;
let injectionCommitted = false;
let restoreNativeIntent = false;
let committed = false;
let initialSelectionWritten = false;
// Before any catalog, journal, client-state or credential write: `CODEX_HOME` is shared with the
// live proxy a sibling instance runs beside, and connecting re-points it (`sibling-start.ts`).
if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
try {
linkMode = (options.transport ?? "hub") === "link";
if (linkMode) {
if (options.credential.kind !== "link" || !options.link
|| !isLinkPort(options.link.tunnelPort)
|| !/^lnk_[0-9a-f]{16}$/.test(options.link.linkId)
|| !/^ocx_data_[0-9a-f]{40}$/.test(options.credential.key)
|| !options.credential.apiKeyId.trim() || options.credential.apiKeyId.length > 256) {
throw new Error("invalid link credential");
}
linkMetadata = { ...options.link };
serverUrl = `http://127.0.0.1:${linkMetadata.tunnelPort}`;
if ((options.managementUrl && options.managementUrl !== serverUrl) || options.managementTransport !== "direct") {
throw new Error("link mode requires direct management on the tunnel origin");
}
managementUrl = serverUrl;
} else {
if (options.credential.kind === "link" || options.link) throw new Error("link credential requires link transport");
serverUrl = normalizeHubOrigin(options.serverUrl);
if (options.managementUrl) managementUrl = normalizeHubOrigin(options.managementUrl);
}
if (options.selectedClients.length < 1 || new Set(options.selectedClients).size !== options.selectedClients.length) {
throw new Error("at least one unique connected client is required");
}
// Only link mode needs the local port before the hub is contacted; hub mode keeps reading config
// after the catalog download, so its stderr order (catalog refusal first) is unchanged.
const earlyConfig = linkMode ? loadConfig() : undefined;
if (earlyConfig) assertRouteIntentPort(earlyConfig.port);
if (earlyConfig && (!Number.isInteger(earlyConfig.port) || earlyConfig.port < 1 || earlyConfig.port > 65535)) {
throw new Error("link mode requires a valid local config port");
}
withClientLifecycleSync(() => withConfigMutationLockSync(() => {
assertActiveConnectingState();
const externalProvider = currentExternalCodexModelProvider();
if (externalProvider) throw new Error("connect refused: an external Codex provider owns config.toml");
if (linkMode) {
const credential = options.credential;
if (credential.kind !== "link") throw new Error("invalid link credential");
const persisted = writeServiceApiTokenFile(credential.key);
pendingConnectFingerprint = persisted.fingerprint;
const reread = readServiceApiTokenState();
if (reread.kind !== "present" || reread.fingerprint !== persisted.fingerprint) {
throw new Error("invalid link credential");
}
markClientConnectPending(persisted.fingerprint);
linkAdmissionToken = reread.token;
}
}), deps.lifecycleLockDeps);
const upstreamFetch = fetchImpl;
const readinessFetch = linkMode
? (async (input, init = {}) => {
const url = input instanceof Request ? input.url : String(input);
if (!url.endsWith("/readyz")) return upstreamFetch(input, init);
const headers = new Headers(init.headers);
headers.set("x-opencodex-api-key", linkAdmissionToken!);
return upstreamFetch(input, { ...init, headers });
}) as typeof fetch
: upstreamFetch;
const ready = await fetchHubReady(serverUrl, { fetchImpl: readinessFetch });
if (ready.status !== "ready") throw new Error(`hub is not ready (${ready.status})`);
if (!linkMode) managementUrl = managementUrl || ready.metadata.managementUrl;
if (!linkMode && options.credential.kind === "pairing-grant") {
const session = await exchangeConnectPairingGrant(
managementUrl,
localGuiOrigin(),
options.credential.value,
{ fetchImpl },
);
cleanupCredential = { kind: "gui-session", value: session };
} else if (!linkMode && options.credential.kind === "admin") {
cleanupCredential = { kind: "admin", value: options.credential.value };
}
if (!linkMode) {
issued = await issueClientKey(managementUrl, cleanupCredential!, clientKeyName(), { fetchImpl });
}
const initialFiles = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
assertActiveConnectingState(linkMode ? pendingConnectFingerprint! : undefined);
const persisted = linkMode
? (() => {
const current = readServiceApiTokenState();
if (current.kind !== "present") throw new Error("invalid link credential");
return { fingerprint: current.fingerprint };
})()
: writeServiceApiTokenFile(issued!.key);
const fingerprint = persisted.fingerprint;
if (!pendingConnectFingerprint) {
markClientConnectPending(fingerprint);
pendingConnectFingerprint = fingerprint;
}
return { prior: catalogSnapshot(), persisted };
}), deps.lifecycleLockDeps);
priorCatalog = initialFiles.prior;
const persisted = initialFiles.persisted;
tokenFingerprint = persisted.fingerprint;
const admissionToken = linkMode ? linkAdmissionToken : issued?.key;
if (!admissionToken) throw new Error("client admission credential unavailable");
const apiKeyId = linkMode ? (options.credential as LinkClientCredential).apiKeyId : issued!.id;
const catalog = await downloadClientCatalog(serverUrl, admissionToken, {
fetchImpl,
timeoutMs: options.catalogTimeoutMs,
});
// Fail closed BEFORE the write (#4207). The hub being reachable and the credential working
// does not mean the selected local Codex runtime can consume what arrived: an older CLI
// exits on an unknown reasoning level before making a single request, while connect
// reports success. Refusing here leaves the previous catalog in place untouched, rather
// than writing one and restoring it afterwards.
assertClientCatalogCompatible(catalog.body, deps.catalogCompatibility);
writtenCatalogFingerprint = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
assertActiveConnectingState(persisted.fingerprint);
mkdirSync(dirname(DEFAULT_CATALOG_PATH), { recursive: true });
atomicWriteFile(DEFAULT_CATALOG_PATH, catalog.body);
return sha256(catalog.body);
}), deps.lifecycleLockDeps);
const config = earlyConfig ?? loadConfig();
const routeIntent = initialConnectRouteIntent(linkMode && linkMetadata
? await prepareConnectedRouteIntent({ transport: "link", link: linkMetadata, apiKeyId }, admissionToken, deps.linkHome,
() => assertActiveConnectingState(persisted.fingerprint)) : undefined,
options.selectedClients, options.selectedClientsExplicit);
const selectedClients = connectedRouteSelectedClients(routeIntent, options.selectedClients);
const target = routingTarget(serverUrl, linkMode ? config.port : undefined, config);
// A link Child writes the Home's OpenCodex-owned Codex settings, not its own (#6957). A read
// that fails here keeps the local values; the next `ocx sync` applies the Home's.
// Read only: the record is written after the connection commits, so a rollback leaves none.
const homeSettings = linkMode && linkMetadata && selectedClients.includes("codex")
? await fetchHomeCodexSettings({ transport: "link", link: linkMetadata, apiKeyId }, admissionToken, deps.linkHome)
: undefined;
const injectConfig = {
...(homeSettings?.kind === "fresh" ? overlayHomeCodexSettings(config, homeSettings.document.settings) : config),
syncResumeHistory: false,
};
const beforeCodexWrite = () => {
assertActiveConnectingState(persisted.fingerprint);
if (routeIntent && (!connectedRouteSelectedClients(routeIntent, options.selectedClients).includes("codex")
|| loadConfig().port !== config.port)) throw new Error("Codex route intent or runtime changed; retry connect");
};
if (!options.noSync && routeIntent && selectedClients.includes("codex") && existsSync(getCodexHome())) {
const { persistNativeRouteIntent } = await import("./route-intent-apply");
// Armed before publication: the write-ahead originals record can exist even when the
// config write or its bookkeeping throws, and rollback must still put the field back.
restoreNativeIntent = true;
withClientLifecycleSync(() => withConfigMutationLockSync(() => {
beforeCodexWrite();
// Home intent owns a selected installed client, including a standalone OFF. Keep
// compensation field-scoped: a failed enrollment restores the recorded standalone
// value, keeps a later edit by the person, and keeps disjoint config changes.
persistNativeRouteIntent("codex", true, beforeCodexWrite, injectConfig, true);
}), deps.lifecycleLockDeps);
}
const preflight = !selectedClients.includes("codex") || (routeIntent && !existsSync(getCodexHome()))
? { success: true, message: "Codex is not selected or installed" } : await injectCodexConfig(config.port, injectConfig, {
validateOnly: true,
routingTarget: target,
catalogPath: DEFAULT_CATALOG_PATH,
journalOwner: { kind: "client", apiKeyId },
beforeClientWrite: beforeCodexWrite,
});
if (!preflight.success) throw new Error(preflight.message);
if (!options.noSync && selectedClients.includes("codex") && (!routeIntent || existsSync(getCodexHome()))) {
const injected = await injectCodexConfig(config.port, injectConfig, {
routingTarget: target,
catalogPath: DEFAULT_CATALOG_PATH,
journalOwner: { kind: "client", apiKeyId },
beforeClientWrite: beforeCodexWrite,
});
if (!injected.success || injected.status === "skipped") throw new Error(injected.message);
injectionCommitted = true;
if (!isCodexRoutingInjected()) throw new Error("Codex routing target was not committed");
}
const now = (deps.now ?? (() => new Date()))().toISOString();
const connection: OcxClientConnectionConfig = {
serverUrl,
managementUrl,
managementTransport: options.managementTransport,
selectedClients: [...selectedClients],
tokenEnv: "OPENCODEX_API_AUTH_TOKEN",
apiKeyId,
tokenFingerprint: persisted.fingerprint,
protocolVersion: 1,
connectedAt: now,
catalogFingerprint: createHash("sha256").update(catalog.body).digest("base64url"),
// Durable so disconnect — a different process — can put back whatever was here
// before. The in-memory `priorCatalog` only covers a connect that fails and rolls
// back in the same run.
priorCatalog: priorCatalog.kind === "file" ? Buffer.from(priorCatalog.body, "utf8").toString("base64") : "",
catalogSyncedAt: now,
...(linkMode ? { transport: "link" as const, link: linkMetadata } : {}),
};
const relayCredential = cleanupCredential && issued
? await provisionHubRelay(connection, cleanupCredential, issued.key, fetchImpl)
: null;
withClientLifecycleSync(() => withConfigMutationLockSync(() => {
assertActiveConnectingState(persisted.fingerprint);
if (linkMetadata && options.selectedClientsExplicit) {
recordInitialRouteIntent(linkMetadata.linkId, routeIntent?.document, options.selectedClients);
initialSelectionWritten = true;
}
// No route apply has begun for this connection; the first one removes this proof.
if (linkMetadata) writeRouteIntentUnappliedProof(linkMetadata.linkId, connection.connectedAt);
clearClientConnectPending(persisted.fingerprint);
commitClientConnection(connection);
committed = true;
if (!linkMode) persistHubRelay(connection, relayCredential);
}), deps.lifecycleLockDeps);
// Only now does the routing belong to this connection: take over a journal another owner wrote
// (src/codex/journal.ts adoptJournalForClient). A failure keeps the connection; sync retries.
if (injectionCommitted) {
try {
const adoption = adoptJournalForClient(apiKeyId, () => {
// Under the Codex lock: still this committed connection (same owner and link) and its
// token, or write nothing. The stored record is normalized, so identity is compared.
assertNoClientDisconnectPending();
const current = readClientConnectionState();
if (current.kind !== "connected" || !sameClientConnectionOwner(current.value, connection)
|| current.value.link?.linkId !== connection.link?.linkId) throw new Error("client_connection_changed");
const token = readServiceApiTokenState();
if (token.kind !== "present" || token.fingerprint !== connection.tokenFingerprint) throw new Error("client_token_changed");
});
if (journalHandoverIncomplete(adoption)) console.warn(FOREIGN_JOURNAL_WARNING);
}
catch { console.warn("Warning: the Codex journal could not be handed to this connection; run 'ocx sync' so a supervised restart keeps Codex routing."); }
}
// Recorded only when the injection that applied it ran (not with --no-sync). The connection is
// already committed, so a failed record write must not reach the rollback below: it is a
// warning, and `ocx status` reports no recorded apply until `ocx sync` writes one.
if (homeSettings?.kind === "fresh" && linkMetadata && injectionCommitted) {
try {
writeHomeCodexSettingsRecord(homeCodexSettingsReceipt(
linkMetadata.linkId, homeSettings.document, now, (deps.now ?? (() => new Date()))().toISOString(), null,
));
} catch {
console.warn("Warning: the Home's Codex settings were applied, but the apply record was not written; run 'ocx sync' to record it.");
}
}
if (!options.noSync && routeIntent) {
// The connection is committed: nothing from here on may reach the enrollment rollback below,
// including a lifecycle lock another operation holds now or a connection it already changed.
// Either one leaves the route apply to the next sync, which reconciles the current connection.
try {
const appliedConnection = withClientLifecycleSync(() => {
const current = readClientConnectionState();
if (current.kind !== "connected" || !Bun.deepEquals(current.value, connection, true)) throw new Error("client_connection_changed");
return current.value;
}, deps.lifecycleLockDeps);
await applyConnectedRouteIntent(connection, admissionToken, routeIntent, {
codexApplied: injectionCommitted, lifecycleLockDeps: deps.lifecycleLockDeps, beforeWrite: () => {
deps.signal?.throwIfAborted(); assertClientConnectionUnchanged(appliedConnection);
const token = readServiceApiTokenState();
if (token.kind !== "present" || token.fingerprint !== connection.tokenFingerprint) throw new Error("client_token_changed");
},
}, deps.linkHome);
} catch { console.warn("Warning: local route intent needs reconciliation; run 'ocx route to sync'."); }
}
return connection;
} catch (error) {
const rollbackFailures: string[] = [];
if (injectionCommitted) {
try {
const restored = restoreJournalState();
if (!restored.complete) rollbackFailures.push("Codex journal restore was partial");
} catch (restoreError) {
// A concurrent config.toml write refuses the restore and keeps the journal; report it as a
// partial rollback instead of abandoning the rest of the rollback.
if (!(restoreError instanceof ConfigWriteContentChanged)) throw restoreError;
rollbackFailures.push("Codex journal restore deferred: config.toml changed during rollback");
}
}
try {
withClientLifecycleSync(() => withConfigMutationLockSync(() => {
assertNoClientDisconnectPending();
if (initialSelectionWritten && !committed && linkMetadata) {
try { clearInitialRouteIntent(linkMetadata.linkId); }
catch { rollbackFailures.push("initial route selection rollback unavailable"); }
}
// Bound to a connection that never committed, so it could never match; remove it anyway.
if (!committed && linkMetadata) { try { clearRouteIntentUnappliedProof(); } catch { /* matches nothing */ } }
let nativeRestoreFailed = false;
if (restoreNativeIntent && !committed && pendingConnectFingerprint) {
const fingerprint = pendingConnectFingerprint;
try { restoreNativeIntentOriginals(() => assertConnectingState(fingerprint)); }
catch {
// Like disconnect, keep the token (and the marker proving it is this attempt's) until the
// standalone switches are back; ocx disconnect finishes this rollback.
nativeRestoreFailed = true;
rollbackFailures.push(`Standalone native switches were not restored, so the enrollment token was kept. Repair the config or ${nativeIntentOriginalsPath()}, then run ocx disconnect to finish the rollback.`);
}
}
if (priorCatalog && writtenCatalogFingerprint && !restoreCatalogSnapshot(priorCatalog, writtenCatalogFingerprint)) {
rollbackFailures.push("catalog rollback did not match the written artifact");
}
if (pendingConnectFingerprint && !nativeRestoreFailed) {
const removed = removeServiceApiTokenFileIfOwned(pendingConnectFingerprint);
if (removed === "changed") rollbackFailures.push("service token changed during rollback");
// Final commit may fail after this attempt already cleared its marker under the same lock.
else if (pendingClientConnectMayOwnToken(pendingConnectFingerprint)) clearClientConnectPending(pendingConnectFingerprint);
}
}), deps.lifecycleLockDeps);
} catch { rollbackFailures.push("client cleanup ownership unavailable"); }
let remoteCleanup: string | null = null;
if (issued && cleanupCredential && managementUrl) {
remoteCleanup = await cleanupIssuedKey(managementUrl, cleanupCredential, issued.id, deps);
}
const base = error instanceof Error ? error.message : String(error);
const details = [
...rollbackFailures,
...(remoteCleanup ? [remoteCleanup] : []),
];
throw new Error(details.length > 0 ? `${base}. ${details.join(" ")}` : base, { cause: error });
} finally {
releaseConnectCredential(options.credential);
cleanupCredential = null;
issued = null;
if (!committed) {
tokenFingerprint = null;
priorCatalog = null;
writtenCatalogFingerprint = null;
}
}
}
export interface ConnectedSyncResult {
routeIntent?: RouteIntentReceipt;
catalogWritten: boolean;
cacheSynced: boolean;
injected: boolean;
stale: boolean;
homeSettings?: HomeCodexSettingsSource;
/** The apply record this sync committed or kept (link Child with Home settings only). */
appliedRecord?: HomeCodexSettingsRecord;
/** The Home's settings were injected but their record could not be written (OCX-6). */
applyRecordFailed?: true;
/** Routing was injected but the Codex journal stayed with its previous owner; sync again. */
journalHandoverFailed?: true;
/**
* The connection this sync ran under, read inside its lock and compare-and-swapped on every
* write. Callers decide link-vs-hub wording and restart ownership from this, never from a read
* they made before the lock.
*/
connection: OcxClientConnectionConfig;
}
export interface ConnectedSyncOptions {
restartCodex?: boolean;
overwriteConflict?: boolean;
overwriteClient?: import("../link/route-intent").RouteClientId;
/**
* #7694: refuse unless this is the connection found under the lock. A mismatch throws
* `ClientSyncExpectationError` before any request or write.
*/
expect?: ClientSyncExpectation;
}
/**
* Refresh the catalog and Codex config from the hub or Home. Every sync holds the apply lock
* (OCX-6), so a sync that finds a link connection inside, whatever an earlier unlocked read said,
* never interleaves with another apply, and its record names what its own injection wrote.
*/
export async function syncConnectedClient(
options: ConnectedSyncOptions = {},
deps: ClientConnectDeps = {},
): Promise<ConnectedSyncResult> {
let checked = false;
try {
return await withLinkApply(() => syncConnectedClientUnlocked(options, deps, () => { checked = true; }), deps.linkApplyLockPath);
} catch (error) {
// #7694: a pinned sync that cannot take a lock its check needs (a link connect holds the apply
// lock across its network reads) is refused as pending, with nothing written; it never surfaces
// as a generic failure the caller cannot tell from a broken sync.
if (options.expect && !checked && isClientSyncLockBusy(error)) {
throw new ClientSyncExpectationError(options.expect, "pending_operation");
}
throw error;
}
}
async function syncConnectedClientUnlocked(
options: ConnectedSyncOptions = {},
deps: ClientConnectDeps = {},
markChecked: () => void = () => {},
): Promise<ConnectedSyncResult> {
if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
const initial = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
// The expectation is checked by the read that selects this path; everything after is
// compare-and-swapped against the connection it passed (#7694).
if (options.expect) {
assertClientSyncExpectation(options.expect);
markChecked();
}
assertNoClientDisconnectPending();
const state = readClientConnectionState();
if (state.kind !== "connected" || state.value.pendingOperation) throw new Error("client_sync_unavailable");
const token = readServiceApiTokenState();
if (token.kind !== "present" || token.fingerprint !== state.value.tokenFingerprint) throw new Error("client_token_changed");
let assertRuntimeCurrent = () => {};
try { if (isLinkConnection(state.value)) assertRuntimeCurrent = clientSyncRuntimeGuard(); }
catch (error) {
if (options.expect && error instanceof ClientSyncRuntimeError && error.code === "client_runtime_stopping") {
throw new ClientSyncExpectationError(options.expect, "pending_operation");
}
throw error;
}
return { connection: state.value, token, assertRuntimeCurrent };
}), deps.lifecycleLockDeps);
let downloaded: Awaited<ReturnType<typeof downloadClientCatalog>> | undefined;
let stale = false;
try {
downloaded = await downloadClientCatalog(initial.connection.serverUrl, initial.token.token, { fetchImpl: deps.fetchImpl });
} catch (error) {
const transient = error instanceof HubClientError
&& (error.code === "unreachable" || (error.status !== undefined && error.status >= 500));
if (!transient) throw error;
stale = true;
}
// Same gate as connect (#4207): a sync must never replace a catalog the local CLI can parse
// with one it cannot. Refusing leaves the connection and the existing catalog exactly as
// they were, which is the known-good state.
if (downloaded) assertClientCatalogCompatible(downloaded.body, deps.catalogCompatibility);
const routeIntent = await prepareConnectedRouteIntent(initial.connection, initial.token.token, deps.linkHome, () => {
initial.assertRuntimeCurrent(); assertClientConnectionUnchanged(initial.connection);
});
const next = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
initial.assertRuntimeCurrent();
assertClientConnectionUnchanged(initial.connection);
const token = readServiceApiTokenState();
if (token.kind !== "present" || token.fingerprint !== initial.token.fingerprint) throw new Error("client_token_changed");
if (!downloaded) validLocalCatalog();
else atomicWriteFile(DEFAULT_CATALOG_PATH, downloaded.body);
const updated = {
...initial.connection,
selectedClients: [...connectedRouteSelectedClients(routeIntent, initial.connection.selectedClients)],
...(downloaded ? { catalogFingerprint: createHash("sha256").update(downloaded.body).digest("base64url"),
catalogSyncedAt: (deps.now ?? (() => new Date()))().toISOString() } : {}),
};
commitClientConnection(updated);
return updated;
}), deps.lifecycleLockDeps);
// Read-only: injection invokes this while N/C are held. Acquiring L here would invert C→L.
const beforeClientWrite = () => {
initial.assertRuntimeCurrent();
if (isLinkConnection(next)) assertRouteIntentPort(loadConfig().port);
assertClientConnectionUnchanged(next);
const token = readServiceApiTokenState();
if (next.pendingOperation || token.kind !== "present" || token.fingerprint !== next.tokenFingerprint) throw new Error("client_token_changed");
};
const withClientWrite = <T>(write: () => T): T => withConfigMutationLockSync(() => { beforeClientWrite(); return write(); });
let injected = false;
let homeSettings: HomeCodexSettingsSource | undefined;
let appliedRecord: HomeCodexSettingsRecord | undefined;
let applyRecordFailed = false;
let journalHandoverFailed = false;
if (next.selectedClients.includes("codex") && (!routeIntent || existsSync(getCodexHome()))) {
const beforeCodexWrite = () => {
beforeClientWrite();
if (routeIntent && !connectedRouteSelectedClients(routeIntent, next.selectedClients).includes("codex")) {
throw new Error("Codex route intent changed; retry sync");
}
};
let config = loadConfig();
// #6957: a link Child applies the Home's OpenCodex-owned Codex settings with the catalog.
if (isLinkConnection(next)) {
homeSettings = await resolveHomeCodexSettings(next, initial.token.token, { ...deps.linkHome, withWriteGuard: withClientWrite });
if (homeSettings.source !== "local") config = overlayHomeCodexSettings(config, homeSettings.document.settings);
// About to write different settings: until their record commits, report no applied digest
// rather than the previous one (OCX-6). A failed injection then reads "unknown", never a
// digest of values Codex no longer has or never got.
if (homeSettings.source === "home" && next.link) {
const { linkId } = next.link, { document } = homeSettings;
withClientWrite(() => withdrawChangingHomeCodexSettingsRecord(linkId, document));
}
}
// Off persisted false. Reconcile the effective Home intent before the injector rereads
// that durable gate, retaining local opt-outs and the owner/runtime/token commit fences.
if (routeIntent) {
const { persistNativeRouteIntent } = await import("./route-intent-apply");
withClientLifecycleSync(() => persistNativeRouteIntent("codex", true, beforeCodexWrite, config, true), deps.lifecycleLockDeps);
}
const result = await injectCodexConfig(config.port, { ...config, syncResumeHistory: false }, {
routingTarget: routingTarget(next.serverUrl, isLinkConnection(next) ? config.port : undefined, config), catalogPath: DEFAULT_CATALOG_PATH,
journalOwner: { kind: "client", apiKeyId: next.apiKeyId }, beforeClientWrite: beforeCodexWrite,
});
if (!result.success || result.status === "skipped") throw new Error(result.message);
injected = result.configApplied !== false;
// An external provider can preserve config.toml without applying even the same Home digest.
// Withdraw any previous receipt under the current connection fence before reporting parity.
if (!injected && next.link) withClientWrite(clearHomeCodexSettingsRecord);
if (injected) {
// A committed connection re-injected: own the journal too (retries a takeover connect missed),
// under the same connection guard as the injection, so a stale sync claims nothing.
try {
const adoption = adoptJournalForClient(next.apiKeyId, beforeCodexWrite);
// No journal or another client's means the routing is not this connection's to keep.
if (journalHandoverIncomplete(adoption)) journalHandoverFailed = true;
} catch { journalHandoverFailed = true; }
}
if (injected && homeSettings && next.link) {
const linkId = next.link.linkId;
const settings = homeSettings;
try {
appliedRecord = withClientLifecycleSync(() => withClientWrite(() =>
recordHomeCodexSettings(linkId, settings, deps.now) ?? readHomeCodexSettingsRecord(linkId) ?? undefined), deps.lifecycleLockDeps);
} catch (error) {
// An ownership change is not a disk problem: report it as itself.
if (error instanceof ClientSyncRuntimeError || (error instanceof Error && (error.message === "client_token_changed" || error.message === "client_connection_changed"))) throw error;
// The injection committed, so the cache refresh below still runs; the caller reports this.
try { withClientWrite(clearHomeCodexSettingsRecord); } catch { /* status already reads no recorded apply or reports the write */ }
applyRecordFailed = true;
}
}
}
const routeReceipt = await applyConnectedRouteIntent(next, initial.token.token, routeIntent,
{ beforeWrite: beforeClientWrite, codexApplied: injected, lifecycleLockDeps: deps.lifecycleLockDeps,
overwriteConflict: options.overwriteConflict, overwriteClient: options.overwriteClient }, deps.linkHome);
const cacheSynced = withClientLifecycleSync(() => {
// Acquire K before the guarded C commit; never acquire K from inside C.
const owningHome = getCodexHome();
const result = withCatalogWriteSerialization(owningHome, permit => withClientWrite(() =>
invalidateCodexModelsCacheWithPermit(permit, owningHome, { allowWhenDesiredDisabled: true })),
{ intent: "cache", writer: "cache-invalidate" });
return result.kind === "completed" && result.value;
}, deps.lifecycleLockDeps);
return {
catalogWritten: downloaded !== undefined, cacheSynced, injected, stale: stale || routeReceipt?.catalogPending === true || routeIntent?.stale === true,
...(homeSettings ? { homeSettings } : {}),
...(appliedRecord ? { appliedRecord } : {}),
...(applyRecordFailed ? { applyRecordFailed } : {}),
...(routeReceipt ? { routeIntent: routeReceipt } : {}),
...(journalHandoverFailed ? { journalHandoverFailed: true as const } : {}),
connection: next,
};
}
/**
* Put the catalog back the way connect found it.
*
* Not a delete. Connect overwrites whatever catalog was already there, so removing the
* remote one leaves the user with nothing — and disconnect still reports that native Codex
* state was restored. If the connection recorded a prior catalog, it is rewritten;
* `priorCatalog: ""` means there genuinely was none and removal is the restoration.
*
* Still ownership-checked first: a catalog the user edited or replaced since connect is
* theirs, and `changed` refuses rather than overwriting it.
*/
function restorePriorCatalog(connection: OcxClientConnectionConfig): "removed" | "restored" | "absent" | "changed" {
if (!existsSync(DEFAULT_CATALOG_PATH)) return "absent";
try {
const body = validLocalCatalog();
if (!catalogMatchesFingerprint(body, connection.catalogFingerprint)) return "changed";
if (connection.priorCatalog) {
atomicWriteFile(DEFAULT_CATALOG_PATH, Buffer.from(connection.priorCatalog, "base64").toString("utf8"));
return "restored";
}
// Undefined means the connection predates this field: the pre-connect catalog was
// never recorded, so removal is the only honest option and matches the old behavior.
unlinkSync(DEFAULT_CATALOG_PATH);
return "removed";
} catch {
return "changed";
}
}
const DISCONNECT_PHASES: readonly DesktopDisconnectReceipt["phase"][] = [
"prepared", "desktop_restored", "catalog_settled", "removing_token", "token_removed", "clearing_connection", "connection_cleared", "complete",
];
function disconnectAtLeast(receipt: DesktopDisconnectReceipt, phase: DesktopDisconnectReceipt["phase"]): boolean {
return DISCONNECT_PHASES.indexOf(receipt.phase) >= DISCONNECT_PHASES.indexOf(phase);
}
const FOREIGN_JOURNAL_WARNING = "Warning: the Codex journal belongs to an earlier connection, so the next OpenCodex restart restores native Codex routing. After that restart, run 'ocx sync --restart-codex' to point Codex at this connection again.";
function catalogIsRecordedPrior(connection: OcxClientConnectionConfig, snapshot: CatalogSnapshot): boolean {
return snapshot.kind === "file" && !!connection.priorCatalog
&& snapshot.fingerprint === sha256(Buffer.from(connection.priorCatalog, "base64").toString("utf8"));
}
function preflightDisconnectCatalog(connection: OcxClientConnectionConfig, keepCatalog: boolean): void {
const snapshot = catalogSnapshot();
if (!keepCatalog && snapshot.kind === "file"
&& !catalogMatchesFingerprint(snapshot.body, connection.catalogFingerprint)
&& !catalogIsRecordedPrior(connection, snapshot)) throw new Error("client_catalog_ownership_changed");
}
function catalogAfterState(): NonNullable<DesktopDisconnectReceipt["catalogAfter"]> {
const snapshot = catalogSnapshot();
return snapshot.kind === "absent" ? { kind: "absent" } : { kind: "file", fingerprint: snapshot.fingerprint };
}
function verifyDisconnectCatalog(receipt: DesktopDisconnectReceipt): void {
if (!receipt.catalogAfter || JSON.stringify(catalogAfterState()) !== JSON.stringify(receipt.catalogAfter)) {
throw new Error("client_catalog_changed_during_disconnect");
}
}
function restoreConnectedCodex(connection: OcxClientConnectionConfig, receipt: DesktopDisconnectReceipt, recoverConfig = false): string | undefined {
const inspection = readCodexHomeJournal(JOURNAL_PATH);
const owner = journalOwner({ readOnly: true });
const explicitOwner = inspection.kind === "read" ? inspection.journal.owner as Record<string, unknown> | undefined : undefined;
const invalidOwner = explicitOwner !== undefined && (!explicitOwner || typeof explicitOwner !== "object" || Array.isArray(explicitOwner)
|| !(explicitOwner.kind === "client" && typeof explicitOwner.apiKeyId === "string" && explicitOwner.apiKeyId.length > 0
|| explicitOwner.kind === "process" && typeof explicitOwner.pid === "number" && Number.isSafeInteger(explicitOwner.pid) && explicitOwner.pid > 0));
if (inspection.kind === "unknown" || invalidOwner || (inspection.kind === "read" && owner === null)) {
throw new Error("disconnect refused: Codex journal ownership is unknown; journal and connection credentials were retained");
}
// Deselection records desired state, not completed cleanup. A failed off still leaves
// this client's journal to drain; an unrelated process journal grants no such authority.
if (!connection.selectedClients.includes("codex") && owner?.kind !== "client") {
if (inspection.kind === "missing" && isCodexRoutingInjected()) {
throw new Error("disconnect refused: Codex routing is injected but no journal records the original state");
}
return;
}
if (owner && owner.kind === "client" && owner.apiKeyId !== connection.apiKeyId) {
throw new Error("disconnect refused: Codex journal ownership conflicts with the connected key");
}
if (owner !== null) {
const restored = restoreJournalState({ preserveConfigEdits: true,
...(recoverConfig ? { recoverConfigForClient: connection.apiKeyId } : {}),
beforeWrite: () => {
const state = readClientConnectionState(), currentReceipt = readDesktopDisconnectReceipt();
const token = readServiceApiTokenState();
if (state.kind !== "connected" || JSON.stringify(state.value) !== JSON.stringify(connection)
|| currentReceipt.kind !== "valid" || JSON.stringify(currentReceipt.value) !== JSON.stringify(receipt)
|| token.kind !== "present" || token.fingerprint !== receipt.tokenFingerprint) throw new Error("client_disconnect_owner_changed");
},
});
if (!restored.complete) throw new Error(
"disconnect refused: Codex journal restore was partial; journal and connection credentials were retained. "
+ "Retry 'ocx disconnect --recover-config --yes' to privately back up current Codex config/profile and restore only evidenced OCX-owned fields (retain --keep-catalog if originally requested). "
+ "Unknown ownership and edited or unverified profiles remain refused.",
);
return restored.recoveryBackupDir;
} else if (isCodexRoutingInjected()) {
throw new Error("disconnect refused: Codex routing is injected but no journal records the original state");
}
}
/**
* Abort a disconnect that failed before its commit point.
*
* Until `desktop_restored` the receipt records intent only, so removing it returns the Child to a plain
* connected state; left in place it made every client start refuse with client_disconnect_pending
* until someone moved the folder aside by hand. A receipt this attempt wrote is removed outright:
* D excludes other disconnects and every Desktop writer refuses while it exists. A receipt an
* earlier run left (including one stuck by an older release) is removed only while the Desktop
* store shows no restore has started; that run may have stopped inside the Desktop restore before
* it could record desktop_restored, and then the receipt is the gate a retry needs.
*
* On a link Child the route-intent drain runs before the Codex restore, so by then the file
* integrations the link routed may already be off. That is not undone here: the connection stays,
* and the runtime's next route-intent apply turns them back on, as it does after any Home change.
*/
function abortPreparedDisconnect(
prepared: { receipt: DesktopDisconnectReceipt; created: boolean; connection: OcxClientConnectionConfig | null },
error: unknown,
deps: Pick<ClientConnectDeps, "lifecycleLockDeps">,
): Error {
const base = error instanceof Error ? error.message : String(error);
let outcome: "removed" | "desktop_started";
try {
outcome = withClientLifecycleSync(held => withConfigMutationLockSync(() => {
if (!prepared.created && !UNTOUCHED_DESKTOP.has(inspectRemoteDesktopStore(prepared.receipt.owner).kind)) return "desktop_started" as const;
removeDesktopDisconnectReceipt(held, prepared.receipt);
return "removed" as const;
}), deps.lifecycleLockDeps);
} catch {
return new Error(`${base}. The disconnect receipt could not be rolled back; run ocx disconnect again to finish it or roll it back.`, { cause: error });
}
const drained = prepared.connection?.transport === "link"
? " File integrations this link routed may already be off; the runtime's next route-intent apply turns them back on." : "";
return new Error(outcome === "removed"
? `${base}. The disconnect was rolled back: this Child is still connected and its runtime can start.${drained}`
: `${base}. A Claude Desktop restore had already started under this disconnect, so its receipt was kept; once the cause above is fixed, run ocx disconnect again to finish it.`, { cause: error });
}
/** Desktop store states an interrupted disconnect cannot have produced: no restore has begun. */
const UNTOUCHED_DESKTOP: ReadonlySet<string> = new Set(["absent", "active", "legacy_current_connection"]);
/**
* `ocx disconnect --expect-link <id>`: refuse unless this machine is connected to that link (the same
* check `ocx sync --expect-link` makes), read-only under the client lifecycle and config locks. A Home's
* delayed revoke of an old link then cannot disconnect a newer one. Throws ClientSyncExpectationError.
*/
export function assertDisconnectExpectation(linkId: string, deps: Pick<ClientConnectDeps, "lifecycleLockDeps"> = {}): void {
withClientLifecycleSync(() => withConfigMutationLockSync(() => assertHomeInitiatedDisconnect(linkId)), deps.lifecycleLockDeps);
}
/**
* The link expectation, then the Home-initiated check: a Home sends --expect-link only for Home-initiated links, and
* a client-initiated one needs the client-link teardown that path skips. Its sidecar, or the marker that survives a
* lost sidecar, naming this link refuses it (client_initiated_link); an unreadable sidecar or marker refuses too.
* When this link's own unfinished disconnect is on record (the expectation let it resume), the refusal says
* disconnect_pending instead: an earlier attempt may have cleaned part of the Child, and the Home must count the
* cleanup as attempted. Read-only; the caller holds the client lifecycle and config mutation locks.
*/
function assertHomeInitiatedDisconnect(linkId: string): void {
assertDisconnectLinkExpectation(linkId);
let reason: "client_initiated_link" | "invalid_state" | null;
// An unreadable sidecar or marker refuses as invalid_state: it proves nothing about who joined.
try {
const marker = readChildLinkMarker();
reason = marker.kind === "unreadable" ? "invalid_state"
: readClientLinkState()?.linkId === linkId || (marker.kind === "link" && marker.linkId === linkId) ? "client_initiated_link" : null;
} catch { reason = "invalid_state"; }
if (!reason) return;
const receipt = readDesktopDisconnectReceipt();
throw new ClientSyncExpectationError({ kind: "link", linkId }, receipt.kind === "valid" && receipt.value.phase !== "complete" ? "disconnect_pending" : reason);
}
/**
* A disconnected machine with no unfinished disconnect can still hold the standalone native
* switches an interrupted or failed enrollment displaced, and the token that enrollment kept
* because it could not restore them. Plain `ocx disconnect` restores the switches, then removes
* that token only while the pending-connect marker proves it is the enrollment's own.
* `ocx disconnect --orphaned-token` never touches the record.
*/
function drainLoneNativeIntentOriginals(lifecycleLockDeps?: ClientLifecycleLockDeps): {
restored: true; tokenRemoved: boolean; catalogRemoved: false; catalogRestored: false; apiKeyId: string; restartRequired: false; nativeIntentOnly: true;
} | null {
const refused = (error: unknown) => new Error(`disconnect refused: the standalone native switches recorded in ${nativeIntentOriginalsPath()} were not restored (${error instanceof Error ? error.message : String(error)}). Repair the config or that record (remove it only after setting the switches by hand), then rerun ocx disconnect.`);
return withClientLifecycleSync(() => withConfigMutationLockSync(() => {
const read = readDesktopDisconnectReceipt();
if (read.kind === "unsafe" || (read.kind === "valid" && read.value.phase !== "complete")) return null;
if (readClientConnectionState().kind !== "disconnected") return null;
let present: boolean;
try { present = readNativeIntentOriginals() !== null; } catch (error) { throw refused(error); }
if (!present) return null;
try {
restoreNativeIntentOriginals(() => {
assertNoClientDisconnectPending();
if (readClientConnectionState().kind !== "disconnected") throw new Error("client_connection_changed");
});
} catch (error) { throw refused(error); }
const token = readServiceApiTokenState();
let tokenRemoved = false;
if (token.kind === "present" && pendingClientConnectMayOwnToken(token.fingerprint)) {
const removed = removeServiceApiTokenFileIfOwned(token.fingerprint);
if (removed === "changed") throw new Error("client_token_changed");
tokenRemoved = removed === "removed";
clearClientConnectPending(token.fingerprint);
}
return { restored: true, tokenRemoved, catalogRemoved: false, catalogRestored: false, apiKeyId: "", restartRequired: false, nativeIntentOnly: true };
}), lifecycleLockDeps);
}
export async function disconnectClient(
options: Parameters<typeof disconnectClientAttempt>[0] = {},
deps: Pick<ClientConnectDeps, "lifecycleLockDeps" | "fetchImpl"> = {},
): ReturnType<typeof disconnectClientAttempt> {
// The attempt lock is a file under the config directory: wait for parent ACL admission first,
// as every other phase does, so nothing is created under a directory still being hardened.
await withConfigDirHardeningSettled(getConfigDir(), () => undefined);
return withClientDisconnectAttempt(() => disconnectClientAttempt(options, deps), deps.lifecycleLockDeps);
}
async function disconnectClientAttempt(
options: { keepCatalog?: boolean; expectedOwner?: DesktopRemoteOwner; expectLink?: string; recoverConfig?: boolean } = {},
deps: Pick<ClientConnectDeps, "lifecycleLockDeps" | "fetchImpl"> = {},
): Promise<{
restored: boolean; tokenRemoved: boolean; catalogRemoved: boolean; catalogRestored: boolean; apiKeyId: string;
desktopRestoration?: "owned_projection" | "standard_fallback" | "selection_preserved";
restartRequired: boolean;
recoveryBackupDir?: string;
/** Only standalone native switches an interrupted enrollment displaced were restored. */
nativeIntentOnly?: true;
}> {
if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
// A link-bound disconnect changes nothing on a machine that is not connected to that link, so it never drains here.
if (!options.expectedOwner && options.expectLink === undefined) {
// It restores config-root switches under the lifecycle lock, so it admits after overlapping
// config-root ACL work like both phases below (#7815).
const drained = await withConfigDirHardeningSettled(getConfigDir(), () => drainLoneNativeIntentOriginals(deps.lifecycleLockDeps));
if (drained) return drained;
}
const keepCatalog = options.keepCatalog === true;
// Both phases write the disconnect receipt and the remote Desktop store under the config root
// with required ACLs, so each admits after overlapping config-root ACL work (#7815). A timeout
// before phase 1 writes nothing; one before phase 2 leaves the prepared receipt it resumes from.
const prepared = await withConfigDirHardeningSettled(getConfigDir(), () => withClientLifecycleSync(held => withConfigMutationLockSync(() => {
// Checked first, under the same locks, before anything is read for writing or written.
if (options.expectLink !== undefined) assertHomeInitiatedDisconnect(options.expectLink);
const read = readDesktopDisconnectReceipt();
if (read.kind === "unsafe") throw new Error("client_disconnect_receipt_unsafe");
const state = readClientConnectionState();
const previous = read.kind === "valid" ? read.value : null;
const observedOwner = state.kind === "connected" ? desktopOwner(state.value) : previous?.owner;
if (options.expectedOwner && (!observedOwner || !sameClientConnectionOwner(observedOwner, options.expectedOwner))) {
throw new Error("client_disconnect_expected_owner_changed");
}
let receipt = previous;
let created = false;
let connection: OcxClientConnectionConfig | null = null;
if (state.kind === "connected") {
connection = state.value;
if (connection.pendingOperation) throw new Error("client_rotation_recovery_required");
if (receipt?.phase === "complete" && !sameClientConnectionOwner(receipt.owner, connection)) receipt = null;
if (receipt && !sameClientConnectionOwner(receipt.owner, connection)) throw new Error("client_disconnect_owner_changed");
if (receipt?.phase === "complete") throw new Error("client_disconnect_completed_owner_reappeared");
const token = readServiceApiTokenState();
const expectedFingerprint = receipt?.tokenFingerprint ?? connection.tokenFingerprint;
if (connection.tokenFingerprint !== expectedFingerprint
|| (token.kind === "present" ? token.fingerprint !== expectedFingerprint
: token.kind !== "absent" || !receipt || !disconnectAtLeast(receipt, "removing_token"))) {
throw new Error("client_token_changed");
}
if (!receipt) {
const desktop = inspectRemoteDesktopStore(desktopOwner(connection));
if (desktop.kind === "unsafe" || desktop.kind === "conflict") throw new Error(desktopLifecycleRefusal(desktop));
preflightDisconnectCatalog(connection, keepCatalog);
receipt = { version: 1, owner: desktopOwner(connection), tokenFingerprint: connection.tokenFingerprint, keepCatalog, phase: "prepared" };
writeDesktopDisconnectReceipt(held, previous, receipt);
created = true;
}
} else if (state.kind !== "disconnected" || !receipt || !disconnectAtLeast(receipt, "clearing_connection")) {
throw new Error("disconnect refused: no recoverable connected state; if this is not a Hub and no admission secret or installed service uses the token, inspect it and use ocx disconnect --orphaned-token --yes");
}
if (!receipt || receipt.keepCatalog !== keepCatalog) throw new Error("client_disconnect_options_changed");
return { receipt, connection, created };
}), deps.lifecycleLockDeps));
// This sibling step owns only file integrations; failures retain the prepared receipt/token.
if (prepared.connection?.transport === "link" && !disconnectAtLeast(prepared.receipt, "desktop_restored")) {
// It writes the route receipt and file integrations under the config root, so it admits after
// overlapping config-root ACL work like both disconnect phases (#7815).
const connection = prepared.connection;
await withConfigDirHardeningSettled(getConfigDir(), () => cleanupConnectedRouteIntent(connection, prepared.receipt, deps.lifecycleLockDeps, options.recoverConfig === true));
}
// The prepared receipt blocks even a sync queued for its actual N/C injection commit.
// Codex-only restore MUST stay outside L; it never invokes Desktop cleanup.
let recoveryBackupDir: string | undefined;
if (prepared.connection && !disconnectAtLeast(prepared.receipt, "desktop_restored")) {
try { recoveryBackupDir = restoreConnectedCodex(prepared.connection, prepared.receipt, options.recoverConfig === true); }
catch (error) { throw abortPreparedDisconnect(prepared, error, deps); }
}
let revokeRelay: (() => Promise<void>) | undefined;
const result = await withConfigDirHardeningSettled(getConfigDir(), () => withClientLifecycleSync(held => withConfigMutationLockSync(() => {
const read = readDesktopDisconnectReceipt();
if (read.kind !== "valid" || JSON.stringify(read.value) !== JSON.stringify(prepared.receipt)) {
throw new Error("client_disconnect_receipt_changed");
}
let receipt = read.value;
const state = readClientConnectionState();
let connection: OcxClientConnectionConfig | null = null;
if (state.kind === "connected") {
if (!sameClientConnectionOwner(state.value, receipt.owner) || state.value.pendingOperation
|| state.value.tokenFingerprint !== receipt.tokenFingerprint) throw new Error("client_disconnect_owner_changed");
connection = state.value;
} else if (state.kind !== "disconnected" || !disconnectAtLeast(receipt, "clearing_connection")) {
throw new Error("client_disconnect_owner_changed");
}
const token = readServiceApiTokenState();
if (token.kind === "present" ? token.fingerprint !== receipt.tokenFingerprint
: token.kind !== "absent" || !disconnectAtLeast(receipt, "removing_token")) throw new Error("client_token_changed");
const advance = (phase: DesktopDisconnectReceipt["phase"], fields: Partial<DesktopDisconnectReceipt> = {}) => {
const next = { ...receipt, ...fields, phase };
writeDesktopDisconnectReceipt(held, receipt, next);
receipt = next;
};
let desktop: Extract<DesktopStoreResult, { ok: true }>;
if (!disconnectAtLeast(receipt, "desktop_restored")) {
desktop = requireDesktopResult(restoreRemoteDesktopStore(held, {
owner: receipt.owner, knownTokenFingerprints: [receipt.tokenFingerprint],
}));
advance("desktop_restored", desktop.fingerprint ? { desktopAfterFingerprint: desktop.fingerprint } : {});
} else {
// A retry after token/config removal must verify the completed projection,
// not invoke a mutator that needs the now-removed connection credential.
const inspected = inspectRemoteDesktopStore(receipt.owner);
if (inspected.kind !== "restored" && !(inspected.kind === "absent"
&& (!receipt.desktopAfterFingerprint || receipt.phase === "complete"))) {
throw new Error("desktop_disconnect_after_state_changed");
}
desktop = { ok: true, changed: false, status: inspected.kind === "absent" ? "absent" : "restored",
restartRequired: receipt.desktopAfterFingerprint !== undefined };
}
if (!disconnectAtLeast(receipt, "catalog_settled")) {
if (!connection) throw new Error("client_disconnect_catalog_context_missing");
preflightDisconnectCatalog(connection, keepCatalog);
const snapshot = catalogSnapshot();
if (!keepCatalog && snapshot.kind !== "absent" && !catalogIsRecordedPrior(connection, snapshot)) {
if (restorePriorCatalog(connection) === "changed") throw new Error("client_catalog_ownership_changed");
}
advance("catalog_settled", { catalogAfter: catalogAfterState() });
} else verifyDisconnectCatalog(receipt);
if (connection?.transport === "link" && !disconnectAtLeast(receipt, "removing_token")) {
if (connection.link) clearInitialRouteIntent(connection.link.linkId);
clearHomeRouteIntentRecord();
// Its clients were restored by the route cleanup above, which phase gating never reruns.
clearFileIntentOriginals();
if (readRouteIntentReceiptStrict()?.linkId === connection.link?.linkId) clearRouteIntentReceipt();
clearRouteIntentUnappliedProof();
}
// Standalone native switches come back before the token that displaced them is removed.
// The record is machine-scoped, so any transport drains one a crashed enrollment left.
// The locks and the receipt checked above already fence this; a retry is idempotent.
if (!disconnectAtLeast(receipt, "removing_token")) restoreNativeIntentOriginals(() => {});
if (!disconnectAtLeast(receipt, "removing_token")) advance("removing_token");
if (connection && !isLinkConnection(connection) && token.kind === "present") {
const stored = readHubCredential(connection);
if (stored.kind === "present") {
const { managementUrl, apiKeyId } = connection;
revokeRelay = () => revokeHubRelayLease(managementUrl, apiKeyId, token.token, stored.credential, deps.fetchImpl);
}
}
const tokenRemoval = removeServiceApiTokenFileIfOwned(receipt.tokenFingerprint);
if (tokenRemoval === "changed") throw new Error("client_token_changed");
if (!disconnectAtLeast(receipt, "token_removed")) advance("token_removed");
if (!disconnectAtLeast(receipt, "clearing_connection")) advance("clearing_connection");
if (clearClientConnection(receipt.owner) === "conflict") throw new Error("client_disconnect_owner_changed");
if (!disconnectAtLeast(receipt, "connection_cleared")) advance("connection_cleared");
removeHubCredential();
if (connection?.transport === "link" && connection.link) {
// A corrupt sidecar is left in place: the connection is already cleared, the client runtime
// will not start a tunnel for a disconnected client, and the next join overwrites the file.
let sidecarLinkId: string | null = null;
try {
sidecarLinkId = readClientLinkState()?.linkId ?? null;
} catch (error) {
if (!(error instanceof ClientLinkStateError)) throw error;
}
if (sidecarLinkId === connection.link.linkId) clearClientLinkState(connection.link.linkId);
try { clearHomeCodexSettingsRecord(); } catch { /* derived data; never fails a disconnect */ }
}
removeHubStateCache();
requireDesktopResult(finishRemoteDesktopCleanup(held, receipt.owner));
if (receipt.phase !== "complete") advance("complete");
return {
...(recoveryBackupDir ? { recoveryBackupDir } : {}),
restored: true, tokenRemoved: tokenRemoval === "removed",
catalogRemoved: !keepCatalog, catalogRestored: !keepCatalog && receipt.catalogAfter?.kind === "file",
apiKeyId: receipt.owner.apiKeyId, restartRequired: desktop.restartRequired,
...(desktop.restoration ? { desktopRestoration: desktop.restoration } : {}),
};
}), deps.lifecycleLockDeps));
if (revokeRelay) {
try { await revokeRelay(); }
catch { console.warn("Warning: Hub relay revocation was not confirmed. Its credential expires after the Hub's idle timeout."); }
}
return result;
}
/**
* Drop the cached hub-state document (#4236).
*
* It is derived data from a connection that no longer exists, and it is owner-stamped, so a
* reader would reject it anyway — but leaving it behind means `<OPENCODEX_HOME>/hub-state.json`
* keeps naming the previous hub's providers and logins on a machine that is no longer connected
* to anything, which is exactly the wrong artifact to leave where someone might read it.
*
* Best effort and unconditional on the phase: the disconnect has already succeeded by this point,
* and a cache file that cannot be removed must not fail it or block a retry.
*/
function removeHubStateCache(): void {
try {
unlinkSync(hubStateCachePath());
} catch { /* absent, or not ours to remove */ }
}
export async function revokeConnectedClientKey(
credential: { kind: "admin"; value: Uint8Array },
deps: ClientConnectDeps = {},
): Promise<{ apiKeyId: string }> {
try {
return await withClientLifecycle(async () => {
assertNoClientDisconnectPending();
const state = readClientConnectionState();
if (state.kind !== "connected" || state.value.pendingOperation) throw new Error("connect revoke requires a settled connection");
if (isLinkConnection(state.value)) throw new Error("connect revoke is unavailable in link mode");
await revokeClientKey(state.value.managementUrl, credential, state.value.apiKeyId, { fetchImpl: deps.fetchImpl });
assertClientConnectionUnchanged(state.value);
return { apiKeyId: state.value.apiKeyId };
}, deps.lifecycleLockDeps);
} finally { credential.value.fill(0); }
}