phoenix-channels-python-client 0.3.0__tar.gz → 0.3.1__tar.gz

{phoenix_channels_python_client-0.3.0/phoenix_channels_python_client.egg-info → phoenix_channels_python_client-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.3.0
+Version: 0.3.1
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -365,7 +365,7 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 
 ## Security Considerations
 
-**API Key in URL**: This client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
+**API Key in URL**: Without an authentication header, this client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
 
 - Server access logs
 - Reverse proxies and load balancers
@@ -376,8 +376,28 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 - Use short-lived, rotatable tokens rather than long-lived API keys
 - Consider this limitation when evaluating this client for sensitive environments
 
-**Note:** The official Phoenix JS client (v1.8+) supports header-based authentication via the `authToken` option, which avoids URL logging. This client always sends `api_key` in the URL (logged URLs show `api_key=***`). Pass `additional_headers={"x-api-key": key}` to also send it as a handshake header on every (re)connect, e.g. for a proxy that reads it from there.
+Pass `additional_headers={"x-api-key": key}` or `{"x-auth-token": jwt}` to use header-only authentication on every connection and reconnect.
 
 ---
 
 **Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.
+
+### Authentication and diagnostic safety
+
+A nonempty `x-api-key` or `x-auth-token` handshake header selects header-only authentication on
+every connection and reconnect. Embedded API-key parameters are removed; empty
+or conflicting authentication headers and simultaneous token-query authentication
+are rejected before connecting. A JWT header overrides an embedded token and takes
+precedence over an API-key header, matching the platform. Without an authentication header, legacy query authentication
+is preserved and remains visible to servers and proxies. No fallback is attempted.
+
+`client.logger` forwards sanitized connection records without raw arguments,
+exception objects, or socket metadata. `client.redact_diagnostic(text)` applies
+the credential policy to transport errors a caller needs to retain. Caller-visible
+errors may still contain personal data and should not be logged outside this policy.
+
+Connection diagnostics omit dynamic strings and transport payloads, including URLs,
+headers, frame bodies, user/topic identities, and untrusted server error details.
+Logs retain static lifecycle descriptions, native connection states,
+and exception types. Application data and caller-visible errors are not changed;
+applications remain responsible for logs outside this connection-owned boundary.

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/README.md

@@ -334,7 +334,7 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 
 ## Security Considerations
 
-**API Key in URL**: This client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
+**API Key in URL**: Without an authentication header, this client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
 
 - Server access logs
 - Reverse proxies and load balancers
@@ -345,8 +345,28 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 - Use short-lived, rotatable tokens rather than long-lived API keys
 - Consider this limitation when evaluating this client for sensitive environments
 
-**Note:** The official Phoenix JS client (v1.8+) supports header-based authentication via the `authToken` option, which avoids URL logging. This client always sends `api_key` in the URL (logged URLs show `api_key=***`). Pass `additional_headers={"x-api-key": key}` to also send it as a handshake header on every (re)connect, e.g. for a proxy that reads it from there.
+Pass `additional_headers={"x-api-key": key}` or `{"x-auth-token": jwt}` to use header-only authentication on every connection and reconnect.
 
 ---
 
 **Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.
+
+### Authentication and diagnostic safety
+
+A nonempty `x-api-key` or `x-auth-token` handshake header selects header-only authentication on
+every connection and reconnect. Embedded API-key parameters are removed; empty
+or conflicting authentication headers and simultaneous token-query authentication
+are rejected before connecting. A JWT header overrides an embedded token and takes
+precedence over an API-key header, matching the platform. Without an authentication header, legacy query authentication
+is preserved and remains visible to servers and proxies. No fallback is attempted.
+
+`client.logger` forwards sanitized connection records without raw arguments,
+exception objects, or socket metadata. `client.redact_diagnostic(text)` applies
+the credential policy to transport errors a caller needs to retain. Caller-visible
+errors may still contain personal data and should not be logged outside this policy.
+
+Connection diagnostics omit dynamic strings and transport payloads, including URLs,
+headers, frame bodies, user/topic identities, and untrusted server error details.
+Logs retain static lifecycle descriptions, native connection states,
+and exception types. Application data and caller-visible errors are not changed;
+applications remain responsible for logs outside this connection-owned boundary.

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/phoenix_channels_python_client/__init__.py

@@ -19,7 +19,7 @@ from phoenix_channels_python_client.protocol_handler import (
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [

phoenix_channels_python_client-0.3.1/phoenix_channels_python_client/authentication.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+API_KEY_PARAMETER = "api_key"
+TOKEN_PARAMETER = "token"  # noqa: S105 -- protocol parameter name
+
+
+class AuthenticationHeader(StrEnum):
+    API_KEY = "x-api-key"
+    TOKEN = "x-auth-token"  # noqa: S105 -- protocol header name
+
+
+def normalize_headers(headers: dict[str, str] | None) -> dict[str, str]:
+    normalized = dict(headers or {})
+    for header in AuthenticationHeader:
+        credentials = [
+            value for name, value in normalized.items() if name.casefold() == header
+        ]
+        if not credentials:
+            continue
+        if (
+            any(not value.strip() for value in credentials)
+            or len(set(credentials)) != 1
+        ):
+            raise ValueError(f"{header} headers must contain one nonempty credential")
+        normalized = {
+            name: value
+            for name, value in normalized.items()
+            if name.casefold() != header
+        }
+        normalized[header] = credentials[0]
+    return normalized
+
+
+def select_authentication_header(
+    headers: dict[str, str],
+) -> AuthenticationHeader | None:
+    # The platform gives a supplied JWT precedence over an API key.
+    for header in (AuthenticationHeader.TOKEN, AuthenticationHeader.API_KEY):
+        if header in headers:
+            return header
+    return None

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/phoenix_channels_python_client/client.py

@@ -5,13 +5,24 @@ import logging
 from collections import deque
 from collections.abc import Awaitable, Callable
 from types import TracebackType
-from typing import Self
+from typing import Self, cast
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
 from websockets import ClientConnection
 
+from phoenix_channels_python_client.authentication import (
+    API_KEY_PARAMETER,
+    TOKEN_PARAMETER,
+    AuthenticationHeader,
+    normalize_headers,
+    select_authentication_header,
+)
 from phoenix_channels_python_client.client_state_machine import transition_client_state
 from phoenix_channels_python_client.client_types import ClientState, ReconnectPolicy
+from phoenix_channels_python_client.diagnostics import (
+    ConnectionLogger,
+    diagnostic_secrets,
+)
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 from phoenix_channels_python_client.protocol_handler import (
     DEFAULT_PROTOCOL_VERSION,
@@ -36,39 +47,56 @@ TopicLostCallback = Callable[[str, Exception], Awaitable[None]]
 
 
 def _build_channel_socket_urls(
-    websocket_url: str, api_key: str, vsn: str
+    websocket_url: str,
+    api_key: str,
+    vsn: str,
+    *,
+    header_auth: AuthenticationHeader | None = None,
 ) -> tuple[str, str]:
     split_url = urlsplit(websocket_url)
     query_params = parse_qsl(split_url.query, keep_blank_values=True)
+    if header_auth is AuthenticationHeader.API_KEY and any(
+        key.casefold() == TOKEN_PARAMETER and value for key, value in query_params
+    ):
+        raise ValueError("token query authentication cannot be combined with x-api-key")
     filtered = [
-        (key, value) for key, value in query_params if key not in {"api_key", "vsn"}
-    ]
-    with_auth = [*filtered, ("api_key", api_key), ("vsn", vsn)]
-
-    connect_url = urlunsplit(
-        (
-            split_url.scheme,
-            split_url.netloc,
-            split_url.path,
-            urlencode(with_auth),
-            split_url.fragment,
+        (key, value)
+        for key, value in query_params
+        if key.casefold()
+        not in (
+            {API_KEY_PARAMETER, "vsn", TOKEN_PARAMETER}
+            if header_auth
+            else {API_KEY_PARAMETER, "vsn"}
         )
-    )
-    redacted_url = urlunsplit(
-        (
-            split_url.scheme,
-            split_url.netloc,
-            split_url.path,
-            urlencode(
-                [
-                    (key, "***" if key == "api_key" else value)
-                    for key, value in with_auth
-                ]
-            ),
-            split_url.fragment,
+    ]
+    with_auth = [
+        *filtered,
+        *([] if header_auth else [(API_KEY_PARAMETER, api_key)]),
+        ("vsn", vsn),
+    ]
+
+    def build(params: list[tuple[str, str]]) -> str:
+        return urlunsplit(
+            (
+                split_url.scheme,
+                split_url.netloc,
+                split_url.path,
+                urlencode(params),
+                split_url.fragment,
+            )
         )
+
+    return build(with_auth), build(
+        [
+            (
+                key,
+                "***"
+                if key.casefold() in {API_KEY_PARAMETER, TOKEN_PARAMETER}
+                else value,
+            )
+            for key, value in with_auth
+        ]
     )
-    return connect_url, redacted_url
 
 
 class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerMixin):
@@ -92,7 +120,10 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         on_topic_lost: TopicLostCallback | None = None,
         additional_headers: dict[str, str] | None = None,
     ) -> None:
-        self.logger = logger
+        self.additional_headers = normalize_headers(additional_headers)
+        self.logger = ConnectionLogger(
+            logger, diagnostic_secrets(websocket_url, api_key, self.additional_headers)
+        )
 
         if heartbeat_interval_s is not None and heartbeat_interval_s <= 0:
             raise ValueError("heartbeat_interval_s must be > 0 or None to disable")
@@ -106,21 +137,18 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         if callback_drain_timeout_s <= 0:
             raise ValueError("callback_drain_timeout_s must be > 0")
 
-        self._protocol_handler = PHXProtocolHandler(protocol_version)
+        self._protocol_handler = PHXProtocolHandler(
+            protocol_version, diagnostic_logger=self.logger
+        )
         connect_url, redacted_url = _build_channel_socket_urls(
             websocket_url=websocket_url,
             api_key=api_key,
             vsn=self._protocol_handler.protocol_version.vsn,
+            header_auth=select_authentication_header(self.additional_headers),
         )
         self.channel_socket_url = connect_url
         self.channel_socket_url_redacted = redacted_url
 
-        # Extra WebSocket handshake headers, re-sent on every (re)connect. Lets a
-        # caller send the API key as an ``x-api-key`` header instead of (or
-        # alongside) the URL query, so a trusted proxy can inject/replace it
-        # in-header and the credential stays out of URL/proxy logs.
-        self.additional_headers = dict(additional_headers or {})
-
         self.auto_reconnect = auto_reconnect
         self.reconnect_policy = reconnect_policy or ReconnectPolicy()
         self.join_timeout_s = join_timeout_s
@@ -152,6 +180,10 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._lifecycle_tasks: set[asyncio.Task[None]] = set()
         self._forced_close_pending = False
 
+    def redact_diagnostic(self, text: str) -> str:
+        """Sanitize untrusted transport error text using this connection's policy."""
+        return cast(ConnectionLogger, self.logger).redact(text)
+
     @property
     def _active_shutdown(self) -> asyncio.Task[None] | None:
         task = self._shutdown_task

phoenix_channels_python_client-0.3.1/phoenix_channels_python_client/diagnostics.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+from urllib.parse import parse_qsl, quote, quote_plus, urlsplit
+
+from websockets.protocol import State
+
+from phoenix_channels_python_client.authentication import (
+    API_KEY_PARAMETER,
+    TOKEN_PARAMETER,
+    AuthenticationHeader,
+)
+
+REDACTED = "[REDACTED]"
+PERCENT_ESCAPE = re.compile(r"%[0-9a-fA-F]{2}")
+
+
+AUTHENTICATION_NAMES = frozenset(
+    {
+        API_KEY_PARAMETER,
+        TOKEN_PARAMETER,
+        *AuthenticationHeader,
+        "x-token",
+        "authorization",
+        "cookie",
+    }
+)
+AUTHENTICATION_LABEL = re.compile(
+    r"(?i)((?:"
+    + "|".join(
+        re.escape(name) for name in sorted(AUTHENTICATION_NAMES, key=len, reverse=True)
+    )
+    + r")[\"\']?\s*[:=]\s*[\"\']?(?:(?:Bearer|Basic)\s+)?)([^\s&\"\']+)"
+)
+
+
+class ConnectionLogger(logging.Logger):
+    """Forward only sanitized records; raw transport objects never reach handlers."""
+
+    def __init__(self, target: logging.Logger, secrets: set[str]) -> None:
+        super().__init__(target.name)
+        self.target = target
+        self.parent = target
+        variants = sorted(
+            {
+                encoded
+                for secret in secrets
+                if secret
+                for encoded in (
+                    secret,
+                    quote(secret, safe=""),
+                    quote(secret),
+                    quote(secret, safe=";/?:@&=+$,#-_.!~*'()"),
+                    quote_plus(secret, safe=""),
+                    json.dumps(secret)[1:-1],
+                )
+            },
+            key=len,
+            reverse=True,
+        )
+
+        self.patterns = [
+            re.compile(
+                PERCENT_ESCAPE.sub(lambda match: f"(?i:{match[0]})", re.escape(secret))
+            )
+            for secret in variants
+        ]
+
+    def isEnabledFor(self, level: int) -> bool:  # noqa: N802 -- logging API
+        # Connection loggers are intentionally absent from the global registry,
+        # so its cache invalidation cannot track their effective level.
+        return (
+            not self.disabled
+            and not self.target.disabled
+            and self.manager.disable < level
+            and level >= self.getEffectiveLevel()
+        )
+
+    def redact(self, text: str) -> str:
+        for pattern in self.patterns:
+            text = pattern.sub(REDACTED, text)
+        return AUTHENTICATION_LABEL.sub(lambda match: match[1] + REDACTED, text)
+
+    def handle(self, record: logging.LogRecord) -> None:
+        if self.target.disabled:
+            return
+        message = str(record.msg)
+        if (
+            record.msg == "= connection is %s"
+            and isinstance(record.args, tuple)
+            and len(record.args) == 1
+            and isinstance(record.args[0], str)
+            and record.args[0] in State.__members__
+        ):
+            message = record.msg % record.args
+        if record.exc_info and record.exc_info[0]:
+            message += " [" + record.exc_info[0].__name__ + "]"
+        safe_record = logging.LogRecord(
+            record.name,
+            record.levelno,
+            record.pathname,
+            record.lineno,
+            self.redact(message),
+            (),
+            None,
+            record.funcName,
+        )
+        filtered = self.target.filter(safe_record)
+        if filtered:
+            if isinstance(filtered, logging.LogRecord):
+                safe_record = filtered
+            super().handle(safe_record)
+
+
+def diagnostic_secrets(url: str, api_key: str, headers: dict[str, str]) -> set[str]:
+    """Collect connection credentials without changing authentication bytes."""
+    return {
+        api_key,
+        *(
+            value
+            for name, value in parse_qsl(urlsplit(url).query)
+            if name.casefold() in AUTHENTICATION_NAMES
+        ),
+        *(
+            value
+            for name, value in headers.items()
+            if name.casefold() in AUTHENTICATION_NAMES
+        ),
+    }

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/phoenix_channels_python_client/protocol_handler.py

@@ -9,6 +9,7 @@ from typing import Any, NamedTuple
 
 from websockets import ClientConnection
 
+from phoenix_channels_python_client.diagnostics import ConnectionLogger
 from phoenix_channels_python_client.phx_messages import (
     PHOENIX_TOPIC,
     ChannelMessage,
@@ -110,6 +111,8 @@ class PHXProtocolHandler:
         self,
         protocol_version: PhoenixChannelsProtocolVersion
         | str = DEFAULT_PROTOCOL_VERSION,
+        *,
+        diagnostic_logger: logging.Logger | None = None,
     ) -> None:
         # Non-v2 values select v1 for compatibility with the original client.
         self.protocol_version = (
@@ -117,7 +120,9 @@ class PHXProtocolHandler:
             if protocol_version == PhoenixChannelsProtocolVersion.V2
             else PhoenixChannelsProtocolVersion.V1
         )
-        self.logger = logger.getChild("ProtocolHandler")
+        self.logger = diagnostic_logger or ConnectionLogger(
+            logger.getChild("ProtocolHandler"), set()
+        )
         self.logger.debug(
             "Initialized PHXProtocolHandler for protocol version %s",
             self.protocol_version,

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/phoenix_channels_python_client/reconnect_controller.py

@@ -15,10 +15,13 @@ from phoenix_channels_python_client.client_types import (
 )
 from phoenix_channels_python_client.exceptions import PHXConnectionError
 
-logger = logging.getLogger(__name__)
-
 
 class ReconnectControllerMixin:
+    logger: logging.Logger
+
+    def redact_diagnostic(self, text: str) -> str:
+        raise NotImplementedError
+
     reconnect_policy: ReconnectPolicy
     _rapid_disconnects: deque[float]
 
@@ -34,7 +37,7 @@ class ReconnectControllerMixin:
         if connection_uptime_s < self.reconnect_policy.rapid_disconnect_uptime_s:
             self._rapid_disconnects.append(now)
         self._prune_rapid_disconnects(now)
-        logger.debug(
+        self.logger.debug(
             "Recorded disconnect. uptime_s=%s rapid_count=%s rapid_window_s=%s",
             connection_uptime_s,
             len(self._rapid_disconnects),
@@ -50,7 +53,7 @@ class ReconnectControllerMixin:
         threshold = self.reconnect_policy.rapid_suppress_disconnect_count
         should_suppress = threshold > 0 and len(self._rapid_disconnects) >= threshold
         if should_suppress:
-            logger.debug(
+            self.logger.debug(
                 "Reconnect suppression threshold met. rapid_count=%s threshold=%s",
                 len(self._rapid_disconnects),
                 threshold,
@@ -115,7 +118,7 @@ class ReconnectControllerMixin:
             min_jittered = delay * low_ratio
             max_jittered = delay * high_ratio
             computed = self._random_between(min_jittered, max_jittered)
-            logger.debug(
+            self.logger.debug(
                 "Computed reconnect delay with hold-down jitter. attempt=%s "
                 "rapid_count=%s base_delay_s=%s min_delay_s=%s computed_delay_s=%s",
                 attempt,
@@ -134,7 +137,7 @@ class ReconnectControllerMixin:
             return computed
 
         computed = self._equal_jitter(delay)
-        logger.debug(
+        self.logger.debug(
             "Computed reconnect delay with equal jitter. attempt=%s rapid_count=%s "
             "base_delay_s=%s min_delay_s=%s computed_delay_s=%s",
             attempt,
@@ -170,7 +173,7 @@ class ReconnectControllerMixin:
     ) -> ReconnectDecision:
         if close_code is None:
             decision = ReconnectDecision(should_reconnect=True)
-            logger.debug(
+            self.logger.debug(
                 "Disconnect classification result. close_code=%s close_reason=%s "
                 "should_reconnect=%s",
                 close_code,
@@ -189,7 +192,7 @@ class ReconnectControllerMixin:
             and not self.reconnect_policy.reconnect_on_normal_close
         ):
             decision = ReconnectDecision(should_reconnect=False)
-            logger.debug(
+            self.logger.debug(
                 "Disconnect classification result. close_code=%s close_reason=%s "
                 "should_reconnect=%s",
                 close_code,
@@ -215,7 +218,7 @@ class ReconnectControllerMixin:
                     f"{CloseCode.POLICY_VIOLATION} ({reason})"
                 ),
             )
-            logger.debug(
+            self.logger.debug(
                 "Disconnect classification result. close_code=%s close_reason=%s "
                 "should_reconnect=%s terminal=%s",
                 close_code,
@@ -237,7 +240,7 @@ class ReconnectControllerMixin:
                 min_delay_s=self.reconnect_policy.service_restart_min_delay_s,
                 max_delay_s=self.reconnect_policy.service_restart_max_delay_s,
             )
-            logger.debug(
+            self.logger.debug(
                 "Disconnect classification result. close_code=%s close_reason=%s "
                 "should_reconnect=%s min_delay_s=%s max_delay_s=%s",
                 close_code,
@@ -261,7 +264,7 @@ class ReconnectControllerMixin:
                 min_delay_s=self.reconnect_policy.try_again_later_min_delay_s,
                 max_delay_s=self.reconnect_policy.try_again_later_max_delay_s,
             )
-            logger.debug(
+            self.logger.debug(
                 "Disconnect classification result. close_code=%s close_reason=%s "
                 "should_reconnect=%s min_delay_s=%s max_delay_s=%s",
                 close_code,
@@ -280,7 +283,7 @@ class ReconnectControllerMixin:
             return decision
 
         decision = ReconnectDecision(should_reconnect=True)
-        logger.debug(
+        self.logger.debug(
             "Disconnect classification result. close_code=%s close_reason=%s "
             "should_reconnect=%s",
             close_code,

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/phoenix_channels_python_client/supervisor.py

@@ -52,6 +52,8 @@ class _CloseDetails(NamedTuple):
 
 
 class _SupervisorRuntimeDeps(Protocol):
+    def redact_diagnostic(self, text: str) -> str: ...
+
     def _generate_ref(self) -> str: ...
     async def _rejoin_topics(self, generation: int) -> None: ...
     def _fail_pending_joins(self, error: Exception) -> None: ...
@@ -243,14 +245,19 @@ class SupervisorMixin:
 
     async def _connect(self) -> ClientConnection:
         return await connect(
-            self.channel_socket_url, additional_headers=self.additional_headers
+            self.channel_socket_url,
+            additional_headers=self.additional_headers,
+            logger=self.logger,
         )
 
     def _retry_after_connect_failure(self, exc: Exception) -> bool:
         if not self.auto_reconnect:
             self._settle_initial_connection(
                 PHXConnectionError(
-                    f"Failed to connect to {self.channel_socket_url_redacted}: {exc}"
+                    self._deps.redact_diagnostic(
+                        "Failed to connect to "
+                        f"{self.channel_socket_url_redacted}: {exc}"
+                    )
                 )
             )
             self.logger.error("Connection failed and auto_reconnect=False: %s", exc)

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1/phoenix_channels_python_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.3.0
+Version: 0.3.1
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -365,7 +365,7 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 
 ## Security Considerations
 
-**API Key in URL**: This client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
+**API Key in URL**: Without an authentication header, this client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
 
 - Server access logs
 - Reverse proxies and load balancers
@@ -376,8 +376,28 @@ setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_clie
 - Use short-lived, rotatable tokens rather than long-lived API keys
 - Consider this limitation when evaluating this client for sensitive environments
 
-**Note:** The official Phoenix JS client (v1.8+) supports header-based authentication via the `authToken` option, which avoids URL logging. This client always sends `api_key` in the URL (logged URLs show `api_key=***`). Pass `additional_headers={"x-api-key": key}` to also send it as a handshake header on every (re)connect, e.g. for a proxy that reads it from there.
+Pass `additional_headers={"x-api-key": key}` or `{"x-auth-token": jwt}` to use header-only authentication on every connection and reconnect.
 
 ---
 
 **Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.
+
+### Authentication and diagnostic safety
+
+A nonempty `x-api-key` or `x-auth-token` handshake header selects header-only authentication on
+every connection and reconnect. Embedded API-key parameters are removed; empty
+or conflicting authentication headers and simultaneous token-query authentication
+are rejected before connecting. A JWT header overrides an embedded token and takes
+precedence over an API-key header, matching the platform. Without an authentication header, legacy query authentication
+is preserved and remains visible to servers and proxies. No fallback is attempted.
+
+`client.logger` forwards sanitized connection records without raw arguments,
+exception objects, or socket metadata. `client.redact_diagnostic(text)` applies
+the credential policy to transport errors a caller needs to retain. Caller-visible
+errors may still contain personal data and should not be logged outside this policy.
+
+Connection diagnostics omit dynamic strings and transport payloads, including URLs,
+headers, frame bodies, user/topic identities, and untrusted server error details.
+Logs retain static lifecycle descriptions, native connection states,
+and exception types. Application data and caller-visible errors are not changed;
+applications remain responsible for logs outside this connection-owned boundary.

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/phoenix_channels_python_client.egg-info/SOURCES.txt

@@ -3,9 +3,11 @@ MANIFEST.in
 README.md
 pyproject.toml
 phoenix_channels_python_client/__init__.py
+phoenix_channels_python_client/authentication.py
 phoenix_channels_python_client/client.py
 phoenix_channels_python_client/client_state_machine.py
 phoenix_channels_python_client/client_types.py
+phoenix_channels_python_client/diagnostics.py
 phoenix_channels_python_client/exceptions.py
 phoenix_channels_python_client/phx_messages.py
 phoenix_channels_python_client/protocol_handler.py
@@ -30,6 +32,7 @@ tests/test_reconnect.py
 tests/test_reconnect_policy_invariants.py
 tests/test_reconnect_stress.py
 tests/test_run_forever_signals.py
+tests/test_security.py
 tests/test_shutdown_races.py
 tests/test_subscriptions.py
 tests/test_supervisor_internals.py

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phoenix-channels-python-client"
-version = "0.3.0"
+version = "0.3.1"
 description = "A Python client library for connecting to Phoenix Channels"
 readme = "README.md"
 license = "MIT"

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/tests/test_channel_recovery.py

@@ -90,7 +90,7 @@ async def test_a_crashed_channel_rejoins_on_the_live_socket(
         assert (await expect_message(received)).event == EVENT
         assert reconnects.count == 0
 
-    assert f"Recovered channel for topic {TOPIC}" in caplog.text
+    assert "Recovered channel for topic %s" in caplog.text
 
 
 @each_protocol
@@ -155,7 +155,7 @@ async def test_a_rejected_channel_rejoin_loses_the_topic(
         lost.only_error()
         assert TOPIC not in client.get_current_subscriptions()
         assert joins(phoenix_server) == REJOINED_ONCE
-    assert f"Lost topic {TOPIC}" in caplog.text
+    assert "Lost topic %s" in caplog.text
 
 
 @each_protocol

{phoenix_channels_python_client-0.3.0 → phoenix_channels_python_client-0.3.1}/tests/test_connection.py

@@ -155,8 +155,7 @@ async def test_additional_headers_are_sent_on_the_ws_handshake(
         assert server_ws.request is not None
         assert server_ws.request.headers["x-api-key"] == headers["x-api-key"]
 
-    # the header is additive; the existing api_key query param is untouched
-    assert f"api_key={API_KEY}" in client.channel_socket_url
+    assert "api_key=" not in client.channel_socket_url
 
 
 async def test_entering_fails_when_the_server_is_unreachable(

phoenix_channels_python_client-0.3.1/tests/test_security.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from http import HTTPStatus
+from logging.handlers import BufferingHandler
+from urllib.parse import parse_qsl, quote, urlsplit
+
+import pytest
+from websockets.asyncio.server import ServerConnection, serve
+from websockets.http11 import Request, Response
+
+from phoenix_channels_python_client import PHXChannelsClient
+from phoenix_channels_python_client.client_types import ReconnectPolicy
+from phoenix_channels_python_client.diagnostics import ConnectionLogger
+from phoenix_channels_python_client.exceptions import PHXConnectionError
+
+
+class TestConnectionSecurity:
+    @pytest.mark.parametrize(
+        "headers",
+        [
+            {"X-API-Key": ""},
+            {"x-api-key": "  "},
+            {"x-api-key": "one", "X-Api-Key": "two"},
+            {"x-auth-token": ""},
+            {"X-Auth-Token": " "},
+            {"x-auth-token": "one", "X-Auth-Token": "two"},
+        ],
+    )
+    def test_invalid_headers_are_rejected_before_network(
+        self, headers: dict[str, str]
+    ) -> None:
+        with pytest.raises(ValueError, match="nonempty credential"):
+            PHXChannelsClient(
+                "ws://127.0.0.1:1/socket", "query-secret", additional_headers=headers
+            )
+
+    def test_mixed_authentication_is_rejected(self) -> None:
+        with pytest.raises(ValueError, match="token query authentication"):
+            PHXChannelsClient(
+                "ws://127.0.0.1:1/socket?token=jwt",
+                "query-secret",
+                additional_headers={"x-api-key": "header-secret"},
+            )
+
+    def test_diagnostic_levels_follow_live_configuration(self) -> None:
+        target = logging.Logger("synthetic-target", logging.INFO)  # noqa: LOG001 -- isolated target avoids global state
+        logger = ConnectionLogger(target, {"synthetic-credential"})
+        collector = BufferingHandler(100)
+        logger.addHandler(collector)
+        logger.debug("initially suppressed")
+        target.setLevel(logging.DEBUG)
+        logger.debug("inherited debug")
+        target.setLevel(logging.WARNING)
+        logger.debug("inherited suppression")
+        logger.setLevel(logging.DEBUG)
+        logger.debug("local debug")
+        logger.setLevel(logging.WARNING)
+        logger.debug("local suppression")
+        logger.setLevel(logging.DEBUG)
+        previous_disable = logging.root.manager.disable
+        try:
+            logging.disable(logging.CRITICAL)
+            logger.debug("globally suppressed")
+            logging.disable(logging.NOTSET)
+            logger.debug("globally restored")
+        finally:
+            logging.disable(previous_disable)
+        assert [record.getMessage() for record in collector.buffer] == [
+            "inherited debug",
+            "local debug",
+            "globally restored",
+        ]
+
+    def test_connections_keep_independent_diagnostic_policies(self) -> None:
+        first = PHXChannelsClient("ws://127.0.0.1:1/socket", "first-credential")
+        second = PHXChannelsClient("ws://127.0.0.1:1/socket", "second-credential")
+        assert first.redact_diagnostic("first-credential") == "[REDACTED]"
+        assert second.redact_diagnostic("first-credential") == "first-credential"
+        assert second.redact_diagnostic("second-credential") == "[REDACTED]"
+        assert first.redact_diagnostic("correlation%2fother") == "correlation%2fother"
+
+    @pytest.mark.parametrize("policy", ["disabled", "filtered"])
+    def test_connection_records_respect_registered_logger_policy(
+        self, policy: str
+    ) -> None:
+        client = PHXChannelsClient("ws://127.0.0.1:1/socket", "synthetic-key")
+        target = logging.getLogger("phoenix_channels_python_client.client")
+        collector = BufferingHandler(100)
+        client.logger.addHandler(collector)
+        client.logger.setLevel(logging.WARNING)
+        previous_disabled = target.disabled
+
+        def reject(_record: logging.LogRecord) -> bool:
+            return False
+
+        try:
+            target.disabled = policy == "disabled"
+            if policy == "filtered":
+                target.addFilter(reject)
+            client.logger.warning("suppressed connection record")
+            assert collector.buffer == []
+
+            target.disabled = False
+            target.removeFilter(reject)
+            client.logger.warning("enabled connection record")
+            assert [record.getMessage() for record in collector.buffer] == [
+                "enabled connection record"
+            ]
+        finally:
+            target.disabled = previous_disabled
+            target.removeFilter(reject)
+
+    @pytest.mark.parametrize(
+        "header_names",
+        [
+            ("X-Api-Key",),
+            ("x-api-key", "X-API-KEY"),
+            ("X-Auth-Token",),
+            ("x-auth-token", "X-AUTH-TOKEN"),
+            ("x-api-key", "x-auth-token"),
+        ],
+    )
+    async def test_real_reconnect_uses_only_header_and_safe_raw_records(
+        self, caplog: pytest.LogCaptureFixture, header_names: tuple[str, ...]
+    ) -> None:
+        secret = "synthetic/private+ credential?x=1&z=#[]"  # noqa: S105 -- synthetic test credential
+        positional = "different-positional-secret"
+        requests = []
+        reconnected = asyncio.Event()
+
+        async def peer(connection: ServerConnection) -> None:
+            requests.append(connection.request)
+            if len(requests) == 1:
+                await connection.close(code=1012, reason=secret)
+            else:
+                reconnected.set()
+                await connection.wait_closed()
+
+        caplog.set_level(logging.DEBUG, logger="phoenix_channels_python_client.client")
+        async with serve(peer, "127.0.0.1", 0) as server:
+            port = server.sockets[0].getsockname()[1]
+            token = (
+                "legacy-jwt"
+                if any(name.casefold() == "x-auth-token" for name in header_names)
+                else ""
+            )
+            url = f"ws://127.0.0.1:{port}/socket?API%5FKEY=embedded-secret&api_key=embedded-secret&aPi_KeY=embedded-secret&token={token}&keep=one&keep=&vsn=old"
+            async with PHXChannelsClient(
+                url,
+                positional,
+                additional_headers={
+                    **dict.fromkeys(header_names, secret),
+                    "x-token": "synthetic-additional-token",
+                },
+                heartbeat_interval_s=None,
+                reconnect_policy=ReconnectPolicy(
+                    base_delay_s=0.01,
+                    service_restart_min_delay_s=0.01,
+                    service_restart_max_delay_s=0.01,
+                    rapid_first_min_delay_s=0.01,
+                ),
+            ) as client:
+                collector = BufferingHandler(1000)
+                client.logger.addHandler(collector)
+                await asyncio.wait_for(reconnected.wait(), 5)
+                client.logger.error(
+                    "authorization: Bearer %s", "unconfigured-bearer-value"
+                )
+                client.logger.error(
+                    '"authorization": "Basic %s"', "unconfigured-basic-value"
+                )
+                client.logger.error(
+                    "untrusted %s", secret, extra={"websocket": {"secret": secret}}
+                )
+                assert client.redact_diagnostic(quote(secret, safe="")) == "[REDACTED]"
+                assert client.redact_diagnostic(quote(secret)) == "[REDACTED]"
+                assert (
+                    client.redact_diagnostic(
+                        quote(secret, safe="").replace("%2F", "%2f")
+                    )
+                    == "[REDACTED]"
+                )
+                try:
+                    raise RuntimeError(secret)  # noqa: TRY301 -- exercise exception records
+                except RuntimeError:
+                    client.logger.exception(
+                        "refused credential", extra={"websocket": secret}
+                    )
+        for request in requests:
+            assert parse_qsl(urlsplit(request.path).query, keep_blank_values=True) == [
+                ("keep", "one"),
+                ("keep", ""),
+                ("vsn", "2.0.0"),
+            ]
+            for name in header_names:
+                assert request.headers[name] == secret
+            assert request.headers["x-token"] == "synthetic-additional-token"
+        records = [
+            record
+            for record in caplog.records
+            if record.name == "phoenix_channels_python_client.client"
+        ]
+        assert records
+        assert collector.buffer
+        for record in [*records, *collector.buffer]:
+            assert record.args == ()
+            assert record.exc_info is None
+            assert not hasattr(record, "websocket")
+            for credential in (
+                secret,
+                positional,
+                "embedded-secret",
+                "synthetic-additional-token",
+                "unconfigured-bearer-value",
+                "unconfigured-basic-value",
+                quote(secret, safe=""),
+            ):
+                assert credential not in repr(record.__dict__)
+        assert any("OPEN" in record.getMessage() for record in records)
+
+    async def test_refused_jwt_handshake_keeps_token_out_of_query_and_records(
+        self, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        secret = "synthetic.jwt/private+ token"  # noqa: S105 -- synthetic credential
+        requests = []
+
+        def refuse(connection: ServerConnection, request: Request) -> Response:
+            requests.append(request)
+            return connection.respond(HTTPStatus.UNAUTHORIZED, secret)
+
+        async def peer(connection: ServerConnection) -> None:
+            await connection.wait_closed()
+
+        caplog.set_level(logging.DEBUG, logger="phoenix_channels_python_client.client")
+        async with serve(peer, "127.0.0.1", 0, process_request=refuse) as server:
+            port = server.sockets[0].getsockname()[1]
+            client = PHXChannelsClient(
+                f"ws://127.0.0.1:{port}/socket?token=old-jwt&api_key=old-key",
+                secret,
+                additional_headers={"X-Auth-Token": secret},
+                auto_reconnect=False,
+            )
+            with pytest.raises(PHXConnectionError, match="401"):
+                await client.__aenter__()
+        [request] = requests
+        assert parse_qsl(urlsplit(request.path).query) == [("vsn", "2.0.0")]
+        assert request.headers["x-auth-token"] == secret
+        records = [
+            record
+            for record in caplog.records
+            if record.name == "phoenix_channels_python_client.client"
+        ]
+        assert records
+        assert all(secret not in repr(record.__dict__) for record in records)
+
+    async def test_transport_and_protocol_records_omit_personal_data(
+        self, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        identity = "synthetic-person@example.invalid"
+        session = "synthetic-cookie-session"
+        delivered = asyncio.Event()
+
+        def response(
+            _connection: ServerConnection, _request: Request, reply: Response
+        ) -> Response:
+            reply.headers["Set-Cookie"] = "session=" + session + "; HttpOnly"
+            return reply
+
+        async def peer(connection: ServerConnection) -> None:
+            await connection.send(
+                json.dumps([None, None, identity, "event", {"email": identity}])
+            )
+            delivered.set()
+            await connection.wait_closed()
+
+        caplog.set_level(logging.DEBUG, logger="phoenix_channels_python_client.client")
+        async with serve(peer, "127.0.0.1", 0, process_response=response) as server:
+            port = server.sockets[0].getsockname()[1]
+            client = PHXChannelsClient(
+                f"ws://127.0.0.1:{port}/socket?email={identity}",
+                "synthetic-key",
+                additional_headers={
+                    "x-api-key": "synthetic-key",
+                    "Cookie": "session=" + session,
+                },
+                auto_reconnect=False,
+                heartbeat_interval_s=None,
+            )
+            collector = BufferingHandler(1000)
+            client.logger.addHandler(collector)
+            async with client:
+                await asyncio.wait_for(delivered.wait(), 5)
+                await asyncio.sleep(0.01)
+                try:
+                    raise RuntimeError(identity)  # noqa: TRY301 -- exercise exception records
+                except RuntimeError:
+                    client.logger.exception("Connection callback failed: %s", session)
+                client.logger.warning(
+                    "Untrusted numeric identity: %d %.2f %s",
+                    15555550123,
+                    15555550123.0,
+                    identity,
+                )
+        assert any(
+            "Parsing raw message:" in record.getMessage() for record in collector.buffer
+        )
+        assert any("OPEN" in record.getMessage() for record in collector.buffer)
+        for record in collector.buffer:
+            assert identity not in repr(record.__dict__)
+            assert session not in repr(record.__dict__)
+            assert "15555550123" not in repr(record.__dict__)
+            assert record.args == ()
+            assert record.exc_info is None