fix(cachekitio): keep a schemeless API URL's username out of the HTTPS error (LAB-4643)

Without a scheme, urlparse reads 'user:pw@host' as scheme 'user', so the
credentials check never sees userinfo and the HTTPS check rejected it
with 'got: user://', echoing the username. The HTTPS error is now fixed
text. The credentials check tests for '@' in the netloc, the same split
httpx uses, instead of two username/password conditions.

Docs: the credentials rule is listed wherever the API URL rules are
(configuration security notes, the SSRF page's custom-host note,
SECURITY.md's transport-log scope), and the @cache.io ConfigurationError
lists now include a CACHEKIT_API_URL that fails validation.

Author: 27Bslash6

SECURITY.md

@@ -192,7 +192,7 @@ See [SSRF Protection](docs/features/ssrf-protection.md) for full details, includ
 
 Cache keys can embed caller-supplied tenant/user identifiers, so **the SDK's own loggers** (`cachekit.*`) never emit them verbatim ([CWE-532][cwe-532]). Every cachekit log path — decorator error handling (structured and backwards-compat), cache-operation logs, and SWR/TTL-refresh debug logs — replaces the key with a fixed-length blake2b digest (`<redacted:…>`), keeping log lines correlatable without leaking the key. Error paths are covered centrally at the shared error sink (`FeatureOrchestrator.handle_cache_error` / `log_cache_operation`), so new call sites are redacted by construction. Both structured cache-operation sinks (`FeatureOrchestrator.log_cache_operation`, `StructuredLogger.cache_operation`) also sanitise an exception passed as `error=` themselves — pass the exception object, never `str(e)`, which is emitted as-is. `BackendError` redacts the key in its formatted text (`str(e)` carries `key=<redacted:…>`), while the `.key` attribute keeps the raw caller-supplied key for programmatic use — never log `e.key`. Its free-form `message` is caller-supplied and third-party exception text (a redis `ResponseError` naming the key, a pymemcache illegal-input error echoing it) has unknown provenance — so **no cachekit log line renders `str(e)`**. Every logging call that mentions an exception goes through `redact_error_for_log`, which emits only the exception type plus, for `BackendError`, its `BackendErrorType` classification; the full exception stays on the object (`original_exception`, `.message`) for programmatic access. Operators lose the provider's message text in the log line and keep it on the exception. An architecture test (`tests/unit/test_log_redaction_architecture.py`) walks every logging call in the package — `logger.*()`, `get_logger().*()`, `getattr(logger, level)()` — and fails CI if a key-shaped value reaches one unredacted in the message, `%s` arguments, or `extra=`; if an exception — any name bound by `except ... as`, a conventional name (`e`, `exc`, `err`, `error`, `*_err`), or an attribute of one — reaches one outside `redact_error_for_log`; or if a call emits a traceback (`logger.exception`, `exc_info=`). The guarantee does not depend on the next contributor remembering it. It is flow-insensitive: build log lines inline, not via a pre-formatted variable, and bind exceptions with `except ... as` or a conventional name (an `Exception`-typed parameter called `failure` is invisible to it), or the guard cannot see them.
 
-**Scope — transport logs are not covered.** The CachekitIO backend addresses entries by key in the request path (`GET /v1/cache/{key}`), and `httpx` logs every request line — method, full URL, status — at `INFO` on its own `httpx` logger. An application that enables `INFO` globally (`logging.basicConfig(level=logging.INFO)`) will therefore see raw keys in *httpx's* output on every operation, exactly as it would see any REST resource path. cachekit does not mute a third-party logger on your behalf; if your keys carry identifiers, silence or raise the level of that logger in your logging config:
+**Scope — transport logs are not covered.** The CachekitIO backend addresses entries by key in the request path (`GET /v1/cache/{key}`), and `httpx` logs every request line — method, full URL, status — at `INFO` on its own `httpx` logger. An application that enables `INFO` globally (`logging.basicConfig(level=logging.INFO)`) will therefore see raw keys in *httpx's* output on every operation, exactly as it would see any REST resource path. That line never carries a password: an API URL with credentials (`user:password@`) is rejected at construction. cachekit does not mute a third-party logger on your behalf; if your keys carry identifiers, silence or raise the level of that logger in your logging config:
 
 ```python
 import logging

docs/api-reference.md

@@ -217,7 +217,7 @@ def get_exchange_rates():
 
 #### Raises
 
-- **`ConfigurationError`**: If `CACHEKIT_API_KEY` is not set
+- **`ConfigurationError`**: If no API key is available (argument or `CACHEKIT_API_KEY`), the key contains whitespace, `CACHEKIT_API_URL` fails validation, or `backend=` / `config=` is passed
 
 #### Notes
 

docs/backends/cachekitio.md

@@ -62,8 +62,8 @@ def tenant_b_function(x):
 ```
 
 `@cache.io()` raises `ConfigurationError` at decoration time if it has no key from either
-source, if the key contains whitespace (usually a trailing newline from a secrets file), or
-if you pass `backend=` or `config=` — it always caches through its own `CachekitIOBackend`.
+source, if the key contains whitespace (usually a trailing newline from a secrets file), if
+`CACHEKIT_API_URL` fails validation, or if you pass `backend=` or `config=` — it always caches through its own `CachekitIOBackend`.
 To cache through another backend, use `@cache.production(backend=...)`.
 
 The RORO form `@cache(config=DecoratorConfig.io(api_key=...))` keeps its own key even when

docs/configuration.md

@@ -147,6 +147,7 @@ CACHEKIT_ALLOW_CUSTOM_HOST=false
 
 **Security notes:**
 - `CACHEKIT_API_URL` must use HTTPS. HTTP is rejected at startup.
+- Credentials in the URL (`user:password@`) are rejected: the API key is the only credential.
 - Private/internal IP addresses are blocked (SSRF protection). This includes `10.x`, `172.16-31.x`, `192.168.x`, `127.x`, and link-local ranges.
 - `CACHEKIT_ALLOW_CUSTOM_HOST=true` disables the hostname allowlist. Only use with trusted configuration (e.g., a local test server running over HTTPS with a self-signed cert).
 

docs/features/ssrf-protection.md

@@ -120,7 +120,7 @@ config = CachekitIOBackendConfig(
 # CACHEKIT_API_URL=https://cache.internal.company.com
 ```
 
-**Important**: Even with `allow_custom_host=True`, private IP addresses are still blocked. The allowlist bypass only affects hostname validation.
+**Important**: Even with `allow_custom_host=True`, private IP addresses and credentials in the URL (`user:password@`) are still rejected. The allowlist bypass only affects hostname validation.
 
 ## Environment Variables
 

src/cachekit/backends/cachekitio/config.py

@@ -167,12 +167,13 @@ def validate_api_url(cls, v: str) -> str:
 
         # Userinfo never authenticates here: httpx sends it as Basic auth in place of the Bearer key,
         # and its INFO log prints the full request URL, password included (CWE-532).
-        if parsed.username is not None or parsed.password is not None:
+        if "@" in parsed.netloc:
             raise ValueError("API URL must not contain credentials (user:password@)")
 
         # Enforce HTTPS protocol
         if parsed.scheme != "https":
-            raise ValueError(f"API URL must use HTTPS protocol, got: {parsed.scheme}://")
+            # No scheme echo: in "user:pw@host" urlparse reads the username as the scheme.
+            raise ValueError("API URL must use HTTPS protocol")
 
         # Reject private/internal IP addresses
         hostname = parsed.hostname or ""

src/cachekit/config/decorator.py

@@ -565,7 +565,8 @@ def io(cls, api_key: str | None = None, **kwargs: Any) -> DecoratorConfig:
 
         Raises:
             ConfigurationError: If the API key is missing, empty or contains whitespace
-                (argument and CACHEKIT_API_KEY), or if ``backend=`` is passed.
+                (argument and CACHEKIT_API_KEY), if CACHEKIT_API_URL fails validation, or if
+                ``backend=`` is passed.
 
         Example:
             >>> config = DecoratorConfig.io(api_key="ck_test_key", ttl=300)  # pragma: allowlist secret

tests/unit/backends/test_cachekitio_backend.py

@@ -178,6 +178,13 @@ def test_url_with_userinfo_is_rejected(self, mock_sync_client: MagicMock, userin
             CachekitIOBackend(api_key=_TEST_API_KEY, api_url=f"https://{userinfo}api.cachekit.io")
         assert "SECRET" not in str(info.value)
 
+    def test_https_error_never_echoes_a_schemeless_url(self, mock_sync_client: MagicMock) -> None:
+        """Without a scheme, urlparse reads the username as one, and the HTTPS error once echoed it."""
+        url = "SECRETUSER:pw@api.cachekit.io"  # pragma: allowlist secret
+        with pytest.raises(ConfigurationError, match="must use HTTPS") as info:
+            CachekitIOBackend(api_key=_TEST_API_KEY, api_url=url)
+        assert "secretuser" not in str(info.value).lower()  # urlparse lowercases the scheme
+
     def test_config_error_never_echoes_the_key(self, mock_sync_client: MagicMock, monkeypatch: pytest.MonkeyPatch) -> None:
         """CWE-532: a rejected api_url must not carry the key into the exception text or its chain."""
         monkeypatch.delenv("CACHEKIT_ALLOW_CUSTOM_HOST", raising=False)