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

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

@@ -7,6 +7,38 @@ 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.4.1
+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.1 → 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.1 → span_panel_api-3.5.0}/pyproject.toml

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

{span_panel_api-3.4.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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
 # ===================================================================

{span_panel_api-3.4.1 → span_panel_api-3.5.0}/tests/test_https_transport.py

@@ -27,6 +27,7 @@ from span_panel_api.auth import (
     regenerate_passphrase,
     register_fqdn,
     register_v2,
+    rotate_passphrase,
 )
 from span_panel_api.detection import detect_api_version
 from span_panel_api.exceptions import SpanPanelValidationError
@@ -153,6 +154,12 @@ class TestAuthCallsUseHttps:
                 _json_response({"ebusBrokerPassword": "new"}),
                 "/api/v2/auth/passphrase",
             ),
+            (
+                lambda ctx, c: rotate_passphrase(HOST, "tok", httpx_client=c, ssl_context=ctx),
+                "put",
+                _json_response({"ebusBrokerPassword": "new", "hopPassphrase": "new"}),
+                "/api/v2/auth/passphrase",
+            ),
             (
                 lambda ctx, c: register_fqdn(HOST, "tok", "panel.example", httpx_client=c, ssl_context=ctx),
                 "post",
@@ -188,6 +195,7 @@ class TestAuthCallsUseHttps:
             "register_v2",
             "get_homie_schema",
             "regenerate_passphrase",
+            "rotate_passphrase",
             "register_fqdn",
             "get_fqdn",
             "delete_fqdn",

{span_panel_api-3.4.1 → span_panel_api-3.5.0}/tests/test_mqtt_connect_flow.py

@@ -11,10 +11,10 @@ import ssl
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
-from paho.mqtt.client import ConnectFlags, DisconnectFlags, MQTTMessage
+from paho.mqtt.client import ConnackCode, ConnectFlags, DisconnectFlags, MQTTMessage, convert_connack_rc_to_reason_code
 from paho.mqtt.reasoncodes import ReasonCode
 
-from span_panel_api.exceptions import SpanPanelAPIError, SpanPanelConnectionError
+from span_panel_api.exceptions import SpanPanelAPIError, SpanPanelAuthError, SpanPanelConnectionError
 from span_panel_api.mqtt.client import SpanMqttClient
 from span_panel_api.mqtt.connection import AsyncMqttBridge
 from span_panel_api.mqtt.const import MQTT_FULL_REBUILD_AFTER_FAILURES, MQTT_RECONNECT_MIN_DELAY_S
@@ -141,6 +141,93 @@ class TestBridgeConnect:
         mqtt_client_mock.disconnect.assert_called_once()
 
 
+def _refuse_connack(mqtt_client_mock: MagicMock, reason_code: ReasonCode) -> None:
+    """Make the mock broker answer CONNECT with a refused CONNACK."""
+    loop = asyncio.get_running_loop()
+
+    def _connect(**_kwargs: object) -> int:
+        loop.call_soon_threadsafe(
+            mqtt_client_mock.on_connect,
+            mqtt_client_mock,
+            None,
+            ConnectFlags(session_present=False),
+            reason_code,
+            None,
+        )
+        return 0
+
+    mqtt_client_mock.connect.side_effect = _connect
+
+
+class TestBridgeConnackRefusal:
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "reason_code",
+        [
+            convert_connack_rc_to_reason_code(ConnackCode.CONNACK_REFUSED_BAD_USERNAME_PASSWORD),
+            convert_connack_rc_to_reason_code(ConnackCode.CONNACK_REFUSED_NOT_AUTHORIZED),
+            ReasonCode(packetType=2, identifier=0x86),
+            ReasonCode(packetType=2, identifier=0x87),
+        ],
+        ids=["v311-rc4", "v311-rc5", "v5-0x86", "v5-0x87"],
+    )
+    async def test_credential_refusal_raises_auth_error(self, mqtt_client_mock: MagicMock, reason_code: ReasonCode) -> None:
+        bridge = _make_bridge()
+        _refuse_connack(mqtt_client_mock, reason_code)
+
+        with pytest.raises(SpanPanelAuthError, match=str(reason_code)) as exc_info:
+            await bridge.connect()
+
+        assert not isinstance(exc_info.value, SpanPanelConnectionError)
+        assert bridge.is_connected() is False
+        assert bridge._initial_connect_done is False
+
+    @pytest.mark.asyncio
+    async def test_other_refusal_still_raises_connection_error(self, mqtt_client_mock: MagicMock) -> None:
+        bridge = _make_bridge()
+        _refuse_connack(
+            mqtt_client_mock,
+            convert_connack_rc_to_reason_code(ConnackCode.CONNACK_REFUSED_SERVER_UNAVAILABLE),
+        )
+
+        with pytest.raises(SpanPanelConnectionError, match="MQTT connection failed"):
+            await bridge.connect()
+
+    @pytest.mark.asyncio
+    async def test_refusal_does_not_outlive_its_connect(self, mqtt_client_mock: MagicMock) -> None:
+        """A credential refusal from an earlier attempt does not color a later one."""
+        bridge = _make_bridge()
+        _refuse_connack(mqtt_client_mock, ReasonCode(packetType=2, identifier=0x86))
+        with pytest.raises(SpanPanelAuthError):
+            await bridge.connect()
+
+        # The socket closes before any CONNACK arrives on the second attempt.
+        loop = asyncio.get_running_loop()
+
+        def _connect_then_drop(**_kwargs: object) -> int:
+            loop.call_soon_threadsafe(
+                mqtt_client_mock.on_disconnect,
+                mqtt_client_mock,
+                None,
+                DisconnectFlags(is_disconnect_packet_from_server=False),
+                ReasonCode(packetType=2, aName="Unspecified error"),
+                None,
+            )
+            return 0
+
+        mqtt_client_mock.connect.side_effect = _connect_then_drop
+        with pytest.raises(SpanPanelConnectionError, match="MQTT connection failed"):
+            await bridge.connect()
+
+    @pytest.mark.asyncio
+    async def test_span_client_connect_propagates_auth_error(self, mqtt_client_mock: MagicMock) -> None:
+        client = _make_span_client()
+        _refuse_connack(mqtt_client_mock, ReasonCode(packetType=2, aName="Bad user name or password"))
+
+        with pytest.raises(SpanPanelAuthError):
+            await client.connect()
+
+
 # ---------------------------------------------------------------------------
 # AsyncMqttBridge — subscribe / publish
 # ---------------------------------------------------------------------------

