Skip to content

v0.1.4

Choose a tag to compare

View all tags
@ruslanmv ruslanmv released this 25 Aug 09:59
· 32 commits to master since this release
v0.1.4
442d4c0

matrix-python-sdk v0.1.4 — Hotfix: Cross‑platform TLS trust (default OS store)

Release date: 2025‑08‑25
Type: Hotfix (security/robustness)

Summary

This release resolves SSL: CERTIFICATE_VERIFY_FAILED errors observed in certain virtualenv/WSL/CI setups by making OS trust the default across Windows, macOS, and Linux. The SDK now installs truststore>=0.8 by default and integrates a minimal, production‑safe TLS hardening step on client initialization.

What changed

  • Default to OS trust store using https://pypi.org/project/truststore/ on all platforms.

  • New helper: matrix_sdk.ssl_compat.configure_ssl_trust() is invoked once at MatrixClient.__init__, before any network I/O.

  • Respect user overrides: if SSL_CERT_FILE or REQUESTS_CA_BUNDLE are set, the SDK does nothing and defers to your configuration.

  • Runtime control via env:

    • MATRIX_SSL_TRUST=auto (default)
    • MATRIX_SSL_TRUST=truststore (force OS store)
    • MATRIX_SSL_TRUST=system (Unix/mac fallback to known CA bundle files)
    • MATRIX_SSL_TRUST=off (disable adjustments)
    • Debug: MATRIX_SSL_TRUST_DEBUG=1

  • Packaging: truststore>=0.8 is now a hard dependency (installed automatically from PyPI). No other runtime deps changed.

  • CI/Testing: Added network‑free tests (tests/test_ssl_compat.py) and a tox.ini matrix to validate behavior with different TLS modes.

Why this matters

Some environments used certifi's bundled CA file, which may lack intermediates or corporate roots. Root/system Python often works because it uses the OS store. This hotfix standardizes behavior so virtualenvs and CI match system reliability—without disabling TLS verification.

Backwards compatibility

  • No API breaks.
  • User‑provided CA settings are preserved; the SDK will not override SSL_CERT_FILE / REQUESTS_CA_BUNDLE.
  • You can opt out at runtime with MATRIX_SSL_TRUST=off.

Upgrading

pip install -U matrix-python-sdk

Nothing else required. If you previously installed the optional extra matrix-python-sdk[truststore], you can now remove the extra—the dependency is first‑class.

Configuration examples

# Default (auto): OS trust via truststore
export MATRIX_SSL_TRUST=auto

# Force OS trust explicitly
export MATRIX_SSL_TRUST=truststore

# Force system bundle path on Unix/macOS (if you prefer files over OS store)
export MATRIX_SSL_TRUST=system

# Disable adjustments entirely (use your own CA settings)
export MATRIX_SSL_TRUST=off

# Respect explicit CA bundle (SDK will not override this)
export REQUESTS_CA_BUNDLE=/path/to/corp-root-bundle.pem

Notes for enterprise/proxy environments

If your network performs TLS inspection (MITM), ensure the proxy’s root CA is present in the OS trust store or pointed to via REQUESTS_CA_BUNDLE/SSL_CERT_FILE. The SDK keeps verification enabled and will not bypass certificate checks.

Acknowledgements

Thanks to users who reported venv/WSL TLS issues and helped validate fixes.

Hashes/Artifacts: No binary changes in this release aside from packaging metadata.

Python compatibility: >=3.11,<3.13 unchanged.

Assets 4
Loading