@bitkyc08/opencodex 2.78.0 → 2.80.0

package/src/claude/intercept/local-ca-files.ts

@@ -0,0 +1,265 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, type BigIntStats } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { withClientLifecycleSync } from "../../client/lifecycle-lock";
+import { forgetEphemeralSecretPath, hardenSecretDir, hardenSecretPath, windowsSecretAclApplies } from "../../lib/windows-secret-acl";
+import { assertLocalCaWindowsAcl } from "./local-ca-windows";
+
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const NONBLOCK = constants.O_NONBLOCK ?? 0;
+const MAX_PEM_BYTES = 64 * 1024;
+const KEY = "ca.key";
+const CERT = "ca.pem";
+type FileMode = 0o600 | 0o644;
+type AclLevel = "owner" | "inherited" | "private";
+type AclCheck = ((path: string, stat: BigIntStats, level?: AclLevel) => void) & { forget(stat: BigIntStats): void };
+type FileHooks = { beforeRead?: (path: string) => void; beforeWrite?: (path: string) => void; beforePublish?: (path: string) => void };
+let hooks: FileHooks = {};
+/** Boundary fault injection for substitution and zero-secret-write assertions. */
+export function setLocalCaFileHooksForTests(next: FileHooks | null): void { hooks = next ?? {}; }
+
+function unsafe(): Error {
+  return Object.assign(new Error("Local CA requires safe owner-controlled files and directory"), { code: "local_ca_path_unsafe" });
+}
+function missing(error: unknown): boolean { return (error as NodeJS.ErrnoException)?.code === "ENOENT"; }
+function owned(stat: BigIntStats, directory = false, mode: FileMode = 0o600): void {
+  if (stat.isSymbolicLink() || !(directory ? stat.isDirectory() : stat.isFile() && stat.nlink === 1n)) throw unsafe();
+  if (!windowsSecretAclApplies()) {
+    if (typeof process.geteuid !== "function" || stat.uid !== BigInt(process.geteuid())) throw unsafe();
+    const forbidden = directory || mode === 0o600 ? 0o077 : 0o022;
+    if ((Number(stat.mode) & forbidden) !== 0) throw unsafe();
+  }
+}
+function same(path: string, expected: BigIntStats, directory = false, mode: FileMode = 0o600): BigIntStats {
+  const stat = lstatSync(path, { bigint: true });
+  owned(stat, directory, mode);
+  if (stat.dev !== expected.dev || stat.ino !== expected.ino || stat.ino === 0n) throw unsafe();
+  return stat;
+}
+function inspect(path: string, mode: FileMode, checkAcl: AclCheck, sqliteSidecar = false): BigIntStats | null {
+  let stat: BigIntStats;
+  try { stat = lstatSync(path, { bigint: true }); } catch (error) { if (missing(error)) return null; throw error; }
+  owned(stat, false, mode);
+  if (windowsSecretAclApplies()) {
+    if (sqliteSidecar) checkAcl(path, stat, "inherited");
+    else {
+      try { checkAcl(path, stat); }
+      catch {
+        // Legacy files may inherit only trusted grants; verify before narrowing.
+        checkAcl(path, stat, "inherited");
+        same(path, stat, false, mode);
+        hardenSecretPath(path, { required: true });
+        same(path, stat, false, mode);
+        checkAcl(path, stat);
+      }
+    }
+  }
+  same(path, stat, false, mode);
+  return stat;
+}
+
+function protectNew(path: string, fd: number, mode: FileMode, checkAcl: AclCheck): void {
+  const created = fstatSync(fd, { bigint: true });
+  owned(created, false, mode);
+  if (windowsSecretAclApplies()) {
+    // Only O_CREAT|O_EXCL entries reach here. Narrow the empty file we created,
+    // then strictly verify before writing; an Administrators default owner still fails closed.
+    same(path, created, false, mode);
+    hardenSecretPath(path, { required: true });
+    checkAcl(path, created);
+  } else fchmodSync(fd, mode);
+  same(path, created, false, mode);
+}
+
+function readPinned(path: string, expected: BigIntStats, mode: FileMode, assertDirectory: () => void, checkAcl: AclCheck): string {
+  hooks.beforeRead?.(path);
+  assertDirectory();
+  same(path, expected, false, mode);
+  const fd = openSync(path, constants.O_RDONLY | NOFOLLOW | NONBLOCK);
+  try {
+    const opened = fstatSync(fd, { bigint: true });
+    owned(opened, false, mode);
+    if (opened.dev !== expected.dev || opened.ino !== expected.ino || opened.size > BigInt(MAX_PEM_BYTES)) throw unsafe();
+    checkAcl(path, opened);
+    same(path, opened, false, mode);
+    const bytes = Buffer.alloc(MAX_PEM_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(fd, bytes, length, bytes.length - length, length);
+      if (!count) break;
+      length += count;
+    }
+    const after = fstatSync(fd, { bigint: true });
+    owned(after, false, mode);
+    if (length > MAX_PEM_BYTES || BigInt(length) !== after.size || after.mtimeNs !== opened.mtimeNs || after.ctimeNs !== opened.ctimeNs) throw unsafe();
+    same(path, opened, false, mode);
+    assertDirectory();
+    return bytes.subarray(0, length).toString("utf8");
+  } finally { closeSync(fd); }
+}
+
+export interface LocalCaFiles {
+  readPair(): { certPem: string; keyPem: string } | null;
+  writePair(pair: { certPem: string; keyPem: string }): void;
+}
+
+function stage(path: string, contents: string, mode: FileMode, assertDirectory: () => void, checkAcl: AclCheck): { publish(): void; dispose(): void } {
+  assertDirectory();
+  const previous = inspect(path, mode, checkAcl);
+  const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(16).toString("hex")}.tmp`);
+  const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW | NONBLOCK, mode);
+  let created: BigIntStats;
+  try { created = fstatSync(fd, { bigint: true }); }
+  catch (error) { closeSync(fd); throw error; }
+  let closed = false;
+  let removed = false;
+  const dispose = (): void => {
+    if (!closed) { closed = true; closeSync(fd); }
+    if (removed) return;
+    try { same(temp, created, false, mode); unlinkSync(temp); removed = true; }
+    catch (error) { if (missing(error)) removed = true; else throw error; }
+    if (removed) { checkAcl.forget(created); forgetEphemeralSecretPath(temp); }
+  };
+  try {
+    protectNew(temp, fd, mode, checkAcl);
+    assertDirectory();
+    hooks.beforeWrite?.(temp);
+    same(temp, created, false, mode);
+    assertDirectory();
+    checkAcl(temp, created);
+    writeFileSync(fd, contents, { encoding: "utf8" });
+    same(temp, created, false, mode);
+    return {
+      publish() {
+        hooks.beforePublish?.(path);
+        assertDirectory();
+        same(temp, created, false, mode);
+        checkAcl(temp, created);
+        const current = inspect(path, mode, checkAcl);
+        if (previous ? !current || previous.dev !== current.dev || previous.ino !== current.ino : current !== null) throw unsafe();
+        renameSync(temp, path);
+        if (current) checkAcl.forget(current);
+        removed = true;
+        forgetEphemeralSecretPath(temp);
+        same(path, created, false, mode);
+        assertDirectory();
+      },
+      dispose,
+    };
+  } catch (error) {
+    try { dispose(); } catch { /* preserve safety failure; never remove a substituted path */ }
+    throw error;
+  }
+}
+
+/** Guard every CA entry before SQLite or PEM access. The directory and lock stay pinned. */
+export function withLocalCaPublication<T>(dir: string, lockName: string, work: (files: LocalCaFiles) => T): T {
+  if (basename(lockName) !== lockName || [KEY, CERT, ".", ".."].includes(lockName)) throw unsafe();
+  mkdirSync(dirname(dir), { recursive: true, mode: 0o700 });
+  let created = false;
+  try { mkdirSync(dir, { mode: 0o700 }); created = true; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+  // Publication-local only: a private DACL can be changed only by the owner,
+  // SYSTEM or Administrators. Every memo hit still checks lstat identity via same().
+  // bigint birthtimeNs adds discrimination for recycled SQLite sidecar file IDs; it is not a
+  // uniqueness guarantee (NTFS tunneling can restore creation times). Safety rests on the
+  // verified-private directory DACL. Creation time survives same-volume rename, so staged
+  // entries keep their memo.
+  const verified = new Map<string, AclLevel>();
+  const strength = { owner: 0, inherited: 1, private: 2 };
+  const checkAcl: AclCheck = Object.assign((path: string, stat: BigIntStats, level: AclLevel = "private") => {
+    if (!windowsSecretAclApplies()) return;
+    const identity = same(path, stat, stat.isDirectory());
+    const key = `${identity.dev}:${identity.ino}:${identity.birthtimeNs}`;
+    const prior = verified.get(key);
+    if (prior !== undefined && strength[prior] >= strength[level]) return;
+    assertLocalCaWindowsAcl(path, level);
+    same(path, stat, stat.isDirectory());
+    verified.set(key, level);
+  }, {
+    // An identity this publication unlinked or replaced is retired; a recycled id must be re-inspected.
+    forget(stat: BigIntStats): void { verified.delete(`${stat.dev}:${stat.ino}:${stat.birthtimeNs}`); },
+  });
+  const directory = lstatSync(dir, { bigint: true });
+  owned(directory, true);
+  const dirFd = windowsSecretAclApplies() ? null : openSync(dir, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | NOFOLLOW);
+  let lockFd: number | undefined;
+  try {
+    if (dirFd !== null) {
+      const opened = fstatSync(dirFd, { bigint: true });
+      if (opened.dev !== directory.dev || opened.ino !== directory.ino) throw unsafe();
+      owned(opened, true);
+    } else {
+      let needsHardening = created;
+      // A successful mkdir created this directory; strict verification after narrowing
+      // still refuses an Administrators default owner before any CA access.
+      if (!created) {
+        try { checkAcl(dir, directory); }
+        catch { checkAcl(dir, directory, "inherited"); needsHardening = true; }
+      }
+      if (needsHardening) {
+        same(dir, directory, true);
+        hardenSecretDir(dir, { required: true });
+        same(dir, directory, true);
+        checkAcl(dir, directory);
+      }
+    }
+    const assertDirectory = (): void => { same(dir, directory, true); };
+    assertDirectory();
+    const lockPath = join(dir, lockName);
+    const assertEntries = (): void => {
+      assertDirectory();
+      inspect(join(dir, KEY), 0o600, checkAcl);
+      inspect(join(dir, CERT), 0o644, checkAcl);
+      inspect(lockPath, 0o600, checkAcl);
+      // SQLite creates sidecars itself, inheriting only the protected directory's
+      // current-user ACE. Inspect every grant and owner; an inherited DACL is valid here.
+      for (const suffix of ["-journal", "-wal", "-shm"]) inspect(`${lockPath}${suffix}`, 0o600, checkAcl, true);
+      assertDirectory();
+    };
+    assertEntries();
+    try {
+      lockFd = openSync(lockPath, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | NOFOLLOW | NONBLOCK, 0o600);
+      protectNew(lockPath, lockFd, 0o600, checkAcl);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const existing = inspect(lockPath, 0o600, checkAcl);
+      if (!existing) throw unsafe();
+      lockFd = openSync(lockPath, constants.O_RDONLY | NOFOLLOW | NONBLOCK);
+      const opened = fstatSync(lockFd, { bigint: true });
+      owned(opened);
+      if (opened.dev !== existing.dev || opened.ino !== existing.ino) throw unsafe();
+    }
+    const lock = fstatSync(lockFd, { bigint: true });
+    assertEntries();
+    same(lockPath, lock);
+    return withClientLifecycleSync(() => {
+      same(lockPath, lock);
+      assertEntries();
+      const files: LocalCaFiles = {
+        readPair() {
+          assertEntries();
+          const cert = inspect(join(dir, CERT), 0o644, checkAcl);
+          const key = inspect(join(dir, KEY), 0o600, checkAcl);
+          if (!cert || !key) return null;
+          return { certPem: readPinned(join(dir, CERT), cert, 0o644, assertDirectory, checkAcl), keyPem: readPinned(join(dir, KEY), key, 0o600, assertDirectory, checkAcl) };
+        },
+        writePair(pair) {
+          assertEntries();
+          const key = stage(join(dir, KEY), pair.keyPem, 0o600, assertDirectory, checkAcl);
+          let cert: ReturnType<typeof stage> | undefined;
+          try {
+            cert = stage(join(dir, CERT), pair.certPem, 0o644, assertDirectory, checkAcl);
+            assertEntries();
+            key.publish();
+            cert.publish();
+          } finally { try { key.dispose(); } finally { cert?.dispose(); } }
+        },
+      };
+      const value = work(files);
+      same(lockPath, lock);
+      assertEntries();
+      return value;
+    }, { lockPath });
+  } finally { try { if (lockFd !== undefined) closeSync(lockFd); } finally { if (dirFd !== null) closeSync(dirFd); } }
+}

package/src/claude/intercept/local-ca-windows.ts

@@ -0,0 +1,73 @@
+/** Strict local-CA policy layered on the shared Windows ACL hardener. */
+import { resolveTrustedWindowsPowerShellExe } from "../../lib/windows-elevation";
+import { resolveCurrentWindowsPrincipal, WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS } from "../../lib/windows-user-principal";
+import type { IcaclsResult } from "../../lib/windows-secret-acl";
+
+type AclRunner = (path: string, timeoutMs: number) => IcaclsResult;
+const MAX_ACL_BYTES = 64 * 1024;
+const SID = /^S-1-(?:\d+-)+\d+$/i;
+
+function nativeAclRunner(path: string, timeoutMs: number): IcaclsResult {
+  // Encode the path as data, not PowerShell syntax. SID-form rules avoid localized account names.
+  // .NET only: Get-Acl/ConvertTo-Json/ForEach-Object are module-autoloaded cmdlets, and
+  // autoload resolves them through the per-profile module analysis cache. With a fresh or
+  // redirected LOCALAPPDATA that rebuild scans every PSModulePath module and can exceed the
+  // inspection budget (hosted Windows runners: 30 s timeouts during `ocx start`); it also lets
+  // a module earlier on PSModulePath shadow the cmdlet. SIDs, ints and booleans need no escaping;
+  // the JSON quote is [char]34 so the -Command argument carries no double quotes to re-parse.
+  const encodedPath = Buffer.from(path, "utf8").toString("base64");
+  const script = [
+    "$ErrorActionPreference='Stop'",
+    `$p=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))`,
+    "$s=[System.Security.Principal.SecurityIdentifier]",
+    "$q=[char]34",
+    "$c=[System.Security.AccessControl.AccessControlSections]'Owner,Access'",
+    "if([System.IO.Directory]::Exists($p)){$a=[System.Security.AccessControl.DirectorySecurity]::new($p,$c)}else{$a=[System.Security.AccessControl.FileSecurity]::new($p,$c)}",
+    "$r=foreach($x in $a.GetAccessRules($true,$true,$s)){'{'+$q+'sid'+$q+':'+$q+$x.IdentityReference.Value+$q+','+$q+'type'+$q+':'+[int]$x.AccessControlType+','+$q+'rights'+$q+':'+[long]$x.FileSystemRights+'}'}",
+    "$o='{'+$q+'owner'+$q+':'+$q+$a.GetOwner($s).Value+$q+','+$q+'protected'+$q+':'+$(if($a.AreAccessRulesProtected){'true'}else{'false'})+','+$q+'rules'+$q+':['+(@($r) -join ',')+']}'",
+    "[Console]::Out.Write($o)",
+    "[Console]::Out.Flush()",
+  ].join(";");
+  const result = Bun.spawnSync([resolveTrustedWindowsPowerShellExe(), "-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script], {
+    stdin: "ignore", stdout: "pipe", stderr: "ignore", timeout: timeoutMs, windowsHide: true,
+  });
+  return { success: result.success, exitCode: result.exitCode, timedOut: result.exitedDueToTimeout ?? false, stdout: result.stdout.toString("utf8") };
+}
+
+let aclRunner: AclRunner = nativeAclRunner;
+/** Native-result fault injection; production always uses the trusted bounded runner. */
+export function setLocalCaWindowsAclRunnerForTests(next: AclRunner | null): void {
+  aclRunner = next ?? nativeAclRunner;
+}
+
+export function assertLocalCaWindowsAcl(path: string, inspection: "owner" | "private" | "inherited" = "private"): void {
+  try {
+    const deadline = Date.now() + WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS;
+    const current = resolveCurrentWindowsPrincipal(deadline - Date.now()).replace(/^\*/, "").toUpperCase();
+    if (!SID.test(current)) throw new Error("invalid effective SID");
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new Error("ACL inspection deadline");
+    const result = aclRunner(path, remaining);
+    if (!result.success || result.timedOut || result.exitCode !== 0 || Buffer.byteLength(result.stdout) > MAX_ACL_BYTES) throw new Error("ACL inspection failed");
+    const acl: unknown = JSON.parse(result.stdout.replace(/^\uFEFF/, ""));
+    if (!acl || typeof acl !== "object" || !("owner" in acl) || !("protected" in acl) || !("rules" in acl)
+      || typeof acl.owner !== "string" || acl.owner.toUpperCase() !== current
+      || typeof acl.protected !== "boolean" || !Array.isArray(acl.rules)) throw new Error("unsafe ACL owner or shape");
+    // Newly created empty entries can inherit broad grants. Verify the owner
+    // before hardening, then require the complete private policy before use.
+    if (inspection === "owner") return;
+    if (inspection === "private" && !acl.protected) throw new Error("unprotected DACL");
+    const allowed = new Set([current, "S-1-5-18", "S-1-5-32-544"]);
+    if (acl.rules.length === 0) throw new Error("empty DACL");
+    for (const rule of acl.rules) {
+      if (!rule || typeof rule !== "object" || typeof rule.sid !== "string" || !SID.test(rule.sid)
+        || ![0, 1].includes(rule.type) || !Number.isSafeInteger(rule.rights) || rule.rights < 0 || rule.rights > 0xffffffff) throw new Error("ambiguous ACL rule");
+      // Reject every unexpected nonzero Allow ACE, including inherited and tamper-only grants.
+      // Deny ACEs confer no access. SYSTEM and built-in Administrators are the only exceptions.
+      if (rule.type === 0 && rule.rights !== 0 && !allowed.has(rule.sid.toUpperCase())) throw new Error("unexpected ACL principal");
+    }
+  } catch {
+    // Never expose path, raw ACL output, account names or native diagnostic text.
+    throw Object.assign(new Error("Local CA Windows owner/ACL inspection failed"), { code: "local_ca_path_unsafe" });
+  }
+}

package/src/claude/intercept/local-ca.ts

@@ -1,7 +1,6 @@
 import { createHash, generateKeyPairSync, createPrivateKey, createPublicKey, sign, X509Certificate, type KeyObject } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { withClientLifecycleSync } from "../../client/lifecycle-lock";
+import { withLocalCaPublication, type LocalCaFiles } from "./local-ca-files";
 
 /**
  * Local certificate authority for the Claude intercept listener.
@@ -307,7 +306,6 @@ export function issueLocalInterceptLeaf(ca: LocalInterceptCa, hosts: readonly st
 
 export const CLAUDE_INTERCEPT_STATE_DIR = "claude-intercept";
 export const CLAUDE_INTERCEPT_CA_CERT_FILE = "ca.pem";
-const CA_KEY_FILE = "ca.key";
 
 export function claudeInterceptStateDir(configDir: string): string {
   return join(configDir, CLAUDE_INTERCEPT_STATE_DIR);
@@ -318,50 +316,40 @@ export function claudeInterceptCaCertPath(configDir: string): string {
   return join(claudeInterceptStateDir(configDir), CLAUDE_INTERCEPT_CA_CERT_FILE);
 }
 
-function writeFileAtomic(path: string, contents: string, mode: number): void {
-  const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, contents, { mode });
-  try { chmodSync(tmp, mode); } catch { /* best-effort on platforms without POSIX modes */ }
-  renameSync(tmp, path);
-}
-
-function loadPersistedCa(dir: string, accept?: (cert: X509Certificate) => boolean): LocalInterceptCa | null {
-  const certPath = join(dir, CLAUDE_INTERCEPT_CA_CERT_FILE);
-  const keyPath = join(dir, CA_KEY_FILE);
-  if (!existsSync(certPath) || !existsSync(keyPath)) return null;
+function loadPersistedCa(files: LocalCaFiles, accept?: (cert: X509Certificate) => boolean): LocalInterceptCa | null {
+  // Filesystem safety and access errors must escape; only benign PEM corruption regenerates.
+  const pair = files.readPair();
+  if (!pair) return null;
+  const { certPem, keyPem } = pair;
   try {
-    const certPem = readFileSync(certPath, "utf8");
-    const keyPem = readFileSync(keyPath, "utf8");
     const privateKey = createPrivateKey(keyPem);
     const publicKey = createPublicKey(keyPem);
     const certificate = new X509Certificate(certPem);
     if (!certificate.ca || !certificate.checkPrivateKey(privateKey) || !certificate.verify(publicKey)
       || (accept && !accept(certificate))) return null;
     return { certPem, keyPem, publicKey, privateKey };
-  } catch { // no-excuse-ok: catch -- an unreadable or corrupt authority is regenerated below.
+  } catch { // no-excuse-ok: catch -- malformed PEM in validated owner-controlled files is regenerated below.
     return null;
   }
 }
 
-/** Persist an authority under its own lease, replacing unreadable or rejected pairs. */
+/** Persist an authority under its own lease, replacing corrupt or rejected safe pairs. */
 export function ensurePersistedAuthority(
   dir: string,
   options: AuthorityOptions,
   lockName = "ca-publication.sqlite",
   accept?: (cert: X509Certificate) => boolean,
 ): LocalInterceptCa {
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
   // A separate SQLite namespace binds exclusion to the explicit CA directory.
   // The OS releases it on crash; a contending caller fails before touching either
   // PEM. Readers also take the lease so they cannot observe half a publication.
-  return withClientLifecycleSync(() => {
-    const existing = loadPersistedCa(dir, accept);
+  return withLocalCaPublication(dir, lockName, files => {
+    const existing = loadPersistedCa(files, accept);
     if (existing) return existing;
     const ca = createCertificateAuthority(options);
-    writeFileAtomic(join(dir, CA_KEY_FILE), ca.keyPem, 0o600);
-    writeFileAtomic(join(dir, CLAUDE_INTERCEPT_CA_CERT_FILE), ca.certPem, 0o644);
+    files.writePair(ca);
     return ca;
-  }, { lockPath: join(dir, lockName) });
+  });
 }
 
 /** Preserve the original intercept CA path, name, permissions and extension set. */

package/src/claude/intercept/picker-ca-persistence.ts

@@ -0,0 +1,106 @@
+import { X509Certificate } from "node:crypto";
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync, realpathSync, rmSync, writeFileSync, type Stats } from "node:fs";
+import { join } from "node:path";
+import {
+  decodePickerCaCredential, openPickerCaCredential, pickerCaConfigId, readPickerCaCredential,
+  writePickerCaCredential, type PickerCaStore, type StoredPickerCa,
+} from "./picker-ca-store";
+
+const MAX_PUBLIC_STATE_BYTES = 64 * 1024;
+interface AuthorityMetadata { schema: 1; configId: string; fingerprint: string }
+interface Initialization extends AuthorityMetadata { predecessor: string | null }
+
+export function canonicalPickerConfigDir(configDir: string): string {
+  const canonical = realpathSync(configDir);
+  const stat = lstatSync(canonical);
+  if (!stat.isDirectory() || (process.platform !== "win32" && stat.uid !== process.getuid!())) {
+    throw new Error("picker_ca_config_unsafe");
+  }
+  return canonical;
+}
+
+/** Public records still cannot follow symlinks or accept oversized/malformed recovery data. */
+function readState(path: string, configId: string, initialization: boolean): Initialization | AuthorityMetadata | null {
+  let expected: Stats;
+  try { expected = lstatSync(path); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw new Error("picker_ca_metadata_unsafe"); }
+  if (expected.isSymbolicLink()) throw new Error("picker_ca_metadata_unsafe");
+  let fd: number;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw new Error("picker_ca_metadata_unsafe"); }
+  try {
+    const stat = fstatSync(fd);
+    if (stat.dev !== expected.dev || stat.ino !== expected.ino) throw new Error("picker_ca_metadata_unsafe");
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_PUBLIC_STATE_BYTES
+      || (process.platform !== "win32" && stat.uid !== process.getuid!())) throw new Error();
+    const bytes = Buffer.alloc(MAX_PUBLIC_STATE_BYTES + 1);
+    let used = 0;
+    while (used < bytes.length) {
+      const count = readSync(fd, bytes, used, bytes.length - used, null);
+      if (count === 0) break;
+      used += count;
+    }
+    if (used > MAX_PUBLIC_STATE_BYTES) throw new Error();
+    const raw = bytes.subarray(0, used).toString("utf8");
+    const value = JSON.parse(raw);
+    const keys = initialization ? "configId,fingerprint,predecessor,schema" : "configId,fingerprint,schema";
+    if (value === null || typeof value !== "object" || Array.isArray(value)
+      || Object.keys(value).sort().join(",") !== keys || value.schema !== 1 || value.configId !== configId
+      || typeof value.fingerprint !== "string" || !/^[A-F0-9]{64}$/.test(value.fingerprint)
+      || (initialization && value.predecessor !== null && typeof value.predecessor !== "string")) throw new Error();
+    if (initialization && value.predecessor !== null
+      && new X509Certificate(value.predecessor).toString() !== value.predecessor) throw new Error();
+    return value;
+  } catch (error) {
+    if (error instanceof Error && error.message === "picker_ca_metadata_unsafe") throw error;
+    throw new Error("picker_ca_metadata_invalid");
+  }
+  finally { closeSync(fd); }
+}
+
+export interface PersistentPickerCaOptions {
+  configDir: string;
+  stateDir: string;
+  store?: PickerCaStore;
+  acceptsAuthority: (pem: string) => boolean;
+  create: () => StoredPickerCa;
+  /** Refuses a different live predecessor BEFORE the journal or credential can be written. */
+  predecessor: (ca: StoredPickerCa) => string | null;
+  publish: (ca: StoredPickerCa, predecessor: string | null) => void;
+  publishMetadata: (path: string, value: string) => void;
+}
+
+/** Caller holds the canonical picker CA lease throughout the store/publication transaction. */
+export function ensurePersistentPickerCa(options: PersistentPickerCaOptions): StoredPickerCa {
+  const configId = pickerCaConfigId(options.configDir);
+  const metadataPath = join(options.stateDir, "authority.json");
+  const journalPath = join(options.stateDir, "authority-init.json");
+  const metadata = readState(metadataPath, configId, false);
+  let journal = readState(journalPath, configId, true) as Initialization | null;
+  const entry = openPickerCaCredential(configId, options.store);
+  const raw = readPickerCaCredential(entry);
+  let ca: StoredPickerCa;
+  if (raw === null) {
+    if (metadata || journal) throw new Error("picker_ca_store_missing");
+    ca = options.create();
+    const predecessor = options.predecessor(ca);
+    journal = { schema: 1, configId, fingerprint: ca.fingerprint, predecessor };
+    // Exclusive evidence is durable before ANY credential mutation. Never erase it on failure.
+    writeFileSync(journalPath, JSON.stringify(journal) + "\n", { flag: "wx", mode: 0o600 });
+    writePickerCaCredential(entry, configId, ca);
+  } else {
+    ca = decodePickerCaCredential(raw, configId, options.acceptsAuthority);
+    if ((!metadata && !journal) || (metadata && metadata.fingerprint !== ca.fingerprint)
+      || (journal && journal.fingerprint !== ca.fingerprint)) throw new Error("picker_ca_metadata_mismatch");
+    const predecessor = options.predecessor(ca);
+    if (journal) {
+      // A crash may have published the new certificate already, but no different predecessor
+      // may be adopted under an existing journal. Public evidence must be exact and key-free.
+      if (predecessor !== null && predecessor !== journal.predecessor) throw new Error("picker_ca_metadata_mismatch");
+    } else if (predecessor !== null) throw new Error("picker_ca_metadata_mismatch");
+  }
+  options.publishMetadata(metadataPath, JSON.stringify({ schema: 1, configId, fingerprint: ca.fingerprint }) + "\n");
+  options.publish(ca, journal?.predecessor ?? null);
+  if (journal) rmSync(journalPath); // Last: store, metadata, certificate, owner, and cleanup evidence now exist.
+  return ca;
+}

package/src/claude/intercept/picker-ca-startup.ts

@@ -0,0 +1,16 @@
+import { ensurePickerCa, type PickerCa } from "./picker-ca";
+import { drainPendingPickerCaUntrust } from "./picker-ca-cleanup";
+import type { PickerCaStore } from "./picker-ca-store";
+import type { SecurityRunner } from "./picker-trust";
+
+/** Internal activation seam: finish legacy cleanup before a persistent issuer is usable. */
+export async function preparePersistentPickerAuthority(options: {
+  configDir: string; store?: PickerCaStore; security?: SecurityRunner; platform: NodeJS.Platform;
+}): Promise<PickerCa> {
+  if (options.platform !== "darwin") throw new Error("picker_ca_unsupported_platform");
+  const drain = () => drainPendingPickerCaUntrust(options.configDir, options.security, options.platform);
+  if (!await drain()) throw new Error("picker_ca_pending_untrust");
+  const ca = ensurePickerCa(options.configDir, { rotation: "startup", persistent: true, store: options.store });
+  if (!await drain()) throw new Error("picker_ca_pending_untrust");
+  return ca;
+}

package/src/claude/intercept/picker-ca-store.ts

@@ -0,0 +1,70 @@
+import { createHash, createPrivateKey, createPublicKey, X509Certificate } from "node:crypto";
+import { loadKeyringBinding } from "../../lib/keyring-native";
+import type { LocalInterceptCa } from "./local-ca";
+
+export const PICKER_CA_STORE_SERVICE = "opencodex.claude-desktop-picker.ca.v1";
+const MAX_PAYLOAD_BYTES = 16 * 1024;
+export interface PickerCaCredential {
+  getPassword(): string | null;
+  setPassword(value: string): void;
+}
+export type PickerCaStore = (service: string, account: string) => PickerCaCredential;
+export interface StoredPickerCa extends LocalInterceptCa { fingerprint: string }
+
+export function pickerCaConfigId(canonicalConfigDir: string): string {
+  return createHash("sha256").update(canonicalConfigDir).digest("hex");
+}
+
+function nativeStore(service: string, account: string): PickerCaCredential {
+  const { Entry } = loadKeyringBinding();
+  // The shared loader is deliberately binding-agnostic; this is the sync Entry contract.
+  return new Entry(service, account) as PickerCaCredential;
+}
+
+export function openPickerCaCredential(configId: string, store: PickerCaStore = nativeStore): PickerCaCredential {
+  try { return store(PICKER_CA_STORE_SERVICE, configId); }
+  catch { throw new Error("picker_ca_store_unavailable"); }
+}
+
+export function readPickerCaCredential(entry: PickerCaCredential): string | null {
+  try {
+    const value = entry.getPassword();
+    if (value === null) return null;
+    if (typeof value !== "string") throw new Error();
+    return value;
+  } catch { throw new Error("picker_ca_store_unavailable"); }
+}
+
+/** OS credential contents are an untrusted, bounded, exact-shape boundary. */
+export function decodePickerCaCredential(
+  raw: string, configId: string, acceptsAuthority: (pem: string) => boolean,
+): StoredPickerCa {
+  try {
+    if (Buffer.byteLength(raw) > MAX_PAYLOAD_BYTES) throw new Error();
+    const value = JSON.parse(raw);
+    if (value === null || typeof value !== "object" || Array.isArray(value)
+      || Object.keys(value).sort().join(",") !== "certPem,configId,fingerprint,keyPem,schema"
+      || value.schema !== 1 || value.configId !== configId
+      || typeof value.certPem !== "string" || typeof value.keyPem !== "string"
+      || typeof value.fingerprint !== "string" || !/^[A-F0-9]{64}$/.test(value.fingerprint)) throw new Error();
+    const cert = new X509Certificate(value.certPem);
+    const privateKey = createPrivateKey(value.keyPem);
+    const publicKey = createPublicKey(value.keyPem);
+    const now = Date.now();
+    if (cert.toString() !== value.certPem || !acceptsAuthority(value.certPem)
+      || !cert.ca || !cert.checkPrivateKey(privateKey) || !cert.verify(publicKey)
+      || privateKey.asymmetricKeyType !== "ec" || privateKey.asymmetricKeyDetails?.namedCurve !== "prime256v1"
+      || privateKey.export({ type: "pkcs8", format: "pem" }) !== value.keyPem
+      || !(Date.parse(cert.validFrom) <= now && now < Date.parse(cert.validTo))
+      || createHash("sha256").update(cert.raw).digest("hex").toUpperCase() !== value.fingerprint) throw new Error();
+    return { certPem: value.certPem, keyPem: value.keyPem, fingerprint: value.fingerprint, privateKey, publicKey };
+  } catch { throw new Error("picker_ca_store_invalid"); }
+}
+
+export function writePickerCaCredential(entry: PickerCaCredential, configId: string, ca: StoredPickerCa): void {
+  const raw = JSON.stringify({ schema: 1, configId, fingerprint: ca.fingerprint, certPem: ca.certPem, keyPem: ca.keyPem });
+  if (Buffer.byteLength(raw) > MAX_PAYLOAD_BYTES) throw new Error("picker_ca_store_invalid");
+  try { entry.setPassword(raw); }
+  catch { throw new Error("picker_ca_store_unavailable"); }
+  if (readPickerCaCredential(entry) !== raw) throw new Error("picker_ca_store_readback_failed");
+}