fix(launcher): coexist with another MITM via ca-trust.d instead of clobbering NODE_EXTRA_CA_CERTS

[codeslake]

Goal

NODE_EXTRA_CA_CERTS accepts exactly one file. On a host where something else also MITMs api.anthropic.com — a corporate agent, an account-switching pin proxy — whoever assigns that variable last silently untrusts every other CA. Measured 2026-07-30: two such components on one machine took turns breaking each other's TLS, with no error attributable to either. Remote Control inbound stopped working and neither component logged anything.

This implements the consumer + publisher half of a cross-component contract, negotiated with the two other components' owners and implemented independently in three languages:

• each component writes only <config>/ca-trust.d/<component>.pem — own filename, never a sibling's, rewritten every launch, content-compare to skip a no-op
• exactly one external writer builds the merged <config>/ca-trust.pem = ambient/corporate roots + sort(ca-trust.d/*.pem); components never write it
• consumers read the merged bundle if usable, else fall back to their own CA
• <config> = CLAUDE_CONFIG_DIR || ~/.claude, resolved identically by all three

A host with no other MITM and no bundle builder sees no change at all — the launcher falls back to its own CA, which is byte-for-byte what it did before.

Non-Functional Requirements

Size/complexity budget. ~130 lines in bin/claude-via-proxy.mjs (two blocks in one existing function, no new module), ~500 in tests, ~80 in docs. No new dependency: the guard uses node:crypto's X509Certificate rather than forking openssl.

Threat model. This decides what the client trusts for the host its API keys travel to, so both failure directions matter and are treated asymmetrically:

• accepting a bad bundle makes the client distrust the very proxy it is routed through — every request fails TLS. Strictly worse than not using the bundle at all.
• rejecting a good bundle costs only the other components' CAs; the session still works.

So the guard is allowed to be conservative, never permissive. Verified: ca.pem is cert-only, no private key is read or published, and nothing is written outside ca-trust.d/. The publish path never follows a symlink into a victim file — rename replaces the link itself (verified).

Maintainability. No new abstraction in the launcher. One test helper was hoisted because two tests need the same two-launch sequence; the older inline forks were left alone.

Performance/reliability. One extra file read and up to N X509Certificate constructions per launch. Measured against the live 132-cert bundle on the dev host: not perceptible next to spawning the proxy.

Load-bearing? YES. TLS trust path, shared on-disk contract with two external components.

What the guards actually check

Both conditions are checked by parsing, not by matching substrings. Node's PEM reader aborts the whole extras load on one block it cannot decode, so a damaged entry does not merely lose itself — it can void every other component CA and corporate root in the file, ours included.

A first implementation used substring checks (balanced BEGIN/END markers + includes(ourCA)). Code review found it accepts bundles that break the session. Reproduced with real TLS handshakes against a leaf signed by the CCF CA, node v24.11.1 / openssl 3.5.4:

bundle shape	substring guard	real handshake
corrupt base64 ahead, markers intact	accept	FAIL
torn BEGIN TRUSTED CERTIFICATE ahead	accept	FAIL
whole bundle CRLF-normalized	reject	authorized

Counting BEGIN/END says nothing about whether a body decodes, and hard-coding the CERTIFICATE label makes any other label a corporate bundle carries invisible to the count — so a torn one lands in the fatal leading position unseen. There was also a vacuous case: an empty ca.pem makes merged.includes("") true, accepting a bundle that does not carry us at all.

Now: every PEM block must construct an X509Certificate, and one must equal ours by DER (which also fixes the CRLF false reject). Verified against the live 132-cert bundle on the dev host — still accepted, so real-world behavior is unchanged.

Position matters, and it is why this is not belt-and-braces:

torn ahead of ours  ->  UNABLE_TO_VERIFY_LEAF_SIGNATURE
ours alone          ->  authorized
torn after ours     ->  authorized (warns "bad end line")

The builder concatenates sort(ca-trust.d/*.pem), so a torn ccf.pem sorts early and lands in exactly the fatal position.

Atomic publish

ca-trust.d/ccf.pem is published via temp + rename rather than writeFileSync onto the target. A plain write opens with O_TRUNC and leaves a torn pem visible to a builder reading the directory — producing precisely the bundle the read path now has to reject. Temp is in the same directory (a cross-filesystem rename is not atomic and would EXDEV) and carries pid + uuid: pid alone collides across PID namespaces sharing a bind-mounted config dir. Temps orphaned by a kill between write and rename are reaped on the next launch.

Observability

A bundle that exists and is refused now warns on stderr. Silence is kept for absent, which is the normal state on a host with no builder. In a three-component contract a broken builder has to be visible: the session still works (we fall back), while every other component's CA is silently gone — the failure nobody would otherwise notice.

What a consumer cannot check

The guard establishes that the file parses and carries us. It cannot establish that the bundle is complete — a reader has no previous state to compare against, and a legitimately small bundle is indistinguishable from a narrowed one. Measured across three healthy hosts: 2, 132, and 168 certs. Any cert-count floor tuned to one breaks another. Completeness is therefore the builder's guarantee, stated as such in the README so nobody later adds a floor.

Nor do the guards prove usability: only a handshake does that, and the launcher performs none. They are pre-flight checks that keep a known-bad bundle away from the client.

Tests

test/proxy-wrapper.test.mjs (18) and test/proxy-forward-ca.test.mjs (12), including:

• publish happens before exec, to our filename only, never a sibling's, never the merged bundle
• fallback to our own CA with no bundle — the unchanged-standalone case
• every known-bad bundle shape, with the guard's verdict required to agree with a real handshake
• an empty ca.pem does not make the check vacuous
• two handshake tests standing up a TLS server with the ensureCA() leaf, with a no-extra-CA control required to FAIL so a green result cannot pass for an unrelated reason

Every guard was mutation-tested, so none is decoration:

mutation	result
drop the block-parse check	only the torn-bundle case fails
drop containment	only the stale-bundle case fails
writeFileSync(dst) (O_TRUNC)	only the truncation case fails
bundle without our CA	only the positive handshake fails

One test is named for less than it might appear to prove. The publish test is called "never leaves a truncated ccf.pem visible" rather than "publishes atomically", because mutation testing showed unlink; write — maximally non-atomic — still passes it: that window is shorter than the sampler's 1 ms floor. Catching it would need an inotify watch for IN_DELETE-before-IN_CREATE, which is not worth a dependency for a shape nothing here writes. Named for what it demonstrates.

Test isolation fix (please read even if skimming)

Six --remote-control tests set no CLAUDE_CONFIG_DIR, so the launcher published a throwaway temp CA over the developer's real ~/.claude/ca-trust.d/ccf.pem. Measured: one test run took the host's pem from 5dc414fc to 3773c611, leaving that machine's merged bundle advertising a CA nothing signs with — the exact failure this feature exists to prevent. It also silently poisoned an earlier mutation-test result. cleanEnv() now allocates a config dir by default rather than per-test opt-in, and each run is verified to leave the host pem untouched.

Separately, ambient NO_PROXY leaked into the child and made the lowercase-no_proxy merge test read the shell's value instead of the fixture — pre-existing, unrelated to ca-trust, fixed by the same change.

Docs

• README: the ca-trust.d contract, the fallback ladder, and the consumer/builder boundary.
• README: CACHE_FIX_DOWNLOAD_REWRITE=on disables claude update entirely. It reads like a performance knob and was previously mentioned only in a CHANGELOG parenthetical as "download-acceleration"; that misreading cost several days of a broken updater on a fleet. Rewriting a URL requires MITM-ing downloads.claude.ai, whose release client pins public roots only. It cannot be narrowed to the binary download (MITM is decided per host at CONNECT, and the version check shares the host), and no client-side override reaches that client — HTTPS_PROXY, /etc/hosts, /etc/resolv.conf, NODE_EXTRA_CA_CERTS were each disproved against a control.
• Missing CACHE_FIX_CA_TRUST_DIR row added to the env table; CHANGELOG entry added.

Test results

Full suite on this branch: 1390 tests, 1389 pass, 1 fail.

The one failure is proxy-server.test.mjs → "POST /v1/messages routes to upstream", which needs real upstream reachability. Proven pre-existing rather than asserted: the entire change was stashed to a tree byte-identical to the base (git status empty), and the same test fails the same way there.

Worth knowing for anyone running the suite behind a proxy: that test hangs indefinitely rather than failing when a proxy env var is set, and --test-timeout does not cut it. Run with env -u HTTPS_PROXY -u https_proxy -u HTTP_PROXY -u http_proxy -u ALL_PROXY -u all_proxy or it never terminates.

Base

Branches from current main; independent of #261 (touches no file that PR touches).

[vsits-codex-review-agent]

Review: PR #283 — fix(launcher): coexist with another MITM via ca-trust.d instead of clobbering NODE_EXTRA_CA_CERTS

Date: 2026-07-31
Reviewed: bin/claude-via-proxy.mjs, test/proxy-forward-ca.test.mjs, test/proxy-wrapper.test.mjs, README.md, CHANGELOG.md at 2f8b2b939726f149cfbdd30bbe77b06813a04595, re-reviewed as a clean merge onto origin/main 0770147
Round: 1
Label applied: changes-requested

What Is Correct

• The trust-selection guard is conservative in the right direction. bin/claude-via-proxy.mjs:286 only accepts ca-trust.pem if every PEM block parses via X509Certificate and one block DER-equals our CA; otherwise it falls back to our own ca.pem. That does prevent the two concrete failure modes called out in the PR description: stale bundles that do not carry our CA, and torn / malformed bundles that would make Node ignore the extra-CA file.
• The no-other-MITM path is preserved. When no merged bundle exists, the wrapper still points NODE_EXTRA_CA_CERTS at ${CACHE_FIX_CA_DIR||claudeHome()/cache-fix-ca}/ca.pem (bin/claude-via-proxy.mjs:284-342), and test/proxy-wrapper.test.mjs:324-348 pins that unchanged fallback.
• CLAUDE_CONFIG_DIR resolution matches the existing claudeHome() contract rather than freezing at import time. The launcher resolves the config root live per invocation (bin/claude-via-proxy.mjs:198-199, 226, 284), which matches the semantics introduced by PR #246.
• The new tests are materially better than string-shape tests: test/proxy-forward-ca.test.mjs:242-349 verifies the guard against real TLS authorization outcomes, and the merged tree passes the full suite (node --test: 1448 passing tests on my run).

Blockers

1. bin/claude-via-proxy.mjs:257-261 reaps every ccf.pem.* temp after each launch, which is not safe against a concurrent launcher. A second launcher can have already written its own temp sibling but not yet executed renameSync(tmp, dst); the first launcher will then delete that still-live temp as an "orphan". Best case, the loser logs a spurious publish failure. Worse, if the two launchers are not byte-identical (for example because CACHE_FIX_CA_DIR points at a different CA root), the directory entry left behind is whichever launch happened to win first, not necessarily the current publisher's bytes. That contradicts the PR's claim that orphan-temp cleanup is safe under concurrency and leaves the on-disk trust contract nondeterministic.
2. The PR says the contract is a fixed on-disk rendezvous at <config>/ca-trust.d/<component>.pem plus <config>/ca-trust.pem, but the implementation adds a unilateral publisher-only escape hatch: CACHE_FIX_CA_TRUST_DIR (bin/claude-via-proxy.mjs:226-227, documented in README.md:314, CHANGELOG.md:7). Consumers still read the merged bundle only from <config>/ca-trust.pem (bin/claude-via-proxy.mjs:284), and nothing in this PR defines a corresponding cross-component way for the external bundle builder to discover that alternate publish directory. For a load-bearing three-language contract that is supposed to be durable, this is too loose: one participant can silently stop publishing to the canonical rendezvous path while still claiming to implement the contract.

What Needs Attention

• The contract is operationally sound as a cooperative same-user convention, not as a tamper-evident trust boundary. A local actor who can replace ca-trust.pem with a fully-parseable bundle containing both our CA and an attacker CA will still pass the current guard, because the guard intentionally proves only "parses + carries us," not "contains only approved writers." I am not calling that a third blocker because the PR text already scopes completeness/integrity to the external builder, but I do think the limitation should be stated explicitly anywhere this contract is documented as load-bearing.
• I could not reproduce the author's live multi-MITM host measurements. My validation of the accept/reject guard is based on the local TLS-handshake tests added in this PR plus direct Node v24.11.1 X509Certificate behavior, not on a real second MITM or corporate bundle builder.

Bloat / Non-Functional

• None.

Recommendations

• Make temp cleanup ownership-safe before merge. At minimum, do not delete another process's still-live temp by glob alone; the reaper needs enough provenance (or age / successful-publication gating) to distinguish true leftovers from an in-flight sibling publish.
• Remove CACHE_FIX_CA_TRUST_DIR from the contract, or elevate it into the shared spec with matching producer / builder / consumer semantics. Right now it weakens the very durability claim this PR is trying to establish.
• Once those two issues are fixed, re-run the merged-suite path and live multi-MITM validation. This change still merits human review before merge because it fixes a real trust-path bug by introducing a new shared trust contract.

Bottom Line

The acceptance guard and the default fallback behavior are in good shape, and the tests do a credible job of proving the launcher now fails closed on the known bad bundle shapes. But I do not think the on-disk contract is sound enough to freeze yet: the current temp-file reaper can interfere with a concurrent publisher, and the new CACHE_FIX_CA_TRUST_DIR override means the launcher no longer implements a single canonical rendezvous path that other components can rely on. Please fix those two contract-level issues before this is approved. — Codex review

[vsits-proxy-builder]

Thanks for this — the problem is real and the diagnosis is the useful kind: two components taking turns untrusting each other, with neither logging anything, is exactly the failure nobody finds by reading code.

Review result: changes requested. Two blockers, both contract-level rather than defects in the guard itself. I verified each against the diff before posting.

1. The temp reaper isn't concurrency-safe (bin/claude-via-proxy.mjs:260-262)

for (const f of readdirSync(caTrustDir)) {
  if (f.startsWith("ccf.pem.")) try { rmSync(join(caTrustDir, f)); } catch { }
}

This runs unconditionally after your own renameSync, and deletes every ccf.pem.* — including a sibling launcher's temp that has been written but not yet renamed. That launcher's renameSync then throws, and it logs a publish failure it didn't cause. If the two launchers aren't byte-identical (different CACHE_FIX_CA_DIR), whichever won first is what stays on disk. The PR body states orphan reaping is safe under concurrency; as written it isn't.

Age-gating would probably do it — a temp older than any plausible write-to-rename window is genuinely orphaned, one that isn't may be live.

2. CACHE_FIX_CA_TRUST_DIR breaks the rendezvous the PR is establishing

Publish path is CACHE_FIX_CA_TRUST_DIR || <config>/ca-trust.d (line 227); read path is hardcoded <config>/ca-trust.pem (line 284). Set the override and this launcher publishes where no builder is looking while still consuming the canonical bundle — silently dropping out of the contract while appearing to implement it. For a three-language contract that's meant to be durable, one participant being able to unilaterally relocate its half is the thing most likely to cause a confusing outage a year from now.

Either drop it, or lift it into the shared spec with matching producer/builder/consumer semantics.

Not blocking, but worth stating in the README where the contract is documented: the guard proves parses + carries us, not contains only approved writers. A local actor who can write a well-formed bundle containing your CA plus theirs passes it. You already scope completeness to the builder — this is the same boundary, and readers will assume more than it promises unless it's written down.

What's good: the guard's failure direction is right, and the asymmetry argument holds. Replacing the substring checks with X509Certificate + DER comparison is the correct fix — the vacuous merged.includes("") case was a genuine hole. The no-other-MITM path is a real no-op, which matters because that's every user who isn't you. And the TLS-handshake tests are doing actual work rather than asserting on string shapes.

Two process notes:

• This is load-bearing (TLS trust path + cross-component on-disk contract), so it needs human review from Chris in addition to ours before merge. Labelled schema-change and needs-sim-validation accordingly.
• We can't run CI on fork PRs (workflow approval is gated and our bot can't clear it), so we verify the full suite locally at the merge commit. Yours passed at 1448 merged onto current main.

Your live multi-MITM host isn't reproducible here — the handshake results and the 132-cert bundle validation are taken as your measurements, not independently confirmed. Flagging that so it's on the record rather than implied.

Happy to re-review as soon as the two blockers are addressed.

— Proxy Builder

[vsits-codex-review-agent]

Review: PR #283 — fix(launcher): coexist with another MITM via ca-trust.d instead of clobbering NODE_EXTRA_CA_CERTS

Date: 2026-08-01
Reviewed: README.md, CHANGELOG.md, bin/claude-via-proxy.mjs, test/proxy-forward-ca.test.mjs, test/proxy-wrapper.test.mjs at a329f21ae583ac3a7333197dd7cb7acb182aee97, re-reviewed as a clean merge onto origin/main 209f8679b1fea8daeac65a10cfec8db6ed3d63ee
Round: 2
Label applied: reviewed-by-codex-agent, approved-by-codex-agent

What Is Correct

• [Measured] node --test in a detached worktree with PR head merged onto origin/main passed 1499 tests, 0 failed, in 31428.832324ms.
• [Read] Round-1 blocker 1 is fixed in the launcher. The publish path is now the canonical join(configDir, "ca-trust.d") with no publisher-only override, and the temp reaper now only removes ccf.pem.* files older than 60_000ms by statSync(...).mtimeMs rather than deleting every temp unconditionally (bin/claude-via-proxy.mjs:233-280).
• [Measured] The new wrapper test --remote-control reaps an old orphan temp but leaves a concurrent publisher's fresh one alone passed in the merged suite, exercising both sides of the reaper decision in one launch (test/proxy-wrapper.test.mjs:470-500).
• [Measured] I benchmarked the vulnerable write→rename window on this host with node -e '...writeFileSync(tmp); renameSync(tmp,dst)...' for 5000 iterations in one directory; result: iterations=5000 max_ms=0.880873. That is ample headroom for ordinary host load relative to a 60_000ms gate.
• [Read] A deliberately frozen process could still exceed the age gate, but I did not reproduce that and the code path between writeFileSync and renameSync has no awaits or external RPCs (bin/claude-via-proxy.mjs:260-262). For the race I blocked on in round 1, this is now proportionate: deleting late has no functional cost, while deleting early is what breaks a peer.
• [Measured] Round-1 blocker 2 is fixed. rg -n "CACHE_FIX_CA_TRUST_DIR" README.md CHANGELOG.md bin/claude-via-proxy.mjs test/proxy-wrapper.test.mjs test/proxy-forward-ca.test.mjs returned no matches, and the code now hard-codes the canonical rendezvous paths <config>/ca-trust.d/ccf.pem and <config>/ca-trust.pem (bin/claude-via-proxy.mjs:223-235, 287-358; README.md:112-139; CHANGELOG.md:7).
• [Read] The round-1 documentation caveat is now stated honestly. The README now says this is a cooperative same-user convention, not a trust boundary, and that the reader proves only “parses, and carries us,” not “contains only approved writers” (README.md:141-154).
• [Read] The X509/DER guard remains intact after the refactors. The launcher still normalizes CRLF, requires balanced BEGIN counts vs parsed blocks, constructs X509Certificate for every block, and matches our CA by DER before accepting the merged bundle (bin/claude-via-proxy.mjs:335-349). The mirrored handshake coverage is still present in test/proxy-forward-ca.test.mjs:242-349, and the wrapper-level stale/torn bundle tests still cover the launcher path in test/proxy-wrapper.test.mjs:502-565.
• [Measured] The no-other-MITM fallback remains byte-for-byte the old path in behavior. The merged suite passed --remote-control falls back to its own CA when no merged bundle exists (unchanged standalone behaviour) and --remote-control wires forward-proxy env (BASE unset, HTTPS_PROXY + CA set) (test/proxy-wrapper.test.mjs:160-194, 324-349).

Blockers

• None.

What Needs Attention

• [Reported] The author’s live multi-MITM host measurements remain unreproduced here. I did not independently recreate a second live MITM or a real external bundle builder; my approval is based on code read, targeted host measurements, and the merged automated suite. Because this PR is load-bearing (TLS trust path plus a shared on-disk contract), the existing needs-sim-validation label should remain until human/live validation is complete.

Bloat / Non-Functional

• [Measured] Proportion is acceptable for the defect being fixed. git diff --numstat origin/main...pr-283-head shows 248 added production lines (README.md 91, CHANGELOG.md 8, bin/claude-via-proxy.mjs 149) and 545 added test lines (test/proxy-forward-ca.test.mjs 144, test/proxy-wrapper.test.mjs 401), for an added-lines test:prod ratio of about 2.2x.
• [Measured] Surface-area growth is restrained at head: 0 new files, 0 new exports, 0 new env vars, and 2 on-disk contract paths (<config>/ca-trust.d/ccf.pem, <config>/ca-trust.pem).
• [Measured] Comment density is high where it should be. On the production code diff for bin/claude-via-proxy.mjs, I counted 105 added comment lines and 44 added non-comment code lines. Under this repo’s current anti-bloat rule that is a non-finding, because the comments explain the race and trust-path mechanics rather than restating the code.

Recommendations

• [Read] I now consider the on-disk contract sound enough to commit to for the three participating components: one fixed publish filename, one fixed merged-bundle filename, explicit same-user/cooperative scope, and a fail-closed reader that rejects stale or malformed bundles before they can break this session.
• [Reported] Keep the human review and live validation step. This change is materially better than round 1, but it still fixes a security-relevant trust path by introducing a cross-component filesystem contract, so Codex approval is necessary and not sufficient.

Bottom Line

The two round-1 contract blockers are genuinely fixed. The launcher now stays on the canonical rendezvous, the temp reaper no longer races an ordinary concurrent publisher, the trust-bundle reader keeps its parse-and-DER guard, and the documentation now states the trust boundary honestly. I am approving this PR, with the remaining live multi-MITM validation explicitly carried as reported rather than reproduced, and with the expectation that Chris will do the final human review because the contract is load-bearing. — Codex review

[vsits-proxy-builder]

Round 2: both blockers confirmed fixed. Codex approves; I verified independently before dispatching.

Age-gated reaper — statSync(...).mtimeMs against a 60s gate (bin/claude-via-proxy.mjs:275-283). What makes this the right fix isn't the constant, it's that the comment now states why deleting late is free and deleting early breaks a peer — that asymmetry is the actual argument, and it was missing in round 1. Codex measured the window it protects: 5,000 write→rename iterations, max 0.88 ms. Four orders of magnitude of headroom.

CACHE_FIX_CA_TRUST_DIR removed — I grepped code, README, and CHANGELOG: zero occurrences. Publish is now unconditionally <config>/ca-trust.d/ccf.pem against the consumer's <config>/ca-trust.pem. The rendezvous is single-valued again, which is the property the whole contract rests on.

The README caveat is the part I'd single out. README.md:141-154 now says plainly that this is a cooperative same-user convention, not a trust boundary, and that the reader proves "parses, and carries us" — not "contains only approved writers." That limitation was already true in round 1; documenting it is what makes it safe to build on, because the next implementer won't assume more than the guard delivers. Given how easily a "CA bundle validator" invites over-trust, that paragraph is doing real work.

The X509/DER guard survived the refactors intact (CRLF normalization, balanced BEGIN counts, X509Certificate per block, DER match) — we looked directly rather than assuming, since a comment-trimming commit touching a security guard is exactly where a regression hides.

Merged suite: 1499 pass, 0 fail on current main — measured on both sides independently. The new test that reaps an old orphan while sparing a fresh concurrent temp exercises both branches of the reaper in one launch, which is the right shape for a race fix.

Remaining, and it's not on you: live multi-MITM validation can't be reproduced here — we have no second MITM or external bundle builder. Your measurements stand as reported, not confirmed. needs-sim-validation stays until that's closed, and this needs Chris's human review before merge since it's load-bearing (TLS trust path plus a three-component on-disk contract). Codex's approval is necessary, not sufficient.

Nothing further from us. Thanks for the turnaround — and for tightening the reaper to three lines afterward rather than leaving the first working version.

— Proxy Builder