@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,337 lines • 56.6 kB
text/typescript
import { createHash } from "node:crypto";
import {
closeSync,
constants as fsConstants,
existsSync,
fstatSync,
lstatSync,
openSync,
readSync,
realpathSync,
statSync,
type BigIntStats,
} from "node:fs";
import { sameFileIdentity, statTimeMs } from "../lib/file-identity";
import { posix, win32 } from "node:path";
import { getConfigDir } from "../config";
import { parseStrictSemver } from "../lib/strict-semver";
import { CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS } from "../update/codex-cli-update-launch-policy.mjs";
import { MAX_NATIVE_BACKING_BYTES } from "./cli-installation-limits";
export { MAX_NATIVE_BACKING_BYTES } from "./cli-installation-limits";
import { isSpawnableCodexCandidate } from "./exec-invocation";
import {
codexRuntimeStatePath,
parsePersistedCodexRuntime,
resolveCodexRuntime,
type ResolveCodexRuntimeDeps,
type ResolveCodexRuntimeResult,
} from "./runtime";
import {
inspectCodexShimBackingForCommand,
isLocalAbsoluteInspectionPath,
isVersionManagerOwnedCodexPath,
type CodexShimBackingForCommand,
} from "./shim";
const CODEX_PACKAGE = "@openai/codex";
const MAX_MANIFEST_BYTES = 256 * 1024;
const MAX_RUNTIME_STATE_BYTES = 256 * 1024;
const MAX_MANIFEST_ANCESTORS = 12;
/** The published package entrypoint is a few KB; 1 MiB leaves wide headroom. */
const MAX_PACKAGE_ENTRYPOINT_BYTES = 1024 * 1024;
const HELD_READ_CHUNK_BYTES = 1024 * 1024;
export type CodexCliInstallKind =
| "npm-global"
| "app-bundle"
| "version-manager"
| "standalone-unverified"
| "unknown";
export type CodexCliInstallReason =
| "candidate_unavailable"
| "candidate_path_unavailable"
| "candidate_path_unsafe"
| "windows_inspection_deferred"
| "shim_state_unknown"
| "shim_update_deferred"
| "app_bundle"
| "version_manager_owned"
| "npm_global_unverified"
| "managed_npm_global"
| "selection_unattested"
| "version_mismatch"
| "unverified_standalone"
| "inspection_failed";
export type CodexCliCandidateSource = "environment" | "persisted";
export type CodexCliInstallEvidence =
| "canonical_path"
| "app_bundle_path"
| "version_manager_path"
| "package_manifest"
| "package_manifest_digest"
| "install_content_digest"
| "shim_backing"
| "global_npm_layout";
export interface ReadOnlyCodexRuntimeCandidate {
readonly command: string;
readonly version: string | null;
readonly evidence: CodexCliCandidateSource;
}
export interface CodexCliInstallReport {
readonly schemaVersion: 1;
readonly candidateAvailable: boolean;
readonly candidateVersion: string | null;
readonly candidateSource: CodexCliCandidateSource | null;
readonly selectionAttested: boolean;
readonly versionEvidence: Readonly<{
kind: "package-manifest" | "advisory-runtime" | "unavailable";
}>;
readonly provenance: CodexCliInstallKind;
readonly managed: boolean;
readonly reason: CodexCliInstallReason;
readonly location: string | null;
/**
* sha256 digest of the canonical package manifest root when one was observed,
* otherwise null. Digest-only so the public report still carries no path; plan
* identity binds this value so two different install roots cannot share a plan.
*/
readonly installDigest: string | null;
/**
* sha256 digest over the bounded content observation of the versioned file
* set the supported npm-global layout defines: the package manifest, its
* declared bin/codex.js entrypoint, and the platform backing package manifest
* plus vendored binary at the locations the layout's modeled Node lookup
* produces. This binds the bytes that were actually read under a
* held-identity window; it is not an execution guarantee. It does not prove
* which bytes a launcher run would execute, that the files are authentic
* upstream artifacts, or that the rest of the install tree is unchanged — a
* later apply phase must re-observe under its own held handles rather than
* treating this plan-time digest as durable proof. Null when the caller did
* not request the observation or when the required set could not be bound.
*/
readonly installContentDigest: string | null;
readonly packageVersion: string | null;
readonly shim: Readonly<{
status: "not-tracked" | "matched" | "unknown";
backingKind: "backup" | "real" | null;
}>;
readonly evidence: readonly CodexCliInstallEvidence[];
}
/** Process-local evidence; deliberately absent from the public/redacted report. */
export interface CodexCliMutationEvidence {
readonly prefix: string;
readonly launcher: string;
readonly canonicalLauncher: string;
readonly packageRoot: string;
readonly backingRoot: string | null;
}
const mutationEvidence = new WeakMap<CodexCliInstallReport, CodexCliMutationEvidence>();
export function codexCliMutationEvidence(report: CodexCliInstallReport): CodexCliMutationEvidence | null {
return mutationEvidence.get(report) ?? null;
}
/** Final synchronous selector/link observation after a potentially long full-file readback. */
export function codexCliMutationSelectionMatches(evidence: CodexCliMutationEvidence, deps: CodexCliInstallProvenanceDeps): boolean {
const selected = observeCodexCliSelectedCommand(deps);
const path = selected ? resolveCandidateCommandPath(selected, deps) : null;
return !!path && canonicalize(path, deps) === evidence.canonicalLauncher
&& canonicalize(evidence.launcher, deps) === evidence.canonicalLauncher;
}
export interface CodexCliInstallProvenanceDeps {
readonly env?: NodeJS.ProcessEnv;
readonly platform?: NodeJS.Platform;
readonly configDir?: string;
readonly exists?: (path: string) => boolean;
readonly lstat?: typeof lstatSync;
readonly stat?: typeof statSync;
readonly readFile?: (path: string) => Buffer;
readonly boundedFileReadMode?: "native-hardened" | "injected-test";
readonly realpath?: (path: string) => string;
/**
* The architecture the launcher would report for its own interpreter. The
* published entrypoint picks its native backing by (platform, arch); the
* value is recorded inside the content digest so a different launcher
* architecture can never silently share a plan.
*/
readonly arch?: NodeJS.Architecture;
/**
* Opt-in switch for the bounded install-content observation. Reading the
* required file set can stream a vendored binary of up to
* MAX_NATIVE_BACKING_BYTES, so a caller that only needs the ownership
* classification leaves this unset and receives a null installContentDigest;
* the update-plan path sets it because its planId binds the digest.
*/
readonly observeInstallContent?: boolean;
readonly inspectShim?: (
command: string,
platform: NodeJS.Platform,
configDir: string,
) => CodexShimBackingForCommand;
/**
* Caller assertion that `env.CODEX_CLI_PATH` is the runtime the launcher actually
* selected, not merely a configured name. Only a proof-bound caller may set this;
* a persisted selection and an arbitrary environment stay unattested.
*/
readonly selectionAttested?: boolean;
/**
* The command the runtime resolver actually selected under the same evidence.
* Attestation additionally requires its canonical path to match the inspected
* candidate, so a snapshot candidate the resolver would have rejected cannot
* turn a different installation managed.
*/
readonly selectedCommand?: string | null;
}
interface PackageManifestEvidence {
readonly path: string;
readonly root: string;
readonly binPath: string;
readonly version: string;
readonly digest: string;
}
function sha256(domain: string, value: string | Uint8Array): string {
return createHash("sha256")
.update(domain, "utf8")
.update("\0", "utf8")
.update(value)
.digest("hex");
}
function validatedVersion(value: string | null | undefined): string | null {
if (typeof value !== "string" || value !== value.trim()) return null;
return parseStrictSemver(value, 96)?.raw ?? null;
}
function publicExecutableLocation(path: string, platform: NodeJS.Platform): string {
const raw = pathTools(platform).basename(path).toLowerCase();
const safe = ["codex", "codex.exe", "codex.cmd", "codex.bat", "codex.com", "codex.js"].includes(raw)
? raw : "codex";
return `<path>/${safe}`;
}
function freezeReport(report: CodexCliInstallReport): CodexCliInstallReport {
Object.freeze(report.shim);
Object.freeze(report.evidence);
return Object.freeze(report);
}
function unknownReport(
reason: CodexCliInstallReason,
candidate?: ReadOnlyCodexRuntimeCandidate,
extra: Partial<Pick<CodexCliInstallReport, "location">> = {},
): CodexCliInstallReport {
return freezeReport({
schemaVersion: 1,
candidateAvailable: Boolean(candidate),
candidateVersion: candidate?.version ?? null,
candidateSource: candidate?.evidence ?? null,
selectionAttested: false,
versionEvidence: Object.freeze({
kind: candidate?.version ? "advisory-runtime" as const : "unavailable" as const,
}),
provenance: "unknown",
managed: false,
reason,
location: extra.location ?? null,
installDigest: null,
installContentDigest: null,
packageVersion: null,
shim: Object.freeze({ status: "not-tracked", backingKind: null }),
evidence: Object.freeze([]),
});
}
function unknownWindowsReport(
reason: CodexCliInstallReason,
candidate?: ReadOnlyCodexRuntimeCandidate,
extra: Partial<Pick<CodexCliInstallReport, "location">> = {},
): CodexCliInstallReport {
return freezeReport({
...unknownReport(reason, candidate, extra),
shim: Object.freeze({ status: "unknown", backingKind: null }),
});
}
function readPersistedCandidate(
deps: CodexCliInstallProvenanceDeps,
): ReadOnlyCodexRuntimeCandidate | null {
// A pathname-only Windows read cannot prove that a writable ancestor stayed
// local and non-reparse between validation and open. PR1 therefore accepts
// only the proof-captured environment candidate on Windows; persisted-state
// inspection requires the later handle-bound Windows provenance layer.
if ((deps.platform ?? process.platform) === "win32") return null;
const configDir = deps.configDir ?? getConfigDir();
if (!isSafeLocalInspectionPath(configDir, deps)) return null;
try {
const statePath = codexRuntimeStatePath(configDir);
const bytes = readBoundedFile(statePath, MAX_RUNTIME_STATE_BYTES, deps);
if (!bytes) return null;
const parsed = parsePersistedCodexRuntime(
bytes,
);
if (!parsed) return null;
return {
command: parsed.command,
version: validatedVersion(parsed.selectedVersion),
evidence: "persisted",
};
} catch {
return null;
}
}
/**
* Observe configured candidate evidence without launching Codex, creating a
* probe home, or persisting a replacement selection.
*/
export function observeCodexRuntimeCandidateReadOnly(
deps: CodexCliInstallProvenanceDeps = {},
): ReadOnlyCodexRuntimeCandidate | null {
const env = deps.env ?? process.env;
const configured = env.CODEX_CLI_PATH?.trim();
if (configured) {
return {
command: configured,
version: null,
evidence: "environment",
};
}
return readPersistedCandidate(deps);
}
function pathTools(platform: NodeJS.Platform): typeof posix | typeof win32 {
return platform === "win32" ? win32 : posix;
}
function isWindowsPlatform(platform: NodeJS.Platform): boolean {
return platform === "win32";
}
function isSafeLocalInspectionPath(
path: string,
deps: CodexCliInstallProvenanceDeps,
): boolean {
const platform = deps.platform ?? process.platform;
return isLocalAbsoluteInspectionPath(path, platform);
}
function caseInsensitiveEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {
const entry = Object.entries(env).find(([key]) => key.toLowerCase() === name.toLowerCase());
return entry?.[1];
}
function resolveCandidateCommandPath(
command: string,
deps: CodexCliInstallProvenanceDeps,
): string | null {
const platform = deps.platform ?? process.platform;
// Windows inspection returns before this resolver until the next slice can
// bind command resolution and wrapper reads to stable filesystem handles.
if (isWindowsPlatform(platform)) return null;
const exists = deps.exists ?? existsSync;
const lstat = deps.lstat ?? lstatSync;
const stat = deps.stat ?? statSync;
const usable = (path: string): boolean => {
if (!isSafeLocalInspectionPath(path, deps)) return false;
try {
const entry = lstat(path);
if (!exists(path) || (!entry.isFile() && !entry.isSymbolicLink()) || !isSpawnableCodexCandidate(path, platform)) return false;
if (platform !== "win32") {
const target = stat(path);
if (!target.isFile() || (target.mode & 0o111) === 0) return false;
}
return true;
} catch {
return false;
}
};
const env = deps.env ?? process.env;
const tools = pathTools(platform);
const explicit = tools.isAbsolute(command) || command.includes("/") || command.includes("\\");
if (explicit) return usable(command) ? command : null;
const pathValue = env.PATH ?? "";
const names = [command];
for (const entry of pathValue.split(tools.delimiter)) {
// Empty and relative entries name the current working directory. Either can
// shadow a later absolute hit and therefore makes the candidate path unknown.
if (!entry || !isSafeLocalInspectionPath(entry, deps)) return null;
for (const name of names) {
const candidate = tools.join(entry, name);
if (usable(candidate)) return candidate;
}
}
return null;
}
/** Resolve selection under inspection's bounded, local-only filesystem policy. */
export function observeCodexCliSelectedCommand(
deps: CodexCliInstallProvenanceDeps,
resolve: (deps: ResolveCodexRuntimeDeps) => ResolveCodexRuntimeResult = resolveCodexRuntime,
): string | null {
const platform = deps.platform ?? process.platform;
// Even the general resolver's existence checks can touch a remote Windows
// candidate. Deferred inspection must return before invoking it at all.
if (platform === "win32") return null;
const configDir = deps.configDir ?? getConfigDir();
if (!isSafeLocalInspectionPath(configDir, deps)) return null;
try {
return resolve({
platform,
env: deps.env,
configDir,
discoverAlternatives: false,
probeVersion: false,
// Runtime and shim state must use the same no-follow, nonblocking,
// size-bounded descriptor reads as provenance, including before selection.
readFileSync: path => {
const bytes = readBoundedFile(path, MAX_RUNTIME_STATE_BYTES, deps);
if (!bytes) throw new Error("inspection_state_unavailable");
return bytes.toString("utf8");
},
existsSync: path => resolveCandidateCommandPath(path, deps) !== null,
}).runtime.command ?? null;
} catch {
return null;
}
}
function canonicalize(path: string, deps: CodexCliInstallProvenanceDeps): string | null {
if (!isSafeLocalInspectionPath(path, deps)) return null;
try {
const canonical = (deps.realpath ?? realpathSync.native)(path);
return isSafeLocalInspectionPath(canonical, deps) ? canonical : null;
} catch {
return null;
}
}
function normalizePath(path: string, platform: NodeJS.Platform): string {
const slashNormalized = platform === "win32" ? path.replace(/\\/g, "/") : path;
const normalized = platform !== "win32" && /^\/+$/u.test(slashNormalized)
? "/"
: slashNormalized.replace(/\/+$/, "");
return platform === "win32" ? normalized.toLowerCase() : normalized;
}
function samePath(left: string, right: string, platform: NodeJS.Platform): boolean {
return normalizePath(left, platform) === normalizePath(right, platform);
}
export function isAppBundledCodexPath(path: string, platform: NodeJS.Platform): boolean {
const normalized = normalizePath(path, platform);
if (platform === "win32") {
return normalized.includes("/windowsapps/")
|| normalized.includes("/microsoft/windowsapps/")
|| normalized.includes("/openai/codex/bin/")
|| normalized.includes("/packages/openai.codex_");
}
if (platform === "darwin") return /[.]app\/contents\//i.test(normalized);
return normalized.startsWith("/snap/") || normalized.includes("/flatpak/app/");
}
/** Updater ownership is intentionally broader than shim-repair refusal. */
export function isCodexCliUpdateVersionManagerPath(
path: string,
platform: NodeJS.Platform = process.platform,
): boolean {
const normalized = (platform === "win32"
? win32.normalize(path).replace(/\\/g, "/")
: posix.normalize(path)).toLowerCase();
if (isVersionManagerOwnedCodexPath(normalized, platform)) return true;
return normalized.includes("/.nvm/")
|| normalized.includes("/nvm/versions/")
|| /\/nvm\/v?\d+(?:[.]\d+){1,2}(?:\/|$)/.test(normalized)
|| normalized.includes("/.proto/")
|| normalized.includes("/proto/tools/")
|| normalized.includes("/.nodenv/")
|| normalized.includes("/nodenv/versions/")
|| normalized.includes("/.nvs/")
|| normalized.includes("/nvs/node/")
|| normalized.includes("/.fnm/")
|| normalized.includes("/fnm/node-versions/")
|| normalized.includes("/fnm_multishells/")
|| (platform === "win32" && (
normalized.includes("/scoop/apps/")
|| normalized.includes("/scoop/shims/")
));
}
function configuredVersionManagerRoots(
env: NodeJS.ProcessEnv,
platform: NodeJS.Platform,
deps: CodexCliInstallProvenanceDeps,
): readonly string[] {
const roots: string[] = [];
for (const name of CODEX_CLI_VERSION_MANAGER_ROOT_ENV_SLOTS) {
const raw = platform === "win32" ? caseInsensitiveEnv(env, name) : env[name];
if (!raw) continue;
// Preserve Windows root spellings for lexical exclusions; the managed-plan
// layer refuses roots that cannot be verified as canonical through handles.
if (platform === "win32") {
roots.push(normalizePath(win32.normalize(raw), platform));
continue;
}
if (!isLocalAbsoluteInspectionPath(raw, platform)) continue;
const canonical = isSafeLocalInspectionPath(raw, deps) ? canonicalize(raw, deps) : null;
if (canonical) roots.push(normalizePath(canonical, platform));
}
return Object.freeze([...new Set(roots)]);
}
function isWithinConfiguredVersionManagerRoot(path: string, roots: readonly string[], platform: NodeJS.Platform): boolean {
const candidate = normalizePath(path, platform);
return roots.some(root => {
const filesystemRoot = root === "/" || (platform === "win32" && /^[a-z]:$/i.test(root));
return candidate === root || (!filesystemRoot && candidate.startsWith(`${root}/`));
});
}
function readBoundedFile(
path: string,
maxBytes: number,
deps: CodexCliInstallProvenanceDeps,
): Buffer | null {
if (!isSafeLocalInspectionPath(path, deps)) return null;
// Production inspection accepts only a direct regular file. This prevents a
// persisted-state or manifest symlink from silently redirecting a nominally
// local check. Virtual filesystem tests may omit lstat and retain their
// injected stat/read behavior.
const inspectLexical = deps.lstat
?? (deps.stat === undefined && deps.readFile === undefined ? lstatSync : null);
let lexicalBefore: BigIntStats | null = null;
if (inspectLexical) {
try {
lexicalBefore = inspectLexical(path, { bigint: true });
if (lexicalBefore.isSymbolicLink() || !lexicalBefore.isFile()) return null;
} catch {
return null;
}
}
const useInjectedReader = deps.boundedFileReadMode === "injected-test";
if (!useInjectedReader) {
let fd: number | null = null;
try {
const flags = process.platform === "win32"
? fsConstants.O_RDONLY
: fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK;
fd = openSync(path, flags);
const before = fstatSync(fd, { bigint: true });
if (!before.isFile() || before.size > maxBytes) return null;
const bytes = Buffer.allocUnsafe(Number(before.size));
let offset = 0;
while (offset < bytes.length) {
const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
if (count <= 0) return null;
offset += count;
}
const extra = Buffer.allocUnsafe(1);
if (readSync(fd, extra, 0, 1, offset) !== 0) return null;
const after = fstatSync(fd, { bigint: true });
const lexicalAfter = inspectLexical ? inspectLexical(path, { bigint: true }) : null;
if (lexicalAfter?.isSymbolicLink()) return null;
if (!sameFileIdentity(before, after) || before.size !== after.size
|| statTimeMs(before.mtimeNs) !== statTimeMs(after.mtimeNs) || statTimeMs(before.ctimeNs) !== statTimeMs(after.ctimeNs)
|| (lexicalBefore !== null && (lexicalAfter === null || lexicalAfter.isSymbolicLink()
|| !sameFileIdentity(lexicalBefore, before)
|| !sameFileIdentity(lexicalAfter, after)
|| lexicalAfter.size !== after.size || statTimeMs(lexicalAfter.mtimeNs) !== statTimeMs(after.mtimeNs)
|| statTimeMs(lexicalAfter.ctimeNs) !== statTimeMs(after.ctimeNs)))) return null;
return bytes;
} catch {
return null;
} finally {
if (fd !== null) closeSync(fd);
}
}
if (!deps.stat || !deps.readFile) return null;
const stat = deps.stat;
const read = deps.readFile;
try {
const before = stat(path, { bigint: true });
if (!before.isFile() || before.size > maxBytes) return null;
const bytes = read(path);
const after = stat(path, { bigint: true });
const lexicalAfter = inspectLexical ? inspectLexical(path, { bigint: true }) : null;
if (
BigInt(bytes.byteLength) !== before.size
|| !sameFileIdentity(before, after)
|| before.size !== after.size
|| statTimeMs(before.mtimeNs) !== statTimeMs(after.mtimeNs)
|| (lexicalBefore !== null && (lexicalAfter === null || lexicalAfter.isSymbolicLink()
|| !sameFileIdentity(lexicalBefore, before)
|| !sameFileIdentity(lexicalAfter, after)))
) return null;
return bytes;
} catch {
return null;
}
}
function manifestCandidates(
logicalPath: string,
canonicalPath: string,
platform: NodeJS.Platform,
): string[] {
const tools = pathTools(platform);
const candidates: string[] = [];
let cursor = tools.dirname(canonicalPath);
for (let depth = 0; depth < MAX_MANIFEST_ANCESTORS; depth += 1) {
candidates.push(tools.join(cursor, "package.json"));
const parent = tools.dirname(cursor);
if (parent === cursor) break;
cursor = parent;
}
const binDir = tools.dirname(logicalPath);
if (platform === "win32") {
candidates.push(tools.join(binDir, "node_modules", "@openai", "codex", "package.json"));
} else {
const prefix = tools.dirname(binDir);
candidates.push(tools.join(prefix, "lib", "node_modules", "@openai", "codex", "package.json"));
candidates.push(tools.join(prefix, "node_modules", "@openai", "codex", "package.json"));
}
return [...new Set(candidates)];
}
function manifestBinPath(bin: unknown): string | null {
const raw = typeof bin === "string"
? bin
: bin && typeof bin === "object" && !Array.isArray(bin)
? (bin as Record<string, unknown>).codex
: null;
if (typeof raw !== "string") return null;
const normalized = raw.replace(/\\/g, "/").replace(/^\.\//, "");
return normalized === "bin/codex.js" ? normalized : null;
}
function findCodexPackageManifest(
logicalPath: string,
canonicalPath: string,
deps: CodexCliInstallProvenanceDeps,
): PackageManifestEvidence | null {
const platform = deps.platform ?? process.platform;
for (const candidate of manifestCandidates(logicalPath, canonicalPath, platform)) {
const bytes = readBoundedFile(candidate, MAX_MANIFEST_BYTES, deps);
if (!bytes) continue;
try {
const value = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
const version = validatedVersion(typeof value.version === "string" ? value.version : null);
if (value.name !== CODEX_PACKAGE || !version) continue;
const binPath = manifestBinPath(value.bin);
if (!binPath) continue;
const root = canonicalize(pathTools(platform).dirname(candidate), deps);
const path = canonicalize(candidate, deps);
if (!root || !path) continue;
return {
path,
root,
binPath,
version,
digest: sha256("codex-cli-package-manifest-v1", bytes),
};
} catch {
continue;
}
}
return null;
}
function launcherIsLinkedToManifest(
canonicalOwnershipPath: string,
manifest: PackageManifestEvidence,
deps: CodexCliInstallProvenanceDeps,
): boolean {
const platform = deps.platform ?? process.platform;
const tools = pathTools(platform);
const entrypoint = canonicalize(tools.join(manifest.root, ...manifest.binPath.split("/")), deps);
if (!entrypoint) return false;
const normalizedRoot = normalizePath(manifest.root, platform);
const normalizedEntrypoint = normalizePath(entrypoint, platform);
if (!normalizedEntrypoint.startsWith(`${normalizedRoot}/`)) return false;
if (samePath(canonicalOwnershipPath, entrypoint, platform)) return true;
return false;
}
function isProvenGlobalNpmLayout(
launcherPath: string,
packageRoot: string,
platform: NodeJS.Platform,
deps: CodexCliInstallProvenanceDeps,
): boolean {
const tools = pathTools(platform);
const launcherName = tools.basename(launcherPath).toLowerCase();
if (launcherName !== (platform === "win32" ? "codex.cmd" : "codex")) return false;
const root = normalizePath(packageRoot, platform);
// Keep the POSIX launcher itself lexical because npm commonly installs it as
// a symlink into the package. Canonicalize only its parent so a symlinked or
// case-aliased npm prefix is compared against the canonical manifest root.
const launcherParent = tools.dirname(launcherPath);
const canonicalLauncherParent = platform === "win32"
? launcherParent
: canonicalize(launcherParent, deps);
if (!canonicalLauncherParent) return false;
const launcherDir = normalizePath(canonicalLauncherParent, platform);
const suffix = "/node_modules/@openai/codex";
if (!root.endsWith(suffix)) return false;
const beforeNodeModules = root.slice(0, -suffix.length);
if (platform === "win32") return launcherDir === beforeNodeModules;
if (!beforeNodeModules.endsWith("/lib")) return false;
const prefix = beforeNodeModules.slice(0, -"/lib".length);
return launcherDir === `${prefix}/bin`;
}
function shimReport(shim: CodexShimBackingForCommand): CodexCliInstallReport["shim"] {
if (shim.status === "matched") {
return Object.freeze({ status: "matched" as const, backingKind: shim.backingKind });
}
if (shim.status === "unknown") {
return Object.freeze({ status: "unknown" as const, backingKind: null });
}
return Object.freeze({ status: "not-tracked" as const, backingKind: null });
}
/**
* The published @openai/codex bin/codex.js selection table, mirrored as layout
* knowledge: the supported npm-global layout places the platform backing
* package where Node's module lookup from the package's bin directory finds
* "<package>/package.json", then "<package-dir>/vendor/<triple>/bin/codex"
* (codex.exe on Windows), with an in-package "vendor/<triple>" fallback when
* that resolve would throw. This table locates files for observation; it does
* not prove which file a launcher run would select. A launcher following a
* different rule simply produces different observed entrypoint bytes.
*/
const CODEX_PLATFORM_BACKING: Readonly<Record<string, Readonly<{ triple: string; package: string }>>> = {
"linux:x64": { triple: "x86_64-unknown-linux-musl", package: "@openai/codex-linux-x64" },
"linux:arm64": { triple: "aarch64-unknown-linux-musl", package: "@openai/codex-linux-arm64" },
"android:x64": { triple: "x86_64-unknown-linux-musl", package: "@openai/codex-linux-x64" },
"android:arm64": { triple: "aarch64-unknown-linux-musl", package: "@openai/codex-linux-arm64" },
"darwin:x64": { triple: "x86_64-apple-darwin", package: "@openai/codex-darwin-x64" },
"darwin:arm64": { triple: "aarch64-apple-darwin", package: "@openai/codex-darwin-arm64" },
"win32:x64": { triple: "x86_64-pc-windows-msvc", package: "@openai/codex-win32-x64" },
"win32:arm64": { triple: "aarch64-pc-windows-msvc", package: "@openai/codex-win32-arm64" },
};
export function codexCliPlatformBacking(platform: NodeJS.Platform, arch: string) {
return CODEX_PLATFORM_BACKING[platform + ":" + arch] ?? null;
}
/** Node's Module._nodeModulePaths: every ancestor's node_modules child, closest first. */
function nodeModuleDirs(fromDir: string, platform: NodeJS.Platform): string[] {
const tools = pathTools(platform);
const dirs: string[] = [];
let cursor = fromDir;
for (;;) {
// A directory literally named "node_modules" contributes no nested
// node_modules entry of its own in Node's lookup.
if (tools.basename(cursor) !== "node_modules") dirs.push(tools.join(cursor, "node_modules"));
const parent = tools.dirname(cursor);
if (parent === cursor) break;
cursor = parent;
}
return dirs;
}
/**
* Node's global lookup list for the launcher process: NODE_PATH entries first,
* then $HOME/.node_modules and $HOME/.node_libraries, then the lib/node directory
* beside the install prefix of the node binary the captured PATH resolves.
* 'complete' is false when any input cannot be modeled from the bound
* environment — in that case 'require.resolve threw' cannot be proven and the
* in-package vendor fallback lane stays unverifiable.
*/
function globalModuleDirs(
env: NodeJS.ProcessEnv,
platform: NodeJS.Platform,
deps: CodexCliInstallProvenanceDeps,
): { dirs: string[]; complete: boolean } {
const tools = pathTools(platform);
const dirs: string[] = [];
let complete = true;
const nodePath = platform === "win32" ? caseInsensitiveEnv(env, "NODE_PATH") : env.NODE_PATH;
if (nodePath) {
for (const entry of nodePath.split(tools.delimiter)) {
if (!entry) continue;
// Node resolves a relative NODE_PATH entry against the launcher process's
// cwd, which this read-only inspection cannot know.
if (isSafeLocalInspectionPath(entry, deps)) dirs.push(tools.resolve(entry));
else complete = false;
}
}
const home = platform === "win32"
? caseInsensitiveEnv(env, "USERPROFILE") ?? caseInsensitiveEnv(env, "HOME")
: env.HOME;
if (home && isSafeLocalInspectionPath(home, deps)) {
dirs.push(tools.join(home, ".node_modules"), tools.join(home, ".node_libraries"));
} else {
complete = false;
}
const nodeCommand = resolveCandidateCommandPath("node", deps);
const canonicalNode = nodeCommand ? canonicalize(nodeCommand, deps) : null;
if (canonicalNode) {
// POSIX node lives at <prefix>/bin/node, so the lookup prefix is two levels
// up; a Windows prefix sits beside the executable. The win32 arm is
// unreachable today — inspection returns before any candidate I/O there.
const prefix = platform === "win32"
? tools.dirname(canonicalNode)
: tools.dirname(tools.dirname(canonicalNode));
dirs.push(tools.join(prefix, "lib", "node"));
} else {
complete = false;
}
return { dirs, complete };
}
interface InstallContentFile {
readonly role: "manifest" | "entrypoint" | "backing-manifest" | "backing-binary";
readonly path: string;
readonly maxBytes: number;
}
interface ObservedContentFile {
readonly digest: string;
/** Retained only for small role files; the streamed binary keeps none. */
readonly bytes: Buffer | null;
}
function fileContentDomain(role: InstallContentFile["role"]): string {
return role === "manifest" ? "codex-cli-package-manifest-v1" : "codex-cli-observed-file-v1";
}
export function codexCliContentFileDigest(role: InstallContentFile["role"], bytes: Buffer): string {
return sha256(fileContentDomain(role), bytes);
}
export function codexCliContentSetDigest(platform: NodeJS.Platform, arch: string, triple: string,
backingKind: "optional-package" | "package-vendor", files: readonly { role: string; digest: string | undefined }[]): string {
return sha256("codex-cli-install-content-v1", JSON.stringify({ layout: "npm-global", platform, arch, triple, backingKind, files }));
}
/**
* Hash every requested file under one observation window. Native POSIX mode
* opens all files first (O_NOFOLLOW | O_NONBLOCK), streams each digest, then
* re-verifies every descriptor's identity and each canonical path's linkage
* before returning. Injected-test mode performs the equivalent stat -> read ->
* stat sequence per file plus a final identity pass over the whole set. The
* optional finalize hook runs its own checks while the held set is still open,
* so linkage and selector re-verification completes inside the window rather
* than after the descriptors close. Any read, size, identity or finalize
* failure inside the window fails the set closed.
*/
function observeHeldFileSet(
requests: readonly InstallContentFile[],
deps: CodexCliInstallProvenanceDeps,
finalize?: () => boolean,
): Map<string, ObservedContentFile> | null {
const keepBytes = (role: InstallContentFile["role"]): boolean => role !== "backing-binary";
if (deps.boundedFileReadMode === "injected-test") {
const stat = deps.stat;
const read = deps.readFile;
if (!stat || !read) return null;
const results = new Map<string, ObservedContentFile>();
const identities: { before: BigIntStats; req: InstallContentFile }[] = [];
try {
for (const req of requests) {
const before = stat(req.path, { bigint: true });
if (!before.isFile() || before.size > req.maxBytes) return null;
const bytes = read(req.path);
const after = stat(req.path, { bigint: true });
if (BigInt(bytes.byteLength) !== before.size
|| !sameFileIdentity(before, after)
|| before.size !== after.size || statTimeMs(before.mtimeNs) !== statTimeMs(after.mtimeNs)) return null;
identities.push({ before, req });
results.set(req.role, {
digest: sha256(fileContentDomain(req.role), bytes),
bytes: keepBytes(req.role) ? bytes : null,
});
}
// A replacement that slipped in after a file's own read still failed.
for (const { before, req } of identities) {
const now = stat(req.path, { bigint: true });
if (!sameFileIdentity(before, now)
|| before.size !== now.size || statTimeMs(before.mtimeNs) !== statTimeMs(now.mtimeNs)) return null;
}
if (finalize && !finalize()) return null;
return results;
} catch {
return null;
}
}
const held: { fd: number; req: InstallContentFile; before: BigIntStats }[] = [];
const openedFds: number[] = [];
try {
const flags = process.platform === "win32"
? fsConstants.O_RDONLY
: fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK;
for (const req of requests) {
if (!isSafeLocalInspectionPath(req.path, deps)) return null;
const fd = openSync(req.path, flags);
// The descriptor joins the close set before any check that can bail, so
// an fstat failure or a refused type/size cannot leak it.
openedFds.push(fd);
const before = fstatSync(fd, { bigint: true });
// O_NONBLOCK keeps a FIFO open nonblocking, so the type check must come
// first: anything that is not a regular file is refused before a read.
if (!before.isFile() || before.size > req.maxBytes) return null;
held.push({ fd, req, before });
}
const results = new Map<string, ObservedContentFile>();
for (const { fd, req, before } of held) {
const hasher = createHash("sha256")
.update(fileContentDomain(req.role), "utf8")
.update("\0", "utf8");
const size = Number(before.size);
const bytes = keepBytes(req.role) ? Buffer.allocUnsafe(size) : null;
const chunk = Buffer.allocUnsafe(Math.max(1, Math.min(HELD_READ_CHUNK_BYTES, size)));
let offset = 0;
while (offset < size) {
const count = readSync(fd, chunk, 0, Math.min(chunk.length, size - offset), offset);
if (count <= 0) return null;
hasher.update(chunk.subarray(0, count));
if (bytes) chunk.copy(bytes, offset, 0, count);
offset += count;
}
// A file that grew inside the window is a different file than was hashed.
if (readSync(fd, chunk, 0, 1, offset) !== 0) return null;
results.set(req.role, { digest: hasher.digest("hex"), bytes });
}
for (const { fd, req, before } of held) {
const after = fstatSync(fd, { bigint: true });
const lexical = lstatSync(req.path, { bigint: true });
const followed = statSync(req.path, { bigint: true });
if (!sameFileIdentity(before, after)
|| before.size !== after.size || statTimeMs(before.mtimeNs) !== statTimeMs(after.mtimeNs)
|| statTimeMs(before.ctimeNs) !== statTimeMs(after.ctimeNs)
|| lexical.isSymbolicLink() || !lexical.isFile()
|| !sameFileIdentity(lexical, before)
|| !sameFileIdentity(followed, before)) return null;
}
if (finalize && !finalize()) return null;
return results;
} catch {
return null;
} finally {
for (const fd of openedFds) {
try { closeSync(fd); } catch { /* the observation already failed */ }
}
}
}
/**
* Bind the versioned file set the supported npm-global layout defines: the
* manifest, its declared bin/codex.js entrypoint, and the platform backing
* (manifest plus vendored binary) at the locations the layout's modeled Node
* lookup produces. The bound set is deliberately small and versioned; this is
* not an execution proof, an artifact-authenticity claim, or a
* whole-tree-integrity claim.
*/
function observeInstallContent(
manifest: PackageManifestEvidence,
npmPrefix: string,
platform: NodeJS.Platform,
env: NodeJS.ProcessEnv,
deps: CodexCliInstallProvenanceDeps,
selection: { readonly lexical: string; readonly canonical: string },
observedBacking?: (root: string | null) => void,
): string | null {
const arch = deps.arch ?? process.arch;
const backing = CODEX_PLATFORM_BACKING[platform + ":" + arch];
if (!backing) return null;
const tools = pathTools(platform);
const normalizedPrefix = normalizePath(npmPrefix, platform);
// A filesystem-root prefix cannot bound anything; treat it as unsupported.
if (!normalizedPrefix || normalizedPrefix === "/") return null;
const withinPrefix = (path: string): boolean => {
const normalized = normalizePath(path, platform);
return normalized === normalizedPrefix || normalized.startsWith(normalizedPrefix + "/");
};
// Every lexical path that produced a bound canonical target — the selected
// launcher included — is re-resolved at the window's final observed boundary.
// Held descriptors do not prevent link mutation; this check observes whether
// the selection still reaches the bound files at that instant.
const links: { readonly lexical: string; readonly canonical: string }[] = [
{ lexical: selection.lexical, canonical: selection.canonical },
];
const canonicalBound = (path: string): string | null => {
const canonical = canonicalize(path, deps);
if (!canonical || !withinPrefix(canonical)) return null;
links.push({ lexical: path, canonical });
return canonical;
};
const entrypoint = canonicalBound(tools.join(manifest.root, ...manifest.binPath.split("/")));
if (!entrypoint) return null;
const globals = globalModuleDirs(env, platform, deps);
const lstat = deps.lstat ?? lstatSync;
// Probe one modeled lookup lane in order; the first hit wins.
const probeDirs = (
dirs: readonly string[],
): { kind: "none" } | { kind: "hit"; path: string; dir: string } | { kind: "refuse" } => {
for (const dir of dirs) {
const probe = tools.join(dir, ...backing.package.split("/"), "package.json");
let entry;
try {
entry = lstat(probe);
} catch (error) {
const code = (error as NodeJS.ErrnoException | null)?.code;
if (code === "ENOENT" || code === "ENOTDIR") continue;
return { kind: "refuse" };
}
if (!entry.isFile() && !entry.isSymbolicLink()) continue;
// First hit wins, matching the lookup order the layout models.
const canonical = canonicalize(probe, deps);
if (!canonical || !withinPrefix(canonical)) return { kind: "refuse" };
links.push({ lexical: probe, canonical });
return { kind: "hit", path: canonical, dir: tools.dirname(canonical) };
}
return { kind: "none" };
};
const probeBacking = (): ReturnType<typeof probeDirs> => {
const local = probeDirs(nodeModuleDirs(tools.dirname(entrypoint), platform));
if (local.kind !== "none") return local;
// Missing lookup seeds leave unknown earlier global lanes. Even an
// observed in-prefix global hit cannot prove which package wins there.
if (!globals.complete) return { kind: "refuse" };
return probeDirs(globals.dirs);
};
const selectedBacking = probeBacking();
if (selectedBacking.kind === "refuse") return null;
const backingManifestPath = selectedBacking.kind === "hit" ? selectedBacking.path : null;
const backingPackageDir = selectedBacking.kind === "hit" ? selectedBacking.dir : null;
const binName = platform === "win32" ? "codex.exe" : "codex";
const backingBinary = canonicalBound(backingPackageDir
? tools.join(backingPackageDir, "vendor", backing.triple, "bin", binName)
: tools.join(manifest.root, "vendor", backing.triple, "bin", binName));
// The launcher cannot run without the vendored binary; a missing one makes
// the required set incomplete, not merely shorter.
if (!backingBinary) return null;
const requests: InstallContentFile[] = [
{ role: "manifest", path: manifest.path, maxBytes: MAX_MANIFEST_BYTES },
{ role: "entrypoint", path: entrypoint, maxBytes: MAX_PACKAGE_ENTRYPOINT_BYTES },
...(backingManifestPath
? [{ role: "backing-manifest" as const, path: backingManifestPath, maxBytes: MAX_MANIFEST_BYTES }]
: []),
{ role: "backing-binary", path: backingBinary, maxBytes: MAX_NATIVE_BACKING_BYTES },
];
const observed = observeHeldFileSet(requests, deps, () => {
// Re-run the selector after the final file identity pass, while native
// descriptors remain open. An earlier lane gaining a package or the
// selected one disappearing makes the bound set ambiguous.
const selectedAgain = probeBacking();
if (selectedAgain.kind !== selectedBacking.kind
|| (selectedAgain.kind === "hit" && selectedBacking.kind === "hit"
&& selectedAgain.path !== selectedBacking.path)) return false;
// A canonical-path lstat cannot see a retargeted lexical selection link.
for (const link of links) {
const resolved = canonicalize(link.lexical, deps);
if (!resolved || !samePath(resolved, link.canonical, platform)) return false;
}
return true;
});
if (!observed) return null;
// The manifest was already hashed once while provenance was being decided.
// If the bytes read now differ, ownership answered a different file than the
// content claim would describe.
if (observed.get("manifest")?.digest !== manifest.digest) return null;
const backingManifest = observed.get("backing-manifest");
if (backingManifest?.bytes) {
// A backing manifest carrying an exports map can make the real
// require.resolve throw instead of returning this file; without modeling
// export conditions the resolution lane would be ambiguous, so it is refused.
try {
const value: unknown = JSON.parse(backingManifest.bytes.toString("utf8"));
if (!value || typeof value !== "object" || Array.isArray(value)) return null;
if ("exports" in value) return null;
} catch {
return null;
}
}
observedBacking?.(backingPackageDir);
return codexCliContentSetDigest(platform, arch, backing.triple,
backingManifestPath ? "optional-package" : "package-vendor",
requests.map(req => ({ role: req.role, digest: observed.get(req.role)?.digest })));
}
/** Inspect ownership of one configured Codex CLI candidate, without mutation. */
export async function inspectCodexCliInstall(
deps: CodexCliInstallProvenanceDeps = {},
): Promise<CodexCliInstallReport> {
const platform = deps.platform ?? process.platform;
const candidate = observeCodexRuntimeCandidateReadOnly(deps);
if (!candidate) {
// This slice reads no candidate or configuration file on Windows, so an
// absent proof-captured environment candidate does not establish that no
// Codex CLI exists: a persisted selection is simply never consulted there.
// Report the deferral that actually happened instead of the stronger claim
// that the candidate is unavailable. POSIX retains its existing result
// when no candidate is observed.
return isWindowsPlatform(platform)
? unknownWindowsReport("windows_inspection_deferred")
: unknownReport("candidate_unavailable");
}
const env = deps.env ?? process.env;
if (platform === "win32") {
// Lexical exclusions precede the restricted handle-bound plan predicate.
// Other Windows layouts remain observation-only; pathname prechecks alone
// cannot prove a writable ancestor stayed local and non-reparse.
const lexicalCandidatePath = win32.isAbsolute(candidate.command)
&& isLocalAbsoluteInspectionPath(candidate.command, platform)
? win32.normalize(candidate.command)
: null;
if (!lexicalCandidatePath) {
return unknownWindowsReport("candidate_path_unavailable", candidate);
}
const managerRoots = configuredVersionManagerRoots(env, platform, deps);
const appBundle = isAppBundledCodexPath(lexicalCandidatePath, platform);
const versionManager = isCodexCliUpdateVersionManagerPath(lexicalCandidatePath, platform)
|| isWithinConfiguredVersionManagerRoot(lexicalCandidatePath, managerRoots, platform);
if (appBundle || versionManager) {
return freezeReport({
schemaVersion: 1,
candidateAvailable: true,
candidateVersion: candidate.version,
candidateSource: candidate.evidence,
selectionAttested: false,
versionEvidence: Object.freeze({
kind: candidate.version ? "advisory-runtime" as const : "unavailable" as const,
}),
provenance: appBundle ? "app-bundle" : "version-manager",
managed: false,
reason: appBundle ? "app_bundle" : "version_manager_owned",
location: publicExecutableLocation(lexicalCandidatePath, platform),
installDigest: null,
installContentDigest: null,
packageVersion: null,
shim: Object.freeze({ status: "unknown", backingKind: null }),
evidence: Object.freeze([appBundle ? "app_bundle_path" : "version_manager_path"]),
});
}
const deferred = unknownWindowsReport("windows_inspection_deferred", candidate, {
location: publicExecutableLocation(lexicalCandidatePath, platform),
});
return (await import("./cli-windows-plan-provenance")).inspectWindowsCodexCliPlanInstall(deps, deferred,
path => isAppBundledCodexPath(path, platform) || isCodexCliUpdateVersionManagerPath(path, platform)
|| isWithinConfiguredVersionManagerRoot(path, managerRoots, platform), managerRoots);
}
const configDir = deps.configDir ?? getConfigDir();
if (!isSafeLocalInspectionPath(configDir, deps)) {
return unknownReport("shim_state_unknown", candidate);
}
const candidatePath = resolveCandidateCommandPath(candidate.command, deps);
if (!candidatePath) {
return unknownReport("candidate_path_unavailable", candidate);
}
const canonicalCandidatePath = canonicalize(candidatePath, deps);
if (!canonicalCandidatePath) {
return unknownReport("candidate_path_unsafe", candidate);
}
// Only a proof-bound caller may attest that the environment candidate is the
// runtime it actually selected, and only when the runtime resolver picked the
// same canonical path under the same evidence. A persisted selection records
// intent, not the resolved binary, and an arbitrary environment is ambient —
// neither can become managed here; a resolver that would choose a different
// executable cannot attest the snapshot's installation either.
const resolverPicked = deps.selectedCommand
? canonicalize(
resolveCandidateCommandPath(deps.selectedCommand, deps) ?? deps.selectedCommand,
deps,
)
: null;
const selectionAttested =
deps.selectionAttested === true
&& candidate.evidence === "environment"
&& resolverPicked !== null
&& samePath(resolverPicked, canonicalCandidatePath, platform);
const inspectShim = deps.inspectShim ?? inspectCodexShimBackingForCommand;
const shim = inspectShim(candidatePath, platform, configDir);
if (shim.status === "unknown") {
return freezeReport({
...unknownReport("shim_state_unknown", candidate, {
location: publicExecutableLocation(canonicalCandidatePath, platform),
}),
selectionAttested,
shim: shimReport(shim),
});
}
if (shim.status === "matched") {
return freezeReport({
...unknownReport("shim_update_deferred", candidate, {
location: publicExecutableLocation(canonicalCandidatePath, platform),
}),
selectionAttested,
provenance: "standalone-unverified",
shim: shimReport(shim),
evidence: Object.freeze(["canonical_path", "shim_backing"] as const),
});
}
const ownershipPath = candidatePath;
const canonicalOwnershipPath = canonicalize(ownershipPath, deps);
if (!canonicalOwnershipPath) {
return unknownReport("candidate_path_unsafe", candidate);
}
const location = publicExecutableLocation(canonicalCandidatePath, platform);
const canonicalPathSet = [canonicalCandidatePath, canonicalOwnershipPath];
if (canonicalPathSet.some(path => isAppBundledCodexPath(path, platform))) {
return freezeReport({
schemaVersion: 1,
candidateAvailable: true,
candidateVersion: candidate.version,
candidateSource: candidate.evidence,
selectionAttested,
versionEvidence: Object.freeze({
kind: candidate.version ? "advisory-runtime" as const : "unavailable" as const,
}),
provenance: "app-bundle",
managed: false,
reason: "app_bundle",
location,
installDigest: null,
installContentDigest: null,
packageVersion: null,
shim: shimReport(shim),
evidence: Object.freeze(["canonical_path", "app_bundle_path"]),
});
}
const configuredManagerRoots = configuredVersionManagerRoots(env, platform, deps);
if (canonicalPathSet.some(path => isCodexCliUpdateVersionManagerPath(path, platform)
|| isWithinConfiguredVersionManagerRoot(path, configuredManagerRoots, platform))) {
return freezeReport({
schemaVersion: 1,
candidateAvailable: true,
candidateVersion: candidate.version,
candidateSource: candidate.evidence,
selectionAttested,
versionEvidence: Object.freeze({
kind: candidate.version ? "advisory-runtime" as const : "unavailable" as const,
}),
provenance: "version-manager",
managed: false,
reason: "version_manager_owned",
location,
installDigest: null,
installContentDigest: null,
packageVersion: null,
shim: shimReport(shim),
evidence: Object.freeze(["canonical_path", "version_manager_path"]),
});
}
if (/codex[.]opencodex-real(?:[.](?:cmd|bat|exe))?$/i.test(pathTools(platform).basename(candidatePath))) {
return freezeReport({
...unknownReport("shim_state_unknown", candidate, { location }),
selectionAttested,
shim: shimReport(shim),
});
}
const manifest = findCodexPackageManifest(ownershipPath, canonicalOwnershipPath, deps);
if (manifest) {
// POSIX npm launchers are commonly symlinks into the package, so their
// lexical prefix is the ownership evidence instead.
const global = isProvenGlobalNpmLayout(
ownershipPath,
manifest.root,
platform,
deps,
);
const linked = launcherIsLinkedToManifest(
canonicalOwnershipPath,
manifest,
deps,
);
const manifestOwned = global && linked;
// The npm-global prefix bounds every content path this observation may
// follow: it is the manifest root minus the fixed package suffix. An
// install that cannot prove the layout keeps a null digest.
const npmPrefix = manifestOwned
? manifest.root.slice(0, manifest.root.length - "/lib/node_modules/@openai/codex".length)
: "";
let backingRoot: string | null = null;
const installContentDigest = manifestOwned && deps.observeInstallContent === true
// The selection's own lexical->canonical link is part of the claim:
// verified again at the end of the observation so a retargeted launcher
// cannot leave the digest bound to bytes it no longer selects.
? observeInstallContent(manifest, npmPrefix, platform, env, deps, {
lexical: ownershipPath,
canonical: canonicalOwnershipPath,
}, root => { backingRoot = root; })
: null;
const versionMatches = candidate.version === null || candidate.version === manifest.version;
const reason: CodexCliInstallReason = !global || !linked
? "npm_global_unverified"
: !versionMatches ? "version_mismatch"
: selectionAttested ? "managed_npm_global" : "selection_unattested";
const report = freezeReport({
schemaVersion: 1,
candidateAvailable: true,
candidateVersion: candidate.version,
candidateSource: candidate.evidence,
selectionAttested,
versionEvidence: Object.freeze({
// The manifest is the on-disk record of what is installed. An absent advisory
// version (the launcher snapshot carries no version) cannot contradict it,
// while a reported one that disagrees already classified as version_mismatch.
kind: manifestOwned && versionMatches
? "package-manifest" as const
: candidate.version !== null ? "advisory-runtime" as const : "unavailable" as const,
}),
provenance: manifestOwned ? "npm-global" : "standalone-unverified",
managed: manifestOwned && versionMatches && selectionAttested,
reason,
location,
// Plan identity binds this digest, not the redacted display location: two
// package roots that resolve to the same "<path>/codex" string must still
// produce different plans.
installDigest: sha256("codex-cli-install-root-v1", normalizePath(manifest.root, platform)),
installContentDigest,
packageVersion: manifest.version,
shim: shimReport(shim),
evidence: Object.freeze<CodexCliInstallEvidence[]>([
"canonical_path", "package_manifest", "package_manifest_digest",
...(manifestOwned ? ["global_npm_layout" as const] : []),
...(installContentDigest ? ["install_content_digest" as const] : []),
]),
});
if (report.managed && report.installContentDigest && shim.status === "not-tracked") {
mutationEvidence.set(report, Object.freeze({ prefix: npmPrefix, launcher: ownershipPath,
canonicalLauncher: canonicalOwnershipPath, packageRoot: manifest.root, backingRoot }));
}
return report;
}
const stat = deps.stat ?? statSync;
if (!isSafeLocalInspectionPath(canonicalOwnershipPath, deps)) {
return unknownReport("candidate_path_unsafe", candidate);
}
try {
if (!stat(canonicalOwnershipPath).isFile()) {
return unknownReport("candidate_path_unsafe", candidate);
}
} catch {
return unknownReport("inspection_failed", candidate);
}
return freezeReport({
schemaVersion: 1,
candidateAvailable: true,
candidateVersion: candidate.version,
candidateSource: candidate.evidence,
selectionAttested,
versionEvidence: Object.freeze({
kind: candidate.version ? "advisory-runtime" as const : "unavailable" as const,
}),
provenance: "standalone-unverified",
managed: false,
reason: "unverified_standalone",
location,
installDigest: null,
installContentDigest: null,
packageVersion: null,
shim: shimReport(shim),
evidence: Object.freeze(["canonical_path"]),
});
}