@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/codex/desktop-app/picker-freshness.ts

@@ -0,0 +1,96 @@
+/**
+ * Whether the Codex desktop app's model picker already shows the current catalog (#4761).
+ *
+ * `ocx system codex-restart` used to quit and relaunch the desktop shell every time, which
+ * discards everything that lives only in the client: composer drafts, an unsent picker
+ * selection, a pending approval prompt. Upstream's own restart (`codex app-server daemon
+ * restart`) restarts only the app-server and lets clients reconnect, and the desktop app
+ * already respawns its own app-server child when it exits.
+ *
+ * The one thing an app-server restart cannot refresh is the picker: the renderer builds
+ * the roster once when the shell launches, and `model_catalog_json` is startup-only. So
+ * the shell has to restart only when it launched before the catalog it should show was
+ * written. The catalog writer skips byte-identical rewrites to keep this mtime honest
+ * (`src/codex/catalog/retained-sync.ts`), which is what makes the comparison usable.
+ *
+ * The mtime only means something for the catalog `config.toml` actually binds. With no
+ * `model_catalog_json` the shell shows Codex's own roster, which no local file dates, so
+ * an unbound config is `unknown`. `config.toml`'s own mtime is no substitute: injection
+ * rewrites it on every sync even when the bytes are identical. A binding changed by THIS
+ * request's sync is caught by the caller comparing it across the sync; one changed by an
+ * earlier sync over a byte-identical catalog file is not observable here.
+ *
+ * Anything we cannot read answers `unknown`, and the caller falls back to the full
+ * desktop restart: a stale picker the operator asked us to fix is the failure this
+ * command exists to prevent, so missing evidence never skips it.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { activeCodexConfigPath, resolveActiveCodexConfigPath } from "../catalog/parsing";
+import { readRootTomlString } from "../paths";
+import { readProcessStartMsBatch } from "../app-server-processes";
+import { listCodexDesktopShellPids, type DesktopAppRestartIo } from "../desktop-app-restart";
+import { isTestHomeGuardArmed } from "../../lib/test-home-guard";
+import type { CodexDesktopPickerState } from "../../lib/codex-restart-contract";
+
+export type DesktopPickerState = CodexDesktopPickerState;
+
+/**
+ * Pure decision. `shellStartsMs === null` means the shells could not be listed; a null
+ * entry means one shell's start time was unreadable.
+ *
+ * Strictly later, never equal: macOS `ps lstart` has one-second granularity, so a shell
+ * that started in the same second as the catalog write may predate it.
+ */
+export function classifyDesktopPicker(
+  shellStartsMs: readonly (number | null)[] | null,
+  catalogMtimeMs: number | null,
+): DesktopPickerState {
+  if (shellStartsMs === null) return "unknown";
+  if (shellStartsMs.length === 0) return "not_running";
+  if (catalogMtimeMs === null) return "unknown";
+  if (shellStartsMs.some(start => start === null)) return "unknown";
+  return shellStartsMs.every(start => start! > catalogMtimeMs) ? "current" : "stale";
+}
+
+export interface DesktopPickerIo extends DesktopAppRestartIo {
+  readStartMs?: (pids: readonly number[]) => Map<number, number | null>;
+  /** The catalog `config.toml` binds, or null when it binds none or cannot be read. */
+  catalogBinding?: () => string | null;
+  catalogMtimeMs?: (path: string) => number | null;
+}
+
+/** The resolved `model_catalog_json` path, or null when config.toml binds no catalog. */
+export function readCodexCatalogBinding(): string | null {
+  try {
+    const configPath = activeCodexConfigPath();
+    if (!existsSync(configPath)) return null;
+    const path = readRootTomlString(readFileSync(configPath, "utf-8"), "model_catalog_json");
+    return path ? resolveActiveCodexConfigPath(path) : null;
+  } catch {
+    return null;
+  }
+}
+
+function defaultCatalogMtimeMs(path: string): number | null {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+export function readCodexDesktopPickerState(io: DesktopPickerIo = {}): DesktopPickerState {
+  // An armed test process without an injected executor answers `unknown`, which keeps the
+  // caller on the desktop-restart seam the test injected. Reading is harmless, but whether
+  // the developer's own Codex is open must not decide which branch a test takes.
+  if (!io.execFile && isTestHomeGuardArmed()) return "unknown";
+  const platform = io.platform ?? process.platform;
+  const pids = listCodexDesktopShellPids(io);
+  if (pids === null || pids.length === 0) return classifyDesktopPicker(pids, null);
+  const starts = (io.readStartMs ?? (list => readProcessStartMsBatch(list, platform)))(pids);
+  const binding = (io.catalogBinding ?? readCodexCatalogBinding)();
+  return classifyDesktopPicker(
+    pids.map(pid => starts.get(pid) ?? null),
+    binding === null ? null : (io.catalogMtimeMs ?? defaultCatalogMtimeMs)(binding),
+  );
+}

package/src/codex/desktop-app/types.ts

@@ -51,6 +51,8 @@ export interface DesktopProcess {
   createdAt: string;
   /** Absolute executable path, used for membership and the shell predicate. */
   executable: string;
+  /** Windows-only private launch context; never included in restart results or logs. */
+  commandLine?: string;
 }
 
 export interface DesktopAppAdapter {

package/src/codex/desktop-app/windows.ts

@@ -13,6 +13,7 @@
 import { execFileSync } from "node:child_process";
 import { sep, win32 } from "node:path";
 import { resolveTrustedWindowsPowerShellExe, resolveTrustedWindowsTaskkillExe } from "../../lib/windows-elevation";
+import { activateWindowsCodexCompatibility, assertWindowsCompatibilityContext, captureWindowsCompatibilityContext } from "../desktop-compatibility/windows-package-command";
 import {
   isUnderRoot,
   type DesktopAppAdapter,
@@ -50,8 +51,7 @@ function isMemberExecutable(executable: string, root: string): boolean {
  * changes between builds, so a literal AUMID would silently stop matching and
  * then either do nothing or — worse — match a package we did not mean.
  */
-function discoverPackage(exec: DesktopExec): DesktopAppInstall | null {
-  const script = [
+export const WINDOWS_PACKAGE_DISCOVERY_SCRIPT = [
     "$ErrorActionPreference='SilentlyContinue'",
     "Import-Module Appx -ErrorAction SilentlyContinue",
     "$p = Get-AppxPackage -Name OpenAI.Codex",
@@ -60,12 +60,8 @@ function discoverPackage(exec: DesktopExec): DesktopAppInstall | null {
     "  $p.PackageFamilyName; $p.InstallLocation; \"$($p.PackageFamilyName)!App\"",
     "}",
   ].join("; ");
-  let stdout: string;
-  try {
-    stdout = exec(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", script], POWERSHELL_PROBE_OPTIONS);
-  } catch {
-    return null;
-  }
+
+export function parseWindowsDesktopPackage(stdout: string): DesktopAppInstall | null {
   const lines = stdout.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
   if (lines.length < 3 || lines[0] === "MISS") return null;
   const [family, installLocation, aumid] = lines;
@@ -73,6 +69,16 @@ function discoverPackage(exec: DesktopExec): DesktopAppInstall | null {
   return { id: family, root: installLocation, relaunch: aumid };
 }
 
+function discoverPackage(exec: DesktopExec): DesktopAppInstall | null {
+  let stdout: string;
+  try {
+    stdout = exec(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", WINDOWS_PACKAGE_DISCOVERY_SCRIPT], POWERSHELL_PROBE_OPTIONS);
+  } catch {
+    return null;
+  }
+  return parseWindowsDesktopPackage(stdout);
+}
+
 /**
  * Only `ChatGPT.exe` processes whose image lives under the discovered install
  * location AND owned by the current user. The install location alone is not
@@ -100,7 +106,8 @@ function listPackageProcesses(exec: DesktopExec, install: DesktopAppInstall): De
     "    if ($o -and $o.ReturnValue -eq 0 -and $o.User) {",
     "      $owner = if ($o.Domain) { \"$($o.Domain)\\$($o.User)\" } else { $o.User }",
     "      if ($owner -ieq $me) {",
-    "        \"$($_.ProcessId) $($_.ParentProcessId) $($_.CreationDate.ToString('o')) $($_.ExecutablePath)\"",
+    "        $encoded=[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$_.CommandLine))",
+    "        \"$($_.ProcessId) $($_.ParentProcessId) $($_.CreationDate.ToString('o')) $($_.ExecutablePath)`t$encoded\"",
     "      }",
     "    }",
     "  }",
@@ -126,7 +133,9 @@ function listPackageProcesses(exec: DesktopExec, install: DesktopAppInstall): De
 }
 
 function parseProcessLine(line: string, root: string): DesktopProcess | null {
-  const match = /^\s*(\d+)\s+(\d+)\s+(\S+)(?:\s+(.+))?$/.exec(line);
+  const [listing, encoded, ...extra] = line.split("\t");
+  if (extra.length || (encoded && (encoded.length > 65_536 || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)))) return null;
+  const match = /^\s*(\d+)\s+(\d+)\s+(\S+)(?:\s+(.+))?$/.exec(listing ?? "");
   if (!match) return null;
   const pid = Number(match[1]);
   const parentPid = Number(match[2]);
@@ -143,7 +152,8 @@ function parseProcessLine(line: string, root: string): DesktopProcess | null {
   // Authoritative membership. PowerShell StartsWith already cheap-filtered, but
   // that test is a string prefix and is how a sibling install would sneak in.
   if (!isMemberExecutable(executable, root)) return null;
-  return { pid, parentPid, createdAt, executable };
+  return { pid, parentPid, createdAt, executable,
+    ...(encoded !== undefined ? { commandLine: Buffer.from(encoded, "base64").toString("utf8") } : {}) };
 }
 
 /**
@@ -215,13 +225,16 @@ export const windowsDesktopAppAdapter: DesktopAppAdapter = {
     exec(resolveTrustedWindowsTaskkillExe(), ["/PID", String(root.pid), "/T", "/F"], POWERSHELL_PROBE_OPTIONS);
   },
 
-  captureRelaunchContext(): Record<string, string> {
-    // The session is supplied by the shell:AppsFolder launch, so nothing needs
-    // carrying forward.
-    return {};
+  captureRelaunchContext(_exec, _install, processes): Record<string, string> {
+    return captureWindowsCompatibilityContext(processes);
   },
 
-  relaunch(exec, install): void {
+  relaunch(exec, install, context): void {
+    if (context.codexCompatibilityPacUrl) {
+      assertWindowsCompatibilityContext(context);
+      activateWindowsCodexCompatibility(exec, install, context.codexCompatibilityPacUrl);
+      return;
+    }
     // Throws on failure so the ladder reports relaunch_failed. The old code
     // returned targets_survived here, which was dishonest: everything HAD died
     // and it was the relaunch that failed.

package/src/codex/desktop-app-restart.ts

@@ -89,6 +89,7 @@ export type DesktopAppRestartReason =
   | "self_ancestry"
   | "restart_in_flight"
   | "handoff_started"
+  | "relaunch_context_failed"
   | "targets_survived"
   | "relaunch_failed";
 
@@ -205,6 +206,27 @@ export function listCodexDesktopAppPids(io: DesktopAppRestartIo = {}): number[]
   return processes === null ? null : processes.map(entry => entry.pid);
 }
 
+/**
+ * Pids of the running desktop-app ROOT shells, or null when discovery or the probe failed.
+ *
+ * Read-only. The shell is the process whose renderer built the model picker, so its start
+ * time is what tells `performCodexRestart` whether the picker predates the catalog (#4761).
+ * `[]` means the probe ran and the app is not running.
+ */
+export function listCodexDesktopShellPids(io: DesktopAppRestartIo = {}): number[] | null {
+  const platform = io.platform ?? process.platform;
+  const selected = ADAPTERS[platform];
+  const adapter = io.adapter ?? selected?.adapter;
+  if (!adapter) return null;
+  const exec = io.execFile ?? selected?.exec;
+  if (!exec) return null;
+  const install = adapter.discover(exec);
+  if (!install) return null;
+  const processes = adapter.listProcesses(exec, install);
+  if (processes === null) return null;
+  return rootShells(processes, install, adapter).map(entry => entry.pid);
+}
+
 export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopAppRestartResult {
   const skipped = (reason: DesktopAppRestartReason): DesktopAppRestartResult => ({
     attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason,
@@ -263,7 +285,9 @@ export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopApp
     // graphical session variables, and after termination there is nothing to read them
     // from. Ordering this wrongly works on macOS and Windows and produces a Linux app
     // that cannot reach the compositor.
-    const context = adapter.captureRelaunchContext(exec, install, processes);
+    let context: Record<string, string>;
+    try { context = adapter.captureRelaunchContext(exec, install, processes); }
+    catch { return skipped("relaunch_context_failed"); }
 
     const isAlive = io.isAlive ?? defaultIsAlive;
     const sleep = io.sleep ?? defaultSleep;
@@ -345,4 +369,3 @@ export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopApp
     if (!handedOff) releaseDesktopRestartLock(io.lock);
   }
 }
-

package/src/codex/desktop-compatibility/certificate-service.ts

@@ -0,0 +1,99 @@
+import { join } from "node:path";
+import { getConfigDir } from "../../config/paths";
+import { windowsDefaultExec, windowsDesktopAppAdapter } from "../desktop-app/windows";
+import { ensureDesktopCompatibilityAuthority, inspectDesktopCompatibilityAuthority, loadDesktopCompatibilityAuthority, renewDesktopCompatibilityAuthority, type DesktopAuthorityInspection, type StoredDesktopAuthority } from "./certificate-store";
+import { createWindowsCertificateTrust, inspectWindowsCertificateTrust, type DesktopCertificateTrust } from "./windows-certificate-trust";
+import { acquireDesktopCertificateMutation, desktopCompatibilityRuntimeActive } from "./runtime-ownership";
+
+export interface DesktopCertificateStatus {
+  supported: boolean;
+  state: "missing" | "invalid" | "expired" | "renewal-required" | "prepared" | "trusted" | "unknown";
+  fingerprint?: string;
+  expiresAt?: number;
+  renewalDue?: boolean;
+  trust?: DesktopCertificateTrust;
+  busy: "prepare" | "trust" | "remove-trust" | "renew" | null;
+}
+
+export interface DesktopCertificateServiceIo {
+  platform?: string;
+  inspect?: () => DesktopAuthorityInspection;
+  prepare?: () => Promise<StoredDesktopAuthority>;
+  load?: (allowExpiredForRemoval: boolean) => Promise<StoredDesktopAuthority>;
+  renew?: (fingerprint: string) => Promise<StoredDesktopAuthority>;
+  readTrust?: (authority: Extract<DesktopAuthorityInspection, { fingerprint: string }>) => Promise<DesktopCertificateTrust>;
+  changeTrust?: (authority: StoredDesktopAuthority, action: "trust" | "remove") => Promise<DesktopCertificateTrust>;
+  appRunning?: () => Promise<boolean | null>;
+}
+
+export class DesktopCertificateServiceError extends Error {
+  constructor(readonly code: "unsupported" | "busy" | "not_prepared" | "fingerprint_changed" | "app_running" | "runtime_running" | "app_state_unknown" | "trust_unknown" | "trust_not_applied") {
+    super(`desktop_compatibility_${code}`); this.name = "DesktopCertificateServiceError";
+  }
+}
+
+/** This service owns setup only: no proxy listeners, app restart, account or quota writes. */
+export function createDesktopCertificateService(directory = join(getConfigDir(), "codex-desktop-compatibility"), io: DesktopCertificateServiceIo = {}) {
+  const platform = io.platform ?? process.platform;
+  const inspect = io.inspect ?? (() => inspectDesktopCompatibilityAuthority(directory));
+  const prepare = io.prepare ?? (() => ensureDesktopCompatibilityAuthority({ directory }));
+  const load = io.load ?? (allowExpired => loadDesktopCompatibilityAuthority({ directory }, allowExpired));
+  const renew = io.renew ?? (fingerprint => renewDesktopCompatibilityAuthority({ directory }, fingerprint));
+  const readTrust = io.readTrust ?? (value => inspectWindowsCertificateTrust(value.certPem, value.fingerprint));
+  const changeTrust = io.changeTrust ?? ((authority, action) => createWindowsCertificateTrust(authority, authority.fingerprint)[action]());
+  const appRunning = io.appRunning ?? (async () => {
+    const install = windowsDesktopAppAdapter.discover(windowsDefaultExec);
+    if (!install) return null; // Unknown installation is not proof that no app uses the authority.
+    const processes = windowsDesktopAppAdapter.listProcesses(windowsDefaultExec, install);
+    return processes === null ? null : processes.length > 0;
+  });
+  let busy: DesktopCertificateStatus["busy"] = null;
+  async function status(): Promise<DesktopCertificateStatus> {
+    if (platform !== "win32") return { supported: false, state: "missing", busy };
+    const stored = inspect();
+    if (!("fingerprint" in stored)) return { supported: true, state: stored.status, busy };
+    const trusted = await readTrust(stored).catch(() => "unknown" as const);
+    return { supported: true, state: stored.status === "expired" ? "expired"
+      : stored.status === "renewal-required" ? "renewal-required"
+      : trusted === "trusted" ? "trusted" : trusted === "not-trusted" ? "prepared" : "unknown",
+      fingerprint: stored.fingerprint, expiresAt: stored.expiresAt, renewalDue: stored.renewalDue, trust: trusted, busy };
+  }
+  async function action(kind: NonNullable<DesktopCertificateStatus["busy"]>, expectedFingerprint?: string): Promise<DesktopCertificateStatus> {
+    if (platform !== "win32") throw new DesktopCertificateServiceError("unsupported");
+    if (busy !== null) throw new DesktopCertificateServiceError("busy");
+    if (desktopCompatibilityRuntimeActive()) throw new DesktopCertificateServiceError("runtime_running");
+    let release: () => void;
+    try { release = acquireDesktopCertificateMutation(); } catch { throw new DesktopCertificateServiceError("busy"); }
+    busy = kind;
+    try {
+      if (kind !== "prepare") {
+        const before = inspect();
+        if (!("fingerprint" in before)) throw new DesktopCertificateServiceError("not_prepared");
+        if (before.fingerprint !== expectedFingerprint) throw new DesktopCertificateServiceError("fingerprint_changed");
+        if (kind === "remove-trust" || kind === "renew") {
+          const running = await appRunning();
+          if (running === null) throw new DesktopCertificateServiceError("app_state_unknown");
+          if (running) throw new DesktopCertificateServiceError("app_running");
+        }
+      }
+      const authority = kind === "prepare" ? await prepare() : await load(kind !== "trust");
+      if (kind !== "prepare") {
+        if (authority.fingerprint !== expectedFingerprint) throw new DesktopCertificateServiceError("fingerprint_changed");
+        const current = inspect();
+        if (!("fingerprint" in current) || current.fingerprint !== authority.fingerprint) throw new DesktopCertificateServiceError("fingerprint_changed");
+        const result = await changeTrust(authority, kind === "trust" ? "trust" : "remove");
+        if (result === "unknown") throw new DesktopCertificateServiceError("trust_unknown");
+        if (result !== (kind === "trust" ? "trusted" : "not-trusted")) throw new DesktopCertificateServiceError("trust_not_applied");
+        // Never discard the only removable old identity until OS trust removal is proven.
+        // Publication failure leaves its protected envelope intact for an explicit retry.
+        if (kind === "renew") await renew(authority.fingerprint);
+      }
+      busy = null;
+      return status();
+    } finally { busy = null; release(); }
+  }
+  return { status, prepare: () => action("prepare"), trust: (fingerprint: string) => action("trust", fingerprint),
+    removeTrust: (fingerprint: string) => action("remove-trust", fingerprint), renew: (fingerprint: string) => action("renew", fingerprint) };
+}
+
+export type DesktopCertificateService = ReturnType<typeof createDesktopCertificateService>;

package/src/codex/desktop-compatibility/certificate-store.ts

@@ -0,0 +1,193 @@
+import { createHash, createPrivateKey, createPublicKey, randomUUID, X509Certificate } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { createCertificateAuthority, isServerAuthOnlyCertificate, type LocalInterceptCa } from "../../claude/intercept/local-ca";
+import { withClientLifecycle } from "../../client/lifecycle-lock";
+import { hardenSecretDirAsync, hardenSecretPathAsync } from "../../lib/windows-secret-acl";
+import { windowsAuthorityKeyProtection, type AuthorityKeyProtection } from "./windows-key-protection";
+
+const POLICY = "codex-desktop-chatgpt-only/v1";
+const FILE = "authority.json";
+const MAX_FILE = 131_072;
+const VALIDITY_DAYS = 30;
+const DAY = 86_400_000;
+const digest = (value: string) => createHash("sha256").update(value).digest("hex");
+
+export class DesktopAuthorityError extends Error {
+  constructor(readonly code: "unsafe_path" | "unreadable" | "expired" | "renewal_required" | "protection_failed" | "fingerprint_changed") {
+    super(`desktop_compatibility_authority_${code}`); this.name = "DesktopAuthorityError";
+  }
+}
+
+export interface DesktopAuthorityStoreOptions {
+  /** Explicit feature-owned directory; never an OS trust store or existing Claude CA. */
+  directory: string;
+  now?: () => number;
+  /** Test seam; production always uses Windows CurrentUser DPAPI. */
+  protection?: AuthorityKeyProtection;
+}
+
+export interface StoredDesktopAuthority {
+  authority: LocalInterceptCa;
+  commonName: string;
+  fingerprint: string;
+  expiresAt: number;
+  renewalDue: boolean;
+  reused: boolean;
+}
+
+export type DesktopAuthorityInspection =
+  | { status: "missing" | "invalid" }
+  | { status: "present" | "expired" | "renewal-required"; certPem: string; fingerprint: string; expiresAt: number; renewalDue: boolean };
+
+/** Read-only public metadata for status: no key decryption, ACL write, lock or generation. */
+export function inspectDesktopCompatibilityAuthority(directory: string, now = Date.now()): DesktopAuthorityInspection {
+  if (!isAbsolute(directory) || !Number.isFinite(now)) return { status: "invalid" };
+  const path = join(directory, FILE);
+  try {
+    if (!pathPresent(directory)) return { status: "missing" };
+    assertPath(directory, true);
+    if (!pathPresent(path)) return { status: "missing" };
+    assertPath(path, false);
+    const saved = JSON.parse(readFileSync(path, "utf8"));
+    if (saved.version !== 1 || saved.protection !== "windows-current-user-dpapi" || typeof saved.certPem !== "string"
+      || typeof saved.sealed !== "string" || !/^[A-Za-z0-9+/]+={0,2}$/.test(saved.sealed) || saved.sealed.length > MAX_FILE) return { status: "invalid" };
+    const certificate = new X509Certificate(saved.certPem), expiresAt = Date.parse(certificate.validTo);
+    if (!certificate.ca || !Number.isFinite(expiresAt)) return { status: "invalid" };
+    return { status: expiresAt <= now ? "expired" : isServerAuthOnlyCertificate(certificate) ? "present" : "renewal-required", certPem: saved.certPem,
+      fingerprint: certificate.fingerprint256.replaceAll(":", ""), expiresAt, renewalDue: expiresAt - now <= 7 * DAY };
+  } catch { return { status: "invalid" }; }
+}
+
+function assertPath(path: string, directory: boolean): void {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1 || stat.size > MAX_FILE)) {
+    throw new DesktopAuthorityError("unsafe_path");
+  }
+}
+
+function pathPresent(path: string): boolean {
+  try { lstatSync(path); return true; }
+  catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return false;
+    throw new DesktopAuthorityError("unsafe_path");
+  }
+}
+
+function validatedAuthority(certPem: string, keyPem: string, commonName: string, now: number, reused: boolean, allowExpired = false): StoredDesktopAuthority {
+  try {
+    const certificate = new X509Certificate(certPem);
+    const privateKey = createPrivateKey(keyPem), publicKey = createPublicKey(keyPem);
+    if (!certificate.ca || !certificate.checkPrivateKey(privateKey) || !certificate.verify(publicKey)
+      || certificate.subject !== certificate.issuer
+      || !commonName.startsWith("OpenCodex Codex Desktop ") || !certificate.subject.split("\n").includes(`CN=${commonName}`)) {
+      throw new Error("invalid");
+    }
+    const expiresAt = Date.parse(certificate.validTo), startsAt = Date.parse(certificate.validFrom);
+    if (!Number.isFinite(expiresAt) || !Number.isFinite(startsAt) || startsAt > now
+      || expiresAt - startsAt > (VALIDITY_DAYS + 1) * DAY) throw new Error("invalid");
+    if (expiresAt <= now && !allowExpired) throw new DesktopAuthorityError("expired");
+    if (!allowExpired && !isServerAuthOnlyCertificate(certificate)) throw new DesktopAuthorityError("renewal_required");
+    return { authority: { certPem, keyPem, privateKey, publicKey }, commonName,
+      fingerprint: certificate.fingerprint256.replaceAll(":", ""), expiresAt,
+      renewalDue: expiresAt - now <= 7 * DAY, reused };
+  } catch (error) {
+    if (error instanceof DesktopAuthorityError) throw error;
+    throw new DesktopAuthorityError("unreadable");
+  }
+}
+
+async function readAuthority(path: string, protection: AuthorityKeyProtection, now: number, allowExpired = false): Promise<StoredDesktopAuthority> {
+  assertPath(path, false);
+  await hardenSecretPathAsync(path, { required: true });
+  assertPath(path, false);
+  let cleartext: Uint8Array | undefined;
+  try {
+    const saved = JSON.parse(readFileSync(path, "utf8"));
+    if (saved.version !== 1 || saved.protection !== "windows-current-user-dpapi"
+      || typeof saved.certPem !== "string" || typeof saved.sealed !== "string"
+      || !/^[A-Za-z0-9+/]+={0,2}$/.test(saved.sealed) || saved.sealed.length > MAX_FILE) throw new Error("invalid");
+    cleartext = await protection.unprotect(Buffer.from(saved.sealed, "base64"));
+    const secret = JSON.parse(Buffer.from(cleartext).toString("utf8"));
+    if (secret.policy !== POLICY || secret.certSha256 !== digest(saved.certPem)
+      || typeof secret.keyPem !== "string" || typeof secret.commonName !== "string") throw new Error("invalid");
+    return validatedAuthority(saved.certPem, secret.keyPem, secret.commonName, now, true, allowExpired);
+  } catch (error) {
+    if (error instanceof DesktopAuthorityError) throw error;
+    // A corrupt or foreign-user key never silently regenerates a new root or trust prompt.
+    throw new DesktopAuthorityError("unreadable");
+  } finally { cleartext?.fill(0); }
+}
+
+/** Loads only existing state. Expired or legacy-purpose keys may be loaded solely for trust removal/renewal. */
+export async function loadDesktopCompatibilityAuthority(options: DesktopAuthorityStoreOptions, allowExpiredForRemoval = false): Promise<StoredDesktopAuthority> {
+  if (!isAbsolute(options.directory)) throw new DesktopAuthorityError("unsafe_path");
+  const now = options.now?.() ?? Date.now();
+  if (!Number.isFinite(now)) throw new DesktopAuthorityError("unreadable");
+  assertPath(options.directory, true);
+  const path = join(options.directory, FILE);
+  if (!pathPresent(path)) throw new DesktopAuthorityError("unreadable");
+  return readAuthority(path, options.protection ?? windowsAuthorityKeyProtection, now, allowExpiredForRemoval);
+}
+
+/** Reuses one user-protected root across restarts; never installs, rotates or removes trust. */
+export async function ensureDesktopCompatibilityAuthority(options: DesktopAuthorityStoreOptions): Promise<StoredDesktopAuthority> {
+  return publishAuthority(options);
+}
+
+/** Deliberate replacement after the caller has removed OS trust and stopped consumers. */
+export async function renewDesktopCompatibilityAuthority(options: DesktopAuthorityStoreOptions, expectedFingerprint: string): Promise<StoredDesktopAuthority> {
+  if (!/^[A-F0-9]{64}$/.test(expectedFingerprint)) throw new DesktopAuthorityError("fingerprint_changed");
+  return publishAuthority(options, expectedFingerprint);
+}
+
+async function publishAuthority(options: DesktopAuthorityStoreOptions, expectedFingerprint?: string): Promise<StoredDesktopAuthority> {
+  if (!isAbsolute(options.directory)) throw new DesktopAuthorityError("unsafe_path");
+  if (!options.protection && process.platform !== "win32") throw new Error("desktop_compatibility_windows_required");
+  const now = options.now?.() ?? Date.now();
+  if (!Number.isFinite(now)) throw new DesktopAuthorityError("unreadable");
+  const protection = options.protection ?? windowsAuthorityKeyProtection;
+  mkdirSync(options.directory, { recursive: true, mode: 0o700 });
+  assertPath(options.directory, true);
+  await hardenSecretDirAsync(options.directory, { required: true });
+  return withClientLifecycle(async () => {
+    assertPath(options.directory, true);
+    const path = join(options.directory, FILE);
+    let original: string | undefined;
+    if (expectedFingerprint !== undefined) {
+      if (!pathPresent(path)) throw new DesktopAuthorityError("fingerprint_changed");
+      const previous = await readAuthority(path, protection, now, true);
+      if (previous.fingerprint !== expectedFingerprint) throw new DesktopAuthorityError("fingerprint_changed");
+      original = readFileSync(path, "utf8");
+    } else if (pathPresent(path)) return readAuthority(path, protection, now);
+    const commonName = `OpenCodex Codex Desktop ${randomUUID()}`;
+    const authority = createCertificateAuthority({ commonName, validityDays: VALIDITY_DAYS,
+      permittedDnsNames: ["chatgpt.com"], excludeAllIpAddresses: true, serverAuthOnly: true });
+    const cleartext = Buffer.from(JSON.stringify({ policy: POLICY, certSha256: digest(authority.certPem), commonName, keyPem: authority.keyPem }));
+    let sealed: Uint8Array;
+    try { sealed = await protection.protect(cleartext); }
+    catch { throw new DesktopAuthorityError("protection_failed"); }
+    finally { cleartext.fill(0); }
+    if (sealed.byteLength === 0 || sealed.byteLength > 65_536) throw new DesktopAuthorityError("protection_failed");
+    const contents = JSON.stringify({ version: 1, protection: "windows-current-user-dpapi", certPem: authority.certPem,
+      sealed: Buffer.from(sealed).toString("base64") });
+    const temporary = join(options.directory, `authority-${randomUUID()}.tmp`);
+    let created = false;
+    try {
+      const fd = openSync(temporary, "wx", 0o600); created = true;
+      try { writeFileSync(fd, contents); fsyncSync(fd); } finally { closeSync(fd); }
+      await hardenSecretPathAsync(temporary, { required: true });
+      assertPath(temporary, false); assertPath(options.directory, true);
+      // Verify the new encrypted envelope before replacing the only recovery source.
+      await readAuthority(temporary, protection, now);
+      if (original !== undefined) {
+        assertPath(path, false);
+        if (readFileSync(path, "utf8") !== original) throw new DesktopAuthorityError("fingerprint_changed");
+      } else if (pathPresent(path)) throw new DesktopAuthorityError("unsafe_path");
+      renameSync(temporary, path); created = false;
+      // Read back the actual persisted pair before reporting a successful setup.
+      const persisted = await readAuthority(path, protection, now);
+      return { ...persisted, reused: false };
+    } finally { if (created) unlinkSync(temporary); }
+  }, { lockPath: join(options.directory, "authority-publication.sqlite") });
+}

package/src/codex/desktop-compatibility/connection-store.ts

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { withClientLifecycle } from "../../client/lifecycle-lock";
+import { hardenSecretDirAsync, hardenSecretPathAsync } from "../../lib/windows-secret-acl";
+
+export interface DesktopConnectionIdentity {
+  version: 1;
+  id: string;
+  connectPort: number;
+  pacPort: number;
+}
+export interface DesktopConnectionStore {
+  read(): DesktopConnectionIdentity | null;
+  publish(value: DesktopConnectionIdentity): Promise<DesktopConnectionIdentity>;
+}
+const FILE = "connection.json";
+const fail = (reason: "invalid" | "changed" | "cleanup_required", cause?: unknown) => new Error(`desktop_compatibility_connection_${reason}`, { cause });
+const port = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) >= 1024 && Number(value) <= 65535;
+function validate(value: unknown): DesktopConnectionIdentity {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw fail("invalid");
+  const row = value as Record<string, unknown>;
+  if (Object.keys(row).length !== 4 || row.version !== 1 || typeof row.id !== "string"
+    || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(row.id)
+    || !port(row.connectPort) || !port(row.pacPort) || row.connectPort === row.pacPort) throw fail("invalid");
+  return { version: 1, id: row.id, connectPort: row.connectPort, pacPort: row.pacPort };
+}
+function assertPath(path: string, directory: boolean): void {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1 || stat.size > 4096)) throw fail("invalid");
+}
+function present(path: string): boolean {
+  try { lstatSync(path); return true; }
+  catch (error) { if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return false; throw fail("invalid"); }
+}
+function same(left: DesktopConnectionIdentity, right: DesktopConnectionIdentity): boolean {
+  return left.version === right.version && left.id === right.id && left.connectPort === right.connectPort && left.pacPort === right.pacPort;
+}
+
+/** Public endpoint identity only. No token, account, private key or expiry is persisted here. */
+export function createDesktopConnectionStore(directory: string): DesktopConnectionStore {
+  if (!isAbsolute(directory)) throw fail("invalid");
+  const path = join(directory, FILE);
+  const read = (): DesktopConnectionIdentity | null => {
+    try {
+      if (!present(directory)) return null;
+      assertPath(directory, true);
+      if (!present(path)) return null;
+      assertPath(path, false);
+      return validate(JSON.parse(readFileSync(path, "utf8")));
+    } catch { throw fail("invalid"); }
+  };
+  const verifyExisting = (value: DesktopConnectionIdentity): DesktopConnectionIdentity | null => {
+    const existing = read();
+    if (existing && !same(existing, value)) throw fail("changed");
+    return existing;
+  };
+  return { read, async publish(input) {
+    const value = validate(input);
+    const existing = verifyExisting(value); if (existing) return existing;
+    // A trusted authority must already own this directory. Never create a replacement home.
+    assertPath(directory, true); await hardenSecretDirAsync(directory, { required: true });
+    return withClientLifecycle(async () => {
+      const raced = verifyExisting(value); if (raced) return raced;
+      const temporary = join(directory, `connection-${randomUUID()}.tmp`);
+      let created = false;
+      try {
+        const fd = openSync(temporary, "wx", 0o600); created = true;
+        try { writeFileSync(fd, JSON.stringify(value)); fsyncSync(fd); } finally { closeSync(fd); }
+        await hardenSecretPathAsync(temporary, { required: true });
+        assertPath(directory, true); assertPath(temporary, false);
+        // Create-only publication cannot overwrite another process's endpoint identity.
+        try { linkSync(temporary, path); }
+        catch (error) {
+          const winner = verifyExisting(value); if (!winner) throw error;
+        }
+        unlinkSync(temporary); created = false;
+        const published = verifyExisting(value); if (!published) throw fail("changed");
+        return published;
+      } catch (error) {
+        try { if (created && present(temporary)) unlinkSync(temporary); }
+        catch (cleanupError) { throw fail("cleanup_required", new AggregateError([error, cleanupError], "Endpoint publication and cleanup failed")); }
+        throw error;
+      }
+    }, { lockPath: join(directory, "connection-publication.sqlite") });
+  } };
+}