Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -991,7 +991,7 @@ How each client is pointed at the proxy (set automatically in the child env):
| hermes | `HTTPS_PROXY` (plain-http rides absolute-form forward-proxy requests) | `SSL_CERT_FILE` → `combined-ca.pem` (+ legacy `HERMES_CA_BUNDLE` → `root-ca.pem`) |
| dsh | `HTTPS_PROXY` (+ `HTTP_PROXY` for plain-http) + `DEEPSEEK_BASE_URL`; **loopback-only** isolated `DSH_HOME` | `SSL_CERT_FILE` → `combined-ca.pem` |

`NODE_EXTRA_CA_CERTS` *appends* to the built-in trust store, so it points at the MITM root alone (`root-ca.pem`). `SSL_CERT_FILE` *replaces* the default CA bundle, so for codex/dsh/hermes it points at `combined-ca.pem` — a bundle containing the MITM root **plus** the system/Node public roots — keeping pip/git/curl style TLS (blind-tunnelled, real certificates) working inside the child env (#152; hermes since #1375, because current hermes resolves ambient trust only through `SSL_CERT_FILE`).
`NODE_EXTRA_CA_CERTS` *appends* to the built-in trust store, so it points at the MITM root alone (`root-ca.pem`). `SSL_CERT_FILE` *replaces* the default CA bundle, so for codex/dsh/hermes it points at `combined-ca.pem` — a bundle containing the MITM root **plus** the OS trust store and the Node public roots. The OS-store merge matters because some launched clients treat this file as their *entire* trust pool (codex's rustls HTTP stack replaces rather than appends, #1807): any direct, non-proxied connection of theirs must validate against this file alone, so the file must be a superset of what the OS itself trusts (Windows cert stores via PowerShell, macOS keychains via `security(1)`; Linux already reads the filesystem bundle; rebuilt at most once per 24 h). Keeping pip/git/curl style TLS (blind-tunnelled, real certificates) working inside the child env is the original reason for the bundle (#152; hermes since #1375, because current hermes resolves ambient trust only through `SSL_CERT_FILE`; OS-store merge since #1807).

Claude Code's undici fetch ignores `HTTPS_PROXY`, so cert MITM cannot intercept it. Every claude upstream — including a pre-configured `ANTHROPIC_BASE_URL` relay — is routed through the `/bili/` URL form via `ANTHROPIC_BASE_URL` instead; no CA trust is required.

Expand Down
2 changes: 1 addition & 1 deletion CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -966,7 +966,7 @@ MITM 只对一份**白名单**中的模型域名生效(`open.bigmodel.cn`、`a
| hermes | `HTTPS_PROXY`(明文 http 走 absolute-form 正向代理请求) | `SSL_CERT_FILE` → `combined-ca.pem`(另设旧版 `HERMES_CA_BUNDLE` → `root-ca.pem`) |
| dsh | `HTTPS_PROXY`(明文 http 另加 `HTTP_PROXY`)+ `DEEPSEEK_BASE_URL`;**仅回环**隔离 `DSH_HOME` | `SSL_CERT_FILE` → `combined-ca.pem` |

`NODE_EXTRA_CA_CERTS` 是**追加**到内置信任库,所以只指向 MITM 根证书(`root-ca.pem`)即可。`SSL_CERT_FILE` 会**替换**默认 CA bundle,所以 codex/dsh/hermes 指向 `combined-ca.pem` —— 包含 MITM 根证书**加上**系统/Node 公共根 —— 保证子进程环境里 pip/git/curl 类 TLS(盲转发、真证书)不受影响(#152;hermes 自 #1375 起,因为当前 hermes 只经 `SSL_CERT_FILE` 解析环境信任)。
`NODE_EXTRA_CA_CERTS` 是**追加**到内置信任库,所以只指向 MITM 根证书(`root-ca.pem`)即可。`SSL_CERT_FILE` 会**替换**默认 CA bundle,所以 codex/dsh/hermes 指向 `combined-ca.pem` —— 包含 MITM 根证书**加上**操作系统信任库与 Node 公共根。合并 OS 信任库很关键:部分被启动的客户端把这个文件当作**整个**信任池(codex 的 rustls HTTP 栈是替换而非追加,#1807),它们的直连(不经代理)连接只能靠这个文件校验,因此文件必须是 OS 自身信任集合的超集(Windows 经 PowerShell 读证书库、macOS 经 `security(1)` 读钥匙串;Linux 本就直读文件系统 bundle;最多每 24 小时重建一次)。最初引入该 bundle 是为了让子进程环境里 pip/git/curl 类 TLS(盲转发、真证书)不受影响(#152;hermes 自 #1375 起,因为当前 hermes 只经 `SSL_CERT_FILE` 解析环境信任;OS 信任库合并自 #1807 起)。

Claude Code 的 undici fetch 忽略 `HTTPS_PROXY`,所以证书 MITM 拦不到它。claude 的所有上游 —— 包括预先配置的 `ANTHROPIC_BASE_URL` relay —— 一律改走 `/bili/` URL 形式的 `ANTHROPIC_BASE_URL`;无需任何 CA 信任。

Expand Down
142 changes: 134 additions & 8 deletions src/ca.ts
Original file line number Diff line number Diff line change
@@ -1,17 +1,24 @@
import crypto from "node:crypto";
import { execFileSync } from "node:child_process";
import forge from "node-forge";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import tls from "node:tls";
import { caDir } from "./paths.js";
import { log as loggerLog } from "./logger.js";

const ROOT_CERT_FILE = "root-ca.pem";
const ROOT_KEY_FILE = "root-ca-key.pem";
const COMBINED_CA_FILE = "combined-ca.pem";
const ROOT_CN = "billion-context MITM Root CA";
// #1807: the combined bundle merges the OS trust store, which costs a
// PowerShell spawn on Windows — bound the rebuild to once per day per machine.
const COMBINED_MAX_AGE_MS = 24 * 60 * 60 * 1000;

/** First readable candidate wins per platform; Node's Mozilla root set is
* always merged in, which is ALSO the only root source on Windows (no
* filesystem bundle to probe — no XDG on win32). */
* always merged in. On Windows there is no filesystem bundle to probe (no
* XDG on win32) — the OS store comes from collectOsStorePems() instead. */
const PLATFORM_CA_CANDIDATES: readonly string[] =
process.platform === "darwin"
? ["/etc/ssl/cert.pem", "/private/etc/ssl/cert.pem"]
Expand Down Expand Up @@ -73,13 +80,132 @@ export function collectSystemCaPems(env: NodeJS.ProcessEnv = process.env): strin
return pems;
}

/** #1807: sha256 over the whitespace-stripped base64 payload — dedupes the
* same certificate across differently-wrapped PEM encodings (Node's Mozilla
* snapshot vs OS-store exports wrap at different columns). */
export function pemFingerprint(pem: string): string {
const b64 = pem.replace(/-----(BEGIN|END) CERTIFICATE-----/g, "").replace(/\s+/g, "");
return crypto.createHash("sha256").update(b64).digest("hex");
}

/** #1807: wrap a base64 DER certificate as a 64-column PEM block. */
export function wrapDerPem(b64: string): string {
const clean = b64.replace(/[^A-Za-z0-9+/=]/g, "");
const lines: string[] = [];
for (let i = 0; i < clean.length; i += 64) lines.push(clean.slice(i, i + 64));
return `-----BEGIN CERTIFICATE-----\n${lines.join("\n")}\n-----END CERTIFICATE-----\n`;
}

/** #1807: decode captured PowerShell output — PS 5.1 pipes are frequently
* UTF-16LE even though our payload is pure ASCII, so a NUL stride at odd
* offsets is the tell; re-decode accordingly instead of dropping everything. */
export function decodeOsStoreOutput(buf: Buffer): string {
if (buf.length > 2 && buf[1] === 0) return buf.toString("utf16le");
return buf.toString("utf8");
}

/** #1807: parse the NDJSON lines emitted by osStorePowerShellScript() into PEM
* blocks. Malformed/junk lines are skipped, never fatal. */
export function parseOsStoreNdjson(out: string): string[] {
const pems: string[] = [];
for (const line of out.split(/\r?\n/)) {
const t = line.trim();
if (!t.startsWith("{")) continue;
try {
const d = (JSON.parse(t) as { d?: unknown }).d;
if (typeof d === "string" && d.length > 0) pems.push(wrapDerPem(d));
} catch { }
}
return pems;
}

/** #1807: PowerShell 5.1 script exporting every certificate of the machine +
* user Root stores as one NDJSON {"d":"<base64 DER>"} line per certificate
* (NDJSON keeps the pipe output parseable regardless of locale/console code
* page — no human-readable table text to mangle). */
export function osStorePowerShellScript(): string {
return `$ErrorActionPreference='Stop'
$out = New-Object System.Collections.Generic.List[string]
foreach ($loc in 'LocalMachine','CurrentUser') {
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store('Root',$loc)
try { $store.Open('ReadOnly'); foreach ($c in $store.Certificates) { $out.Add([Convert]::ToBase64String($c.Export('Cert'))) } } catch { } finally { $store.Close() }
}
$out | ForEach-Object { '{"d":"' + $_ + '"}' }`;
}

function splitPemBlocks(text: string): string[] {
const out: string[] = [];
const re = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----\s*/g;
let m: RegExpExecArray | null;
while ((m = re.exec(text))) out.push(m[0]);
return out;
}

/** #1807: certificates from the OS-native trust store. Launched clients treat
* combined-ca.pem as their ENTIRE trust pool when SSL_CERT_FILE points at it
* (codex/rustls replace, not append — see codex-rs/http-client custom_ca.rs),
* so the bundle must be a superset of what the OS itself trusts: any direct
* (non-MITM) leg of the client validates against this file alone. On Linux
* the OS store IS the filesystem bundle collectSystemCaPems already reads.
* Best-effort: any failure degrades to the previous bundle shape rather than
* breaking startup. */
export function collectOsStorePems(platform: NodeJS.Platform = process.platform): string[] {
try {
if (platform === "win32") {
const buf = execFileSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", osStorePowerShellScript()],
{ timeout: 30_000, maxBuffer: 16 * 1024 * 1024 });
return parseOsStoreNdjson(decodeOsStoreOutput(buf));
}
if (platform === "darwin") {
const pems: string[] = [];
const keychains = ["/Library/Keychains/System.keychain"];
const login = path.join(os.homedir(), "Library/Keychains/login.keychain-db");
if (fs.existsSync(login)) keychains.push(login);
let failures = 0;
for (const k of keychains) {
// One keychain failing (e.g. a locked login keychain) must not
// drop the certificates already collected from the others.
try {
const out = execFileSync("/usr/bin/security", ["find-certificate", "-a", "-p", k],
{ encoding: "utf8", timeout: 15_000, maxBuffer: 16 * 1024 * 1024 });
pems.push(...splitPemBlocks(out));
} catch { failures++; }
}
if (failures === keychains.length) throw new Error(`all ${keychains.length} keychain exports failed`);
return pems;
}
return [];
} catch (err) {
loggerLog("warn", `os-store merge skipped (${platform}): ${String(err).slice(0, 200)}`);
return [];
}
}

/** Rebuild combined-ca.pem unless a fresh copy (< 24h) already carries the
* current MITM root CA — the OS-store merge makes each rebuild expensive on
* Windows, so steady-state startups reuse the existing file. */
function writeCombinedBundle(): void {
const certs = new Set<string>();
for (const pem of collectSystemCaPems()) certs.add(pem.trim());
for (const pem of tls.rootCertificates) certs.add(pem.trim());
certs.add(rootCertPem!.trim());
const body = [...certs].map((pem) => (pem.endsWith("\n") ? pem : pem + "\n")).join("");
fs.writeFileSync(path.join(caDir(), COMBINED_CA_FILE), body, { mode: 0o644 });
const file = path.join(caDir(), COMBINED_CA_FILE);
try {
const st = fs.statSync(file);
if (Date.now() - st.mtimeMs < COMBINED_MAX_AGE_MS && fs.readFileSync(file, "utf8").includes(rootCertPem!.trim())) return;
} catch { }
const byFingerprint = new Map<string, string>();
const add = (pem: string): void => {
const t = pem.trim();
if (!t.includes("BEGIN CERTIFICATE")) return;
// Sources like collectSystemCaPems hand over a WHOLE FILE as one
// string — split into single-certificate blocks first or the
// fingerprint lands on the concatenated payload and cross-source
// duplicates survive.
for (const block of splitPemBlocks(t)) byFingerprint.set(pemFingerprint(block), block);
};
for (const pem of collectSystemCaPems()) add(pem);
for (const pem of collectOsStorePems()) add(pem);
for (const pem of tls.rootCertificates) add(pem);
add(rootCertPem!);
const body = [...byFingerprint.values()].map((pem) => (pem.endsWith("\n") ? pem : pem + "\n")).join("");
fs.writeFileSync(file, body, { mode: 0o644 });
}

function generateRootCA(): { cert: string; key: string } {
Expand Down
80 changes: 79 additions & 1 deletion tests/ca-combined.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import os from "node:os";
import path from "node:path";
import tls from "node:tls";
import test from "node:test";
import { combinedCaPath, collectSystemCaPems, ensureRootCA, rootCaPath } from "../src/ca.js";
import { combinedCaPath, collectOsStorePems, collectSystemCaPems, decodeOsStoreOutput, ensureRootCA, osStorePowerShellScript, parseOsStoreNdjson, pemFingerprint, rootCaPath, wrapDerPem } from "../src/ca.js";
import { resolveCombinedCaPath } from "../src/launcher.js";
import { rmrf } from "./tmp-rm.ts";

Expand Down Expand Up @@ -78,3 +78,81 @@ test("#152: resolveCombinedCaPath mirrors the caDir layout", () => {
assert.equal(resolveCombinedCaPath({ XDG_DATA_HOME: "/custom/data" } as NodeJS.ProcessEnv),
path.join("/custom/data", "billion-context", "ca", "combined-ca.pem"));
});

const b64Of = (pem: string): string => pem.replace(/-----(BEGIN|END) CERTIFICATE-----/g, "").replace(/\s+/g, "");

test("#1807: wrapDerPem round-trips a real root cert at 64 columns", () => {
const b64 = b64Of(tls.rootCertificates[0]);
const wrapped = wrapDerPem(b64);
const lines = wrapped.trim().split("\n");
assert.equal(lines[0], "-----BEGIN CERTIFICATE-----");
assert.equal(lines[lines.length - 1], "-----END CERTIFICATE-----");
const body = lines.slice(1, -1);
for (const l of body.slice(0, -1)) assert.equal(l.length, 64);
assert.ok(body[body.length - 1].length > 0 && body[body.length - 1].length <= 64, "final base64 line is a short tail");
assert.equal(b64Of(wrapped), b64);
});

test("#1807: pemFingerprint dedupes across wrappings, separates distinct certs", () => {
const b64a = b64Of(tls.rootCertificates[0]);
const altWrap = (b64: string) => `-----BEGIN CERTIFICATE-----\n${b64.match(/.{1,32}/g)!.join("\n")}\n-----END CERTIFICATE-----`;
assert.equal(pemFingerprint(tls.rootCertificates[0]), pemFingerprint(altWrap(b64a)));
assert.notEqual(pemFingerprint(tls.rootCertificates[0]), pemFingerprint(altWrap(b64Of(tls.rootCertificates[1]))));
});

test("#1807: parseOsStoreNdjson skips junk/malformed lines and tolerates CRLF", () => {
const b64 = b64Of(tls.rootCertificates[0]);
const out = `{"d":"${b64}"}\r\ngarbage line\r\nnot json at all\r\n{"d":""}\r\n{"nope":1}\r\n{"d":"${b64}"}\r\n`;
const pems = parseOsStoreNdjson(out);
assert.equal(pems.length, 2);
assert.equal(pems[0], wrapDerPem(b64));
});

test("#1807: decodeOsStoreOutput handles UTF-16LE PowerShell pipes", () => {
const text = '{"d":"QUJDRA=="}';
assert.equal(decodeOsStoreOutput(Buffer.from(text, "utf8")), text);
assert.equal(decodeOsStoreOutput(Buffer.from(text, "utf16le")), text);
});

test("#1807: osStorePowerShellScript covers both Root stores without interpolation leaks", () => {
const s = osStorePowerShellScript();
assert.ok(s.includes("X509Store('Root'"));
assert.ok(s.includes("'LocalMachine','CurrentUser'"));
assert.ok(!s.includes("${"));
});

test("#1807: collectOsStorePems degrades to [] where the platform tooling is absent", () => {
assert.deepEqual(collectOsStorePems("linux"), [], "linux has no OS-store source");
if (process.platform !== "win32") assert.deepEqual(collectOsStorePems("win32"), [], "no powershell off-Windows");
if (process.platform !== "darwin") assert.deepEqual(collectOsStorePems("darwin"), [], "no security(1) off-macOS");
// On a native host the real store IS reachable — exercise the production
// export path end-to-end (PS script + decode + parse on win32, security(1) on darwin).
if (process.platform === "win32" || process.platform === "darwin") {
const pems = collectOsStorePems();
assert.ok(pems.length > 0, `native ${process.platform} OS-store export returned no certs`);
for (const pem of pems) assert.ok(pem.startsWith("-----BEGIN CERTIFICATE-----"));
}
});

test("#1807: combined bundle reused while fresh, rebuilt when stale or CA-missing", () => {
ensureRootCA();
const file = combinedCaPath();
const mitmRoot = fs.readFileSync(rootCaPath(), "utf8").trim();
const future = new Date(Date.now() + 3600e3);
fs.utimesSync(file, future, future);
const before = fs.statSync(file).mtimeMs;
ensureRootCA();
assert.equal(fs.statSync(file).mtimeMs, before, "fresh bundle carrying the MITM CA is NOT rewritten");

const stale = new Date(Date.now() - 25 * 3600e3);
fs.utimesSync(file, stale, stale);
ensureRootCA();
assert.notEqual(fs.statSync(file).mtimeMs, stale.getTime(), "stale (>24h) bundle is rebuilt");
assert.ok(fs.readFileSync(file, "utf8").includes(mitmRoot), "rebuilt bundle carries the MITM CA");

fs.writeFileSync(file, "-----BEGIN CERTIFICATE-----\n" + Buffer.from("junk").toString("base64") + "\n-----END CERTIFICATE-----\n");
const freshButWrong = new Date(Date.now() + 3600e3);
fs.utimesSync(file, freshButWrong, freshButWrong);
ensureRootCA();
assert.ok(fs.readFileSync(file, "utf8").includes(mitmRoot), "fresh file missing the MITM CA is rebuilt");
});
21 changes: 21 additions & 0 deletions tests/claude-native.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ import {
resolveClaudeCli,
stripClaudeManagedBlock,
} from "../src/plugin-install.ts";
import { ensureRootCA } from "../src/ca.ts";
import { ZONE_PORT_BASE, resolveClaudeNativePort, resolveNativeAttachExternal } from "../src/config.ts";
import { chooseWatchdogParentPid, isClaudeHostArgv, isTransientShArgv, planClaudeNativeBootstrap, readPsProcInfo, readWinProcInfo, resolveClaudeHostPid, splitWindowsCommandLine } from "../src/claude-native-bootstrap.ts";
import { rmrf } from "./tmp-rm.ts";
Expand Down Expand Up @@ -1055,6 +1056,26 @@ test("hook e2e: dist script spawns a proxy on the stable port, second run attach
cache: path.join(home, "cache"),
data: path.join(home, "data"),
};
// #1807: first-run CA init now merges the OS trust store — on Windows
// that is a synchronous PowerShell export (~8s on loaded runners) inside
// the hook's 20s bring-up budget. Pre-warm the CA here (outside the
// budget) so the spawned proxy hits the 24h freshness gate and skips the
// export; the export itself stays covered end-to-end by
// tests/ca-combined.test.ts on native hosts.
if (process.platform === "win32") {
const prevHome = process.env.HOME;
const prevData = process.env.XDG_DATA_HOME;
process.env.HOME = xdg.home;
process.env.XDG_DATA_HOME = xdg.data;
try {
ensureRootCA();
} finally {
if (prevHome === undefined) delete process.env.HOME;
else process.env.HOME = prevHome;
if (prevData === undefined) delete process.env.XDG_DATA_HOME;
else process.env.XDG_DATA_HOME = prevData;
}
}
const port = await freePort();
const instanceFile = path.join(xdg.state, "billion-context", "proxy-origin");
let proxyPid = 0;
Expand Down
Loading