Skip to content

Commit c19df63

Browse files
FarisZRclaude
andcommitted
Document why both trust mechanisms are needed
An end-to-end test of OpenCode against a private-CA HTTPS endpoint corrected an assumption. The npm package installs a native opencode-linux-x64 ELF carrying Bun runtime symbols rather than a Node entrypoint, and Bun reads the OS trust store: opencode 1.18.25 reached the endpoint with the trust store alone and no CA variables set, as well as with each variable independently. The upstream 1.17.12+ NODE_EXTRA_CA_CERTS regression (anomalyco/opencode#35365) did not reproduce, so no version pin is needed. That cuts against the earlier framing that Node-family agents all require NODE_EXTRA_CA_CERTS. It holds for agents that really are JS under Node -- pi installs with --ignore-scripts so no native binary is fetched, and gemini-cli is plain npm -- but not for the Bun-packaged binaries. Node 22 does fail with UNABLE_TO_VERIFY_LEAF_SIGNATURE while curl succeeds against the same server, so the trust store alone is genuinely insufficient for those. The useful conclusion is that packaging varies per agent and per version, which is the argument for keeping both halves rather than picking one. Documented as a table of runtime to trust mechanism, with the verification scope stated as what was actually observed. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent bce5460 commit c19df63

1 file changed

Lines changed: 12 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,18 @@ Because the replace-style variables substitute a runtime's trust store rather th
7070

7171
The variables are injected as defaults; an explicit `agent.env` entry for the same key still wins.
7272

73-
Scope of verification: the mechanism is proven end to end per *runtime family* -- a Rust/Codex handshake through `CODEX_CA_CERTIFICATE` and a Node handshake through `NODE_EXTRA_CA_CERTS`, both against a server signed by a private root -- and the tests assert that every registered agent receives the install step and the variables. That is not the same as an end-to-end private-HTTPS handshake through each agent's own binary, so when adopting a new harness, smoke-test that both private and public HTTPS succeed inside the sandbox.
73+
Both halves are needed because the runtime that makes the request differs per agent, and even per agent *version*:
74+
75+
| Runtime | Reads the OS trust store? | Needs a variable |
76+
|---|---|---|
77+
| Rust (codex) | yes, via `rustls_native_certs` | `CODEX_CA_CERTIFICATE` also honoured |
78+
| Bun native binary (opencode, claude-code) | yes | `NODE_EXTRA_CA_CERTS` / `SSL_CERT_FILE` also honoured |
79+
| Node JS via npm (pi, gemini-cli) | **no** -- Node ships its own root list | `NODE_EXTRA_CA_CERTS` required |
80+
| Python (mini-swe-agent, antigravity-sdk) | via `SSL_CERT_FILE`; `requests`/`httpx` default to certifi | `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` |
81+
82+
Node is the reason the OS trust store alone is not sufficient: with a private root correctly installed via `update-ca-certificates`, `curl` succeeds while Node 22 fails with `UNABLE_TO_VERIFY_LEAF_SIGNATURE` (`tls.rootCertificates` is a separate, bundled list). Conversely a Bun-packaged agent works from the trust store with no variables at all -- which is why Pier does both rather than choosing.
83+
84+
Verified end to end against a server signed by a private root: codex 0.151.0 (`CODEX_CA_CERTIFICATE`), opencode 1.18.25 (trust store alone, and each variable independently), and Node 22 (`NODE_EXTRA_CA_CERTS`). The tests additionally assert that every registered agent receives the install step and the variables. When adopting a new harness, smoke-test that both private and public HTTPS succeed inside the sandbox rather than assuming its packaging matches a sibling's.
7485

7586
## Agent runtime configuration
7687

0 commit comments

Comments
 (0)