span-panel-api 3.4.0__tar.gz → 3.5.0__tar.gz

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/CHANGELOG.md

@@ -7,6 +7,48 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 Pre-releases are not listed separately. A beta is a step towards the next public version, so its changes are folded into that version's entry as they land and are described against the **last public release**, never against the beta before it. What one
 beta corrected in an earlier beta does not appear at all: from the point of view of somebody upgrading between released versions, it never happened.
 
+## [3.5.0]
+
+A rotation replaces the panel passphrase as well as the broker password, and the library now hands back both, so a caller no longer loses the only copy of the user's new passphrase. A broker that refuses the credentials is now reported as an authentication
+failure rather than a connection failure.
+
+**Upgrade note.** `connect()` raises `SpanPanelAuthError`, where it raised `SpanPanelConnectionError`, when the broker refuses the credentials (CONNACK "Bad user name or password" or "Not authorized"). The two are siblings under `SpanPanelError`, so a
+caller that caught `SpanPanelConnectionError` to handle a refused login must catch `SpanPanelAuthError` too. Right after a rotation the same error is also how a broker that has not yet accepted the new password answers, so retry it with backoff for up to
+about a minute before treating it as wrong credentials.
+
+Reported and fixed by [@dcj](https://github.com/dcj) in [#179](https://github.com/SpanPanel/span-panel-api/pull/179), from issue [#178](https://github.com/SpanPanel/span-panel-api/issues/178).
+
+### Added
+
+- **`rotate_passphrase()` returns both new values** as a `PassphraseRotation` (`ebus_broker_password`, `hop_passphrase`), because a rotation replaces the hop passphrase as well as the broker password and `register_v2` afterwards accepts only the new one.
+  Exported with the result type. Access tokens already issued are not revoked. The broker may not accept the new password the moment the call returns, and the old one may keep working briefly: reconnect with the new one and never fall back to the old one.
+  If the broker refuses it, retry with backoff for up to about a minute, including `SpanPanelAuthError`, which `connect()` raises for a refused CONNACK and which is what a broker that has not yet accepted the new password produces. If it is still refused,
+  rotate again and use the newly returned value. Do not rely on the old password stopping, or on existing sessions being disconnected, at any particular moment.
+- **`SpanPanelInsufficientPrivilegeError`** for a rotation refused with HTTP 403: the token is reduced-privilege (one obtained by proof of proximity), and registering with the passphrase yields a full-privilege token. A subclass of `SpanPanelAuthError`, so
+  existing except clauses still catch it.
+
+### Changed
+
+- **`regenerate_passphrase()` no longer claims the hop passphrase is unchanged.** It performs the same rotation and still returns only the new broker password as a `str`.
+- **`set_dominant_power_source` refuses with "Panel offers no settable dominant power source control"** where it said "Core node not found in panel topology", since the parent/child schema has no core node and now also refuses a control the panel does not
+  declare settable.
+- **Passphrase rotation raises `SpanPanelServerError` with `status_code` for a 5xx**, instead of a plain `SpanPanelAPIError`. After a 500 the outcome is unknown: the passphrase may or may not have changed.
+
+### Fixed
+
+- **A broker that refuses the credentials now raises `SpanPanelAuthError` from `connect()`**, instead of `SpanPanelConnectionError`, so a consumer can ask for new credentials rather than retry. This covers the CONNACK refusals "Bad user name or password"
+  and "Not authorized"; the error message carries the reason code. Every other refusal still raises `SpanPanelConnectionError`, and the reconnect loop still retries all of them.
+
+## [3.4.1]
+
+A panel that merely advertises itself on the network no longer produces the plaintext-transport warning when discovery probes it, closing the remaining way issue span#264's log line reached an operator who could do nothing about it.
+
+### Changed
+
+- **The status endpoint no longer emits the plaintext-transport warning**, for the CA download's reason from the other side: it is the detection probe made against devices nobody has configured, where no pin can exist and the only action is configuring the
+  panel — whose flow pins before any credential moves. It carries no credential in either direction, and it no longer spends the once-per-host warning slot, which it previously claimed first in every flow so that a genuinely credential-bearing call behind
+  it said nothing. Registration, passphrase rotation, and the schema fetch warn exactly as before.
+
 ## [3.4.0]
 
 A consumer that pinned the panel's CA could not put its schema fetches behind that pin, because the one port `SpanMqttClient` took served two transports with opposite security properties — the schema fetch, which should ride the pinned HTTPS transport, and

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.4.0
+Version: 3.5.0
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
@@ -476,7 +476,7 @@ Standalone async functions for v2-specific HTTP operations:
 ```python
 from span_panel_api import (
     register_v2, download_ca_cert, get_homie_schema,
-    regenerate_passphrase, get_v2_status,
+    rotate_passphrase, get_v2_status,
     register_fqdn, get_fqdn, delete_fqdn,
 )
 
@@ -493,8 +493,14 @@ schema = await get_homie_schema("192.168.1.100")
 print(f"Panel size: {schema.panel_size} spaces")
 print(f"Schema hash: {schema.types_schema_hash}")
 
-# Rotate MQTT broker password (invalidates previous password)
-new_password = await regenerate_passphrase("192.168.1.100", token=auth.access_token)
+# Rotate the passphrase, which is currently also the MQTT broker password; both values change
+# Access tokens already issued are not revoked
+rotation = await rotate_passphrase("192.168.1.100", token=auth.access_token)
+new_password = rotation.ebus_broker_password
+# The broker may not accept new_password immediately, and the old one may keep
+# working briefly. Retry a refused connect (including SpanPanelAuthError) with
+# backoff for up to about a minute; if still refused, rotate again and use the
+# newly returned value. Never fall back to the old password.
 
 # Get panel status (unauthenticated)
 status = await get_v2_status("192.168.1.100")

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/README.md

@@ -449,7 +449,7 @@ Standalone async functions for v2-specific HTTP operations:
 ```python
 from span_panel_api import (
     register_v2, download_ca_cert, get_homie_schema,
-    regenerate_passphrase, get_v2_status,
+    rotate_passphrase, get_v2_status,
     register_fqdn, get_fqdn, delete_fqdn,
 )
 
@@ -466,8 +466,14 @@ schema = await get_homie_schema("192.168.1.100")
 print(f"Panel size: {schema.panel_size} spaces")
 print(f"Schema hash: {schema.types_schema_hash}")
 
-# Rotate MQTT broker password (invalidates previous password)
-new_password = await regenerate_passphrase("192.168.1.100", token=auth.access_token)
+# Rotate the passphrase, which is currently also the MQTT broker password; both values change
+# Access tokens already issued are not revoked
+rotation = await rotate_passphrase("192.168.1.100", token=auth.access_token)
+new_password = rotation.ebus_broker_password
+# The broker may not accept new_password immediately, and the old one may keep
+# working briefly. Retry a refused connect (including SpanPanelAuthError) with
+# backoff for up to about a minute; if still refused, rotate again and use the
+# newly returned value. Never fall back to the old password.
 
 # Get panel status (unauthenticated)
 status = await get_v2_status("192.168.1.100")

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.4.0"
+version = "3.5.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/src/span_panel_api/__init__.py

@@ -16,6 +16,7 @@ from .auth import (
     regenerate_passphrase,
     register_fqdn,
     register_v2,
+    rotate_passphrase,
 )
 from .detection import DetectionResult, detect_api_version
 from .exceptions import (
@@ -26,6 +27,7 @@ from .exceptions import (
     SpanPanelCAChangedError,
     SpanPanelConnectionError,
     SpanPanelError,
+    SpanPanelInsufficientPrivilegeError,
     SpanPanelSchemaVersionError,
     SpanPanelServerError,
     SpanPanelStaleDataError,
@@ -46,6 +48,7 @@ from .models import (
     ExtensionSubject,
     FieldMetadata,
     HomieSchemaTypes,
+    PassphraseRotation,
     SpanBatterySnapshot,
     SpanCircuitSnapshot,
     SpanEvseSnapshot,
@@ -172,6 +175,11 @@ __all__ = [  # noqa: RUF022
     "register_fqdn",
     "regenerate_passphrase",
     "register_v2",
+    # Added 2026-10-02 (3.5.0): the rotation reports both new values, because
+    # it replaces the hop passphrase as well as the broker password. Additive --
+    # regenerate_passphrase keeps its str return.
+    "rotate_passphrase",
+    "PassphraseRotation",
     # Transport
     "MqttClientConfig",
     "SpanMqttClient",
@@ -199,6 +207,9 @@ __all__ = [  # noqa: RUF022
     "SpanPanelSchemaVersionError",
     "SpanPanelConnectionError",
     "SpanPanelError",
+    # Added 2026-10-02 (3.5.0): a 403 from a reduced-privilege token. A subclass
+    # of SpanPanelAuthError, so every existing except clause keeps its meaning.
+    "SpanPanelInsufficientPrivilegeError",
     "SpanPanelServerError",
     "SpanPanelStaleDataError",
     # Added 2026-08-31 (3.4.0): a bootstrap REST call that failed verification

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/src/span_panel_api/_http.py

@@ -31,11 +31,14 @@ DEFAULT_HTTPS_PORT = 443
 #: The one bootstrap path two modules request: the detector probes it to decide
 #: whether the panel speaks v2 at all, and `get_v2_status` reads the same answer
 #: for a caller that already knows it does. Named here rather than spelled out in
-#: each, so the two cannot drift apart the way their parsers had.
+#: each, so the two cannot drift apart the way their parsers had. Load-bearing
+#: for `_warn_plaintext_transport`'s exemption: a request to this path is the
+#: one the warning stays silent for, so a change here changes what warns.
 V2_STATUS_PATH = "/api/v2/status"
 
-#: The one bootstrap path exempt from the plaintext warning, named here because
-#: the transport is what grants the exemption. See `_warn_plaintext_transport`.
+#: Exempt from the plaintext warning alongside `V2_STATUS_PATH`, named here
+#: because the transport is what grants the exemption. See
+#: `_warn_plaintext_transport`.
 CA_CERT_PATH = "/api/v2/certificate/ca"
 
 #: The verbs the bootstrap API uses. Spelled as a `Literal` rather than passed
@@ -174,19 +177,33 @@ def _reset_plaintext_warnings() -> None:
 def _warn_plaintext_transport(host: str, path: str, ssl_context: ssl.SSLContext | None) -> None:
     """Say out loud, once per panel, that its bootstrap traffic is not encrypted.
 
-    **The CA download is exempt, and does not claim the once-per-host slot.**
+    **Two endpoints are exempt, and neither claims the once-per-host slot.**
     The warning exists so an operator can tell a security property is off when
-    it could be on, and for that endpoint there is no "on": verifying the fetch
-    of the anchor would require the anchor being fetched, an unverified-TLS
-    wrapping is readable and forgeable by the same active on-path attacker, and
-    the payload is a public certificate carrying no credential in either
-    direction — its authenticity control is the leaf check callers run *after*
-    the fetch. Each caller also states its own trust posture in its own voice:
-    the bridge's unpinned warning, a config flow's fingerprint confirmation, a
-    consumer's trust-on-first-use log. Warning here anyway named credentials the
-    call never carries, which is the line issue span#264 reported. Not marking
-    the host matters as much as not warning: a pinned consumer's diagnostic
-    re-read must not spend the slot a genuinely plaintext call needs later.
+    it could be on, and for both there is no "on". The CA download fetches the
+    very anchor verification would need — an unverified-TLS wrapping is
+    readable and forgeable by the same active on-path attacker, the payload is
+    a public certificate, and its authenticity control is the leaf check
+    callers run *after* the fetch. The status endpoint is the detection probe:
+    most prominently the request discovery makes against a device nobody has
+    configured, where no pin can exist because trust-on-first-use has not
+    happened and the only action available is configuring the panel — whose
+    flow pins before any credential moves, with a person confirming the
+    fingerprint. Neither call carries a credential in either direction, and
+    warning on them named credentials they never carry: the CA download's line
+    is what issue span#264 reported, and the status probe's is what a merely
+    *advertising* unconfigured panel produced at every boot.
+
+    Two limits of the status exemption, stated rather than implied. The body
+    informs decisions — `proximityProven`, the serial an identity check reads —
+    and a plaintext answer is one anything on the path can write; the controls
+    for that are the panel's own registration gate and the pin the consumer's
+    flow acquires before a credential moves, not a log line. And a consumer
+    *can* probe a configured, pinned panel's status without its context; the
+    exemption means no warning will point that out, so a consumer owes every
+    probe of a configured host the entry's own transport. Not marking the host matters as
+    much as not warning — the probe runs first in every flow and a diagnostic
+    re-read runs on pinned entries, and neither may spend the slot a
+    credential-bearing call needs later.
 
     In the same voice as the MQTT bridge's unpinned-CA warning, and for the same
     reason: a security property that is off by default is only a decision if the
@@ -214,7 +231,7 @@ def _warn_plaintext_transport(host: str, path: str, ssl_context: ssl.SSLContext
     """
     if ssl_context is not None:
         return
-    if path == CA_CERT_PATH:
+    if path in (CA_CERT_PATH, V2_STATUS_PATH):
         return
     if host in _warned_plaintext_hosts:
         return

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/src/span_panel_api/auth.py

@@ -18,9 +18,9 @@ import uuid
 
 import httpx
 
-from ._http import CA_CERT_PATH, V2_STATUS_PATH, _request
-from .exceptions import SpanPanelAPIError, SpanPanelAuthError, SpanPanelServerError
-from .models import HomieSchemaTypes, V2AuthResponse, V2HomieSchema, V2StatusInfo
+from ._http import CA_CERT_PATH, V2_STATUS_PATH, _Reply, _request
+from .exceptions import SpanPanelAPIError, SpanPanelAuthError, SpanPanelInsufficientPrivilegeError, SpanPanelServerError
+from .models import HomieSchemaTypes, PassphraseRotation, V2AuthResponse, V2HomieSchema, V2StatusInfo
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -491,6 +491,64 @@ async def get_homie_schema(
     )
 
 
+async def rotate_passphrase(
+    host: str,
+    token: str,
+    timeout: float = 10.0,
+    port: int | None = None,
+    httpx_client: httpx.AsyncClient | None = None,
+    ssl_context: ssl.SSLContext | None = None,
+) -> PassphraseRotation:
+    """Rotate the panel's passphrase, which is currently also its MQTT broker password.
+
+    One PUT replaces both: the hop passphrase that ``register_v2`` accepts and
+    the broker password, which the panel reports as two fields currently
+    carrying the same new value. Use ``ebus_broker_password`` for the broker.
+    Afterwards ``register_v2`` accepts only the new passphrase. Access tokens
+    already issued are not revoked.
+
+    The broker may not accept the new password the moment this call returns,
+    and the old one may keep working briefly. Reconnect with the new password
+    and never fall back to the old one. If the broker refuses it, retry with
+    backoff for up to about a minute, and include ``SpanPanelAuthError`` in the
+    retry: ``connect()`` raises it for a refused CONNACK, which is what a broker
+    that has not yet accepted the new password produces. If it is still refused
+    after that, rotate again and use the newly returned value. Do not rely on
+    the old password stopping, or on existing sessions being disconnected, at
+    any particular moment.
+
+    Args:
+        host: IP address or hostname of the SPAN Panel
+        token: Valid JWT access token
+        timeout: Request timeout in seconds when ``httpx_client`` is None; ignored when injected.
+        port: Port of the panel bootstrap API. ``None`` means "unspecified" and takes
+            the scheme's default -- 80 without ``ssl_context``, 443 with one.
+        httpx_client: Optional shared ``httpx.AsyncClient``; not closed by this function.
+            Not used when ``ssl_context`` is supplied -- httpx fixes its trust store at
+            construction, so a pinned CA needs a client built for it. See ``_get_client``.
+        ssl_context: Trust anchor for the panel's HTTPS certificate. Supplying one moves
+            this call to ``https://``; ``None`` is byte-identical to 3.0.1.
+
+    Returns:
+        The new broker password and the new hop passphrase.
+
+    Raises:
+        SpanPanelInsufficientPrivilegeError: HTTP 403; the token is reduced-privilege
+        SpanPanelAuthError: HTTP 401 (token invalid or stale) or 412 (no bearer token)
+        SpanPanelServerError: HTTP 5xx. After a 500 the outcome is unknown: the
+            passphrase may or may not have changed.
+        SpanPanelConnectionError: Cannot reach panel
+        SpanPanelTimeoutError: Request timed out
+        SpanPanelAPIError: Unexpected response
+    """
+    reply = await _put_passphrase(host, token, timeout, port, httpx_client, ssl_context)
+    data = reply.json_object("ebusBrokerPassword", "hopPassphrase")
+    return PassphraseRotation(
+        ebus_broker_password=_str(data["ebusBrokerPassword"]),
+        hop_passphrase=_str(data["hopPassphrase"]),
+    )
+
+
 async def regenerate_passphrase(
     host: str,
     token: str,
@@ -499,11 +557,13 @@ async def regenerate_passphrase(
     httpx_client: httpx.AsyncClient | None = None,
     ssl_context: ssl.SSLContext | None = None,
 ) -> str:
-    """Rotate the MQTT broker password on the SPAN Panel.
+    """Rotate the panel's passphrase and return only the new broker password.
 
-    After this call, the previous broker password is invalidated.
-    The new broker password is returned. Note: the hop_passphrase
-    (used for REST auth) is NOT changed by this operation.
+    The same PUT as ``rotate_passphrase``, with the same effect: the hop
+    passphrase changes too, ``register_v2`` accepts only the new one, access
+    tokens already issued are not revoked, and the same reconnect advice
+    applies. Use ``rotate_passphrase`` to receive both values; this function is
+    kept for callers written against its ``str`` return.
 
     Args:
         host: IP address or hostname of the SPAN Panel
@@ -521,11 +581,21 @@ async def regenerate_passphrase(
         New MQTT broker password
 
     Raises:
-        SpanPanelAuthError: Token invalid or expired
-        SpanPanelConnectionError: Cannot reach panel
-        SpanPanelTimeoutError: Request timed out
-        SpanPanelAPIError: Unexpected response
+        Exactly what ``rotate_passphrase`` raises.
     """
+    reply = await _put_passphrase(host, token, timeout, port, httpx_client, ssl_context)
+    return _str(reply.json_object("ebusBrokerPassword")["ebusBrokerPassword"])
+
+
+async def _put_passphrase(
+    host: str,
+    token: str,
+    timeout: float,
+    port: int | None,
+    httpx_client: httpx.AsyncClient | None,
+    ssl_context: ssl.SSLContext | None,
+) -> _Reply:
+    """Send the rotation PUT and raise for every status but 200."""
     reply = await _request(
         "PUT",
         host,
@@ -537,13 +607,27 @@ async def regenerate_passphrase(
         headers=_bearer(token),
     )
 
-    if reply.status_code in (401, 403, 412):
+    if reply.status_code == 403:
+        raise SpanPanelInsufficientPrivilegeError(
+            f"Token lacks the privilege to rotate the passphrase (HTTP {reply.status_code})"
+        )
+
+    if reply.status_code in (401, 412):
         raise SpanPanelAuthError(f"Authentication failed (HTTP {reply.status_code})")
 
+    if reply.status_code >= 500:
+        raise SpanPanelServerError(
+            f"Panel could not rotate the passphrase: HTTP {reply.status_code}",
+            status_code=reply.status_code,
+        )
+
     if reply.status_code != 200:
-        raise SpanPanelAPIError(f"Failed to regenerate passphrase: HTTP {reply.status_code}")
+        raise SpanPanelAPIError(
+            f"Failed to regenerate passphrase: HTTP {reply.status_code}",
+            status_code=reply.status_code,
+        )
 
-    return _str(reply.json_object("ebusBrokerPassword")["ebusBrokerPassword"])
+    return reply
 
 
 async def register_fqdn(

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/src/span_panel_api/exceptions.py

@@ -9,6 +9,16 @@ class SpanPanelAuthError(SpanPanelError):
     """Authentication failed."""
 
 
+class SpanPanelInsufficientPrivilegeError(SpanPanelAuthError):
+    """The token is valid but reduced-privilege, so the panel refused the call (HTTP 403).
+
+    A token obtained by proof of proximity (the door bypass) carries reduced
+    privilege. Registering with the panel's passphrase yields a full-privilege
+    token. A subclass of `SpanPanelAuthError`, so an existing except clause
+    keeps catching it.
+    """
+
+
 class SpanPanelConnectionError(SpanPanelError):
     """Connection to SPAN panel failed."""
 

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/src/span_panel_api/models.py

@@ -526,7 +526,15 @@ class V2AuthResponse:
     ebus_broker_wss_port: int
     hostname: str
     serial_number: str
-    hop_passphrase: str  # For REST auth only; will diverge from broker password
+    hop_passphrase: str  # For REST auth; currently the same value as ebus_broker_password
+
+
+@dataclass(frozen=True, slots=True)
+class PassphraseRotation:
+    """Response from PUT /api/v2/auth/passphrase: both values, both new."""
+
+    ebus_broker_password: str = field(repr=False)
+    hop_passphrase: str = field(repr=False)
 
 
 @dataclass(frozen=True, slots=True)

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/src/span_panel_api/mqtt/client.py

@@ -416,6 +416,7 @@ class SpanMqttClient:
         5. Wait for $state==ready and $description parsed
 
         Raises:
+            SpanPanelAuthError: The broker refused the credentials
             SpanPanelConnectionError: Cannot connect or device not ready
             SpanPanelTimeoutError: Connection or ready timed out
         """
@@ -865,6 +866,13 @@ class SpanMqttClient:
         directly; v1.0 routes the command to `shed/asserted-islanding-state`,
         whose enum is `NONE`/`ON_GRID`/`OFF_GRID`. Publishing `value` unchanged
         would put a string outside that enum on the wire.
+
+        Refused, with nothing published, when the panel does not declare the
+        control settable, and under v1.0 for `NONE` and `UNKNOWN`, which the
+        panel would ignore. Under v1.0 the panel also ignores `ON_GRID` and
+        `OFF_GRID` while its link to the battery is healthy (the battery's
+        `status/communication-state` is `OK`), leaving the published value
+        unchanged.
         """
         adapter = self._require_adapter()
         target = adapter.set_dominant_power_source_target()
@@ -873,7 +881,7 @@ class SpanMqttClient:
                 device_id=self._serial_number,
                 value=value,
                 detail="no such control",
-                message="Core node not found in panel topology",
+                message="Panel offers no settable dominant power source control",
             )
         payload = adapter.dominant_power_source_payload(value)
         if payload is None:

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/src/span_panel_api/mqtt/connection.py

@@ -26,6 +26,7 @@ from .._ssl import LeafNameMismatch, LeafProbe, build_panel_ssl_context, ca_fing
 from ..auth import download_ca_cert
 from ..exceptions import (
     SpanPanelAPIError,
+    SpanPanelAuthError,
     SpanPanelCAChangedError,
     SpanPanelConnectionError,
     SpanPanelError,
@@ -49,6 +50,11 @@ if TYPE_CHECKING:
 
 _LOGGER = logging.getLogger(__name__)
 
+# CONNACK refusals that mean the credentials were rejected: "Bad user name or
+# password" (0x86) and "Not authorized" (0x87). paho reports the MQTT 3.1.1
+# return codes 4 and 5 as these same MQTT 5 reason codes.
+_CONNACK_AUTH_REFUSALS = frozenset({0x86, 0x87})
+
 
 class AsyncMqttBridge:
     """Event-loop-driven paho-mqtt wrapper with async callback dispatch.
@@ -111,6 +117,8 @@ class AsyncMqttBridge:
         self._connected = False
         self._client: AsyncMQTTClient | None = None
         self._connect_event: asyncio.Event | None = None
+        # Reason code of the most recent refused CONNACK; `connect()` reads it.
+        self._connack_refusal: ReasonCode | None = None
 
         self._misc_timer: asyncio.TimerHandle | None = None
         self._should_reconnect = False
@@ -420,6 +428,8 @@ class AsyncMqttBridge:
         (blocking I/O), and waits for CONNACK.
 
         Raises:
+            SpanPanelAuthError: The broker refused the username or password
+                (CONNACK "Bad user name or password" or "Not authorized").
             SpanPanelConnectionError: Cannot connect to broker.
             SpanPanelTimeoutError: Connection timed out.
             SpanPanelCAChangedError: The panel is pinned and now advertises a
@@ -432,6 +442,7 @@ class AsyncMqttBridge:
             self._loop = asyncio.get_running_loop()
 
         self._connect_event = asyncio.Event()
+        self._connack_refusal = None
         self._should_reconnect = True
 
         _LOGGER.debug(
@@ -505,6 +516,9 @@ class AsyncMqttBridge:
             raise SpanPanelTimeoutError(f"Timed out connecting to MQTT broker at {self._host}:{self._port}") from exc
 
         if not self._connected:
+            refusal = self._connack_refusal
+            if refusal is not None and refusal.value in _CONNACK_AUTH_REFUSALS:
+                raise SpanPanelAuthError(f"MQTT broker at {self._host}:{self._port} refused the credentials: {refusal}")
             raise SpanPanelConnectionError(f"MQTT connection failed to {self._host}:{self._port}")
 
         self._initial_connect_done = True
@@ -763,6 +777,7 @@ class AsyncMqttBridge:
                 self._reconnect_task.cancel()
                 self._reconnect_task = None
         else:
+            self._connack_refusal = reason_code
             _LOGGER.warning("MQTT connection refused: %s", reason_code)
 
         # Signal the asyncio connect() waiter

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/src/span_panel_api/protocol.py

@@ -320,7 +320,7 @@ class SchemaAdapter(Protocol):
         """
 
     def set_dominant_power_source_target(self) -> ControlTarget | None:
-        """Where a dominant-power-source command goes, or None if the panel has no such control."""
+        """Where a dominant-power-source command goes, or None if the panel offers no settable one."""
 
     def set_evse_charge_limit_target(self, node_id: str) -> ControlTarget | None:
         """The target that writes one charger's charge-current limit, or None.
@@ -355,7 +355,9 @@ class SchemaAdapter(Protocol):
         `NONE`/`ON_GRID`/`OFF_GRID`, so the value has to be mapped rather than
         forwarded. Returning None means "no legal representation", and the
         transport should refuse the command rather than publish a value the
-        panel will reject.
+        panel will reject. v1.0 returns None for `NONE` and `UNKNOWN`: the panel
+        ignores a written `NONE`, and an assertion clears itself once the
+        panel's link to the battery recovers.
         """
 
     def register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:

{span_panel_api-3.4.0 → span_panel_api-3.5.0}/tests/test_detection_auth.py

@@ -11,9 +11,12 @@ from span_panel_api.exceptions import (
     SpanPanelAPIError,
     SpanPanelAuthError,
     SpanPanelConnectionError,
+    SpanPanelInsufficientPrivilegeError,
+    SpanPanelServerError,
     SpanPanelTimeoutError,
 )
 from span_panel_api.models import (
+    PassphraseRotation,
     V2AuthResponse,
     V2HomieSchema,
     V2StatusInfo,
@@ -28,6 +31,7 @@ from span_panel_api.auth import (
     regenerate_passphrase,
     register_fqdn,
     register_v2,
+    rotate_passphrase,
 )
 
 # ---------------------------------------------------------------------------
@@ -686,6 +690,77 @@ class TestRegeneratePassphrase:
                 await regenerate_passphrase("192.168.65.70", "")
 
 
+def _put_client(response: httpx.Response) -> AsyncMock:
+    """An injected client whose PUT returns `response`."""
+    client = AsyncMock(spec=httpx.AsyncClient)
+    client.put.return_value = response
+    return client
+
+
+ROTATIONS = [
+    pytest.param(regenerate_passphrase, id="regenerate_passphrase"),
+    pytest.param(rotate_passphrase, id="rotate_passphrase"),
+]
+
+
+class TestRotatePassphrase:
+    @pytest.mark.asyncio
+    async def test_returns_both_new_values(self):
+        body = {"ebusBrokerPassword": "new-broker", "hopPassphrase": "new-hop"}
+        result = await rotate_passphrase("192.168.65.70", "jwt", httpx_client=_put_client(_mock_response(200, body)))
+
+        assert result == PassphraseRotation(ebus_broker_password="new-broker", hop_passphrase="new-hop")
+
+    @pytest.mark.asyncio
+    async def test_repr_omits_the_secrets(self):
+        body = {"ebusBrokerPassword": "new-broker", "hopPassphrase": "new-hop"}
+        result = await rotate_passphrase("192.168.65.70", "jwt", httpx_client=_put_client(_mock_response(200, body)))
+
+        assert "new-broker" not in repr(result)
+        assert "new-hop" not in repr(result)
+
+    @pytest.mark.asyncio
+    async def test_a_200_without_hop_passphrase_is_an_api_error(self):
+        response = _mock_response(200, {"ebusBrokerPassword": "new-broker"})
+        with pytest.raises(SpanPanelAPIError, match="hopPassphrase"):
+            await rotate_passphrase("192.168.65.70", "jwt", httpx_client=_put_client(response))
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("call", ROTATIONS)
+    async def test_403_is_insufficient_privilege(self, call):
+        with pytest.raises(SpanPanelInsufficientPrivilegeError, match="403") as caught:
+            await call("192.168.65.70", "door-token", httpx_client=_put_client(_mock_response(403)))
+        assert isinstance(caught.value, SpanPanelAuthError)
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("call", ROTATIONS)
+    @pytest.mark.parametrize("status", [401, 412])
+    async def test_401_and_412_are_auth_errors(self, call, status):
+        with pytest.raises(SpanPanelAuthError, match=str(status)) as caught:
+            await call("192.168.65.70", "jwt", httpx_client=_put_client(_mock_response(status)))
+        assert not isinstance(caught.value, SpanPanelInsufficientPrivilegeError)
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("call", ROTATIONS)
+    @pytest.mark.parametrize("status", [500, 503])
+    async def test_5xx_is_a_server_error_with_status(self, call, status):
+        response = _mock_response(status, text="secret-in-body")
+        with pytest.raises(SpanPanelServerError) as caught:
+            await call("192.168.65.70", "jwt", httpx_client=_put_client(response))
+        assert caught.value.status_code == status
+        assert "secret-in-body" not in str(caught.value)
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("call", ROTATIONS)
+    async def test_other_4xx_is_an_api_error_not_a_server_error(self, call):
+        response = _mock_response(404, text="secret-in-body")
+        with pytest.raises(SpanPanelAPIError) as caught:
+            await call("192.168.65.70", "jwt", httpx_client=_put_client(response))
+        assert not isinstance(caught.value, SpanPanelServerError)
+        assert caught.value.status_code == 404
+        assert "secret-in-body" not in str(caught.value)
+
+
 # ===================================================================
 # register_fqdn
 # ===================================================================