merge ca-trust-guard (upstream PR cnighswonger#296)

Author: codeslake

CHANGELOG.md

@@ -4,7 +4,15 @@
 
 ### Fixed
 
-- **`--remote-control` no longer clobbers another component's `NODE_EXTRA_CA_CERTS`.** That variable takes exactly one file, so on a host where something else also MITMs `api.anthropic.com` (a corporate agent, an account-pinning proxy) the last writer won and every other CA was silently untrusted — measured breaking Remote Control inbound. The launcher now publishes its own CA to `${CLAUDE_CONFIG_DIR:-~/.claude}/ca-trust.d/ccf.pem` (own filename only, never a sibling's, rewritten every launch, atomically via temp + `rename`) and reads a merged `ca-trust.pem` if one exists. It never writes the merged bundle: merging needs ambient corporate-root discovery, which is environment-specific and belongs outside this repo. The bundle is used only when every PEM block in it parses **and** one of them is our own CA (compared by DER) — a bundle that is torn or predates our publish is worse than none, since it makes the client distrust the very proxy it is routed through. On a host with no other MITM and no bundle, behavior is byte-identical to before. Both paths are fixed names under the config dir with no env override: they are two halves of one rendezvous, so a knob on either half alone would let a participant drop out of the contract while appearing to implement it. See [Coexisting with another MITM](README.md#coexisting-with-another-mitm-on-the-same-machine-ca-trustd).
+- **`--remote-control` no longer clobbers another component's `NODE_EXTRA_CA_CERTS`.** That variable takes exactly one file, so on a host where something else also MITMs `api.anthropic.com` (a corporate agent, an account-pinning proxy) the last writer won and every other CA was silently untrusted — measured breaking Remote Control inbound. The launcher now publishes its own CA to `${CLAUDE_CONFIG_DIR:-~/.claude}/ca-trust.d/ccf.pem` (own filename only, never a sibling's, rewritten every launch, atomically via temp + `rename`) and reads a merged `ca-trust.pem` if one exists. It never writes the merged bundle: merging needs ambient corporate-root discovery, which is environment-specific and belongs outside this repo. The bundle is used only when every PEM block in it is terminated **and** one of its `CERTIFICATE` blocks is our own CA (compared by DER) — a bundle that is torn or predates our publish is worse than none, since it makes the client distrust the very proxy it is routed through. On a host with no other MITM and no bundle, behavior is byte-identical to before. Both paths are fixed names under the config dir with no env override: they are two halves of one rendezvous, so a knob on either half alone would let a participant drop out of the contract while appearing to implement it. See [Coexisting with another MITM](README.md#coexisting-with-another-mitm-on-the-same-machine-ca-trustd).
+
+- **The `ca-trust.pem` guard now matches what Node's CA loader actually accepts.** As shipped it disagreed with a real handshake on 8 of 20 measured bundle shapes (node v24.11.1 / openssl 3.6.1). Seven were needless refusals of healthy bundles — any non-certificate block (a CRL, a public key, key material), or a provenance comment that merely mentioned `-----BEGIN `, voided the whole file — and refusing is not the safe direction: it silently drops every sibling and corporate CA for that session, which is the failure this contract exists to prevent. The eighth was the dangerous direction: our own CA relabelled `TRUSTED CERTIFICATE` parses to byte-identical DER, so the guard reported "carries our CA" while Node's loader skipped the block entirely and every request failed TLS. The guard now anchors markers to line starts (tolerating trailing whitespace, which openssl still reacts to), bounds each block's `END` search at the next `BEGIN` so a torn entry cannot borrow a later block's terminator, requires every block to decode — X509 for `CERTIFICATE`, valid base64 armor for everything else, since Node aborts the whole load on any block it cannot read regardless of label — and requires the DER match to land on a `CERTIFICATE` block. Where it cannot tell (a block damaged *after* ours, whose truncated body may still decode) it refuses — conservative, never permissive. The decision moved to `bin/ca-trust.mjs` so the tests drive the shipped code: it was previously inline in a top-level script with a hand-copied twin in the test file, and mutating the real one left the entire suite green.
+
+- **Orphaned publish temps are reaped even when publishing fails.** The reaper shared the publish `try`, so `rename` throwing skipped it — meaning that on exactly the hosts where publishing is persistently broken (a root-owned `ccf.pem`, a read-only mount, `ENOSPC`) each launch abandoned one full-CA temp and collected none, growing without bound in the directory a bundle builder globs.
+
+- **A corrupt `ca.pem` no longer blames the merged bundle, and is no longer handed to the client.** Parsing our own CA sat inside the bundle `try`, so an unparseable `ca.pem` was reported as `ignoring <ca-trust.pem> (...)` — naming a file that may be perfectly healthy — and then `NODE_EXTRA_CA_CERTS` was pointed at the very file that had just failed to parse. It is now parsed in its own step and named in its own message, and when it does not parse the variable is left unset: node falls back to its built-in store, which is the honest state, rather than to a file we vouch for and cannot read.
+
+- **The launcher no longer prints the wiring recipe that would undo its own coexistence.** The spawned proxy's `export NODE_EXTRA_CA_CERTS=<our ca.pem>` banner is correct standalone advice and exactly wrong under `--remote-control`, which relays that stderr: it appeared right after the launcher had published to `ca-trust.d` and adopted the merged bundle, telling the operator to pin the variable to our CA alone. The server now prints the recipe only when the operator is the one wiring: `process.channel` is set exactly when our launcher `fork()`ed it, and the launcher is the only `fork()` site (the `server` subcommand uses `spawn`, and a service manager runs it bare). The mode line still prints either way, so forward-proxy mode stays visible. Standalone, the recipe carries a same-host-MITM caveat, as do the README's manual-wiring recipes.
 
 ### Documentation
 

README.md

@@ -160,7 +160,14 @@ The generated systemd unit / launchd agent carries `CACHE_FIX_FORWARD_PROXY=on`,
 - `HTTPS_PROXY` — where the proxy listens: `http://127.0.0.1:<port>` (default port `9801`, or your `CACHE_FIX_PROXY_PORT`).
 - `NODE_EXTRA_CA_CERTS` — the CA the proxy generated on first start: `~/.claude/cache-fix-ca/ca.pem` (or `$CACHE_FIX_CA_DIR/ca.pem`).
 
-Three ways to wire it, depending on how broadly you want the vars to apply:
+Three ways to wire it, depending on how broadly you want the vars to apply.
+
+> **If anything else on this host also MITMs `api.anthropic.com`** — a corporate
+> TLS-inspecting agent, an account-switching pin proxy — do not use these
+> recipes. `NODE_EXTRA_CA_CERTS` takes one file, so pinning it to our CA alone
+> silently untrusts every other component. Use `--remote-control`, which
+> publishes into `ca-trust.d/` and consumes the merged bundle instead. See
+> [Coexisting with another MITM](#coexisting-with-another-mitm-on-the-same-machine-ca-trustd).
 
 ```bash
 # a) per-invocation — scoped to just this claude run
@@ -207,25 +214,63 @@ environment-specific (a Linux host may keep them outside the bundle a shell
 points at; a Mac keeps them in the keychain), and two components both rebuilding
 it would race one output.
 
-The bundle is used only if it is intact (balanced `BEGIN`/`END` markers) **and**
-carries our own CA. A bundle failing either check is worse than no bundle — it
-would make the client distrust the very proxy it is being routed through, so
-every request fails TLS rather than merely losing some other component's CA. In
-that case, and when no bundle exists at all, the launcher falls back to our own
-CA and behaves exactly as it did before any of this existed. **A host with no
-other MITM and no bundle builder sees no change.**
+The bundle is used only if every PEM block in it is terminated **and** one of its
+`CERTIFICATE` blocks is our own CA. A bundle failing either check is worse than
+no bundle — it would make the client distrust the very proxy it is being routed
+through, so every request fails TLS rather than merely losing some other
+component's CA. In that case, and when no bundle exists at all, the launcher
+falls back to our own CA and behaves exactly as it did before any of this
+existed. **A host with no other MITM and no bundle builder sees no change.**
+
+The check mirrors what Node's `NODE_EXTRA_CA_CERTS` loader does, which is
+narrower than "is this valid PEM" in one direction and wider in another, and both
+were measured against a real handshake rather than read off the spec:
+
+- **Well-formed non-certificate blocks are ignored, not fatal.** A merged bundle
+  legitimately carries CRLs, public keys and key material next to the roots; Node
+  skips them and verifies fine. Parsing every block as a certificate rejected
+  those bundles outright, and rejecting is not the safe direction here — it drops
+  every sibling and corporate CA for the whole session. A *damaged* one is a
+  different matter: Node aborts the whole load on any block it cannot decode,
+  whatever the label, so every block must decode even though only certificates
+  are compared.
+- **The `CERTIFICATE` label is load-bearing.** Our own CA relabelled
+  `TRUSTED CERTIFICATE` parses to byte-identical DER, so a label-blind comparison
+  reports "carries us" — while Node's loader skips the block entirely and the
+  session then fails every request. A DER match on a non-`CERTIFICATE` block does
+  not count.
+- **Markers are line-anchored, but tolerate trailing whitespace.** A provenance
+  header that merely mentions `-----BEGIN ` is prose, not a block. A real marker
+  wearing a trailing space still is one — openssl reacts to it, so a strict
+  end-of-line anchor would hide that block from the guard while Node still tried
+  to load it.
+- **Each block ends at its own `END`.** The terminator is searched for only up to
+  the next `BEGIN`, so an unterminated entry cannot borrow the `END` line of a
+  later one and pass as intact.
+
+Where the guard cannot tell (a block damaged *after* ours, whose truncated body
+may or may not still decode) it refuses. Refusing costs the other components'
+CAs for one session; accepting a bundle Node cannot load costs the session
+entirely, so the guard is allowed to be conservative and never permissive.
 
 Both paths are fixed names under `<config>`, deliberately with no env override
 of their own. They are two halves of one rendezvous: a knob on either half alone
 lets a participant publish where no builder looks, or read a file no builder
 writes, while still appearing to implement the contract. `CLAUDE_CONFIG_DIR`
 already relocates the pair, and it moves both halves together.
 
-Note the limit of what a consumer can check: intact, and carries my CA. Whether
-the bundle is *complete* — that no corporate root went missing — is the
-builder's guarantee, not something a reader can verify, because a reader has no
-previous state to compare against and a legitimately small bundle is
-indistinguishable from a narrowed one.
+Note the limit of what a consumer checks: intact, and carries my CA. Whether the
+bundle is *complete* — that no corporate root went missing — is the builder's
+guarantee, and a consumer must not act on it even where it could.
+
+That is a design choice, not a missing capability, and the distinction matters
+because the other reading is an invitation: someone adds the previous bundle as
+state, believes the limitation is lifted, and adds a floor. It would still be
+wrong. A shrink is *legitimate* whenever a root is retired or a component is
+uninstalled, and only the builder knows which happened — so a reader holding
+both bundles still cannot tell a regression from a fact. Measured: a legitimate
+bundle is 5 certs on one machine here and 168 on another, so any floor that
+catches narrowing on one host rejects a healthy bundle on the next.
 
 **This is a cooperative convention among same-user processes, not a trust
 boundary.** The check proves *parses, and carries us* — never *contains only