UNPKG

@bitkyc08/opencodex

Version:

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

383 lines (368 loc) • 21 kB
import type { Server } from "bun"; import { supportsDesktopPicker } from "../desktop-picker-platform"; import type { OcxConfig } from "../../types"; import { getConfigDir, withConfigDirHardeningSettled } from "../../config/paths"; import { claudeConfigDir } from "../auth-detect"; import type { DesktopPickerController } from "../desktop-picker"; import type { ClaudeFirstPartyDesired } from "../first-party-settings"; import { classifyInterceptClient, interceptRouteFor } from "./client-class"; import { createCliCatalogProvider } from "./cli-picker"; import { CLAUDE_INTERCEPT_HOSTS, isBrowserConnect, startConnectProxy, type ConnectProxyHandle } from "./connect-proxy"; import { startClaudeInterceptListener } from "./listener"; import { claudeInterceptCaCertPath, ensureLocalInterceptCaForStartup, issueLocalInterceptLeaf } from "./local-ca"; import { discardPickerCaKey } from "./picker-ca"; import { preparePersistentPickerAuthority } from "./picker-ca-startup"; import type { PickerCaStore } from "./picker-ca-store"; import type { PickerRouteInput } from "./picker-models"; import { CLAUDE_INTERCEPT_PORT_OFFSET, claudeInterceptEnabled, claudeInterceptProxyPort, claudePickerProxyPort } from "./port-policy"; import { createPickerRuntime, pickerDesired, type CreatePickerRuntimeOptions, type PickerRuntime } from "./picker-runtime"; import type { SecurityRunner } from "./picker-trust"; import { ensureClaudeInterceptProxyToken, readClaudeInterceptProxyToken } from "./proxy-auth"; import { buildClaudeInterceptEnv, migrateClaudeInterceptSettings } from "./settings"; /** * Lifecycle for the Claude intercept pair (CONNECT proxy + TLS listener). * * Started next to the public listener, torn down with it. The proxy port is derived from the * public port unless configured, because Claude Code's `settings.json` must name a port that * survives restarts; the TLS listener is ephemeral and only ever reached through the proxy. * * Picker mode adds a second CONNECT proxy on the next port, used as Claude Desktop's pinned egress * proxy. Desktop also hands that proxy to the Claude Code processes it spawns, so the choice is per * client: Claude Code (no User-Agent on CONNECT) trusts only the intercept CA and gets the * api.anthropic.com intercept and nothing else; the app itself (a browser User-Agent) trusts only * the OS root store and never meets the api.anthropic.com intercept, and only its claude.ai * tunnels may be terminated by the picker runtime (src/claude/intercept/picker-runtime.ts). */ const PICKER_AUTHORITY_ERROR_CODES = new Set([ "picker_ca_store_unavailable", "picker_ca_store_missing", "picker_ca_store_invalid", "picker_ca_store_readback_failed", "picker_ca_metadata_mismatch", "picker_ca_metadata_unsafe", "picker_ca_metadata_invalid", "picker_ca_live_owner", "picker_ca_pending_untrust", "picker_ca_pending_untrust_invalid", "picker_ca_pending_untrust_unsafe", "picker_ca_pending_untrust_changed", "picker_ca_config_unsafe", "picker_ca_directory_unsafe", "picker_ca_rotation_requires_startup", "picker_ca_unsupported_platform", ]); export { CLAUDE_INTERCEPT_PORT_OFFSET, claudeInterceptEnabled, claudeInterceptProxyPort, claudePickerProxyPort } from "./port-policy"; export type ClaudeInterceptOutcome = { ok: true; state: ClaudeInterceptState } | { ok: false; reason: "disabled" | "client_role" | "ephemeral_port" | "port_in_use" | "stopped" | "failed"; port?: number; message?: string }; export interface ClaudeInterceptState { pickerReason?: "port_in_use" | "failed" | null; pickerFailurePort?: number; proxyPort: number; caCertPath: string; /** Desktop egress proxy for picker mode; null when the picker is not wired or could not bind. */ pickerProxyPort: number | null; } export interface ClaudeInterceptHandle<T = undefined> extends ClaudeInterceptState { listener: Server<T>; stop(): Promise<void>; } let activeState: ClaudeInterceptState | null = null; let activePicker: PickerRuntime | null = null; let activeController: DesktopPickerController | null = null; /** Live intercept endpoints, or `null` when the pair is not running in this process. */ export function getClaudeInterceptState(): ClaudeInterceptState | null { return activeState; } /** The running picker runtime, or `null` when picker mode is not wired in this process. */ export function getClaudePickerRuntime(): PickerRuntime | null { return activePicker; } /** The picker controller that owns every picker mutation while this server runs, or `null`. */ export function getClaudePickerController(): DesktopPickerController | null { return activeController; } /** * Persist `claudeCode.intercept.picker` through the field-scoped writer and adopt the committed * subtree into the live config, so a later whole-config save neither reverts nor re-applies it. */ export async function createPickerPreferenceWriter(live: OcxConfig): Promise<(value: boolean) => boolean> { const { adoptPersistedClaudeCode, mutatePersistedConfig } = await import("../../config"); return value => { const outcome = mutatePersistedConfig(persisted => { const claudeCode = persisted.claudeCode ?? {}; const intercept = claudeCode.intercept ?? {}; if (intercept.picker === value) return { changed: false, value: structuredClone(persisted.claudeCode) }; persisted.claudeCode = { ...claudeCode, intercept: { ...intercept, picker: value } }; return { changed: true, value: structuredClone(persisted.claudeCode) }; }); if (outcome.status === "unavailable") return false; adoptPersistedClaudeCode(live, outcome.value); return true; }; } export class ClaudeInterceptProxyBindError extends Error { readonly code: unknown; constructor(error: unknown, readonly port: number) { super(error instanceof Error ? error.message : "CONNECT proxy bind failed", { cause: error }); this.code = error && typeof error === "object" && "code" in error ? error.code : undefined; } } export interface StartClaudeInterceptOptions<T> { config: OcxConfig; /** Bound public port; the derived proxy port is offset from it. */ publicPort: number; /** * Port the operator asked for. `0` (ephemeral) gives the derived proxy port no stable value * to write into `settings.json`, so intercept stays off unless `intercept.port` is explicit. */ requestedPort?: number; dispatch: (req: Request, server: Server<T>) => Promise<Response>; /** Live first-party intent; absent preserves router behavior. */ desiredClients?: () => ClaudeFirstPartyDesired; maxRequestBodySize?: number; configDir?: string; /** Routes for Desktop's Code-tab picker. Picker mode is wired only when this is given. */ loadPickerRoutes?: () => Promise<PickerRouteInput>; /** Test seam: builds the picker runtime. */ createPicker?: (options: CreatePickerRuntimeOptions) => PickerRuntime; /** Test seam: bind real CONNECT handlers on kernel-assigned ports without probe-and-release races. */ startProxy?: typeof startConnectProxy; /** Test seams: the platform trust runner and platform for the picker runtime and controller. */ pickerCaStore?: PickerCaStore; pickerSecurity?: SecurityRunner; pickerPlatform?: NodeJS.Platform; } /** * Bind both halves. Resolves `null` when intercept is disabled. A bind failure is reported by * rejecting; callers treat it as a degraded optional integration, never as a startup failure. */ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptions<T>): Promise<ClaudeInterceptHandle<T> | null> { // An older release may have left the picker's exportable signing key on disk. Remove it on every // start, even when the intercept or the picker is off, so an upgrade with the picker disabled // does not keep the key of a CA that may still be trusted. Failure here must not block startup. try { discardPickerCaKey(options.configDir ?? getConfigDir()); } catch { /* retried on the next start */ } if (!claudeInterceptEnabled(options.config)) return null; const explicitPort = typeof options.config.claudeCode?.intercept?.port === "number"; if (options.requestedPort === 0 && !explicitPort) return null; const configDir = options.configDir ?? getConfigDir(); const ca = await ensureLocalInterceptCaForStartup(configDir); const startProxy = options.startProxy ?? startConnectProxy; const authToken = await withConfigDirHardeningSettled(configDir, () => ensureClaudeInterceptProxyToken(configDir)); const leaf = issueLocalInterceptLeaf(ca, CLAUDE_INTERCEPT_HOSTS); const listener = startClaudeInterceptListener<T>({ leaf, dispatch: options.dispatch, ...(options.desiredClients ? { route: (req: Request) => interceptRouteFor(classifyInterceptClient(req.headers.get("user-agent")), options.desiredClients!()) } : {}), // The CLI's /model catalog (cli-picker.ts): wired from the routes alone, never from Desktop picker state. ...(options.loadPickerRoutes && options.desiredClients ? { cliCatalog: createCliCatalogProvider({ configDir, loadRoutes: options.loadPickerRoutes, desiredClients: options.desiredClients, }) } : {}), upstreamBase: options.config.claudeCode?.anthropicBaseUrl, ...(options.maxRequestBodySize !== undefined ? { maxRequestBodySize: options.maxRequestBodySize } : {}), }); let proxy: ConnectProxyHandle; try { proxy = await startProxy(claudeInterceptProxyPort(options.config, options.publicPort), { interceptPort: listener.port!, // A real apply may recreate a missing token while this listener remains live. // Read current validated authority per CONNECT; absent/invalid means deny, not mint. authToken: () => readClaudeInterceptProxyToken(configDir), }); } catch (error) { await listener.stop(true); throw new ClaudeInterceptProxyBindError(error, claudeInterceptProxyPort(options.config, options.publicPort)); } // Publish only a successfully bound endpoint, using the handle's actual port. A failed // fixed-port bind leaves settings untouched; an ephemeral test binder never publishes :0 // or a probed port another process can steal. Only stale, owned env blocks are rewritten. try { // Fresh admission after the bind await: a nested CLAUDE_CONFIG_DIR shares the config-root flight. await withConfigDirHardeningSettled(claudeConfigDir(), () => migrateClaudeInterceptSettings(buildClaudeInterceptEnv(proxy.port, claudeInterceptCaCertPath(configDir), authToken))); } catch (error) { // Ensure/apply retries a skipped migration; upgraded clients otherwise keep hitting 407. console.warn(`[claude-intercept] settings migration skipped: ${error instanceof Error ? error.message : String(error)}`); } // Widened on purpose: assignments happen in nested awaits the catch below must still see. let picker = null as PickerRuntime | null; let pickerProxy = null as ConnectProxyHandle | null; let controller = null as DesktopPickerController | null; let pickerProxyLive = false; let stopped = false; let pickerReason: ClaudeInterceptState["pickerReason"] = null; let pickerFailurePort: number | undefined; try { if (options.loadPickerRoutes && supportsDesktopPicker(options.pickerPlatform ?? process.platform)) { // Remove any legacy plaintext key before inspecting or activating picker state. discardPickerCaKey(configDir); const { inspectDesktopPickerProfile } = await import("../desktop-picker-profile"); // The applied profile row is durable evidence of the user's picker selection. Rotation keeps // it in place — row id and its recorded previous selection included — so the picker proxy // can fail to bind without losing it, and the restore enable below only updates the proxy // URL inside the same row rather than recreating a selection around a placeholder pivot. const pickerProfile = inspectDesktopPickerProfile({ configDir, ...(options.pickerPlatform ? { platform: options.pickerPlatform } : {}), }); const pickerProfileApplied = pickerProfile.kind === "applied"; let pickerBlocked = false; let pickerWired = false; try { const { observeClaudeDesktopMode, resolveClaudeDesktopMode } = await import("../desktop-first-party"); const fresh = options.config; const platform = options.pickerPlatform ?? process.platform; const pickerRequired = pickerProfileApplied || pickerDesired(fresh, resolveClaudeDesktopMode(fresh, observeClaudeDesktopMode(fresh)), platform); // Preserve macOS's dormant relay; Windows and Linux defer binding until enable or profile recovery. pickerWired = platform === "darwin" || pickerRequired; if (pickerRequired) { await preparePersistentPickerAuthority({ configDir, store: options.pickerCaStore, security: options.pickerSecurity, platform }); } } catch (error) { pickerBlocked = true; pickerReason = "failed"; // Native and filesystem errors may include private contents or paths. Emit only an exact // application-owned code; arbitrary diagnostic text never crosses this boundary. const code = error instanceof Error && PICKER_AUTHORITY_ERROR_CODES.has(error.message) ? error.message : null; console.warn(code === "picker_ca_pending_untrust" ? "⚠ Claude Desktop picker disabled: the previous certificate could not be untrusted" : `⚠ Claude Desktop picker disabled: picker authority unavailable${code ? ` (${code})` : ""}`); } if (pickerBlocked) { if (pickerProfile.kind === "applied") { // Keep Desktop's actual pinned egress alive without ever constructing a TLS terminator. const port = Number(new URL(pickerProfile.proxyUrl).port); try { pickerProxy = await startProxy(port, { interceptPort: listener.port!, interceptHosts: [], selectTunnel: () => ({ kind: "blind" }), }); pickerProxyLive = true; } catch (error) { pickerReason = error && typeof error === "object" && "code" in error && error.code === "EADDRINUSE" ? "port_in_use" : "failed"; if (pickerReason === "port_in_use") pickerFailurePort = port; console.warn(`⚠ Claude Desktop blind egress relay could not start: ${error instanceof Error ? error.message : String(error)}`); } } } picker = pickerBlocked ? null : (options.createPicker ?? createPickerRuntime)({ config: options.config, configDir, persistentAuthority: { store: options.pickerCaStore }, loadRoutes: options.loadPickerRoutes, // The controller's lock: while it is held, periodic refreshes never arm. isBusy: () => controller?.busy() ?? false, // Metadata only: method, bootstrap or other, status, and the rewrite outcome. log: line => console.log(`[claude-picker] ${line}`), ...(options.pickerSecurity ? { security: options.pickerSecurity } : {}), ...(options.pickerPlatform ? { platform: options.pickerPlatform } : {}), }); if (picker) { const runtime = picker; const interceptPort = listener.port!; const pickerPort = claudePickerProxyPort(options.config, options.publicPort); const bindPickerProxy = async (): Promise<void> => { if (stopped || pickerProxyLive) return; try { pickerProxy = await startProxy(pickerPort, { interceptPort, // No authToken: Desktop's egressProxyUrl cannot present proxy credentials, so this // listener stays an unauthenticated loopback relay until the profile format can carry // one. The intercept proxy above is the credential-bearing hop. // No host list here: the choice below depends on which client opened the tunnel. interceptHosts: [], selectTunnel: (host, port, request) => { // Desktop hands its pinned egress proxy to the Claude Code processes it spawns, so their // api.anthropic.com traffic arrives here too and gets the same intercept as on the Claude // Code proxy. Those processes trust only the intercept CA, so the picker never terminates // their claude.ai tunnels; only the app's own (browser) CONNECTs reach the picker. if (!isBrowserConnect(request)) { return port === 443 && (CLAUDE_INTERCEPT_HOSTS as readonly string[]).includes(host.toLowerCase()) ? { kind: "intercept", port: interceptPort } : { kind: "blind" }; } return runtime.selectTunnel(host, port); }, }); if (stopped) { await pickerProxy.close(); return; } pickerProxyLive = true; pickerReason = null; pickerFailurePort = undefined; } catch (error) { // Picker mode is optional: a busy port leaves the intercept pair running without it. // The selected profile row survives; a dormant enable can retry after the port is free. pickerReason = error && typeof error === "object" && "code" in error && error.code === "EADDRINUSE" ? "port_in_use" : "failed"; if (pickerReason === "port_in_use") pickerFailurePort = pickerPort; console.warn(`⚠ Claude Desktop picker proxy could not start: ${error instanceof Error ? error.message : String(error)}`); throw error; } }; if (pickerWired) { try { await bindPickerProxy(); } catch { await runtime.stop(); picker = null; } } if (picker) { // Dynamic: the controller reaches desktop-first-party, which imports this module. const [{ createDesktopPickerController }, { loadConfig }, persistPreference] = await Promise.all([ import("../desktop-picker"), import("../../config"), createPickerPreferenceWriter(options.config), ]); controller = createDesktopPickerController({ runtime: picker, readConfig: loadConfig, persistPreference, proxyPort: () => (pickerProxyLive ? pickerProxy?.port ?? null : null), ensureProxy: async () => { await bindPickerProxy(); if (!pickerProxyLive) return; await runtime.start(); if (!stopped && activeController === controller) activePicker = runtime; }, configDir, persistentAuthority: { store: options.pickerCaStore }, ...(options.pickerSecurity ? { security: options.pickerSecurity } : {}), ...(options.pickerPlatform ? { platform: options.pickerPlatform } : {}), }); if (pickerWired) await picker.start(); // Restore inspects the retained identity without installing trust. Explicit enable/trust // owns consent when trust was revoked or legacy migration introduced a new authority. if (pickerProfileApplied && controller) { void controller.enable({ persist: false, context: "server", allowTrustPrompt: false }) .catch(error => console.warn(`⚠ Claude Desktop picker restore failed: ${error instanceof Error ? error.message : String(error)}`)); } } } } } catch (error) { // Construction or start failed after the CONNECT proxy bound: release every socket first, // so the lifecycle's catch never leaves a bound port without a handle. pickerProxyLive = false; controller = null; await picker?.stop(); await pickerProxy?.close(); await proxy.close(); await listener.stop(true); throw error; } const state: ClaudeInterceptState = { get pickerReason() { return pickerReason; }, get pickerFailurePort() { return pickerFailurePort; }, proxyPort: proxy.port, caCertPath: claudeInterceptCaCertPath(configDir), get pickerProxyPort() { return pickerProxyLive ? pickerProxy?.port ?? null : null; }, }; activeState = state; activePicker = pickerProxyLive ? picker : null; activeController = controller; const ownPicker = picker; const ownController = controller; return { ...state, get pickerProxyPort() { return state.pickerProxyPort; }, get pickerReason() { return state.pickerReason; }, get pickerFailurePort() { return state.pickerFailurePort; }, listener, stop: async () => { stopped = true; if (activeState === state) activeState = null; if (activePicker === ownPicker) activePicker = null; if (activeController === ownController) activeController = null; pickerProxyLive = false; await ownPicker?.stop(); await pickerProxy?.close(); await proxy.close(); await listener.stop(true); }, }; }