@bitkyc08/opencodex 2.55.0-preview.20260914 → 2.56.0

package/src/codex/shim-fingerprint.ts

@@ -0,0 +1,223 @@
+import {
+  closeSync,
+  existsSync,
+  lstatSync,
+  linkSync,
+  openSync,
+  readSync,
+  readlinkSync,
+  statSync,
+  symlinkSync,
+  unlinkSync,
+} from "node:fs";
+import { posix, win32 } from "node:path";
+import { SHIM_MARKER, UNIX_SHIM_REVISION_MARKER } from "./shim-templates";
+import type { ShimFileState } from "./shim-state-file";
+
+const CODEX_SHIM_PROBE_BYTES = 16 * 1024;
+
+interface ShimPathFingerprint {
+  dev: number;
+  ino: number;
+  kind: "file" | "symlink";
+  mode: number;
+  size: number;
+  mtimeMs: number;
+  ctimeMs: number;
+  target?: Omit<ShimPathFingerprint, "target">;
+}
+
+interface StableShimPathProbe {
+  fingerprint: ShimPathFingerprint;
+  prefix: string;
+}
+
+function readShimProbePrefix(path: string): string {
+  const fd = openSync(path, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(CODEX_SHIM_PROBE_BYTES);
+    const bytesRead = readSync(fd, buffer, 0, buffer.length, 0);
+    return buffer.toString("utf8", 0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function statFingerprint(path: string, follow: boolean): Omit<ShimPathFingerprint, "target"> | null {
+  try {
+    const stat = follow ? statSync(path) : lstatSync(path);
+    if (follow ? !stat.isFile() : (!stat.isFile() && !stat.isSymbolicLink())) return null;
+    return {
+      dev: stat.dev,
+      ino: stat.ino,
+      kind: stat.isSymbolicLink() ? "symlink" : "file",
+      mode: stat.mode,
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      ctimeMs: stat.ctimeMs,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function sameFingerprint(
+  left: ShimPathFingerprint | Omit<ShimPathFingerprint, "target">,
+  right: ShimPathFingerprint | Omit<ShimPathFingerprint, "target">,
+): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.kind === right.kind
+    && left.mode === right.mode
+    && left.size === right.size
+    && left.mtimeMs === right.mtimeMs
+    && left.ctimeMs === right.ctimeMs
+    && (!("target" in left) || !("target" in right)
+      ? true
+      : left.target === undefined && right.target === undefined
+        ? true
+        : left.target !== undefined && right.target !== undefined
+          ? sameFingerprint(left.target, right.target)
+          : false);
+}
+
+function sameFingerprintAfterRename(left: ShimPathFingerprint, right: ShimPathFingerprint): boolean {
+  // rename changes the outer directory entry ctime on macOS; every other field,
+  // including a symlink target fingerprint, must remain identical.
+  return sameFingerprint({ ...left, ctimeMs: 0 }, { ...right, ctimeMs: 0 });
+}
+
+function stableShimPathProbe(path: string): StableShimPathProbe | null {
+  const before = statFingerprint(path, false);
+  if (!before) return null;
+  const targetBefore = before.kind === "symlink" ? statFingerprint(path, true) : undefined;
+  if (before.kind === "symlink" && !targetBefore) return null;
+  let prefix: string;
+  try {
+    prefix = readShimProbePrefix(path);
+  } catch {
+    return null;
+  }
+  const targetAfter = before.kind === "symlink" ? statFingerprint(path, true) : undefined;
+  const after = statFingerprint(path, false);
+  if (!after || !sameFingerprint(before, after)) return null;
+  if (before.kind === "symlink") {
+    if (!targetBefore || !targetAfter || !sameFingerprint(targetBefore, targetAfter)) return null;
+  }
+  const fingerprint: ShimPathFingerprint = {
+    ...before,
+    ...(targetBefore ? { target: targetBefore } : {}),
+  };
+  const contentSize = fingerprint.target?.size ?? fingerprint.size;
+  return contentSize > 0 ? { fingerprint, prefix } : null;
+}
+
+function sameStableShimPathProbe(left: StableShimPathProbe, right: StableShimPathProbe): boolean {
+  return left.prefix === right.prefix && sameFingerprint(left.fingerprint, right.fingerprint);
+}
+
+/**
+ * Identity of whatever sits at `path`, read from metadata alone.
+ *
+ * `stableShimPathProbe` answers a different question: it reads content to decide
+ * whether a launcher looks like a healthy shim, and it deliberately returns null
+ * for a zero-byte file. That makes it the wrong instrument for rollback
+ * bookkeeping. A user can legitimately own an empty `codex` launcher, and a fresh
+ * install moves it aside before writing our wrapper; if the move is recorded
+ * without a fingerprint, rollback cannot prove the backup is still the file it
+ * set aside and refuses to restore it — the launcher stays lost (#1625).
+ *
+ * Content is irrelevant to that proof, so this reads dev/ino/mode/size/times and
+ * re-reads them to reject a path that changed under us, following a symlink to
+ * fingerprint its target as well.
+ */
+function shimPathFingerprint(path: string): ShimPathFingerprint | null {
+  const before = statFingerprint(path, false);
+  if (!before) return null;
+  if (before.kind !== "symlink") {
+    const after = statFingerprint(path, false);
+    return after && sameFingerprint(before, after) ? before : null;
+  }
+  const targetBefore = statFingerprint(path, true);
+  if (!targetBefore) return null;
+  const targetAfter = statFingerprint(path, true);
+  const after = statFingerprint(path, false);
+  if (!targetAfter || !after
+    || !sameFingerprint(targetBefore, targetAfter)
+    || !sameFingerprint(before, after)) return null;
+  return { ...before, target: targetBefore };
+}
+
+/**
+ * Move `from` onto `to` without ever replacing an existing entry.
+ *
+ * `renameSync` silently clobbers the destination on POSIX, which is wrong for a
+ * rollback restore: `sourceOccupied` is sampled before the fingerprint check, so
+ * a concurrent installer can publish its own launcher at the original path in
+ * between, and the restore would delete it. `link` fails EEXIST instead, which
+ * is the no-replace primitive we need and needs no native helper.
+ *
+ * `link` follows a symlink to its target rather than preserving the link, so a
+ * symlink launcher is republished with `symlink`, which is also no-replace: it
+ * fails EEXIST on an occupied destination. Checking existence and then renaming
+ * would reintroduce exactly the race this function exists to close.
+ */
+function restoreWithoutReplacing(from: string, to: string): void {
+  const source = lstatSync(from);
+  if (source.isSymbolicLink()) {
+    symlinkSync(readlinkSync(from), to);
+    unlinkSync(from);
+    return;
+  }
+  linkSync(from, to);
+  unlinkSync(from);
+}
+
+function isHealthyShimProbe(probe: StableShimPathProbe, platform: NodeJS.Platform): boolean {
+  if (probe.prefix.length < 180 || !probe.prefix.includes(SHIM_MARKER) || !probe.prefix.includes("ensure")) return false;
+  const mode = probe.fingerprint.target?.mode ?? probe.fingerprint.mode;
+  return platform === "win32" || (mode & 0o111) !== 0;
+}
+
+function isCurrentUnixShimProbe(probe: StableShimPathProbe): boolean {
+  return probe.prefix.includes(UNIX_SHIM_REVISION_MARKER);
+}
+
+function hasUsableBackingPath(file: ShimFileState): boolean {
+  return [existsSync(file.backupPath) ? file.backupPath : undefined, file.realPath]
+    .some(path => {
+      if (!path) return false;
+      const fingerprint = statFingerprint(path, true);
+      return fingerprint !== null && fingerprint.size > 0;
+    });
+}
+
+/**
+ * True when a Codex binary lives inside a version manager's install tree.
+ *
+ * These trees are rewritten in place on upgrade, which destroys both the shim
+ * and the sibling .opencodex-real backup it restores from (#2412). The tempting
+ * repair — adopt the newly installed binary as a fresh original — is wrong
+ * twice: it records a provenance that never happened, and the next upgrade wipes
+ * it again, so the repair silently un-repairs on the version manager's schedule.
+ *
+ * Scope is the three managers named in the report. nvm/fnm/npm-prefix are
+ * deliberately excluded: a false positive here refuses a restore that would
+ * otherwise be correct.
+ */
+export function isVersionManagerOwnedCodexPath(
+  path: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  const normalized = (platform === "win32"
+    ? win32.normalize(path).replace(/\\/g, "/")
+    : posix.normalize(path)).toLowerCase();
+  return normalized.includes("/mise/installs/")
+    || normalized.includes("/mise/shims/")
+    || normalized.includes("/.asdf/installs/")
+    || normalized.includes("/.asdf/shims/")
+    || normalized.includes("/.volta/");
+}
+
+export type { ShimPathFingerprint, StableShimPathProbe };
+export { statFingerprint, sameFingerprint, sameFingerprintAfterRename, stableShimPathProbe, sameStableShimPathProbe, shimPathFingerprint, restoreWithoutReplacing, isHealthyShimProbe, isCurrentUnixShimProbe, hasUsableBackingPath };

package/src/codex/shim-inspect.ts

@@ -0,0 +1,175 @@
+import { lstatSync } from "node:fs";
+import { extname, join, posix, win32 } from "node:path";
+import { getConfigDir } from "../config";
+import { fileErrorCode, readStateResult, stateFiles } from "./shim-state-file";
+import {
+  isHealthyShimProbe,
+  isVersionManagerOwnedCodexPath,
+  shimPathFingerprint,
+  stableShimPathProbe,
+  statFingerprint,
+  type ShimPathFingerprint,
+} from "./shim-fingerprint";
+import { gitBashPath, psString, shQuote, windowsBatchSet } from "./shim-templates";
+
+export type CodexShimBackingForCommand =
+  | Readonly<{ status: "not-tracked" }>
+  | Readonly<{
+      status: "matched";
+      selectedRole: "wrapper" | "backing";
+      backingPath: string;
+      backingKind: "backup" | "real";
+    }>
+  | Readonly<{
+      status: "unknown";
+      reason:
+        | "state_invalid"
+        | "platform_mismatch"
+        | "ambiguous_match"
+        | "preserve_only"
+        | "backing_missing"
+        | "backing_mismatch"
+        | "binding_unavailable"
+        | "wrapper_unhealthy"
+        | "version_manager_refused";
+    }>;
+
+export function isLocalAbsoluteInspectionPath(path: string, platform: NodeJS.Platform): boolean {
+  if (platform !== "win32") return posix.isAbsolute(path);
+  const normalized = path.replace(/\//g, "\\");
+  // UNC and device namespaces can initiate remote I/O while a nominally local
+  // inspection is resolving user-controlled paths. Root-relative paths are
+  // drive-context dependent, so require an explicit local drive as well.
+  return win32.isAbsolute(path)
+    && /^[a-z]:\\/i.test(normalized)
+    && !normalized.startsWith("\\\\");
+}
+
+function windowsShimInspectionIsDeferred(platform: NodeJS.Platform): boolean {
+  return platform === "win32";
+}
+
+/** Resolve one selected command through already-recorded shim state, without repair. */
+export function inspectCodexShimBackingForCommand(
+  selectedCommand: string,
+  platform: NodeJS.Platform = process.platform,
+  configDir: string = getConfigDir(),
+): CodexShimBackingForCommand {
+  // Pathname prechecks cannot prevent a writable Windows ancestor from being
+  // replaced with a remote reparse point before the later state/fingerprint
+  // reads. Keep the exported read-only helper fail-closed until those reads are
+  // performed through a handle-bound Windows provenance layer.
+  if (windowsShimInspectionIsDeferred(platform)) {
+    return Object.freeze({ status: "unknown" as const, reason: "binding_unavailable" as const });
+  }
+  if (!isLocalAbsoluteInspectionPath(configDir, platform)) {
+    return Object.freeze({ status: "unknown" as const, reason: "state_invalid" as const });
+  }
+  const stateFile = join(configDir, "codex-shim.json");
+  try {
+    const stateEntry = lstatSync(stateFile);
+    if (stateEntry.isSymbolicLink()) {
+      return Object.freeze({ status: "unknown" as const, reason: "state_invalid" as const });
+    }
+  } catch (error) {
+    if (fileErrorCode(error) !== "ENOENT") {
+      return Object.freeze({ status: "unknown" as const, reason: "state_invalid" as const });
+    }
+  }
+  const result = readStateResult(stateFile);
+  if (!result.state) {
+    return result.present
+      ? Object.freeze({ status: "unknown" as const, reason: "state_invalid" as const })
+      : Object.freeze({ status: "not-tracked" as const });
+  }
+  const pathApi = platform === "win32" ? win32 : posix;
+  const samePath = (left: string, right: string): boolean => {
+    const normalizedLeft = pathApi.resolve(left);
+    const normalizedRight = pathApi.resolve(right);
+    return platform === "win32"
+      ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+      : normalizedLeft === normalizedRight;
+  };
+  const files = stateFiles(result.state);
+  if (files.some(file => !file.wrapperPath || !file.originalPath || !file.backupPath
+    || ![file.wrapperPath, file.originalPath, file.backupPath, file.realPath]
+      .filter((path): path is string => typeof path === "string")
+      .every(path => isLocalAbsoluteInspectionPath(path, platform)))) {
+    return Object.freeze({ status: "unknown" as const, reason: "state_invalid" as const });
+  }
+  const wrapperKeys = files.map(file => platform === "win32"
+    ? pathApi.resolve(file.wrapperPath).toLowerCase()
+    : pathApi.resolve(file.wrapperPath));
+  if (new Set(wrapperKeys).size !== wrapperKeys.length) {
+    return Object.freeze({ status: "unknown" as const, reason: "state_invalid" as const });
+  }
+  const selectedFingerprint = shimPathFingerprint(selectedCommand);
+  if (!selectedFingerprint) {
+    return Object.freeze({ status: "unknown" as const, reason: "binding_unavailable" as const });
+  }
+  const selectedIdentity = selectedFingerprint.target ?? selectedFingerprint;
+  const sameEffectiveIdentity = (fingerprint: ShimPathFingerprint | null): boolean => {
+    if (!fingerprint) return false;
+    const identity = fingerprint.target ?? fingerprint;
+    return identity.dev === selectedIdentity.dev && identity.ino === selectedIdentity.ino;
+  };
+  const matches = files.flatMap(file => {
+    const backingPath = file.realPath ?? file.backupPath;
+    const roles: Array<"wrapper" | "backing"> = [];
+    if (samePath(file.wrapperPath, selectedCommand)
+      || sameEffectiveIdentity(shimPathFingerprint(file.wrapperPath))) {
+      roles.push("wrapper");
+    }
+    if (samePath(backingPath, selectedCommand)
+      || sameEffectiveIdentity(shimPathFingerprint(backingPath))) {
+      roles.push("backing");
+    }
+    return roles.map(selectedRole => ({ file, backingPath, selectedRole }));
+  });
+  if (matches.length === 0) return Object.freeze({ status: "not-tracked" as const });
+  if (result.state.platform !== platform) {
+    return Object.freeze({ status: "unknown" as const, reason: "platform_mismatch" as const });
+  }
+  if (matches.length !== 1) {
+    return Object.freeze({ status: "unknown" as const, reason: "ambiguous_match" as const });
+  }
+  const { file, backingPath, selectedRole } = matches[0]!;
+  if (file.preserveOnly === true) {
+    return Object.freeze({ status: "unknown" as const, reason: "preserve_only" as const });
+  }
+  const backing = statFingerprint(backingPath, true);
+  if (!backing || backing.size <= 0 || samePath(backingPath, file.wrapperPath)) {
+    return Object.freeze({ status: "unknown" as const, reason: "backing_missing" as const });
+  }
+  const wrapperProbe = stableShimPathProbe(file.wrapperPath);
+  if (!wrapperProbe || !isHealthyShimProbe(wrapperProbe, result.state.platform)) {
+    return Object.freeze({
+      status: "unknown" as const,
+      reason: isVersionManagerOwnedCodexPath(file.wrapperPath)
+        ? "version_manager_refused" as const
+        : "wrapper_unhealthy" as const,
+    });
+  }
+  const wrapperIdentity = wrapperProbe.fingerprint.target ?? wrapperProbe.fingerprint;
+  if (backing.dev === wrapperIdentity.dev && backing.ino === wrapperIdentity.ino) {
+    return Object.freeze({ status: "unknown" as const, reason: "backing_mismatch" as const });
+  }
+  const wrapperExt = extname(file.wrapperPath).toLowerCase();
+  const invokesBacking = platform !== "win32"
+    ? wrapperProbe.prefix.includes(`exec ${shQuote(backingPath)} "$@"`)
+    : wrapperExt === ".cmd" || wrapperExt === ".bat"
+      ? wrapperProbe.prefix.includes(windowsBatchSet("OCX_REAL_CODEX", backingPath))
+        && wrapperProbe.prefix.includes('"%OCX_REAL_CODEX%" %*')
+      : wrapperExt === ".ps1"
+        ? wrapperProbe.prefix.includes(`& ${psString(backingPath)} @args`)
+        : wrapperProbe.prefix.includes(`exec ${shQuote(gitBashPath(backingPath))} "$@"`);
+  if (!invokesBacking) {
+    return Object.freeze({ status: "unknown" as const, reason: "backing_mismatch" as const });
+  }
+  return Object.freeze({
+    status: "matched" as const,
+    selectedRole,
+    backingPath,
+    backingKind: file.realPath !== undefined ? "real" as const : "backup" as const,
+  });
+}