UNPKG

@bitkyc08/opencodex

Version:

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

291 lines (261 loc) • 14.9 kB
import { closeSync, linkSync, lstatSync, openSync, readSync, realpathSync, renameSync, unlinkSync } from "node:fs"; import { posix, sep, win32 } from "node:path"; import { SHIM_MARKER } from "./shim-templates"; import { fileErrorCode, type ShimFileState } from "./shim-state-file"; type PlatformPath = typeof win32; /** * Validation for the legacy Codex shim record (codex-shim.json without schema/mode), which * Windows installs still write. Every path a restore acts on is derived from the layout * OpenCodex itself writes: launchers with fixed names, a backup that is the * `.opencodex-real` sibling of the original, and all of them in one directory. The checks are * pure functions over an injected path flavor so every OS can test them. */ /** Path flavor of the host filesystem; independent of a test-overridden process.platform. */ export function hostShimPathApi(): PlatformPath { return sep === "\\" ? win32 : posix; } /** The backup name OpenCodex gives an original launcher: the suffix goes before the extension. */ export function legacyShimBackupPath(path: string, api: PlatformPath = hostShimPathApi()): string { const ext = api.extname(path); return ext ? `${path.slice(0, -ext.length)}.opencodex-real${ext}` : `${path}.opencodex-real`; } /** In-place wrappers: the launcher npm writes is replaced by the shim at the same path. */ const IN_PLACE_LAUNCHERS = new Set(["codex.cmd", "codex.ps1", "codex"]); /** The earliest Windows installs wrote codex.cmd next to the original launcher. */ const SIDE_BY_SIDE_ORIGINAL = /^codex(\.(exe|com|bat|cmd|ps1))?$/i; const MAX_LEGACY_ENTRIES = 3; const BACKUP_MARKER_SCAN_BYTES = 16 * 1024; export type LegacyShimRecordVerdict = | { ok: true; files: ShimFileState[]; directory: string } | { ok: false; reason: string }; function isRecord(value: unknown): value is Record<string, unknown> { return !!value && typeof value === "object" && !Array.isArray(value); } function pathProblem(path: unknown, api: PlatformPath): string | null { if (typeof path !== "string" || path.length === 0) return "a launcher path is missing"; if (/[\x00-\x1f\x7f]/.test(path)) return "a launcher path contains control characters"; if (api === win32) { if (!/^[A-Za-z]:\\/.test(path)) return "a launcher path is not an absolute drive path"; if (path.indexOf(":", 2) !== -1 || /[<>"|?*/]/.test(path)) return "a launcher path contains reserved characters"; if (path.slice(3).split("\\").some(segment => segment.length === 0 || /[. ]$/.test(segment))) { return "a launcher path is not normalized"; } } else if (!path.startsWith("/")) { return "a launcher path is not absolute"; } if (api.normalize(path) !== path || path.endsWith(api.sep)) return "a launcher path is not normalized"; return null; } function nameKey(path: string, api: PlatformPath): string { return api.basename(path).toLowerCase(); } /** Lexical validation: shape, platform, and the exact layout an OpenCodex install writes. */ export function validateLegacyWindowsShimRecord(value: unknown, api: PlatformPath = hostShimPathApi()): LegacyShimRecordVerdict { const fail = (reason: string): LegacyShimRecordVerdict => ({ ok: false, reason }); if (!isRecord(value)) return fail("the shim record is not an object"); if (value.schema !== undefined || value.mode !== undefined) return fail("the shim record is not a Windows install record"); if (value.platform !== "win32") return fail("the shim record was not written by a Windows install"); const entries: unknown = value.wrappers !== undefined ? value.wrappers : [value]; if (!Array.isArray(entries) || entries.length === 0 || entries.length > MAX_LEGACY_ENTRIES) { return fail("the shim record lists an unexpected number of launchers"); } const files: ShimFileState[] = []; for (const entry of entries) { if (!isRecord(entry)) return fail("a shim record entry is not an object"); for (const key of ["wrapperPath", "originalPath", "backupPath"] as const) { const problem = pathProblem(entry[key], api); if (problem) return fail(problem); } const file = { wrapperPath: entry.wrapperPath as string, originalPath: entry.originalPath as string, backupPath: entry.backupPath as string }; if (entry.realPath !== undefined && entry.realPath !== file.backupPath) return fail("a launcher points at an unexpected backing file"); if (entry.preserveOnly !== undefined && entry.preserveOnly !== false) return fail("a launcher entry has an unexpected mode"); const directory = api.dirname(file.wrapperPath); if (api.dirname(file.originalPath) !== directory || api.dirname(file.backupPath) !== directory) { return fail("the launcher, its original and its backup are not in one directory"); } if (file.wrapperPath === file.originalPath) { if (!IN_PLACE_LAUNCHERS.has(nameKey(file.wrapperPath, api))) return fail("a launcher has an unexpected name"); } else if (entries.length !== 1 || nameKey(file.wrapperPath, api) !== "codex.cmd" || !SIDE_BY_SIDE_ORIGINAL.test(api.basename(file.originalPath)) || nameKey(file.originalPath, api) === "codex.cmd") { return fail("a launcher has an unexpected name"); } if (file.backupPath !== legacyShimBackupPath(file.originalPath, api)) return fail("a backup is not the expected sibling of its original"); files.push(file); } if (value.wrappers !== undefined) { const first = files[0]!; for (const key of ["wrapperPath", "originalPath", "backupPath"] as const) { if (value[key] !== undefined && value[key] !== first[key]) return fail("the shim record summary disagrees with its launcher list"); } } const directory = api.dirname(files[0]!.wrapperPath); // Exact spelling: Windows directories can be case-sensitive, so differently cased names may differ. if (files.some(file => api.dirname(file.wrapperPath) !== directory)) { return fail("the launchers are not in one directory"); } if (new Set(files.map(file => nameKey(file.wrapperPath, api))).size !== files.length) return fail("a launcher is listed twice"); return { ok: true, files, directory }; } export interface LegacyShimDiskDeps { lstat?: (path: string) => { isFile(): boolean; isDirectory(): boolean; isSymbolicLink(): boolean; size: number | bigint; nlink?: number | bigint; dev?: number | bigint; ino?: number | bigint }; realpath?: (path: string) => string; readPrefix?: (path: string, bytes: number) => string; } export type LegacyShimDirectoryVerdict = /** `resolved` is null when the recorded directory no longer exists: nothing to act on. */ | { ok: true; resolved: string | null; identity: string | null } | { ok: false; reason: string }; function defaultReadPrefix(path: string, bytes: number): string { const fd = openSync(path, "r"); try { const buffer = Buffer.alloc(bytes); let total = 0; while (total < bytes) { const count = readSync(fd, buffer, total, bytes - total, total); if (count === 0) break; total += count; } return buffer.subarray(0, total).toString("utf8"); } finally { closeSync(fd); } } /** * Resolves the recorded directory once and requires the resolved chain to hold only real * directories. A link in the recorded spelling (an nvm-windows or scoop prefix) is accepted: * it can only select a directory the record could name directly, and callers act on the * resolved directory. */ const defaultLstat = (path: string) => lstatSync(path, { bigint: true }); export function resolveLegacyShimDirectory(recordedDirectory: string, api: PlatformPath = hostShimPathApi(), deps: LegacyShimDiskDeps = {}): LegacyShimDirectoryVerdict { const lstat = deps.lstat ?? defaultLstat; const realpath = deps.realpath ?? realpathSync.native; let resolved: string; try { resolved = realpath(recordedDirectory); } catch (error) { const code = fileErrorCode(error); if (code === "ENOENT" || code === "ENOTDIR") return { ok: true, resolved: null, identity: null }; return { ok: false, reason: "the launcher directory could not be resolved" }; } if (!api.isAbsolute(resolved)) return { ok: false, reason: "the launcher directory could not be resolved" }; let identity: string | null = null; try { for (let current = resolved; ; current = api.dirname(current)) { const entry = lstat(current); if (entry.isSymbolicLink() || !entry.isDirectory()) return { ok: false, reason: "the launcher directory resolves through a link" }; // Device and inode: a directory replaced at the same path is a different directory. if (current === resolved) identity = `${entry.dev}:${entry.ino}`; if (api.dirname(current) === current) break; } } catch { return { ok: false, reason: "the launcher directory could not be inspected" }; } return { ok: true, resolved, identity }; } type EntryShape = "absent" | "file" | "shared" | "other"; function entryShape(path: string, lstat: NonNullable<LegacyShimDiskDeps["lstat"]>): { shape: EntryShape; size: number } { try { const entry = lstat(path); if (entry.isSymbolicLink() || !entry.isFile()) return { shape: "other", size: 0 }; if (Number(entry.nlink ?? 1) > 1) return { shape: "shared", size: Number(entry.size) }; return { shape: "file", size: Number(entry.size) }; } catch (error) { if (fileErrorCode(error) === "ENOENT") return { shape: "absent", size: 0 }; return { shape: "other", size: 0 }; } } /** File shapes inside the resolved directory: launchers are regular files, a backup is a non-empty non-shim file. */ export function legacyShimFilesProblem(files: readonly ShimFileState[], resolvedDirectory: string, api: PlatformPath = hostShimPathApi(), deps: LegacyShimDiskDeps = {}): string | null { const lstat = deps.lstat ?? defaultLstat; const readPrefix = deps.readPrefix ?? defaultReadPrefix; for (const file of files) { for (const launcher of new Set([file.wrapperPath, file.originalPath])) { const shape = entryShape(api.join(resolvedDirectory, api.basename(launcher)), lstat).shape; if (shape === "other") return "a launcher is not a regular file"; if (shape === "shared") return "a launcher shares its file with another path"; } const backupPath = api.join(resolvedDirectory, api.basename(file.backupPath)); const backup = entryShape(backupPath, lstat); if (backup.shape === "absent") continue; if (backup.shape !== "file" || backup.size === 0) return "a backup is not a non-empty regular file"; try { if (readPrefix(backupPath, BACKUP_MARKER_SCAN_BYTES).includes(SHIM_MARKER)) return "a backup is itself a shim"; } catch { return "a backup could not be read"; } } return null; } export type LegacyShimCheck = | { ok: true; files: ShimFileState[]; recordedDirectory: string; resolvedDirectory: string | null; directoryIdentity: string | null } | { ok: false; reason: string }; /** Lexical layout, resolved directory, and file shapes, in that order. */ export function checkLegacyShimRecord(value: unknown, api: PlatformPath = hostShimPathApi(), deps: LegacyShimDiskDeps = {}): LegacyShimCheck { const record = validateLegacyWindowsShimRecord(value, api); if (!record.ok) return record; const directory = resolveLegacyShimDirectory(record.directory, api, deps); if (!directory.ok) return directory; if (directory.resolved !== null) { const problem = legacyShimFilesProblem(record.files, directory.resolved, api, deps); if (problem) return { ok: false, reason: problem }; } return { ok: true, files: record.files, recordedDirectory: record.directory, resolvedDirectory: directory.resolved, directoryIdentity: directory.identity }; } /** A launcher a fresh install backs up must be a non-empty file; an empty backup is refused by every later restore. */ export function legacyShimFreshLaunchersProblem(files: readonly ShimFileState[], resolvedDirectory: string | null, api: PlatformPath = hostShimPathApi(), deps: LegacyShimDiskDeps = {}): string | null { if (resolvedDirectory === null) return "the launcher directory is missing"; const lstat = deps.lstat ?? defaultLstat; for (const file of files) { const original = entryShape(api.join(resolvedDirectory, api.basename(file.originalPath)), lstat); if (original.shape !== "file" || original.size === 0) return "a launcher is empty or not a regular file"; } return null; } /** True when the recorded directory still resolves to the same link-free directory, by path and identity. */ export function legacyShimDirectoryUnchanged(recordedDirectory: string, resolvedDirectory: string | null, identity: string | null, api: PlatformPath = hostShimPathApi(), deps: LegacyShimDiskDeps = {}): boolean { const now = resolveLegacyShimDirectory(recordedDirectory, api, deps); return now.ok && now.resolved === resolvedDirectory && now.identity === identity; } let mutationGuard: (() => void) | null = null; /** * Binds every later Windows shim mutation to a validated record until the returned release runs: * each rename, link, unlink and write first checks that the recorded directory still resolves to * the directory that was validated. */ export function setLegacyShimMutationGuard(check: Extract<LegacyShimCheck, { ok: true }> | null): () => void { const previous = mutationGuard; mutationGuard = check && (() => { if (!legacyShimDirectoryUnchanged(check.recordedDirectory, check.resolvedDirectory, check.directoryIdentity)) { throw new Error("Codex shim launcher directory changed after validation; refusing to modify it"); } }); return () => { mutationGuard = previous; }; } /** Throws when a guarded Windows shim operation would act outside its validated directory. */ export function assertLegacyShimMutationAllowed(): void { mutationGuard?.(); } /* * The Windows shim modules import these instead of the node:fs calls, so every rename, unlink and * link they make checks the active guard immediately before it runs. Without a guard they are the * plain calls. */ export function guardedRenameSync(from: string, to: string): void { assertLegacyShimMutationAllowed(); renameSync(from, to); } export function guardedUnlinkSync(path: string): void { assertLegacyShimMutationAllowed(); unlinkSync(path); } export function guardedLinkSync(from: string, to: string): void { assertLegacyShimMutationAllowed(); linkSync(from, to); } export function legacyShimManualRestoreMessage(reason: string, statePath: string, partial = false): string { const changed = partial ? "The remaining launcher files were left as they are." : "No launcher file was renamed or deleted."; return `Codex autostart shim needs manual restore: ${reason}. ${changed} If Codex no longer starts, rename the launcher backup that carries the ".opencodex-real" suffix back to its original name, then delete ${statePath} and rerun.`; }