{span_panel_api-3.4.1 → span_panel_api-3.5.0}/tests/test_mqtt_homie.py

@@ -1109,7 +1109,7 @@ class TestSpanMqttClientControl:
         client._adapter = SchemaZeroAdapter(serial_number=SERIAL, schema=flat_schema(32))
 
         # No description loaded — core node not found
-        with pytest.raises(SpanPanelServerError, match="Core node not found"):
+        with pytest.raises(SpanPanelServerError, match="no settable dominant power source control"):
             await client.set_dominant_power_source("GRID")
 
 

{span_panel_api-3.4.1 → span_panel_api-3.5.0}/tests/test_public_api_unchanged.py

@@ -116,6 +116,11 @@ EXPECTED_PUBLIC_API = {
     "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",
@@ -153,6 +158,9 @@ EXPECTED_PUBLIC_API = {
     "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.1 → span_panel_api-3.5.0}/tests/test_rest_transport_contract.py

@@ -35,6 +35,7 @@ from span_panel_api.auth import (
     regenerate_passphrase,
     register_fqdn,
     register_v2,
+    rotate_passphrase,
 )
 from span_panel_api.detection import detect_api_version
 from span_panel_api.exceptions import SpanPanelAPIError, SpanPanelConnectionError, SpanPanelError
@@ -48,6 +49,7 @@ CALLS: list[tuple[str, Callable[[httpx.AsyncClient], Awaitable[object]], str]] =
     ("register_v2", lambda c: register_v2(HOST, "home-assistant", "pass", httpx_client=c), "post"),
     ("download_ca_cert", lambda c: download_ca_cert(HOST, httpx_client=c), "get"),
     ("regenerate_passphrase", lambda c: regenerate_passphrase(HOST, "jwt", httpx_client=c), "put"),
+    ("rotate_passphrase", lambda c: rotate_passphrase(HOST, "jwt", httpx_client=c), "put"),
     ("register_fqdn", lambda c: register_fqdn(HOST, "jwt", "panel.example.com", httpx_client=c), "post"),
     ("get_fqdn", lambda c: get_fqdn(HOST, "jwt", httpx_client=c), "get"),
     ("delete_fqdn", lambda c: delete_fqdn(HOST, "jwt", httpx_client=c), "delete"),
@@ -60,6 +62,7 @@ CALLS: list[tuple[str, Callable[[httpx.AsyncClient], Awaitable[object]], str]] =
 DECODERS: list[tuple[str, Callable[[httpx.AsyncClient], Awaitable[object]], str]] = [
     ("register_v2", lambda c: register_v2(HOST, "home-assistant", "pass", httpx_client=c), "post"),
     ("regenerate_passphrase", lambda c: regenerate_passphrase(HOST, "jwt", httpx_client=c), "put"),
+    ("rotate_passphrase", lambda c: rotate_passphrase(HOST, "jwt", httpx_client=c), "put"),
     ("get_fqdn", lambda c: get_fqdn(HOST, "jwt", httpx_client=c), "get"),
     ("get_v2_status", lambda c: get_v2_status(HOST, httpx_client=c), "get"),
 ]

{span_panel_api-3.4.1 → span_panel_api-3.5.0}/tests/test_schema_one_adapter.py

@@ -418,8 +418,12 @@ def test_the_flat_vocabulary_is_translated_not_forwarded(adapter: SchemaOneAdapt
     for off_grid in ("BATTERY", "PV", "GENERATOR"):
         assert adapter.dominant_power_source_payload(off_grid) == "OFF_GRID", off_grid
 
-    for no_assertion in ("NONE", "UNKNOWN"):
-        assert adapter.dominant_power_source_payload(no_assertion) == "NONE", no_assertion
+
+def test_no_assertion_is_refused_rather_than_published(adapter: SchemaOneAdapter) -> None:
+    """The panel ignores a written `NONE`, so publishing one would report a clear
+    that never happened. An assertion clears itself once the battery link recovers."""
+    for no_assertion in ("NONE", "UNKNOWN", "none"):
+        assert adapter.dominant_power_source_payload(no_assertion) is None, no_assertion
 
 
 def test_an_unrecognised_value_is_refused_rather_than_guessed(adapter: SchemaOneAdapter) -> None:

{span_panel_api-3.4.1 → span_panel_api-3.5.0}/tests/test_schema_one_control_refusal.py

@@ -459,6 +459,31 @@ def test_a_declared_priority_missing_from_its_node_is_undeclared_too(adapter: Sc
 # ---------------------------------------------------------------------------
 
 
+def test_the_capture_declares_the_islanding_assertion_settable(adapter: SchemaOneAdapter) -> None:
+    target = adapter.set_dominant_power_source_target()
+
+    assert target is not None
+    assert target.topic == f"ebus/5/{PANEL}/shed/asserted-islanding-state/set"
+
+
+@pytest.mark.parametrize("settable", [None, False])
+def test_an_islanding_assertion_not_declared_settable_yields_no_target(settable: bool | None) -> None:
+    """The same refusal the relay makes: absence of `$settable` authorizes nothing."""
+    adapter = _adapter(_redeclared(PANEL, "shed", "asserted-islanding-state", settable=settable))
+
+    assert adapter.set_dominant_power_source_target() is None
+
+
+def test_a_panel_without_the_islanding_assertion_yields_no_target() -> None:
+    tree = _copy()
+    description = json.loads(tree[PANEL]["$description"])
+    del description["nodes"]["shed"]["properties"]["asserted-islanding-state"]
+    tree[PANEL]["$description"] = json.dumps(description)
+    tree[PANEL].pop("shed/asserted-islanding-state", None)
+
+    assert _adapter(tree).set_dominant_power_source_target() is None
+
+
 def test_has_circuit_answers_for_the_circuits_and_nothing_else(adapter: SchemaOneAdapter) -> None:
     """Membership of the circuit set, not of the topology.
 

{span_panel_api-3.4.1 → span_panel_api-3.5.0}/tests/test_schema_one_panel.py

@@ -331,15 +331,28 @@ def _synthetic(device_id: str, state: str = "ready", **props: str) -> Discovered
 
 
 def test_islanding_is_sensed_when_the_mid_is_ready() -> None:
-    """Tier 1. The MID is the islanding authority, so its answer wins outright."""
+    """Tier 2. With no assertion in force, the MID is the islanding authority."""
+    mid = _synthetic("mid", grid__islanding_state="OFF_GRID")
+    panel = _synthetic(PANEL, shed__asserted_islanding_state="NONE")
+
+    assert resolve_islanding_state(mid, panel) == "OFF_GRID"
+
+
+def test_an_assertion_in_force_outranks_a_ready_mid() -> None:
+    """Tier 1. The assertion is what the panel acts on, so it is the effective state.
+
+    Reading the MID first reported the sensed value while the panel was acting on the
+    user's assertion, which is the moment the two disagree and the one that matters.
+    """
     mid = _synthetic("mid", grid__islanding_state="OFF_GRID")
-    panel = _synthetic(PANEL, shed__asserted_islanding_state="ON_GRID")
 
-    assert resolve_islanding_state(mid, panel) == "OFF_GRID", "a ready MID outranks the user's assertion"
+    for asserted in ("ON_GRID", "OFF_GRID"):
+        panel = _synthetic(PANEL, shed__asserted_islanding_state=asserted)
+        assert resolve_islanding_state(mid, panel) == asserted, asserted
 
 
 def test_a_stale_mid_falls_back_to_the_users_assertion() -> None:
-    """Tier 2, and the case the assertion control exists for.
+    """Tier 1 again, and the case the assertion control exists for.
 
     When comms to the BESS or MID are lost and the grid returns, the user asserts the
     grid is up so the BESS stops discharging. Declining to read it would wire the
@@ -359,6 +372,14 @@ def test_a_stale_mid_with_no_assertion_is_unknown_not_guessed() -> None:
     assert resolve_islanding_state(mid, panel) is None
 
 
+def test_an_assertion_outside_the_enum_is_not_an_answer() -> None:
+    """Only `ON_GRID` and `OFF_GRID` are states; anything else falls through to the MID."""
+    mid = _synthetic("mid", grid__islanding_state="OFF_GRID")
+    panel = _synthetic(PANEL, shed__asserted_islanding_state="UNKNOWN")
+
+    assert resolve_islanding_state(mid, panel) == "OFF_GRID"
+
+
 def test_no_mid_reads_grid_power_and_never_asserts_off_grid() -> None:
     """Tier 3, and the error worth keeping a test on.