Research platform-native TLS trust configuration

[lukewilliamboswell]

Context

The HTTP host currently builds its TLS connector with with_webpki_roots() in src/http.rs, while Cargo.toml enables the webpki-tokio feature. This embeds the Mozilla root set in every basic-cli application and does not use trust configured by the operating system.

Bundled roots make static applications self-contained and allow public HTTPS to work in minimal environments without a system CA bundle. However, a general-purpose CLI may need to honor:

• enterprise TLS interception and private certificate authorities;
• locally trusted development certificates;
• administrator trust and distrust policy;
• operating-system certificate updates;
• standard CA bundle overrides such as SSL_CERT_FILE and SSL_CERT_DIR.

Research questions

Investigate and document the tradeoffs between:

• a platform verifier;
• loading native roots into rustls;
• retaining only bundled WebPKI roots;
• combining or falling back between native and bundled roots;
• exposing an application-level custom CA configuration.

The investigation should cover:

• x64 and arm64 macOS, x64 Windows, and x64 and arm64 Linux musl;
• static linking, cross-compilation, binary size, and startup/runtime cost;
• minimal containers or hosts with no usable native certificate store;
• whether fallback to bundled roots could bypass an intentional OS distrust decision;
• actionable errors when roots cannot be loaded or a certificate is rejected;
• private CA, public CA, missing-store, and invalid-store test cases.

Desired outcome

Record a recommended trust policy for basic-cli and the rationale behind it. If a change is recommended, define implementation and test follow-ups that provide predictable behavior on every supported target without requiring users to disable certificate verification.

Keep the public runtime documentation updated with the chosen behavior.

Related work

• Document supported targets and host runtime behavior #448 documents the current bundled-root behavior.
• Make Http.TransportErr match host error behavior #438 tracks stable HTTP transport error classification, including TLS failures.
• Add automated Rust dependency advisory checks #445 tracks dependency advisories and rebuild expectations for statically linked applications.