Summary

Users running their own PKI (step-ca, smallstep, homelab OpenSSL) need hass-mcp to verify their HA's certificate without disabling TLS. Supersedes #15 with a portable, defaults-safe mechanism that works across local installs, Docker containers, and standalone deployments.

Two layered mechanisms

1. OS native trust store via truststore — the same library pip has used by default since 24.2 (mid-2024). Bridges to macOS Keychain, Windows Cert Store, and Linux ca-certificates. Users who installed their CA at the OS level get it for free with no config.

2. SSL_CERT_FILE explicit override — the canonical OpenSSL env var, honored by every TLS-aware tool. Primary mechanism for Docker (bind-mount + env var). Also the override path on any platform.

# app/hass.py
def _build_ssl_context() -> ssl.SSLContext:
    cert_file = os.environ.get("SSL_CERT_FILE")
    if cert_file:
        return ssl.create_default_context(cafile=cert_file)
    return truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)

_client = httpx.AsyncClient(timeout=10.0, verify=_build_ssl_context())

Deployment coverage

Documented in README with the canonical Docker example.

Explicitly declined

• REQUESTS_CA_BUNDLE — requests-specific alias, not a standard. We're not a requests codebase; don't propagate it.
• verify=False — silent downgrade is worse than a hard failure. Users who genuinely want unencrypted local LAN can use HA_URL=http://... which is already documented.

Why this is better than #15

#15 reads REQUESTS_CA_BUNDLE/SSL_CERT_FILE and passes to verify=. Two problems:

1. SSL_CERT_FILE is already honored by httpx natively when trust_env=True (default). The env-var read is partially redundant.
2. Doesn't help macOS users with CAs in Keychain — OpenSSL doesn't read the Keychain. And doesn't help Linux users who installed via update-ca-certificates if hass-mcp runs in a Docker container without that file mounted in.

This PR fixes both: truststore handles every OS-native store, SSL_CERT_FILE handles every explicit-path scenario.

Dependency

Adds truststore>=0.10. ~30 KB, no transitive runtime deps. Used by pip, uv, and recommended in the httpx SSL docs for OS-store integration. Python 3.13 (our minimum) satisfies its 3.10+ floor.

Tests

$ uv run pytest tests/
= 46 passed in 9.11s =

Two new tests in tests/test_hass.py::TestSSLContext:

• test_default_uses_truststore_os_native_store — confirms truststore is selected when no env var
• test_ssl_cert_file_takes_precedence — generates a self-signed PEM, points SSL_CERT_FILE at it, confirms a stdlib ssl.SSLContext is built from the file (not truststore)

Credit

@rmoriz flagged the right problem in #15. The cleaner mechanism preserves the spirit (don't weaken TLS) with a more portable implementation. Their PR can be closed as superseded; Co-Authored-By on the merge commit.