UNPKG

@bitkyc08/opencodex

Version:

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

721 lines (680 loc) • 35 kB
import { execFile, type ExecFileException } from "node:child_process"; import { createHash } from "node:crypto"; import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { compareStrictSemver, parseStrictSemver } from "../lib/strict-semver"; import { npmInvocation } from "../update/npm-invocation.mjs"; import { CODEX_CLI_TRANSPORT_ENV_KEYS } from "../update/codex-cli-update-launch-policy.mjs"; import { CODEX_CLI_REGISTRY, isSha512Integrity, codexCliArtifactSetAsync, codexCliArtifactSetDigest, type CodexCliArtifactSet } from "./cli-update-artifacts"; export { CODEX_CLI_REGISTRY } from "./cli-update-artifacts"; import { windowsCodexCliPlanEvidence, windowsCodexCliToolchainDigest, withWindowsCodexCliPlanToolchain } from "./cli-windows-plan-provenance"; import { windowsCliApplyPrefixSupported } from "./cli-update-job-store-windows"; import { windowsInstallNamespaceSupported } from "./cli-update-windows-observation"; import { windowsNpmExecutionArgs } from "./windows-npm-execution"; import { inspectCodexCliInstall, type CodexCliInstallKind, type CodexCliInstallProvenanceDeps, type CodexCliInstallReport, } from "./cli-install-provenance"; import { scanCodexSessionProcessesAsync, type CodexAppServerProcessIo, type CodexAppServerProcessScan, } from "./app-server-processes"; /** * Phase 2 of the Codex CLI update manager: a deterministic dry-run plan. * * Phase 1 ({@link inspectCodexCliInstall}) answers who owns the installation. It never * queries a registry, never enumerates processes and never writes. This module adds the * three inputs it deliberately left out — an exact resolved target with registry * integrity, live session blockers, and a decision — and nothing else. * * Two invariants shape the whole module: * * - No persisted state. The plan is not stored anywhere; {@link CodexCliUpdatePlan.planId} * is a digest over the evidence the decision rests on, so an approved change to any * bound field produces a different id. * - Nothing is terminated or restarted. A live Codex session refuses the plan; it is * never signalled, killed or waited on. The plan performs no application-state * mutation: it resolves registry metadata and reads the process table under a * temporary isolated npm root (cwd, npmrc, cache and logs) that is removed * afterwards; a forcibly terminated run may leave that temp root behind, so the * cleanup contract is best-effort rather than absolute. */ export const CODEX_CLI_PACKAGE = "@openai/codex"; export const CODEX_CLI_UPDATE_SCHEMA_VERSION = 1 as const; /** Only the stable channel is exposed; a moving dist-tag is resolved before it is used. */ export type CodexCliUpdateChannel = "latest"; export type CodexCliUpdateRefusal = | "windows_inspection_deferred" | "windows_apply_disabled" | "not_managed" | "installed_version_unverified" | "install_content_unverified" | "target_unresolved" | "already_current" | "target_not_newer" | "blocked_active_session" | "blocked_process_state_unknown"; /** * `not-evaluated` is not a weaker `unknown`: it records that the plan was already refused * on ownership or target grounds, so the process table was never read. Only `unknown` * means an enumeration attempt failed. */ export type CodexCliUpdateSessionState = "none" | "active" | "unknown" | "not-evaluated"; export interface CodexCliUpdateSession { readonly state: CodexCliUpdateSessionState; /** Match count only. Command lines and paths never leave the process scanner. */ readonly matches: number | null; } export type CodexCliUpdateTarget = | Readonly<{ kind: "resolved"; version: string; integrity: string; artifacts?: CodexCliArtifactSet }> | Readonly<{ kind: "unresolved"; reason: string }>; export interface CodexCliUpdatePlan { readonly schemaVersion: typeof CODEX_CLI_UPDATE_SCHEMA_VERSION; readonly package: typeof CODEX_CLI_PACKAGE; readonly channel: CodexCliUpdateChannel; readonly applicable: boolean; readonly refusal: CodexCliUpdateRefusal | null; /** Also present for a proven Windows read-only plan whose apply remains disabled. */ readonly planId: string | null; readonly provenance: CodexCliInstallKind; readonly managed: boolean; readonly installedVersion: string | null; readonly versionEvidence: CodexCliInstallReport["versionEvidence"]["kind"]; readonly location: string | null; readonly targetVersion: string | null; readonly targetIntegrity: string | null; readonly targetArtifacts?: CodexCliArtifactSet; readonly session: CodexCliUpdateSession; /** * The bounded content observation the installation report produced: digest of * the manifest, declared entrypoint and resolved platform backing the plan's * identity is pinned to. Not an execution guarantee — an apply phase must * re-observe before it can rely on the same bytes. */ readonly installContentDigest: string | null; /** Indicative install argv for the operator to read; the apply phase this plan precedes verifies a packed tarball against the bound sha512 rather than trusting a moving spec. */ readonly command: readonly string[] | null; } export interface CodexCliUpdatePlanDeps { readonly inspect?: (deps: CodexCliInstallProvenanceDeps) => Promise<CodexCliInstallReport>; readonly inspectionDeps?: CodexCliInstallProvenanceDeps; readonly platform?: NodeJS.Platform; readonly channel?: CodexCliUpdateChannel; readonly scanProcesses?: (io?: CodexAppServerProcessIo) => CodexAppServerProcessScan; /** Preferred request-path seam: the real session scan runs its child processes async. */ readonly scanProcessesAsync?: (io?: CodexAppServerProcessIo) => Promise<CodexAppServerProcessScan>; readonly processIo?: CodexAppServerProcessIo; readonly resolveTarget?: (channel: CodexCliUpdateChannel) => CodexCliUpdateTarget | Promise<CodexCliUpdateTarget>; readonly spawnProcess?: CodexCliUpdateSpawn; } const PLAN_ID_LENGTH = 32; const PLAN_ID_RE = /^[0-9a-f]{32}$/; const REGISTRY_TIMEOUT_MS = 12_000; /** The install argv this plan quotes for the operator to read, in argv form. */ export function codexCliUpdateCommand(version: string): readonly string[] { // The displayed command must reproduce the artifact the plan bound: without the // pinned registry the operator's npmrc could silently substitute another origin // for the same package@version string. return Object.freeze([ "npm", "install", "-g", "--registry=" + CODEX_CLI_REGISTRY, `${CODEX_CLI_PACKAGE}@${version}`, ]); } /** * Digest over exactly the evidence the decision rests on. * * Session blockers are deliberately absent: a session that starts or ends between dry-run * and a later apply must not invalidate an otherwise identical plan; it is re-read where * it can only ever refuse. Everything else — ownership, installed version, * location, resolved target, integrity — is bound, so any drift produces a different id. */ export function codexCliUpdatePlanId(bound: { readonly platform: NodeJS.Platform; readonly provenance: CodexCliInstallKind; readonly installedVersion: string; readonly installDigest: string | null; readonly installContentDigest: string; readonly channel: CodexCliUpdateChannel; readonly targetVersion: string; readonly targetIntegrity: string; readonly targetArtifactsDigest?: string; readonly toolchainDigest?: string; }): string { // Ordered pairs, not object key order: the digest must not depend on how a caller // happened to build the record. const fields: readonly (readonly [string, string])[] = [ ["schemaVersion", String(CODEX_CLI_UPDATE_SCHEMA_VERSION)], ["package", CODEX_CLI_PACKAGE], ["platform", bound.platform], ["provenance", bound.provenance], ["installedVersion", bound.installedVersion], ["installDigest", bound.installDigest ?? ""], ["installContentDigest", bound.installContentDigest], ["channel", bound.channel], ["targetVersion", bound.targetVersion], ["targetIntegrity", bound.targetIntegrity], ]; const hash = createHash("sha256"); for (const [key, value] of fields) hash.update(`${key}=${value}\n`); if (bound.targetArtifactsDigest) hash.update(`targetArtifactsDigest=${bound.targetArtifactsDigest}\n`); if (bound.toolchainDigest) hash.update(`toolchainDigest=${bound.toolchainDigest}\n`); return hash.digest("hex").slice(0, PLAN_ID_LENGTH); } interface NpmTarget { readonly bin: string; readonly args: string[]; readonly options: { readonly windowsVerbatimArguments?: boolean; readonly cwd?: string; readonly env?: NodeJS.ProcessEnv; }; } function npmTarget(args: readonly string[], env?: NodeJS.ProcessEnv): NpmTarget | null { const invocation = npmInvocation(args, process.platform, env ?? process.env); if (!invocation) return null; return { bin: invocation.file, args: invocation.args, options: invocation.options }; } /** * The npm environment with every registry-affecting config channel removed. * * npm maps any npm_config_* env var into its configuration, so NPM_CONFIG_REGISTRY or * npm_config_@openai:registry would defeat the pinned --registry flag (a scoped * registry beats the default for that scope). They are all stripped. The settings * this codebase intentionally supports survive untouched: the standard proxy * variables npm itself honors (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY, any case) * and NODE_EXTRA_CA_CERTS, which npm's own Node runtime reads for TLS. * * Node's own startup channels are stripped too. npm runs inside Node, so ambient * NODE_OPTIONS injects code before the first npm line, NODE_PATH redirects module * resolution, and NODE_TLS_REJECT_UNAUTHORIZED would make the pinned-registry TLS * check void - each one reaches the evidence-producing process unless removed. * NODE_V8_COVERAGE and NODE_REDIRECT_WARNINGS are dropped for the same reason in * reverse: they are output paths, so ambient values would write Node artifacts to * arbitrary external directories on exit. ELF/Darwin loader controls (LD_* and * DYLD_*) are also removed: they can load code or redirect loader output before * npm runs. OpenSSL's startup inputs are removed with them: OPENSSL_CONF names * a configuration file the crypto library reads at startup, OPENSSL_CONF_INCLUDE * resolves relative includes inside that configuration, and OPENSSL_MODULES / * OPENSSL_ENGINES name the directories its provider and engine search loads * shared modules from. None of these is input the updater child needs, so * ambient values stay out of the spawned npm. This is a denylist for * process-startup/output channels, not a claim that every ambient variable is * allowlisted. When a proof-bound launcher snapshot is available, proxy and * CA settings are replaced from that snapshot below. */ const NPM_ENV_DROP_KEYS: ReadonlySet<string> = new Set([ "node_options", "node_path", "node_tls_reject_unauthorized", "node_compile_cache", // Output-path channels: ambient values would make the Node process write // coverage JSON or warning output to an arbitrary external directory on exit, // escaping the owned temp root regardless of the isolated --cache. "node_v8_coverage", "node_redirect_warnings", // OpenSSL startup inputs: OPENSSL_CONF points the library at an ambient // startup configuration file (OPENSSL_CONF_INCLUDE resolves that config's // relative includes); OPENSSL_MODULES and OPENSSL_ENGINES point its // provider/engine search at ambient directories that supply loadable // shared modules. "openssl_conf", "openssl_conf_include", "openssl_modules", "openssl_engines", ]); function codexCliUpdateNpmEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv { const env: NodeJS.ProcessEnv = { ...base }; for (const key of Object.keys(env)) { const lower = key.toLowerCase(); if (lower.startsWith("npm_config_") || lower.startsWith("ld_") || lower.startsWith("dyld_") || NPM_ENV_DROP_KEYS.has(lower)) delete env[key]; } return env; } /** * Ambient environment with executable-selection and transport-trust channels replaced by * the proof-bound launcher snapshot. Bun may add project dotenv values after that snapshot, * so PATH/PATHEXT, proxies and NODE_EXTRA_CA_CERTS must all come from the captured context. * A snapshot without PATH means no trusted PATH at all — an empty one fails the spawn closed. */ function codexCliUpdateBoundEnv(bound: NodeJS.ProcessEnv | undefined): NodeJS.ProcessEnv { const merged = codexCliUpdateNpmEnv(); if (bound === undefined) return merged; // Derived from the launcher's allowlist so capture, parsing and the npm child cannot drift. const boundKeys = new Set<string>(["path", "pathext", ...CODEX_CLI_TRANSPORT_ENV_KEYS]); for (const key of Object.keys(merged)) { const k = key.toLowerCase(); if (boundKeys.has(k)) delete merged[key]; } let hasTrustedPath = false; for (const [key, value] of Object.entries(bound)) { const k = key.toLowerCase(); if (boundKeys.has(k) && value !== undefined) { merged[key] = value; if (k === "path") hasTrustedPath = true; } } // A trusted snapshot without PATH means "no trusted PATH", not "keep the ambient // one". Install the empty value explicitly so executable resolution fails closed // instead of silently re-inheriting a PATH the proof never attested. if (!hasTrustedPath) merged.PATH = ""; return merged; } interface NpmConfigIsolation { /** Controlled cwd: contains the sentinel package.json, so npm's project-config walk stops here. */ readonly dir: string; /** Distinct empty files: npm refuses to load one path at two configuration levels. */ readonly npmrc: string; readonly globalNpmrc: string; /** npm cache root under dir: keeps _cacache and _logs inside the owned root so a * successful query cannot leave residue in the ambient ~/.npm. */ readonly cache: string; readonly env: NodeJS.ProcessEnv; } /** * A directory npm cannot read hostile configuration through. * * npm resolves project config from the nearest ancestor containing package.json (or * node_modules/.git), so a bare temp dir is NOT enough — the walk would continue into * the operator's real ancestors. The sentinel package.json anchors the walk here, * where no .npmrc exists. --userconfig/--globalconfig replace the two file configs, * and the env filter removes the env-var channel. What remains is exactly the pinned * --registry flag plus proxy/CA values captured before project dotenv loading. */ export function createNpmConfigIsolation(dir?: string, boundEnv?: NodeJS.ProcessEnv): NpmConfigIsolation { const ownsRoot = dir === undefined; const root = dir ?? mkdtempSync(join(tmpdir(), "ocx-codex-cli-meta-")); try { writeFileSync(join(root, "package.json"), "{}\n"); const npmrc = join(root, "ocx-update.npmrc"); writeFileSync(npmrc, ""); const globalNpmrc = join(root, "ocx-update-global.npmrc"); writeFileSync(globalNpmrc, ""); const cache = join(root, "npm-cache"); const env = codexCliUpdateBoundEnv(boundEnv); // npm enables Node's compile cache itself. Dropping the ambient output path // alone recreates <tmpdir>/node-compile-cache outside this owned lifetime. // The version verification child inherits this same controlled path. env.NODE_COMPILE_CACHE = resolve(root, "node-compile-cache"); return { dir: root, npmrc, globalNpmrc, cache, env }; } catch (error) { // A mid-setup failure must not leak a directory this call created; a // caller-supplied directory stays the caller's responsibility. if (ownsRoot) rmSync(root, { recursive: true, force: true }); throw error; } } /** Registry-pinned, config-isolated argv for one npm call. */ function isolatedNpmArgs(args: readonly string[], isolation: NpmConfigIsolation): readonly string[] { return [ ...args, "--registry=" + CODEX_CLI_REGISTRY, "--userconfig=" + isolation.npmrc, "--globalconfig=" + isolation.globalNpmrc, "--cache=" + isolation.cache, ]; } export function isolatedNpmTarget(args: readonly string[], isolation: NpmConfigIsolation): NpmTarget | null { const target = npmTarget(isolatedNpmArgs(args, isolation), isolation.env); if (!target) return null; return { bin: target.bin, args: target.args, options: { ...target.options, cwd: isolation.dir, env: isolation.env }, }; } /** The option fields one registry-metadata query passes to its spawn. */ export interface CodexCliUpdateSpawnOptions { readonly encoding: "utf8"; readonly timeout: number; readonly maxBuffer?: number; readonly windowsHide: true; readonly cwd?: string; readonly env?: NodeJS.ProcessEnv; readonly windowsVerbatimArguments?: boolean; } /** The fields a resolver reads off one spawn result; sync injections may carry more. */ export interface CodexCliUpdateSpawnResult { readonly status: number | null; readonly stdout: string; } /** * One registry-metadata invocation. The production runner is asynchronous so a slow * npm cannot park the proxy event loop; a synchronous SpawnSync-shaped injection * remains assignable, so tests asserting argv/env without real I/O are unchanged. */ export type CodexCliUpdateSpawn = ( bin: string, args: readonly string[], options: CodexCliUpdateSpawnOptions, ) => CodexCliUpdateSpawnResult | Promise<CodexCliUpdateSpawnResult>; /** * A single bounded registry child whose wait happens off the event loop. * * The previous spawnSync blocked the whole proxy for up to the per-query deadline: * a slow registry stalled unrelated requests and streaming for seconds at a time, * and the background apply repeated the same stall. The observable contract is * unchanged — status null on timeout or spawn failure, stdout bounded by * maxBuffer — but only the awaited caller observes the child. */ export function spawnCodexCliUpdateMetadata( bin: string, args: readonly string[], options: CodexCliUpdateSpawnOptions, ): Promise<CodexCliUpdateSpawnResult> { return new Promise(resolve => { let timedOut = false; let deadline: ReturnType<typeof setTimeout> | undefined; let child: ReturnType<typeof execFile>; try { // execFile's callback is the only terminal observation: it runs after the // child terminated and its piped stdio was fully consumed, so this result — // and the caller's isolation cleanup in its finally — never outrun a live // child, and no arbitrary reap window can fake completion. encoding "utf8" // decodes the buffered output once, so a multibyte character split across // OS pipe chunks stays intact, while maxBuffer bounds both captured // streams in bytes exactly like spawnSync did. This proves only the // child's own termination; any descendants it left behind are outside the // observation, as they were under spawnSync. child = execFile(bin, [...args], { encoding: "utf8", timeout: options.timeout, maxBuffer: options.maxBuffer ?? 1024 * 1024, killSignal: "SIGKILL", windowsHide: true, cwd: options.cwd, env: options.env, windowsVerbatimArguments: options.windowsVerbatimArguments ?? false, }, (error: ExecFileException | null, stdout: string) => { if (deadline) clearTimeout(deadline); // spawnSync reported status null whenever the child was signal-killed // (timeout or maxBuffer) or never spawned; a numeric error.code is the // plain exit code. timedOut is latched so a late code-0 close after the // deadline still refuses, matching the synchronous timeout lane. const status = timedOut ? null : error === null ? 0 : typeof error.code === "number" ? error.code : null; resolve(Object.freeze({ status, stdout })); }); } catch { resolve(Object.freeze({ status: null, stdout: "" })); return; } // A deadline of our own keeps the same per-query bound even on a runtime // that does not honor execFile's timeout option. It only latches the // refusal and signals the child; resolution still waits for the callback. deadline = setTimeout(() => { timedOut = true; try { child.kill("SIGKILL"); } catch { /* the close event still settles */ } }, options.timeout); }); } /** * Resolve the channel to one exact version plus its sha512 integrity token. * * OpenCodex's own updater treats a failed integrity query as `skipped` and proceeds * best-effort. That is a defensible trade for the package we publish ourselves; it is not * acceptable for a foreign package we are about to install on the operator's behalf, so * every failure lane here is a refusal. */ export async function resolveCodexCliUpdateTarget( channel: CodexCliUpdateChannel, spawn: CodexCliUpdateSpawn = spawnCodexCliUpdateMetadata, /** Proof-bound pre-dotenv PATH/PATHEXT and proxy/CA env; absent settings stay absent. */ boundEnv?: NodeJS.ProcessEnv, ): Promise<CodexCliUpdateTarget> { // The pinned registry and the isolation directory together are the boundary: the // version, the integrity token and the tarball URL all come from npmjs or the // target is unresolved — a redirected answer can never be the evidence. let isolation: NpmConfigIsolation; try { isolation = createNpmConfigIsolation(undefined, boundEnv); } catch { // Setup failures are a refusal lane like every other resolve failure, not an // exception escaping the dry-run. return Object.freeze({ kind: "unresolved" as const, reason: "npm configuration isolation setup failed" }); } try { const runView = async (field: string, spec: string): Promise<CodexCliUpdateSpawnResult | null> => { const target = isolatedNpmTarget(["view", spec, field], isolation); if (!target) return null; return spawn(target.bin, target.args, { encoding: "utf8", timeout: REGISTRY_TIMEOUT_MS, windowsHide: true, ...target.options, }); }; const versionRun = await runView("version", `${CODEX_CLI_PACKAGE}@${channel}`); if (!versionRun) return Object.freeze({ kind: "unresolved" as const, reason: "npm executable was not found on a trusted PATH entry" }); // status === null covers a timeout as well as a spawn failure. if (versionRun.status !== 0) { return Object.freeze({ kind: "unresolved" as const, reason: `registry version query failed (status ${versionRun.status ?? "timeout"})` }); } const version = (versionRun.stdout ?? "").trim(); if (!parseStrictSemver(version)) { return Object.freeze({ kind: "unresolved" as const, reason: "registry returned no exact version" }); } const integrityRun = await runView("dist.integrity", `${CODEX_CLI_PACKAGE}@${version}`); if (!integrityRun) return Object.freeze({ kind: "unresolved" as const, reason: "npm executable was not found on a trusted PATH entry" }); if (integrityRun.status !== 0) { return Object.freeze({ kind: "unresolved" as const, reason: `registry integrity query failed (status ${integrityRun.status ?? "timeout"})` }); } // `dist.integrity` may arrive quoted or as a space-separated multi-hash list. const tokens = (integrityRun.stdout ?? "").replace(/["']/g, "").trim().split(/\s+/).filter(Boolean); const integrity = tokens.find(isSha512Integrity); if (!integrity) { return Object.freeze({ kind: "unresolved" as const, reason: "registry returned no sha512 integrity token" }); } // The digest binds the tarball's CONTENT; this binds its ORIGIN. A registry // answer whose tarball lives outside the pinned registry is not the artifact // the plan approved, even if its sha512 matched. const tarballRun = await runView("dist.tarball", `${CODEX_CLI_PACKAGE}@${version}`); if (!tarballRun) return Object.freeze({ kind: "unresolved" as const, reason: "npm executable was not found on a trusted PATH entry" }); if (tarballRun.status !== 0) { return Object.freeze({ kind: "unresolved" as const, reason: `registry tarball query failed (status ${tarballRun.status ?? "timeout"})` }); } const tarball = (tarballRun.stdout ?? "").replace(/["']/g, "").trim(); let tarballOrigin: string | null = null; try { tarballOrigin = new URL(tarball).origin; } catch { tarballOrigin = null; } if (tarballOrigin !== CODEX_CLI_REGISTRY) { return Object.freeze({ kind: "unresolved" as const, reason: "registry returned a tarball outside the official registry origin" }); } return Object.freeze({ kind: "resolved" as const, version, integrity }); } finally { // Cleanup is best-effort; a locked residue must not replace the plan result. try { rmSync(isolation.dir, { recursive: true, force: true }); } catch { /* the owned temporary root may remain, as documented */ } } } /** Resolve both exact archives, including the publisher's platform-package alias. */ export async function resolveCodexCliUpdateArtifactTarget(channel: CodexCliUpdateChannel, spawn: CodexCliUpdateSpawn = spawnCodexCliUpdateMetadata, boundEnv?: NodeJS.ProcessEnv, platform: NodeJS.Platform = process.platform, arch: string = process.arch, windowsToolchain?: { readonly node: string; readonly npmCli: string }): Promise<CodexCliUpdateTarget> { let isolation: NpmConfigIsolation | undefined; try { isolation = createNpmConfigIsolation(undefined, boundEnv); const query = async (spec: string) => { const args = isolatedNpmArgs(["view", spec, "--json"], isolation!); const invocation = windowsToolchain ? { bin: windowsToolchain.node, args: windowsNpmExecutionArgs(windowsToolchain.npmCli, args), options: { cwd: isolation!.dir, env: isolation!.env } } : isolatedNpmTarget(["view", spec, "--json"], isolation!); if (!invocation) throw new Error("npm unavailable"); const result = await spawn(invocation.bin, invocation.args, { encoding: "utf8", timeout: REGISTRY_TIMEOUT_MS, maxBuffer: 1024 * 1024, windowsHide: true, ...invocation.options }); if (result.status !== 0) throw new Error("registry query failed"); return JSON.parse(result.stdout); }; const latest = await query(`${CODEX_CLI_PACKAGE}@${channel}`); if (!parseStrictSemver(latest.version)) throw new Error("target version unavailable"); const pinned = await query(`${CODEX_CLI_PACKAGE}@${latest.version}`); if (pinned.version !== latest.version) throw new Error("target version drift"); const artifacts = await codexCliArtifactSetAsync(pinned, query, platform, arch); return Object.freeze({ kind: "resolved", version: artifacts.main.version, integrity: artifacts.main.integrity, artifacts }); } catch { return Object.freeze({ kind: "unresolved", reason: "main/platform artifact metadata unverified" }); } finally { if (isolation) { try { rmSync(isolation.dir, { recursive: true }); } catch { /* owned metadata residue */ } } } } function refusedPlan( refusal: CodexCliUpdateRefusal, report: CodexCliInstallReport, channel: CodexCliUpdateChannel, target: CodexCliUpdateTarget | null, session: CodexCliUpdateSession, ): CodexCliUpdatePlan { return Object.freeze({ schemaVersion: CODEX_CLI_UPDATE_SCHEMA_VERSION, package: CODEX_CLI_PACKAGE, channel, applicable: false, refusal, planId: null, provenance: report.provenance, managed: report.managed, installedVersion: report.packageVersion, versionEvidence: report.versionEvidence.kind, location: report.location, targetVersion: target?.kind === "resolved" ? target.version : null, targetIntegrity: target?.kind === "resolved" ? target.integrity : null, session, installContentDigest: report.installContentDigest, command: null, }); } const NOT_EVALUATED: CodexCliUpdateSession = Object.freeze({ state: "not-evaluated" as const, matches: null }); /** * Build the dry-run plan. Installs nothing and mutates no application state; * registry evidence is gathered under a temporary isolated npm root whose cache, * logs, npmrc and cwd are all inside it and removed best-effort afterwards. * * The refusal order is deliberate. Ownership and target questions are settled before the * process table is read, so a machine that can never be updated by this workflow does not * pay for an enumeration, and the reported refusal is the decisive one rather than * whichever check happened to run first. */ export async function createCodexCliUpdatePlan(deps: CodexCliUpdatePlanDeps = {}): Promise<CodexCliUpdatePlan> { const channel: CodexCliUpdateChannel = deps.channel ?? "latest"; const platform = deps.platform ?? process.platform; const inspect = deps.inspect ?? inspectCodexCliInstall; // The planId binds the observed file set, so the plan is the one caller that // pays the bounded content read; a bare ownership check leaves it unobserved. const report = await inspect({ ...(deps.inspectionDeps ?? {}), observeInstallContent: true }); // Windows planning requires private evidence from the production handle-bound // predicate. A synthetic/copyable public managed flag cannot open this lane. const windowsEvidence = windowsCodexCliPlanEvidence(report); if ((platform === "win32" && !windowsEvidence) || report.reason === "windows_inspection_deferred") { return refusedPlan("windows_inspection_deferred", report, channel, null, NOT_EVALUATED); } if (!report.managed || report.provenance !== "npm-global") { return refusedPlan("not_managed", report, channel, null, NOT_EVALUATED); } // An advisory runtime string is what a candidate binary said about itself. Only // package-manifest evidence states what is installed on disk, and only that can be // compared with a registry version or read back after an install. const installedVersion = report.versionEvidence.kind === "package-manifest" ? report.packageVersion : null; const installedSemver = installedVersion ? parseStrictSemver(installedVersion) : null; if (!installedVersion || !installedSemver) { return refusedPlan("installed_version_unverified", report, channel, null, NOT_EVALUATED); } // A managed install whose observed content could not be bound produces no // usable plan id — spending a registry query on it can only widen the claim. if (!report.installContentDigest) { return refusedPlan("install_content_unverified", report, channel, null, NOT_EVALUATED); } // The npm evidence channels are bound to the same environment snapshot the // ownership inspection ran against: PATH/PATHEXT and proxy/CA from the proof-bound // pre-dotenv launcher context, never ambient executable or transport overrides. // When the caller had no trusted snapshot, inspectionDeps.env is the fail-closed // { PATH: "" } form, so this resolution cannot silently fall back to ambient. const resolveTarget = deps.resolveTarget ?? (ch => resolveCodexCliUpdateArtifactTarget(ch, deps.spawnProcess ?? spawnCodexCliUpdateMetadata, deps.inspectionDeps?.env, platform, windowsEvidence?.arch ?? deps.inspectionDeps?.arch ?? process.arch, windowsEvidence ?? undefined)); const target = windowsEvidence ? await withWindowsCodexCliPlanToolchain(report, () => resolveTarget(channel)) ?? Object.freeze({ kind: "unresolved" as const, reason: "Windows toolchain identity changed" }) : await resolveTarget(channel); if (target.kind !== "resolved") { return refusedPlan("target_unresolved", report, channel, target, NOT_EVALUATED); } // Raw equality is not the gate: a resolved target must advance the installed // version by semver precedence. Equal versions are already current and lower // ones are refused rather than applied as a silent downgrade. const targetSemver = parseStrictSemver(target.version); if (!targetSemver) { return refusedPlan("target_unresolved", report, channel, target, NOT_EVALUATED); } const versionOrder = compareStrictSemver(targetSemver, installedSemver); if (versionOrder === 0) { return refusedPlan("already_current", report, channel, target, NOT_EVALUATED); } if (versionOrder < 0) { return refusedPlan("target_not_newer", report, channel, target, NOT_EVALUATED); } // The request-path scan keeps registry and process-table waits off the event loop; // a synchronous injection remains honored for tests that never spawn a real child. const scan = deps.scanProcessesAsync ? await deps.scanProcessesAsync(deps.processIo ?? {}) : deps.scanProcesses ? deps.scanProcesses(deps.processIo ?? {}) : await scanCodexSessionProcessesAsync(deps.processIo ?? {}); if (scan.kind !== "observed") { // An unreadable process table is not "no sessions". `listCodexAppServerProcesses` // maps that failure to an empty list because its kill contract must never signal a // process it could not verify; the update contract has to defer instead. return refusedPlan("blocked_process_state_unknown", report, channel, target, Object.freeze({ state: "unknown" as const, matches: null })); } const matches = scan.processes.length; if (matches > 0) { return refusedPlan("blocked_active_session", report, channel, target, Object.freeze({ state: "active" as const, matches })); } const applicable = platform !== "win32" || (!!windowsEvidence && windowsEvidence.arch === "x64" && target.artifacts?.platform === "win32" && target.artifacts.arch === "x64" && process.platform === "win32" && process.arch === "x64" && windowsInstallNamespaceSupported(windowsEvidence.prefix) && await windowsCliApplyPrefixSupported(windowsEvidence.prefix)); return Object.freeze({ schemaVersion: CODEX_CLI_UPDATE_SCHEMA_VERSION, package: CODEX_CLI_PACKAGE, channel, applicable, refusal: applicable ? null : "windows_apply_disabled", planId: codexCliUpdatePlanId({ platform, provenance: report.provenance, installedVersion, installDigest: report.installDigest, installContentDigest: report.installContentDigest, channel, targetVersion: target.version, targetIntegrity: target.integrity, targetArtifactsDigest: target.artifacts ? codexCliArtifactSetDigest(target.artifacts) : undefined, toolchainDigest: windowsCodexCliToolchainDigest(report), }), provenance: report.provenance, managed: report.managed, installedVersion, versionEvidence: report.versionEvidence.kind, location: report.location, targetVersion: target.version, targetIntegrity: target.integrity, ...(target.artifacts ? { targetArtifacts: target.artifacts } : {}), session: Object.freeze({ state: "none" as const, matches: 0 }), installContentDigest: report.installContentDigest, command: codexCliUpdateCommand(target.version), }); }