@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,084 lines • 52.8 kB
text/typescript
import { createHash } from "node:crypto";
import {
existsSync,
lstatSync,
readFileSync,
unlinkSync,
} from "node:fs";
import { hostname } from "node:os";
import { atomicWriteFile, loadConfig, withConfigMutationLockSync } from "../config";
import { claudeDesktopIntegrationEnabledNow } from "../codex/desired-state";
import { siblingOfLivePort, siblingSkipMessage } from "../codex/sibling-start";
import {
inspectRemoteDesktopStore, readDesktopDisconnectReceipt, writeDesktopDisconnectReceipt,
replaceRemoteDesktopCredential, restoreRemoteDesktopStore, finishRemoteDesktopCleanup,
type DesktopDisconnectReceipt, type DesktopRemoteOwner, type DesktopStoreResult,
} from "../claude/desktop-remote-store";
import {
withClientLifecycle, withClientLifecycleSync,
type ClientLifecycleHeld, type ClientLifecycleLockDeps,
} from "./lifecycle-lock";
import { invalidateCodexModelsCache } from "../codex/catalog/sync";
import {
injectCodexConfig,
currentExternalCodexModelProvider,
isCodexRoutingInjected,
standaloneCodexRoutingTarget,
type CodexRoutingTarget,
} from "../codex/inject";
import {
journalOwner,
restoreJournalState,
} from "../codex/journal";
import { DEFAULT_CATALOG_PATH } 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 type {
OcxClientConnectionConfig,
OcxConfig,
OcxConnectedClientId,
} from "../types";
import {
downloadClientCatalog,
abortClientKeyRotation,
commitClientKeyRotation,
exchangeConnectPairingGrant,
fetchHubReady,
HubClientError,
issueClientKey,
normalizeHubOrigin,
probeClientKeyId,
revokeClientKey,
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 { hubStateCachePath } from "./hub-state";
import { ClientLinkStateError, clearClientLinkState, readClientLinkState } from "./link-state";
import { isLinkPort } from "../link/ports";
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[];
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;
}
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}`;
}
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<{ kind: "admin"; value: Uint8Array } | { kind: "gui-session"; value: ConnectGuiSession }> {
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 };
}
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: { kind: "admin"; value: Uint8Array } | { kind: "gui-session"; value: ConnectGuiSession },
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 finalizeRotation(held, connection, backup.fingerprint, current, "committed");
}
if (currentAccepted && !backupAccepted) {
return finalizeRotation(held, connection, backup.fingerprint, current, "committed");
}
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);
assertClientConnectionUnchanged(state.value);
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: { kind: "admin"; value: Uint8Array } | { kind: "gui-session"; value: ConnectGuiSession } | 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.
alignDesktopCredential(held, connection, 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);
assertClientConnectionUnchanged(connection);
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);
});
alignDesktopCredential(held, connection, 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;
return finalizeRotation(held, connection, current.fingerprint, { token: rotation.key, fingerprint: replacement.fingerprint }, "committed");
} 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: { kind: "admin"; value: Uint8Array } | { kind: "gui-session"; value: ConnectGuiSession },
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) {
throw new Error("client_token_changed");
}
}
/** Enroll a client key, keeping its pending ownership visible until commit or rollback. */
export async function connectClient(
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: { kind: "admin"; value: Uint8Array } | { kind: "gui-session"; value: ConnectGuiSession } | 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 committed = 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 && (!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);
atomicWriteFile(DEFAULT_CATALOG_PATH, catalog.body);
return sha256(catalog.body);
}), deps.lifecycleLockDeps);
const config = earlyConfig ?? loadConfig();
const target = routingTarget(serverUrl, linkMode ? config.port : undefined, config);
const injectConfig = { ...config, syncResumeHistory: false };
const preflight = await injectCodexConfig(config.port, injectConfig, {
validateOnly: true,
routingTarget: target,
catalogPath: DEFAULT_CATALOG_PATH,
journalOwner: { kind: "client", apiKeyId },
beforeClientWrite: () => assertActiveConnectingState(persisted.fingerprint),
});
if (!preflight.success) throw new Error(preflight.message);
if (!options.noSync && options.selectedClients.includes("codex")) {
const injected = await injectCodexConfig(config.port, injectConfig, {
routingTarget: target,
catalogPath: DEFAULT_CATALOG_PATH,
journalOwner: { kind: "client", apiKeyId },
beforeClientWrite: () => assertActiveConnectingState(persisted.fingerprint),
});
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: [...options.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 } : {}),
};
withClientLifecycleSync(() => withConfigMutationLockSync(() => {
assertActiveConnectingState(persisted.fingerprint);
clearClientConnectPending(persisted.fingerprint);
commitClientConnection(connection);
committed = true;
}), deps.lifecycleLockDeps);
return connection;
} catch (error) {
const rollbackFailures: string[] = [];
if (injectionCommitted) {
const restored = restoreJournalState();
if (!restored.complete) rollbackFailures.push("Codex journal restore was partial");
}
try {
withClientLifecycleSync(() => withConfigMutationLockSync(() => {
assertNoClientDisconnectPending();
if (priorCatalog && writtenCatalogFingerprint && !restoreCatalogSnapshot(priorCatalog, writtenCatalogFingerprint)) {
rollbackFailures.push("catalog rollback did not match the written artifact");
}
if (pendingConnectFingerprint) {
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 async function syncConnectedClient(
_options: { restartCodex?: boolean } = {},
deps: ClientConnectDeps = {},
): Promise<{ catalogWritten: boolean; cacheSynced: boolean; injected: boolean; stale: boolean }> {
if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
const initial = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
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");
return { connection: state.value, token };
}), 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 next = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
assertClientConnectionUnchanged(initial.connection);
const token = readServiceApiTokenState();
if (token.kind !== "present" || token.fingerprint !== initial.token.fingerprint) throw new Error("client_token_changed");
if (!downloaded) { validLocalCatalog(); return initial.connection; }
atomicWriteFile(DEFAULT_CATALOG_PATH, downloaded.body);
const updated = {
...initial.connection,
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 = () => {
assertClientConnectionUnchanged(next);
const token = readServiceApiTokenState();
if (next.pendingOperation || token.kind !== "present" || token.fingerprint !== next.tokenFingerprint) throw new Error("client_token_changed");
};
let injected = false;
if (next.selectedClients.includes("codex")) {
const config = loadConfig();
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,
});
if (!result.success || result.status === "skipped") throw new Error(result.message);
injected = true;
}
const cacheSynced = withClientLifecycleSync(() => {
beforeClientWrite();
// Cache invalidation acquires K itself (N -> K -> C); never call it while C is held.
return invalidateCodexModelsCache({ allowWhenDesiredDisabled: true });
}, deps.lifecycleLockDeps);
return { catalogWritten: downloaded !== undefined, cacheSynced, injected, stale };
}
/**
* 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);
}
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): void {
if (!connection.selectedClients.includes("codex")) return;
const owner = journalOwner();
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) {
if (!restoreJournalState().complete) throw new Error("disconnect refused: Codex journal restore was partial");
} else if (isCodexRoutingInjected()) {
throw new Error("disconnect refused: Codex routing is injected but no journal records the original state");
}
}
export async function disconnectClient(
options: { keepCatalog?: boolean; expectedOwner?: DesktopRemoteOwner } = {},
deps: Pick<ClientConnectDeps, "lifecycleLockDeps"> = {},
): Promise<{
restored: boolean; tokenRemoved: boolean; catalogRemoved: boolean; catalogRestored: boolean; apiKeyId: string;
desktopRestoration?: "owned_projection" | "standard_fallback" | "selection_preserved";
restartRequired: boolean;
}> {
if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
const keepCatalog = options.keepCatalog === true;
const prepared = withClientLifecycleSync(held => withConfigMutationLockSync(() => {
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 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("desktop_lifecycle_unsafe");
preflightDisconnectCatalog(connection, keepCatalog);
receipt = { version: 1, owner: desktopOwner(connection), tokenFingerprint: connection.tokenFingerprint, keepCatalog, phase: "prepared" };
writeDesktopDisconnectReceipt(held, previous, receipt);
}
} else if (state.kind !== "disconnected" || !receipt || !disconnectAtLeast(receipt, "clearing_connection")) {
throw new Error("disconnect refused: no recoverable connected state");
}
if (!receipt || receipt.keepCatalog !== keepCatalog) throw new Error("client_disconnect_options_changed");
return { receipt, connection };
}), deps.lifecycleLockDeps);
// 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.
if (prepared.connection && !disconnectAtLeast(prepared.receipt, "desktop_restored")) {
restoreConnectedCodex(prepared.connection);
}
return 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 (!disconnectAtLeast(receipt, "removing_token")) advance("removing_token");
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");
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);
}
removeHubStateCache();
requireDesktopResult(finishRemoteDesktopCleanup(held, receipt.owner));
if (receipt.phase !== "complete") advance("complete");
return {
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);
}
/**
* 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); }
}