ADR-0109: https beside http, trusted from the host's CA store

Status: Accepted; amended by ADR-0110, ADR-0111, ADR-0120
Date: 2026-09-12
Deciders: jka
Decision: D109

Context

The maintainer asked for https support in extension repositories, using each platform's certificate store, while keeping plain http first-class: "like with Debian sources, https is an option, not an obligation". ADR-0039 had refused https. tcltls was already a core dependency for the agent.

The providers' transport had its own TLS setup: -require 1 and a CA file chosen from three Unix paths. On Windows none of those paths exist, so verification depended on wherever the OpenSSL build happened to look.

Decision

One TLS policy for every https connection the core makes. rio-core/tls.tcl (rio::tls) is used by repository fetches and by provider requests alike. The CA source is the first that applies:

SSL_CERT_FILE or SSL_CERT_DIR, passed explicitly;
the system CA bundle;
on Windows with tcltls 1.8 or newer on OpenSSL 3.2 or newer, the Windows certificate store;
otherwise no CA source, and -require 1 regardless, so the handshake fails closed.

The choice is a pure function of platform, environment and library versions, tested on any host.

Host names are checked, which requires tcltls 1.8. A loopback probe showed that tcltls 1.8.0 verifies the host name (through -servername) and 1.7.22 does not. An https repository on an older tcltls is refused with an explanation.

http remains first-class. tcltls loads on the first https connection, so a core without it serves http repositories as before. No warning attaches to http. A redirect from https to http is refused (as apt does); http to https is followed; a scheme-relative location inherits the scheme.

Errors explain themselves. A refused certificate had surfaced as a generic socket failure ("check your connection"). On tcltls 1.8 the verification reason is captured and reported ("self-signed certificate", "hostname mismatch"), with SSL_CERT_FILE named where trusting a CA is the fix.

Source identity ignores the scheme. Updates are offered from the same source (ADR-0107). Comparing sources without their scheme means moving a repository from http to https does not make installed extensions look foreign.

Alternatives considered

A CA bundle shipped with rio. Rejected: rio would become a certificate distributor with a refresh obligation; a stale bundle breaks sites or trusts revoked roots; and it would ignore roots an administrator installed, which is exactly the private-CA case self-hosted repositories need.

Consequences

Repositories and providers verify certificates identically on every platform.
The Windows store path follows tcltls documentation and has not yet run on Windows.
The default repository stays http until its host serves https; the change is one line and does not affect existing installs.
Two follow-ups: the agent on old tcltls (ADR-0110), and certificates that fail verification (ADR-0111).