fix(tls): select certifi before macOS clients

[somewheresy]

Summary

• Select Hermes's pinned certifi CA bundle as the process default on macOS before Desktop or CLI networking clients are created.
• Preserve valid operator-provided SSL_CERT_FILE values and the existing non-macOS certificate search order.
• Centralize the existing gateway bootstrap in one lightweight helper and cover real startup behavior on Python 3.11 and 3.13.

Motivation

Hermes Desktop could return no Actual models and fail Responses calls because startup selected Python's compiled /private/etc/ssl/cert.pem before certifi on macOS. That bundle could not validate the Actual relay certificate.

Setting SSL_CERT_FILE to the installed certifi path in .env proves the root cause, but that workaround embeds a username, install location, virtual-environment layout, and Python version. Hermes should select its installed bundle itself.

Links

• Linear: E-998
• Related fix: fix(models): restore authenticated Actual discovery on macOS #86492
• Prior implementation: fix(models): restore authenticated Actual discovery on macOS #83554
• Downstream consumer: actual-computer/actual-computer-monorepo#3283

Approach

1. Move the existing process-level certificate bootstrap from gateway.run into hermes_cli.ssl_certs so CLI and gateway entry points share one policy.
2. Keep an existing valid SSL_CERT_FILE authoritative and continue repairing stale paths.
3. On macOS only, prefer certifi before Python's compiled OpenSSL cafile; keep the established order everywhere else.
4. Run the helper immediately after profile dotenv loading in the CLI, before Desktop clients construct urllib or httpx/OpenAI TLS contexts.
5. Exercise a real macOS CLI import in a subprocess and compare the resulting HTTPS context's CA fingerprints with certifi. The same behavior test passes under Python 3.11 and Python 3.13 without faking sys.platform or mutating private opener state.

Local verification passed 24 focused regression tests on Python 3.11 and the four changed certificate tests on Python 3.13. A live Actual smoke test selected certifi, discovered 27 models through urllib, and completed a Responses request through OpenAI/httpx with TLS_OK.

Reviewer Focus

• Confirm the process default is selected after dotenv but before network clients are created.
• Confirm a valid operator-supplied SSL_CERT_FILE remains authoritative.
• Confirm non-macOS certificate selection is behavior-preserving.
• Confirm the startup test would fail if Python 3.13 eagerly captured the wrong CA context.

Failure Modes

• If certifi is unavailable or its bundle is missing, macOS falls through to the existing compiled and common-path discovery behavior without disabling TLS verification.
• A stale SSL_CERT_FILE is logged, removed, and replaced through normal discovery.
• A valid explicit SSL_CERT_FILE, including a corporate CA bundle, is left unchanged.
• Platforms without certifi retain their previous system-bundle fallback behavior.

Breaking Changes

None.

Post-Merge Behavior

Merging triggers upstream CI and normal release processing only; it does not deploy Actual infrastructure. Source installs and the next Hermes release containing the merge automatically use certifi as the macOS process default. Downstream immutable pins, including Actual PR #3283, must be updated separately after this PR merges.

Diagrams

flowchart LR
    D[Hermes Desktop or CLI] --> E[Load profile dotenv]
    E --> S[Select process CA]
    S -->|valid SSL_CERT_FILE| C[Operator CA]
    S -->|macOS default| B[Installed certifi bundle]
    C --> U[urllib and httpx/OpenAI clients]
    B --> U
    U --> A[Actual models and Responses endpoints]

Loading