UNPKG

@bitkyc08/opencodex

Version:

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

332 lines (308 loc) • 17.1 kB
/** * `ocx codex [codex args...]` — launch Codex wired to the local proxy's routing, * passing through untouched when Codex routing is disabled or foreign. * * Mirrors `ocx claude` (src/cli/claude.ts) and `ocx opencode` (src/cli/opencode.ts): * ensures the proxy is running, then execs the client with stdio inherited. The wiring * channel differs again — Codex routing is config-owned (the injected `openai_base_url` * and model catalog in `~/.codex/config.toml`), so a launch never rewrites a config * file. What the launcher owns instead is the two add-ons `plain codex` lacks: * * - launch-time autostart: the same detached `ocx start` + health poll that * `ocx ensure` gives service- and shim-less setups, attempted before every routed launch; * - an honest route verdict before exec: native and foreign-gateway configs are * announced (and NOT ensured) instead of silently benefiting or fighting them, * reusing the routing classification the shim and doctor share * (src/codex/inject/routing-classify.ts). * * The admission token is re-exported from `~/.opencodex/service-api-token` when the * environment does not carry it — the same injection the generated Codex autostart * shim performs (src/codex/shim-templates.ts), whose argv fast-path grammar * (--help/-h, --version/-V, internal subcommands, global options with values) is * mirrored here so both `codex` entry points behave identically for the same argv. */ import { spawn } from "node:child_process"; import { loadConfig } from "../config"; import { getCodexRoutingKind, type CodexRoutingKind } from "../codex/inject"; import { inspectCodexShimBackingForCommand } from "../codex/shim"; import { validatedCodexExecInvocationAsync, type CodexExecBoundaryAsyncDeps } from "../codex/exec-boundary"; import { CODEX_GLOBAL_OPTIONS_WITH_VALUE, CODEX_INTERNAL_COMMANDS, CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC } from "../codex/shim-templates"; import { withoutSiblingMarker } from "../codex/sibling-start"; import { withProcessRuntimeProvenance } from "../lib/bun-runtime"; import { tokenCollidesWithAdmin } from "../lib/admin-secrets"; import { selfLaunchArgv } from "../lib/self-launch-argv"; import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "../lib/service-secrets"; import { findExecutableOnPath } from "../remote-control/workspace-executable"; import { findLiveProxy, type LiveProxy } from "../server/proxy-liveness"; import { attestCodexRuntime, codexCredentialDestinationIsTrusted, resolveCodexLaunchHome, type CodexRuntimeAttestation } from "./codex-launch-auth"; import { codexCommandCanBypass, CODEX_UNVERIFIED_SHIM } from "./codex-launch-command"; import { codexTokenArgsAreSafe, codexTokenEnvironmentIsSafe } from "./codex-launch-policy"; import { codexTokenWithheldDiagnostic, type CodexTokenRefusal, type CodexTokenRefusalReporter } from "./codex-launch-diagnostics"; import { withoutSupervisorMarkers } from "../lib/supervisor-markers"; export interface CodexLaunchEnv { [key: string]: string | undefined; } type FastPathReason = "help" | "version" | "internal"; /** * Mirrors the generated shim wrapper's argv grammar (src/codex/shim-templates.ts): * an invocation whose first positional operand is a Codex-internal subcommand, or * which only asks for help/version, never needs the proxy. The shell scanners * inline these sets — the exported constants here are the single source they are * read from — while the option-value rules (`--model x`, `-c k=v`, ...) stay in * this scanner in sync with the same templates. */ export function codexFastPathReason(args: readonly string[]): FastPathReason | null { let skipNext = false; for (const arg of args) { if (skipNext) { skipNext = false; continue; } if (arg === "--") return null; // the shim's `break`: rest is operands, ensure runs const options = CODEX_GLOBAL_OPTIONS_WITH_VALUE; if (options.includes(arg)) { skipNext = true; continue; } if (arg === "--help" || arg === "-h") return "help"; if (arg === "--version" || arg === "-V") return "version"; if (arg.startsWith("-")) continue; const value = arg; return (CODEX_INTERNAL_COMMANDS.includes(value)) ? "internal" : null; } return null; } export const CODEX_ROUTING_NATIVE_NOTICE = "ℹ️ Codex does not route through OpenCodex (no injected routing in ~/.codex/config.toml). Launching `codex` unchanged. Run `ocx ensure` to start the proxy and sync Codex config."; export const CODEX_ROUTING_UNKNOWN_NOTICE = "⚠️ Codex routing could not be verified. Ensuring the proxy is up, but the launch may not be redirected; run `ocx doctor` before relying on it."; export const CODEX_ROUTING_CUSTOM_LOCAL_NOTICE = "⚠️ Codex routes through a user-owned local gateway. OpenCodex does not own that route; launching `codex` unchanged. Run `ocx doctor` to verify that gateway."; export const CODEX_ROUTING_CUSTOM_REMOTE_NOTICE = "⚠️ Codex routes through a remote gateway. OpenCodex does not own that route; launching `codex` unchanged."; export type CodexLaunchPlan = | { kind: "routed" } | { kind: "passthrough"; notice?: string; ensureProxy: boolean }; /** * Pure launch decision from the shared routing classification: * * - `opencodex-local` → ensure + exec (the config this launcher exists for); * - `native` / `custom-*` → exec unchanged, no proxy side effects; * - `unknown` (unreadable/ambiguous config) → name it out loud and still attempt * the ensure, because a routed session that starts without its proxy hits the * configured URL's dead port and every request fails. */ export function codexLaunchPlan(routingKind: CodexRoutingKind): CodexLaunchPlan { switch (routingKind) { case "opencodex-local": return { kind: "routed" }; case "native": return { kind: "passthrough", ensureProxy: false, notice: CODEX_ROUTING_NATIVE_NOTICE }; case "custom-local": return { kind: "passthrough", ensureProxy: false, notice: CODEX_ROUTING_CUSTOM_LOCAL_NOTICE }; case "custom-remote": return { kind: "passthrough", ensureProxy: false, notice: CODEX_ROUTING_CUSTOM_REMOTE_NOTICE }; case "unknown": return { kind: "passthrough", ensureProxy: true, notice: CODEX_ROUTING_UNKNOWN_NOTICE }; } } /** Env the detached `ocx start` child inherits (service-owned admission ladder). */ export function codexProxyStartEnv(base: CodexLaunchEnv = process.env): CodexLaunchEnv { const stripped = withoutSiblingMarker(base) as CodexLaunchEnv; const withTokenFile = stripped.OPENCODEX_API_AUTH_TOKEN?.trim() ? stripped : { ...stripped, OCX_API_TOKEN_FILE: serviceApiTokenFilePath() }; // A shell a supervised runtime handed to a tool carries its supervisor's markers; this proxy is not its. return withoutSupervisorMarkers({ ...withTokenFile, OCX_SERVICE: "1" }) as CodexLaunchEnv; } export type CodexProxyEnsureDeps = { findLiveProxy?: typeof findLiveProxy; }; /** * Mirrors ensureProxyForClaude (src/cli/claude.ts) — the same borrowed liveness * retry budget (#764), detached `ocx start` on the configured port, 8 s health * poll — so all `ocx`-launched clients share one autostart contract. */ export async function ensureProxyForCodex(deps: CodexProxyEnsureDeps = {}): Promise<LiveProxy | null> { const probe = deps.findLiveProxy ?? findLiveProxy; const live = await probe({ attempts: 3 }); if (live) return live; const cfgPort = loadConfig().port; const pinPort = typeof cfgPort === "number" && cfgPort > 0 ? cfgPort : 10100; const child = spawn(process.execPath, selfLaunchArgv(["start", "--port", String(pinPort)]), { detached: true, stdio: "ignore", windowsHide: true, // An ordinary owner: a stray sibling marker would otherwise mark it before any probe. env: withProcessRuntimeProvenance(codexProxyStartEnv(process.env) as NodeJS.ProcessEnv), }); // Without a listener an 'error' (bad argv[1], EMFILE, AV denial) throws synchronously // and kills this process; the health poll below already reports the failure properly. child.on("error", () => { /* handled by the deadline loop returning null */ }); child.unref(); const deadline = Date.now() + 8_000; while (Date.now() < deadline) { const started = await probe(); if (started) return started; await new Promise(resolve => setTimeout(resolve, 250)); } return null; } export type CodexLaunchEnvDeps = { routingKind?: CodexRoutingKind; args?: readonly string[]; /** Test seam; production reads the hardened service token file. */ serviceToken?: (base: CodexLaunchEnv) => string | null; credentialDestination?: (home: string, report?: CodexTokenRefusalReporter, runtimeAttestation?: CodexRuntimeAttestation | null) => boolean; /** Exact origin that proved this home's runtime-record secret. */ runtimeAttestation?: CodexRuntimeAttestation | null; }; /** Read the client admission credential from this installation's service-token file. */ const defaultServiceToken = (base: CodexLaunchEnv): string | null => loadServiceTokenFromFile({ ...base, OCX_API_TOKEN_FILE: serviceApiTokenFilePath() }); /** * Launch env for a routed exec. The one injection is the shim's own: a missing * OPENCODEX_API_AUTH_TOKEN is re-exported from the hardened service token file, so * `ocx codex` from a shell without the system-env snapshot authenticates to the * loopback proxy like a shimmed launch does. Fresh credentials require explicit * argv/env/config allowlists, an exclusive managed provider and protected home/system * configuration namespaces. User exports always win. */ export function buildCodexLaunchEnv( base: CodexLaunchEnv = process.env, deps: CodexLaunchEnvDeps = {}, ): CodexLaunchEnv { const env = { ...base }; if (deps.routingKind !== undefined && deps.routingKind !== "opencodex-local") return env; if (!env.OPENCODEX_API_AUTH_TOKEN?.trim()) { const withhold = (reason: CodexTokenRefusal): CodexLaunchEnv => { console.error(codexTokenWithheldDiagnostic(reason)); return env; }; if (!codexTokenArgsAreSafe(deps.args ?? [])) return withhold("args"); if (!codexTokenEnvironmentIsSafe(env)) return withhold("environment"); if (!deps.runtimeAttestation) return withhold("destination"); // NO_PROXY parsing and precedence vary across native HTTP/WebSocket transports. // Without proving bypass, preserve the user's transport but never load a secret. const home = resolveCodexLaunchHome(env); if (!home) return withhold("home"); let refusal: CodexTokenRefusal = "destination"; const report: CodexTokenRefusalReporter = reason => { refusal = reason; }; const trusted = deps.credentialDestination ? deps.credentialDestination(home, report, deps.runtimeAttestation) : codexCredentialDestinationIsTrusted(home, undefined, report, deps.runtimeAttestation); if (!trusted) return withhold(refusal); const token = (deps.serviceToken ?? defaultServiceToken)(env); if (!token) return withhold("credential"); if (tokenCollidesWithAdmin(token, env)) return withhold("collision"); // Reqwest's default transport can discover OS proxies even without proxy // env. Bind both bypass spellings to the allowed loopback hosts, preserving // existing entries and removing conflicting case aliases before handoff. const bypass = ["127.0.0.1", "::1"]; for (const key of Object.keys(env)) if (/^no_proxy$/i.test(key)) { if (env[key]) bypass.push(env[key]!); delete env[key]; } env.NO_PROXY = env.no_proxy = bypass.join(","); env.CODEX_HOME = home; env.OPENCODEX_API_AUTH_TOKEN = token; } return env; } const CODEX_INSTALL_HINT = "❌ `codex` CLI not found. Install it first: npm install -g @openai/codex"; class CodexNotFoundError extends Error {} /** * cmd.exe reports command-not-found as exit 9009 (the win32 launcher routes `.cmd` * shims through cmd.exe, so ENOENT never fires there). Signal exits are not hints. * Same contract as claudeNotFoundHint (devlog 260715_cross_platform_audit/020). */ export function codexNotFoundHint( code: number | null, signal: NodeJS.Signals | null, platform: NodeJS.Platform = process.platform, ): string | null { return platform === "win32" && code === 9009 && !signal ? CODEX_INSTALL_HINT : null; } export type CodexLaunchCommandDeps = { findOnPath?: (name: string) => string | null; inspectShim?: typeof inspectCodexShimBackingForCommand; verifyBypass?: typeof codexCommandCanBypass; }; export type CodexLaunchCommand = { command: string; env: CodexLaunchEnv }; /** * The launcher has already made the ensure decision, so the generated autostart shim * must not make it again: on a passthrough plan it would start the proxy and load the * admission token anyway. When `codex` resolves to a recorded shim wrapper, exec its * backing Codex directly. Unknown state requires a separate bypass-content check; * obsolete or unverifiable Windows wrappers fail closed before starting any child. */ export function resolveCodexLaunchCommand( env: CodexLaunchEnv, deps: CodexLaunchCommandDeps = {}, ): CodexLaunchCommand { try { const selected = (deps.findOnPath ?? findExecutableOnPath)("codex"); if (!selected) throw new CodexNotFoundError(CODEX_INSTALL_HINT); let shim: ReturnType<typeof inspectCodexShimBackingForCommand>; try { shim = (deps.inspectShim ?? inspectCodexShimBackingForCommand)(selected); } catch { shim = { status: "unknown", reason: "binding_unavailable" }; } if (shim.status === "matched" && shim.selectedRole === "wrapper") return { command: shim.backingPath, env }; if (shim.status !== "unknown") return { command: selected, env }; if (!(deps.verifyBypass ?? codexCommandCanBypass)(selected, env)) throw new Error(CODEX_UNVERIFIED_SHIM); return { command: selected, env: { ...env, OCX_SHIM_BYPASS: "1" } }; } catch (error) { if (error instanceof CodexNotFoundError) throw error; throw new Error(CODEX_UNVERIFIED_SHIM); } } export interface CodexSpawnDeps extends CodexLaunchCommandDeps { execBoundary?: CodexExecBoundaryAsyncDeps; spawn?: typeof spawn; } /** Validate the final backing command immediately before each launch, including fast paths. */ export async function spawnCodex(args: readonly string[], env: CodexLaunchEnv, deps: CodexSpawnDeps = {}): Promise<number> { let launch: CodexLaunchCommand, inv: Awaited<ReturnType<typeof validatedCodexExecInvocationAsync>>; try { launch = resolveCodexLaunchCommand(env, deps); inv = await validatedCodexExecInvocationAsync(launch.command, args, { ...deps.execBoundary, verifyAnyAppBundle: true, env: launch.env as NodeJS.ProcessEnv }); } catch (error) { // A selected executable that vanished before verification is the same missing CLI // the spawn-time ENOENT branch below reports, not a trust refusal. const missing = error instanceof CodexNotFoundError || (error as NodeJS.ErrnoException | null)?.code === "ENOENT"; console.error(missing ? CODEX_INSTALL_HINT : `❌ Cannot launch codex: ${error instanceof Error ? error.message : "executable verification failed"}`); return 1; } return new Promise<number>(resolve => { const child = (deps.spawn ?? spawn)(inv.file, inv.args, { stdio: "inherit", env: launch.env as NodeJS.ProcessEnv, ...inv.options }); child.on("error", (err: NodeJS.ErrnoException) => { if (err.code === "ENOENT") { console.error(CODEX_INSTALL_HINT); } else { console.error(`❌ Failed to launch codex: ${err.message}`); } resolve(1); }); child.on("exit", (code, signal) => { const hint = codexNotFoundHint(code, signal); if (hint) console.error(hint); resolve(signal ? 1 : code ?? 0); }); }); } /** Apply the argument/routing plan, then hand the original arguments to Codex. */ export async function cmdCodex(args: string[]): Promise<number> { if (codexFastPathReason(args) !== null) return spawnCodex(args, { ...process.env }); const routingKind = getCodexRoutingKind(); const plan = codexLaunchPlan(routingKind); const notice = plan.kind === "passthrough" ? plan.notice : undefined; if (notice) console.error(notice); const needsProxy = plan.kind === "routed" || (plan.kind === "passthrough" && plan.ensureProxy); if (!needsProxy) return spawnCodex(args, { ...process.env }); const live = await ensureProxyForCodex(); if (!live) { // A failed ensure warns and continues, subject to executable verification. // The already-injected config decides // what the session does next; `ocx doctor` names the autostart failure. console.error(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC); } // A public health marker proves liveness, not ownership of the listener. Never read the // persisted service token until the exact runtime-record endpoint answers a fresh challenge. const runtimeAttestation = plan.kind === "routed" && live !== null ? await attestCodexRuntime(live) : null; return spawnCodex(args, buildCodexLaunchEnv(process.env, { routingKind, args, runtimeAttestation })); }