fix: honor ESPERANTO_SSL_* for connection tests and discovery (#1214)

* fix: honor ESPERANTO_SSL_* for connection tests and discovery

Test Connection and Discover Models used raw httpx without the
documented Esperanto SSL env vars, so corporate/self-signed HTTPS
endpoints failed with a misleading ConnectError while chat worked.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: reject missing ESPERANTO_SSL_CA_BUNDLE instead of falling through

Match Esperanto: a configured but missing CA path raises ValueError so
Test Connection cannot silently disable TLS via ESPERANTO_SSL_VERIFY.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(credentials): let FakeAsyncClient accept httpx constructor kwargs

discover_with_config now builds httpx.AsyncClient(verify=...) so the
ESPERANTO_SSL_* settings are honored. The test doubles rejected any
constructor argument, so the mocked requests were never captured and
six discovery tests failed after merging main. Accept **kwargs like the
real client does.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PEHJVwHQbundHuCFVHAHZS

---------

Co-authored-by: dalexsys <dalexsys@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Luis Novo <lfnovo@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: 4 people

api/credentials_service.py

@@ -25,6 +25,7 @@
 from open_notebook.ai.provider_registry import PROVIDERS
 from open_notebook.domain.credential import Credential
 from open_notebook.utils.encryption import get_secret_from_env
+from open_notebook.utils.ssl_config import httpx_verify_setting
 from open_notebook.utils.url_validation import (
     prepare_pinned_http_target,
 )
@@ -452,7 +453,7 @@ def models_endpoint(url: str) -> str:
                 f"{ollama_url.rstrip('/')}/api/tags", "ollama"
             )
             headers = dict(target.headers)
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(verify=httpx_verify_setting()) as client:
                 response = await client.get(
                     target.url,
                     headers=headers,
@@ -486,7 +487,7 @@ def models_endpoint(url: str) -> str:
             headers = dict(target.headers)
             if api_key:
                 headers["Authorization"] = f"Bearer {api_key}"
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(verify=httpx_verify_setting()) as client:
                 response = await client.get(
                     target.url,
                     headers=headers,
@@ -518,7 +519,7 @@ def models_endpoint(url: str) -> str:
             headers = dict(target.headers)
             headers["x-api-key"] = api_key
             headers["anthropic-version"] = "2023-06-01"
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(verify=httpx_verify_setting()) as client:
                 response = await client.get(
                     target.url,
                     headers=headers,
@@ -545,7 +546,7 @@ def models_endpoint(url: str) -> str:
             headers = dict(target.headers)
             if api_key:
                 headers["Authorization"] = f"Bearer {api_key}"
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(verify=httpx_verify_setting()) as client:
                 response = await client.get(
                     target.url,
                     headers=headers,
@@ -575,7 +576,7 @@ def models_endpoint(url: str) -> str:
             target = await prepare_pinned_http_target(url, "azure")
             headers = dict(target.headers)
             headers["api-key"] = api_key
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(verify=httpx_verify_setting()) as client:
                 response = await client.get(
                     target.url,
                     headers=headers,
@@ -607,7 +608,7 @@ def models_endpoint(url: str) -> str:
     if provider == "google":
         try:
             headers = {"X-Goog-Api-Key": api_key} if api_key else {}
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(verify=httpx_verify_setting()) as client:
                 response = await client.get(
                     "https://generativelanguage.googleapis.com/v1/models",
                     headers=headers,
@@ -671,7 +672,7 @@ def models_endpoint(url: str) -> str:
         else:
             request_url = discovery_url
             extensions = {}
-        async with httpx.AsyncClient() as client:
+        async with httpx.AsyncClient(verify=httpx_verify_setting()) as client:
             response = await client.get(
                 request_url,
                 headers=headers,

docs/6-TROUBLESHOOTING/connection-issues.md

@@ -402,7 +402,7 @@ Connection error when using HTTPS endpoints
 Works with HTTP but fails with HTTPS
 ```
 
-**Cause:** Self-signed certificates not trusted by Python's SSL verification
+**Cause:** Self-signed or privately issued certificates not trusted by Python's SSL verification inside the container. Chat via Esperanto may honor `ESPERANTO_SSL_*`, but **Test Connection** and **Discover Models** used raw httpx and historically ignored those settings (fixed so they share the same env vars).
 
 **Solutions:**
 
@@ -419,13 +419,17 @@ environment:
   - ESPERANTO_SSL_CA_BUNDLE=/certs/ca-bundle.pem
 ```
 
+This applies to chat **and** to credential Test Connection / model discovery.
+
 ### Solution 2: Disable SSL Verification (Development Only)
 ```bash
 # WARNING: Only use in trusted development environments
 # In .env:
 ESPERANTO_SSL_VERIFY=false
 ```
 
+Same scope: Esperanto providers, Test Connection, and Discover Models.
+
 ### Solution 3: Use HTTP Instead
 If services are on a trusted local network, HTTP is acceptable:
 ```
@@ -435,6 +439,11 @@ Example: http://localhost:1234/v1
 
 > **Security Note:** Disabling SSL verification exposes you to man-in-the-middle attacks. Always prefer custom CA bundle or HTTP on trusted networks.
 
+> **Note:** SSL failures on Test Connection are often reported as a generic
+> "Cannot connect to server" message (httpx wraps `CERTIFICATE_VERIFY_FAILED`
+> as `ConnectError`). If chat or `curl -k` works but Test Connection fails,
+> check `ESPERANTO_SSL_CA_BUNDLE` / `ESPERANTO_SSL_VERIFY` first.
+
 ---
 
 ## Still Having Issues?

open_notebook/ai/connection_tester.py

@@ -23,6 +23,7 @@
 from loguru import logger
 
 from open_notebook.ai.provider_registry import PROVIDERS
+from open_notebook.utils.ssl_config import httpx_verify_setting
 from open_notebook.utils.url_validation import prepare_pinned_http_target
 
 
@@ -115,7 +116,7 @@ async def _test_azure_connection(
         target = await prepare_pinned_http_target(models_url, "azure")
         headers = dict(target.headers)
         headers["api-key"] = test_api_key
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with httpx.AsyncClient(timeout=10.0, verify=httpx_verify_setting()) as client:
             response = await client.get(
                 target.url,
                 headers=headers,
@@ -158,7 +159,7 @@ async def _test_ollama_connection(base_url: str) -> Tuple[bool, str]:
         target = await prepare_pinned_http_target(
             f"{base_url.rstrip('/')}/api/tags", "ollama"
         )
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with httpx.AsyncClient(timeout=10.0, verify=httpx_verify_setting()) as client:
             # Try /api/tags endpoint (standard Ollama)
             response = await client.get(
                 target.url,
@@ -209,7 +210,7 @@ async def _test_openai_compatible_connection(base_url: str, api_key: Optional[st
         if api_key:
             headers["Authorization"] = f"Bearer {api_key}"
 
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with httpx.AsyncClient(timeout=10.0, verify=httpx_verify_setting()) as client:
             # Try /models endpoint (standard OpenAI-compatible)
             response = await client.get(
                 target.url,
@@ -262,7 +263,7 @@ async def _test_anthropic_compatible_connection(
         if api_key:
             headers["x-api-key"] = api_key
 
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with httpx.AsyncClient(timeout=10.0, verify=httpx_verify_setting()) as client:
             response = await client.get(
                 target.url,
                 headers=headers,

open_notebook/utils/ssl_config.py

@@ -0,0 +1,44 @@
+"""SSL settings shared by Esperanto providers and raw httpx clients.
+
+Connection tests and model discovery use httpx directly. Those paths must
+honor the same ESPERANTO_SSL_* environment variables documented for Esperanto,
+otherwise corporate / self-signed HTTPS endpoints pass chat but fail
+"Test Connection" / Discover Models with a misleading ConnectError.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Union
+
+# Keep names aligned with esperanto.utils.ssl
+SSL_VERIFY_ENV_VAR = "ESPERANTO_SSL_VERIFY"
+SSL_CA_BUNDLE_ENV_VAR = "ESPERANTO_SSL_CA_BUNDLE"
+
+
+def httpx_verify_setting() -> Union[bool, str]:
+    """Return a value suitable for ``httpx.AsyncClient(verify=...)``.
+
+    Priority (highest first), matching Esperanto's SSLMixin:
+
+    1. ``ESPERANTO_SSL_CA_BUNDLE`` — path to a CA bundle file
+    2. ``ESPERANTO_SSL_VERIFY=false|0|no`` — disable verification
+    3. Default — ``True`` (system trust store)
+
+    Raises:
+        ValueError: If ``ESPERANTO_SSL_CA_BUNDLE`` is set but the file is
+            missing. Esperanto rejects invalid bundles instead of falling
+            through to ``ESPERANTO_SSL_VERIFY``; we do the same so Test
+            Connection cannot silently disable TLS when a CA path is wrong.
+    """
+    ca_bundle = os.getenv(SSL_CA_BUNDLE_ENV_VAR)
+    if ca_bundle:
+        if not os.path.isfile(ca_bundle):
+            raise ValueError(f"CA bundle file not found: {ca_bundle}")
+        return ca_bundle
+
+    verify_env = os.getenv(SSL_VERIFY_ENV_VAR, "").lower()
+    if verify_env in ("false", "0", "no"):
+        return False
+
+    return True

tests/test_credentials_api.py

@@ -110,6 +110,10 @@ async def test_openai_discovery_respects_base_url(self, monkeypatch):
         requests = []
 
         class FakeAsyncClient:
+            def __init__(self, *args, **kwargs):
+                # Accept httpx.AsyncClient kwargs (e.g. verify=...)
+                pass
+
             async def __aenter__(self):
                 return self
 
@@ -169,6 +173,10 @@ async def test_model_discovery_base_url_can_include_models_path(self, monkeypatc
         requests = []
 
         class FakeAsyncClient:
+            def __init__(self, *args, **kwargs):
+                # Accept httpx.AsyncClient kwargs (e.g. verify=...)
+                pass
+
             async def __aenter__(self):
                 return self
 
@@ -210,6 +218,10 @@ async def test_anthropic_compatible_discovery_normalizes_models_path(
         requests = []
 
         class FakeAsyncClient:
+            def __init__(self, *args, **kwargs):
+                # Accept httpx.AsyncClient kwargs (e.g. verify=...)
+                pass
+
             async def __aenter__(self):
                 return self
 
@@ -256,6 +268,10 @@ async def test_openai_discovery_pins_user_supplied_base_url(self, monkeypatch):
         captured = {}
 
         class FakeAsyncClient:
+            def __init__(self, *args, **kwargs):
+                # Accept httpx.AsyncClient kwargs (e.g. verify=...)
+                pass
+
             async def __aenter__(self):
                 return self
 
@@ -318,6 +334,10 @@ async def test_omlx_discovery_defaults_base_url_and_pins(self, monkeypatch):
         pinned_calls = []
 
         class FakeAsyncClient:
+            def __init__(self, *args, **kwargs):
+                # Accept httpx.AsyncClient kwargs (e.g. verify=...)
+                pass
+
             async def __aenter__(self):
                 return self
 
@@ -356,6 +376,10 @@ async def test_omlx_discovery_sends_optional_api_key(self, monkeypatch):
         captured = {}
 
         class FakeAsyncClient:
+            def __init__(self, *args, **kwargs):
+                # Accept httpx.AsyncClient kwargs (e.g. verify=...)
+                pass
+
             async def __aenter__(self):
                 return self
 

tests/test_ssl_config.py

@@ -0,0 +1,43 @@
+"""Tests for ESPERANTO_SSL_* → httpx verify mapping."""
+
+from pathlib import Path
+
+import pytest
+
+from open_notebook.utils.ssl_config import httpx_verify_setting
+
+
+@pytest.fixture(autouse=True)
+def _clear_ssl_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("ESPERANTO_SSL_VERIFY", raising=False)
+    monkeypatch.delenv("ESPERANTO_SSL_CA_BUNDLE", raising=False)
+
+
+def test_default_verify_enabled() -> None:
+    assert httpx_verify_setting() is True
+
+
+@pytest.mark.parametrize("value", ["false", "0", "no", "FALSE", "No"])
+def test_verify_disabled_via_env(value: str, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ESPERANTO_SSL_VERIFY", value)
+    assert httpx_verify_setting() is False
+
+
+def test_ca_bundle_takes_priority_over_verify_false(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    ca = tmp_path / "ca.pem"
+    ca.write_text("dummy-ca\n", encoding="utf-8")
+    monkeypatch.setenv("ESPERANTO_SSL_CA_BUNDLE", str(ca))
+    monkeypatch.setenv("ESPERANTO_SSL_VERIFY", "false")
+    assert httpx_verify_setting() == str(ca)
+
+
+def test_missing_ca_bundle_raises_instead_of_falling_through(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Misconfigured CA must not silently honor ESPERANTO_SSL_VERIFY=false."""
+    monkeypatch.setenv("ESPERANTO_SSL_CA_BUNDLE", "/no/such/ca.pem")
+    monkeypatch.setenv("ESPERANTO_SSL_VERIFY", "false")
+    with pytest.raises(ValueError, match="CA bundle file not found"):
+        httpx_verify_setting()