@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/claude/intercept/connect-proxy.ts

@@ -0,0 +1,179 @@
+import { BlockList, createServer, connect, isIP, type Server, type Socket } from "node:net";
+
+/**
+ * Loopback HTTP CONNECT proxy for Claude Code.
+ *
+ * Claude Code honours `HTTPS_PROXY` and opens `CONNECT <host>:443` for every upstream. This
+ * proxy splices tunnels for the intercepted hosts onto the local TLS listener (which holds a
+ * leaf certificate for them) and blindly relays every other tunnel to its real destination,
+ * so telemetry, OAuth refresh and claude.ai traffic stay native and opaque to opencodex.
+ *
+ * Only CONNECT is served. Plain proxied HTTP requests are refused: Claude Code never sends
+ * them, and answering them would turn this socket into a generic forward proxy.
+ */
+
+export const CLAUDE_INTERCEPT_HOSTS = ["api.anthropic.com"] as const;
+
+const MAX_HEAD_BYTES = 8 * 1024;
+const HEAD_TIMEOUT_MS = 10_000;
+const UPSTREAM_CONNECT_TIMEOUT_MS = 15_000;
+
+export interface ConnectProxyOptions {
+  /** Loopback port of the TLS listener that terminates intercepted tunnels. */
+  interceptPort: number;
+  /** Hostnames (lowercase) whose 443 tunnels are spliced onto `interceptPort`. */
+  interceptHosts?: readonly string[];
+  /** Test seam: dial the real destination for a blind tunnel. */
+  dialUpstream?: (host: string, port: number) => Socket;
+}
+
+export interface ConnectProxyHandle {
+  port: number;
+  close(): Promise<void>;
+}
+
+interface ConnectTarget {
+  host: string;
+  port: number;
+}
+
+/** Parse `CONNECT host:port HTTP/1.1` from a request head; `null` for anything else. */
+export function parseConnectRequestLine(head: string): ConnectTarget | null {
+  const requestLine = head.split("\r\n", 1)[0] ?? "";
+  const match = /^CONNECT\s+(\S+)\s+HTTP\/1\.[01]$/.exec(requestLine);
+  if (!match) return null;
+  const authority = match[1]!;
+  // Bracketed IPv6 (`[::1]:443`) and plain `host:port`.
+  const ipv6 = /^\[([^\]]+)\]:(\d{1,5})$/.exec(authority);
+  const hostPort = ipv6 ?? /^([^:]+):(\d{1,5})$/.exec(authority);
+  if (!hostPort) return null;
+  const port = Number(hostPort[2]);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  return { host: hostPort[1]!.toLowerCase().replace(/\.$/, ""), port };
+}
+
+// 127/8 and ::1, which `BlockList` also matches in IPv4-mapped form (`::ffff:127.0.0.1`,
+// `::ffff:7f00:1`). The unspecified addresses dial the local host too.
+const LOCAL_TARGETS = new BlockList();
+LOCAL_TARGETS.addSubnet("127.0.0.0", 8, "ipv4");
+LOCAL_TARGETS.addAddress("0.0.0.0", "ipv4");
+LOCAL_TARGETS.addAddress("::1", "ipv6");
+LOCAL_TARGETS.addAddress("::", "ipv6");
+
+export function isLoopbackTarget(host: string): boolean {
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  const family = isIP(host);
+  if (family !== 0) return LOCAL_TARGETS.check(host, family === 6 ? "ipv6" : "ipv4");
+  // `127.1`, `0x7f000001`, `2130706433`: resolver shorthand for a loopback literal, not a name.
+  return /^(0x[0-9a-f]+|\d+)(\.(0x[0-9a-f]+|\d+))*$/.test(host);
+}
+
+function respond(socket: Socket, status: number, reason: string): void {
+  if (socket.destroyed) return;
+  socket.end(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+}
+
+function splice(client: Socket, upstream: Socket, pending: Uint8Array): void {
+  const teardown = () => {
+    client.destroy();
+    upstream.destroy();
+  };
+  client.on("error", teardown);
+  upstream.on("error", teardown);
+  client.on("close", () => upstream.destroy());
+  upstream.on("close", () => client.destroy());
+  client.setTimeout(0);
+  client.setNoDelay(true);
+  upstream.setNoDelay(true);
+  if (pending.length > 0) upstream.write(pending);
+  client.pipe(upstream);
+  upstream.pipe(client);
+}
+
+function handleConnection(socket: Socket, options: Required<Pick<ConnectProxyOptions, "interceptPort" | "interceptHosts" | "dialUpstream">>): void {
+  let head: Buffer = Buffer.alloc(0);
+  socket.on("error", () => socket.destroy());
+  socket.setTimeout(HEAD_TIMEOUT_MS, () => respond(socket, 408, "Request Timeout"));
+
+  const onData = (chunk: Buffer) => {
+    head = head.length === 0 ? chunk : Buffer.concat([head, chunk]);
+    const end = head.indexOf("\r\n\r\n");
+    if (end === -1) {
+      if (head.length > MAX_HEAD_BYTES) {
+        socket.off("data", onData);
+        respond(socket, 431, "Request Header Fields Too Large");
+      }
+      return;
+    }
+    socket.off("data", onData);
+    socket.pause();
+    const target = parseConnectRequestLine(head.subarray(0, end).toString("latin1"));
+    // Bytes after the head belong to the tunnel (a client may pipeline its TLS ClientHello).
+    const pending = head.subarray(end + 4);
+    if (!target) {
+      respond(socket, 405, "Method Not Allowed");
+      return;
+    }
+    if (isLoopbackTarget(target.host)) {
+      respond(socket, 403, "Forbidden");
+      return;
+    }
+    const intercept = target.port === 443 && options.interceptHosts.includes(target.host);
+    const upstream = intercept
+      ? connect({ host: "127.0.0.1", port: options.interceptPort })
+      : options.dialUpstream(target.host, target.port);
+    let established = false;
+    const connectTimer = setTimeout(() => {
+      if (!established) {
+        upstream.destroy();
+        respond(socket, 504, "Gateway Timeout");
+      }
+    }, UPSTREAM_CONNECT_TIMEOUT_MS);
+    upstream.once("error", () => {
+      clearTimeout(connectTimer);
+      if (!established) respond(socket, 502, "Bad Gateway");
+    });
+    upstream.once("connect", () => {
+      established = true;
+      clearTimeout(connectTimer);
+      if (socket.destroyed) {
+        upstream.destroy();
+        return;
+      }
+      socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      splice(socket, upstream, pending);
+      socket.resume();
+    });
+  };
+  socket.on("data", onData);
+}
+
+/** Bind the CONNECT proxy on 127.0.0.1. Rejects when the port is unavailable. */
+export function startConnectProxy(port: number, options: ConnectProxyOptions): Promise<ConnectProxyHandle> {
+  const resolved = {
+    interceptPort: options.interceptPort,
+    interceptHosts: options.interceptHosts ?? CLAUDE_INTERCEPT_HOSTS,
+    dialUpstream: options.dialUpstream ?? ((host: string, targetPort: number) => connect({ host, port: targetPort })),
+  };
+  return new Promise((resolve, reject) => {
+    const server: Server = createServer(socket => handleConnection(socket, resolved));
+    const sockets = new Set<Socket>();
+    server.on("connection", socket => {
+      sockets.add(socket);
+      socket.once("close", () => sockets.delete(socket));
+    });
+    server.once("error", reject);
+    server.listen({ port, host: "127.0.0.1", exclusive: true }, () => {
+      server.off("error", reject);
+      const address = server.address();
+      const boundPort = address && typeof address === "object" ? address.port : port;
+      resolve({
+        port: boundPort,
+        close: () => new Promise<void>(done => {
+          for (const socket of sockets) socket.destroy();
+          server.close(() => done());
+        }),
+      });
+    });
+  });
+}

package/src/claude/intercept/listener.ts

@@ -0,0 +1,122 @@
+import type { Server } from "bun";
+import type { PemKeyPair } from "./local-ca";
+
+/**
+ * TLS listener that terminates intercepted `api.anthropic.com` tunnels.
+ *
+ * The CONNECT proxy splices a Claude Code tunnel onto this socket; the client then speaks
+ * HTTPS believing it reached Anthropic. Messages traffic is rewritten to a loopback URL and
+ * handed to the router's own request handler, which already knows how to route mapped models
+ * to providers and pass genuine Claude models through with the caller's subscription
+ * credential. Every other path (usage, feedback, model listings, …) is relayed verbatim to
+ * the real upstream so the client keeps behaving like a first-party install.
+ */
+
+export const CLAUDE_INTERCEPT_UPSTREAM = "https://api.anthropic.com";
+
+const INTERCEPTED_PATHS = new Set(["/v1/messages", "/v1/messages/count_tokens"]);
+
+const HOP_BY_HOP_HEADERS = new Set([
+  "connection", "keep-alive", "transfer-encoding", "upgrade", "te", "trailer",
+  "proxy-authenticate", "proxy-authorization", "proxy-connection", "host", "content-length",
+  "accept-encoding",
+]);
+
+// fetch() transparently decodes the body, so the encoding headers would describe bytes the
+// client never sees.
+const RESPONSE_STRIP_HEADERS = new Set([
+  "connection", "keep-alive", "transfer-encoding", "content-encoding", "content-length",
+]);
+
+export function isClaudeInterceptedPath(pathname: string, method: string): boolean {
+  return method === "POST" && INTERCEPTED_PATHS.has(pathname);
+}
+
+/**
+ * Rebuild the request as if the client had dialled the router directly on loopback: the
+ * admission and Host checks then take the same path a plain loopback bind always has.
+ */
+export function rewriteInterceptedRequest(req: Request, loopbackOrigin: string): Request {
+  const url = new URL(req.url);
+  const headers = new Headers(req.headers);
+  headers.set("host", loopbackOrigin.replace(/^https?:\/\//, ""));
+  return new Request(`${loopbackOrigin}${url.pathname}${url.search}`, {
+    method: req.method,
+    headers,
+    body: req.body,
+    signal: req.signal,
+    redirect: "manual",
+    // @ts-expect-error -- streaming request bodies require half duplex under the fetch spec.
+    duplex: "half",
+  });
+}
+
+export function forwardHeadersForUpstream(source: Headers): Headers {
+  const headers = new Headers();
+  source.forEach((value, name) => {
+    if (!HOP_BY_HOP_HEADERS.has(name.toLowerCase())) headers.append(name, value);
+  });
+  return headers;
+}
+
+export async function relayToUpstream(req: Request, upstreamBase: string, fetchImpl: typeof fetch = fetch): Promise<Response> {
+  const url = new URL(req.url);
+  const target = `${upstreamBase.replace(/\/$/, "")}${url.pathname}${url.search}`;
+  const hasBody = req.method !== "GET" && req.method !== "HEAD";
+  let upstream: Response;
+  try {
+    upstream = await fetchImpl(target, {
+      method: req.method,
+      headers: forwardHeadersForUpstream(req.headers),
+      body: hasBody ? req.body : undefined,
+      signal: req.signal,
+      redirect: "manual",
+      // @ts-expect-error -- streaming request bodies require half duplex under the fetch spec.
+      duplex: "half",
+    });
+  } catch (error) {
+    return Response.json(
+      { type: "error", error: { type: "api_error", message: `intercept relay failed: ${error instanceof Error ? error.message : String(error)}` } },
+      { status: 502 },
+    );
+  }
+  const headers = new Headers();
+  upstream.headers.forEach((value, name) => {
+    if (!RESPONSE_STRIP_HEADERS.has(name.toLowerCase())) headers.append(name, value);
+  });
+  return new Response(upstream.body, { status: upstream.status, statusText: upstream.statusText, headers });
+}
+
+export interface ClaudeInterceptListenerOptions<T = undefined> {
+  leaf: PemKeyPair;
+  /** Router request handler; receives the loopback-rewritten request and the intercept server. */
+  dispatch: (req: Request, server: Server<T>) => Promise<Response>;
+  upstreamBase?: string;
+  maxRequestBodySize?: number;
+  idleTimeout?: number;
+  fetchImpl?: typeof fetch;
+  /** Test seam: bind a fixed port instead of an ephemeral one. */
+  port?: number;
+}
+
+/** Bind the intercept TLS listener on an ephemeral loopback port. */
+export function startClaudeInterceptListener<T = undefined>(options: ClaudeInterceptListenerOptions<T>): Server<T> {
+  const upstreamBase = options.upstreamBase ?? CLAUDE_INTERCEPT_UPSTREAM;
+  let loopbackOrigin = "";
+  const server = Bun.serve<T>({
+    port: options.port ?? 0,
+    hostname: "127.0.0.1",
+    tls: { cert: options.leaf.certPem, key: options.leaf.keyPem },
+    idleTimeout: options.idleTimeout ?? 255,
+    ...(options.maxRequestBodySize !== undefined ? { maxRequestBodySize: options.maxRequestBodySize } : {}),
+    async fetch(req, requestServer) {
+      const url = new URL(req.url);
+      if (isClaudeInterceptedPath(url.pathname, req.method)) {
+        return options.dispatch(rewriteInterceptedRequest(req, loopbackOrigin), requestServer);
+      }
+      return relayToUpstream(req, upstreamBase, options.fetchImpl);
+    },
+  });
+  loopbackOrigin = `http://127.0.0.1:${server.port}`;
+  return server;
+}

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

@@ -0,0 +1,298 @@
+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";
+
+/**
+ * Local certificate authority for the Claude intercept listener.
+ *
+ * Claude Code opens `CONNECT api.anthropic.com:443` through `HTTPS_PROXY` and then expects a
+ * TLS server that presents a certificate for that name. This module mints that authority and
+ * its leaves with nothing but `node:crypto`: no OpenSSL shell-out, no third-party ASN.1
+ * library. The CA is trusted by the Claude Code process alone via `NODE_EXTRA_CA_CERTS`; it is
+ * never installed into an OS trust store.
+ *
+ * Only the subset of X.509 needed for a v3 CA and a serverAuth leaf is encoded. ECDSA P-256 is
+ * used for both, which Node's TLS stack accepts without any additional configuration.
+ */
+
+export const CLAUDE_INTERCEPT_CA_COMMON_NAME = "opencodex Claude Intercept CA";
+const ORGANIZATION = "opencodex";
+const CA_VALIDITY_DAYS = 3650;
+const LEAF_VALIDITY_DAYS = 365;
+
+// ── DER encoding ────────────────────────────────────────────────────────────────
+
+function derLength(length: number): Uint8Array {
+  if (length < 0x80) return Uint8Array.of(length);
+  const bytes: number[] = [];
+  let rest = length;
+  while (rest > 0) {
+    bytes.unshift(rest & 0xff);
+    rest >>= 8;
+  }
+  return Uint8Array.of(0x80 | bytes.length, ...bytes);
+}
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}
+
+function tlv(tag: number, body: Uint8Array): Uint8Array {
+  return concat(Uint8Array.of(tag), derLength(body.length), body);
+}
+
+const sequence = (...parts: Uint8Array[]) => tlv(0x30, concat(...parts));
+const set = (...parts: Uint8Array[]) => tlv(0x31, concat(...parts));
+const boolean = (value: boolean) => tlv(0x01, Uint8Array.of(value ? 0xff : 0x00));
+const octetString = (body: Uint8Array) => tlv(0x04, body);
+const utf8String = (text: string) => tlv(0x0c, new TextEncoder().encode(text));
+const contextTag = (n: number, body: Uint8Array, constructed = true) => tlv((constructed ? 0xa0 : 0x80) | n, body);
+
+function integer(bytes: Uint8Array): Uint8Array {
+  return tlv(0x02, (bytes[0]! & 0x80) !== 0 ? concat(Uint8Array.of(0), bytes) : bytes);
+}
+
+function bitString(bytes: Uint8Array, unusedBits = 0): Uint8Array {
+  return tlv(0x03, concat(Uint8Array.of(unusedBits), bytes));
+}
+
+function objectIdentifier(dotted: string): Uint8Array {
+  const arcs = dotted.split(".").map(Number);
+  const bytes: number[] = [arcs[0]! * 40 + arcs[1]!];
+  for (const arc of arcs.slice(2)) {
+    const encoded: number[] = [arc & 0x7f];
+    let rest = arc >> 7;
+    while (rest > 0) {
+      encoded.unshift((rest & 0x7f) | 0x80);
+      rest >>= 7;
+    }
+    bytes.push(...encoded);
+  }
+  return tlv(0x06, Uint8Array.from(bytes));
+}
+
+function utcTime(date: Date): Uint8Array {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const text = `${pad(date.getUTCFullYear() % 100)}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}`
+    + `${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}Z`;
+  return tlv(0x17, new TextEncoder().encode(text));
+}
+
+const OID = {
+  commonName: "2.5.4.3",
+  organization: "2.5.4.10",
+  ecdsaWithSha256: "1.2.840.10045.4.3.2",
+  basicConstraints: "2.5.29.19",
+  keyUsage: "2.5.29.15",
+  subjectAltName: "2.5.29.17",
+  extendedKeyUsage: "2.5.29.37",
+  subjectKeyIdentifier: "2.5.29.14",
+  authorityKeyIdentifier: "2.5.29.35",
+  serverAuth: "1.3.6.1.5.5.7.3.1",
+} as const;
+
+function distinguishedName(commonName: string): Uint8Array {
+  return sequence(
+    set(sequence(objectIdentifier(OID.organization), utf8String(ORGANIZATION))),
+    set(sequence(objectIdentifier(OID.commonName), utf8String(commonName))),
+  );
+}
+
+function extension(oid: string, critical: boolean, value: Uint8Array): Uint8Array {
+  return critical
+    ? sequence(objectIdentifier(oid), boolean(true), octetString(value))
+    : sequence(objectIdentifier(oid), octetString(value));
+}
+
+function subjectPublicKeyInfo(key: KeyObject): Uint8Array {
+  return new Uint8Array(key.export({ type: "spki", format: "der" }));
+}
+
+/** RFC 5280 permits any unique octet string; a truncated SHA-256 of the SPKI is stable and collision-safe. */
+function keyIdentifier(key: KeyObject): Uint8Array {
+  return new Uint8Array(createHash("sha256").update(subjectPublicKeyInfo(key)).digest()).subarray(0, 20);
+}
+
+function randomSerial(): Uint8Array {
+  const serial = crypto.getRandomValues(new Uint8Array(16));
+  serial[0]! &= 0x7f;
+  if (serial[0] === 0) serial[0] = 1;
+  return serial;
+}
+
+function toPem(label: string, der: Uint8Array): string {
+  const base64 = Buffer.from(der).toString("base64").replace(/(.{64})/g, "$1\n").trimEnd();
+  return `-----BEGIN ${label}-----\n${base64}\n-----END ${label}-----\n`;
+}
+
+interface IssueOptions {
+  subject: Uint8Array;
+  issuer: Uint8Array;
+  subjectKey: KeyObject;
+  signingKey: KeyObject;
+  validityDays: number;
+  extensions: Uint8Array[];
+}
+
+function issueCertificate(options: IssueOptions): Uint8Array {
+  // Back-date slightly so a client whose clock trails ours by a few minutes still accepts it.
+  const notBefore = new Date(Date.now() - 5 * 60_000);
+  const notAfter = new Date(notBefore.getTime() + options.validityDays * 86_400_000);
+  const algorithm = sequence(objectIdentifier(OID.ecdsaWithSha256));
+  const tbsCertificate = sequence(
+    contextTag(0, tlv(0x02, Uint8Array.of(2))),
+    integer(randomSerial()),
+    algorithm,
+    options.issuer,
+    sequence(utcTime(notBefore), utcTime(notAfter)),
+    options.subject,
+    subjectPublicKeyInfo(options.subjectKey),
+    contextTag(3, sequence(...options.extensions)),
+  );
+  const signature = new Uint8Array(sign("sha256", tbsCertificate, { key: options.signingKey, dsaEncoding: "der" }));
+  return sequence(tbsCertificate, algorithm, bitString(signature));
+}
+
+// ── Authority + leaves ──────────────────────────────────────────────────────────
+
+export interface PemKeyPair {
+  certPem: string;
+  keyPem: string;
+}
+
+export interface LocalInterceptCa extends PemKeyPair {
+  publicKey: KeyObject;
+  privateKey: KeyObject;
+}
+
+export function createLocalInterceptCa(): LocalInterceptCa {
+  const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const name = distinguishedName(CLAUDE_INTERCEPT_CA_COMMON_NAME);
+  const der = issueCertificate({
+    subject: name,
+    issuer: name,
+    subjectKey: publicKey,
+    signingKey: privateKey,
+    validityDays: CA_VALIDITY_DAYS,
+    extensions: [
+      extension(OID.basicConstraints, true, sequence(boolean(true), tlv(0x02, Uint8Array.of(0)))),
+      // keyCertSign | cRLSign
+      extension(OID.keyUsage, true, bitString(Uint8Array.of(0x06), 1)),
+      extension(OID.subjectKeyIdentifier, false, octetString(keyIdentifier(publicKey))),
+    ],
+  });
+  return {
+    certPem: toPem("CERTIFICATE", der),
+    keyPem: privateKey.export({ type: "pkcs8", format: "pem" }) as string,
+    publicKey,
+    privateKey,
+  };
+}
+
+/** Issue a serverAuth leaf for `hosts` (first entry becomes the CN; all become SAN dNSNames). */
+export function issueLocalInterceptLeaf(ca: LocalInterceptCa, hosts: readonly string[]): PemKeyPair {
+  if (hosts.length === 0) throw new Error("intercept leaf requires at least one host");
+  const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const der = issueCertificate({
+    subject: distinguishedName(hosts[0]!),
+    issuer: distinguishedName(CLAUDE_INTERCEPT_CA_COMMON_NAME),
+    subjectKey: publicKey,
+    signingKey: ca.privateKey,
+    validityDays: LEAF_VALIDITY_DAYS,
+    extensions: [
+      extension(OID.basicConstraints, true, sequence()),
+      // digitalSignature
+      extension(OID.keyUsage, true, bitString(Uint8Array.of(0x80), 7)),
+      extension(OID.extendedKeyUsage, false, sequence(objectIdentifier(OID.serverAuth))),
+      extension(OID.subjectAltName, false, sequence(
+        ...hosts.map(host => contextTag(2, new TextEncoder().encode(host), false)),
+      )),
+      extension(OID.authorityKeyIdentifier, false, sequence(contextTag(0, keyIdentifier(ca.publicKey), false))),
+    ],
+  });
+  return {
+    certPem: toPem("CERTIFICATE", der),
+    keyPem: privateKey.export({ type: "pkcs8", format: "pem" }) as string,
+  };
+}
+
+// ── Persistence ─────────────────────────────────────────────────────────────────
+
+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);
+}
+
+/** Path Claude Code must see in `NODE_EXTRA_CA_CERTS`. Stable across restarts. */
+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): 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;
+  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)) return null;
+    return { certPem, keyPem, publicKey, privateKey };
+  } catch { // no-excuse-ok: catch -- an unreadable or corrupt authority is regenerated below.
+    return null;
+  }
+}
+
+/**
+ * Load the persisted authority under `<configDir>/claude-intercept/`, minting one when absent
+ * or unreadable. The private key is written 0600; the certificate is world-readable because
+ * `NODE_EXTRA_CA_CERTS` only needs the public half.
+ */
+export function ensureLocalInterceptCa(configDir: string): LocalInterceptCa {
+  const dir = claudeInterceptStateDir(configDir);
+  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);
+    if (existing) return existing;
+    const ca = createLocalInterceptCa();
+    writeFileAtomic(join(dir, CA_KEY_FILE), ca.keyPem, 0o600);
+    writeFileAtomic(join(dir, CLAUDE_INTERCEPT_CA_CERT_FILE), ca.certPem, 0o644);
+    return ca;
+  }, { lockPath: join(dir, "ca-publication.sqlite") });
+}
+
+/** Startup may race a settings apply publishing the same CA. Retry only lease
+ * contention, before binding listeners, without blocking the main event loop. */
+export async function ensureLocalInterceptCaForStartup(configDir: string): Promise<LocalInterceptCa> {
+  for (let attempt = 0; ; attempt += 1) {
+    try { return ensureLocalInterceptCa(configDir); }
+    catch (error) {
+      if (attempt >= 49 || !(error instanceof Error)
+        || !("code" in error) || error.code !== "client_lifecycle_busy") throw error;
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  }
+}