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

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

@@ -7,6 +7,57 @@ 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.6.0]
+
+The snapshot carries every PV inverter a panel commissions, and registration copes with a panel that cannot read its own passphrase.
+
+### Added
+
+- **`SpanPanelSnapshot.pv_inverters`** carries every commissioned PV inverter, keyed by its feeding circuit's id, which stays put when firmware r202639 renames a panel's inverters, or by its device id where no circuit feeds it.
+- **`SpanPVSnapshot.serial_number`, `device_id` and `node_id`** give an inverter's serial number when one is published, its id on the wire, and its key in `pv_inverters`.
+- **`SpanEvseSnapshot.effective_charge_current_limit_a`** is the charge-current limit a charger is applying, its user limit when one is published and its ceiling otherwise, since from firmware r202639 a SPAN Drive publishes a user limit only once someone
+  sets one.
+- **`SpanPanelPassphraseUnavailableError`**, raised by `register_v2` and `create_span_client` for a panel that cannot read its own passphrase, is a `SpanPanelAPIError` rather than a `SpanPanelAuthError` because the passphrase the user gave may be correct.
+
+### Changed
+
+- **`V2AuthResponse.ebus_broker_password` and `hop_passphrase` are `str | None`**, `None` when a panel on firmware r202639 or later cannot read its passphrase yet still issues a valid access token.
+- **`register_v2` raises `SpanPanelServerError` with `status_code` for any 5xx**, including the 503 a panel on firmware r202639 answers until it knows its serial number, where it raised a plain `SpanPanelAPIError`.
+- **`SpanPanelSnapshot.pv` is the inverter on the lowest breaker space when more than one is commissioned**, rather than whichever one the adapter met first.
+- **`SpanPVSnapshot.nameplate_capacity_w` is documented as the array's DC size recorded at installation**, an informational figure and never a ceiling on PV power.
+
+## [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.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.4.1
+Version: 3.6.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
@@ -20,9 +20,9 @@ Requires-Dist: httpx<1.0,>=0.28.1
 Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
-Requires-Dist: span-panel-api-schema-0>=1.1.0; extra == 'schema-0'
+Requires-Dist: span-panel-api-schema-0>=1.2.0; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.1.0; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.2.0; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -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.6.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.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.4.1"
+version = "3.6.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -58,8 +58,12 @@ dependencies = [
 # makes every public protocol member mandatory of every adapter wheel — so a 1.0.0
 # adapter installed against this bootstrap is rejected at discovery rather than
 # working in a degraded way. The two must move together.
-schema-0 = ["span-panel-api-schema-0>=1.1.0"]
-schema-1 = ["span-panel-api-schema-1>=1.1.0"]
+# Raised to 1.2.0 for 3.6.0 for a different reason: no protocol member changed,
+# so a 1.1.x adapter is still accepted, but it fills neither `pv_inverters` nor
+# the inverter identity fields 3.6.0 adds. Upgrading through the extra is what
+# brings the adapters that do.
+schema-0 = ["span-panel-api-schema-0>=1.2.0"]
+schema-1 = ["span-panel-api-schema-1>=1.2.0"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"

{span_panel_api-3.4.1 → span_panel_api-3.6.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,8 @@ from .exceptions import (
     SpanPanelCAChangedError,
     SpanPanelConnectionError,
     SpanPanelError,
+    SpanPanelInsufficientPrivilegeError,
+    SpanPanelPassphraseUnavailableError,
     SpanPanelSchemaVersionError,
     SpanPanelServerError,
     SpanPanelStaleDataError,
@@ -46,6 +49,7 @@ from .models import (
     ExtensionSubject,
     FieldMetadata,
     HomieSchemaTypes,
+    PassphraseRotation,
     SpanBatterySnapshot,
     SpanCircuitSnapshot,
     SpanEvseSnapshot,
@@ -172,6 +176,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 +208,14 @@ __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",
+    # Added 2026-10-06 (3.6.0): registration reached a panel that cannot read its own
+    # passphrase. A subclass of SpanPanelAPIError, so existing except clauses
+    # keep their meaning; deliberately not a SpanPanelAuthError, because the
+    # passphrase the user supplied may be correct.
+    "SpanPanelPassphraseUnavailableError",
     "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.6.0}/src/span_panel_api/auth.py

@@ -18,9 +18,15 @@ 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,
+    SpanPanelPassphraseUnavailableError,
+    SpanPanelServerError,
+)
+from .models import HomieSchemaTypes, PassphraseRotation, V2AuthResponse, V2HomieSchema, V2StatusInfo
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -171,6 +177,11 @@ def _str(val: object) -> str:
     return str(val) if val is not None else ""
 
 
+def _optional_str(val: object) -> str | None:
+    """Extract a string from a JSON-decoded value that the panel may send as null or omit."""
+    return None if val is None else str(val)
+
+
 def _int(val: object) -> int:
     """Extract an int from a JSON-decoded value."""
     if isinstance(val, int):
@@ -182,6 +193,24 @@ def _int(val: object) -> int:
 
 HTTP_TOO_MANY_REQUESTS = 429
 
+#: The ``detail`` a registration 422 carries when the panel cannot read its own
+#: passphrase. Compared whole and quoted in the exception message, which is safe
+#: only because it is this fixed string and never anything the panel echoed.
+REGISTRATION_UNAVAILABLE_DETAIL = "Dashboard password is not available"
+
+
+def _error_detail(response: httpx.Response) -> str | None:
+    """The ``detail`` string of an error body, or None when there is no such string."""
+    try:
+        parsed = response.json()
+    except ValueError:
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    detail = parsed.get("detail")
+    return detail if isinstance(detail, str) else None
+
+
 #: Default attempts and base backoff used when the panel rate-limits a request.
 CA_CERT_MAX_ATTEMPTS = 5
 CA_CERT_BACKOFF_S = 1.5
@@ -240,10 +269,15 @@ async def register_v2(
             this call to ``https://``; ``None`` is byte-identical to 3.0.1.
 
     Returns:
-        V2AuthResponse with access token and MQTT broker credentials
+        V2AuthResponse with access token and MQTT broker credentials. From firmware
+        r202639 the broker password and passphrase are ``None`` when the panel
+        cannot read its passphrase; the access token is still valid.
 
     Raises:
         SpanPanelAuthError: Invalid passphrase or auth failure
+        SpanPanelPassphraseUnavailableError: The panel cannot read its own passphrase
+        SpanPanelServerError: The panel is not ready to register clients (any 5xx,
+            including the 503 it answers before its serial number is known); retryable
         SpanPanelConnectionError: Cannot reach panel
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response
@@ -267,6 +301,29 @@ async def register_v2(
         json=payload,
     )
 
+    sent = () if passphrase is None else (passphrase,)
+
+    if reply.status_code >= 500:
+        # From r202639 the panel answers 503 until it knows its own serial
+        # number, which is a panel still starting rather than a refusal. The
+        # same class `get_homie_schema` raises for a booting panel, so one retry
+        # clause covers both.
+        _log_auth_failure(reply.endpoint, reply.response, sent)
+        raise SpanPanelServerError(
+            f"Panel not ready: HTTP {reply.status_code} from /api/v2/auth/register",
+            status_code=reply.status_code,
+        )
+
+    if reply.status_code == 422 and _error_detail(reply.response) == REGISTRATION_UNAVAILABLE_DETAIL:
+        # Checked before the general 422 below, which means "credential not
+        # accepted". This one is the panel failing to read its own passphrase,
+        # and telling a user theirs is wrong would be false.
+        _log_auth_failure(reply.endpoint, reply.response, sent)
+        raise SpanPanelPassphraseUnavailableError(
+            f"Panel cannot register clients: {REGISTRATION_UNAVAILABLE_DETAIL} (HTTP 422)",
+            status_code=reply.status_code,
+        )
+
     if reply.status_code in (401, 403, 422):
         # Status only, matching the shape the branch below already uses. The body
         # is logged at DEBUG instead: a 422 from the panel's validation layer
@@ -276,39 +333,40 @@ async def register_v2(
         # passphrase goes with it because this is the one place in the library
         # that knows what was sent, and the panel is under no obligation to
         # quote it back under a key that names it.
-        _log_auth_failure(reply.endpoint, reply.response, () if passphrase is None else (passphrase,))
+        _log_auth_failure(reply.endpoint, reply.response, sent)
         raise SpanPanelAuthError(f"Authentication failed (HTTP {reply.status_code})")
 
     if reply.status_code != 200:
         raise SpanPanelAPIError(f"Unexpected response from /api/v2/auth/register: HTTP {reply.status_code}")
 
+    # The two credentials are not required: from r202639 the panel sends them
+    # as null, or may omit them, when it cannot read its passphrase, and the
+    # access token beside them is still good. Both read as None either way.
     data = reply.json_object(
         "accessToken",
         "tokenType",
         "iatMs",
         "ebusBrokerUsername",
-        "ebusBrokerPassword",
         "ebusBrokerHost",
         "ebusBrokerMqttsPort",
         "ebusBrokerWsPort",
         "ebusBrokerWssPort",
         "hostname",
         "serialNumber",
-        "hopPassphrase",
     )
     return V2AuthResponse(
         access_token=_str(data["accessToken"]),
         token_type=_str(data["tokenType"]),
         iat_ms=_int(data["iatMs"]),
         ebus_broker_username=_str(data["ebusBrokerUsername"]),
-        ebus_broker_password=_str(data["ebusBrokerPassword"]),
+        ebus_broker_password=_optional_str(data.get("ebusBrokerPassword")),
         ebus_broker_host=_str(data["ebusBrokerHost"]),
         ebus_broker_mqtts_port=_int(data["ebusBrokerMqttsPort"]),
         ebus_broker_ws_port=_int(data["ebusBrokerWsPort"]),
         ebus_broker_wss_port=_int(data["ebusBrokerWssPort"]),
         hostname=_str(data["hostname"]),
         serial_number=_str(data["serialNumber"]),
-        hop_passphrase=_str(data["hopPassphrase"]),
+        hop_passphrase=_optional_str(data.get("hopPassphrase")),
     )
 
 
@@ -491,6 +549,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 +615,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 +639,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 +665,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.6.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."""
 
@@ -58,6 +68,22 @@ class SpanPanelServerError(SpanPanelAPIError):
     """
 
 
+class SpanPanelPassphraseUnavailableError(SpanPanelAPIError):
+    """The panel cannot read its own passphrase, so it cannot issue broker credentials.
+
+    A fault on the panel, not a rejected credential, which is why this is not a
+    `SpanPanelAuthError`: a caller that maps that class to "wrong passphrase"
+    would send the user back to retype one that may well be correct.
+
+    Raised in two places. ``register_v2`` raises it for the 422 a panel answers
+    when registration needs the passphrase and the panel cannot read it.
+    ``create_span_client`` raises it when registration succeeded but returned no
+    broker password, which from firmware r202639 is how a panel in the same
+    state answers a registration it can otherwise complete; connecting to the
+    broker without a password could only fail later and less clearly.
+    """
+
+
 class SpanPanelCAChangedError(SpanPanelError):
     """The panel is presenting a certificate chain from a different CA than the pin.
 

{span_panel_api-3.4.1 → span_panel_api-3.6.0}/src/span_panel_api/factory.py

@@ -15,7 +15,7 @@ from .adapters import resolve_adapter
 from .auth import get_homie_schema, register_v2
 from .detection import detect_api_version
 from .dispatch import select_adapter_key
-from .exceptions import SpanPanelAuthError
+from .exceptions import SpanPanelAuthError, SpanPanelPassphraseUnavailableError
 from .mqtt.client import SpanMqttClient
 from .mqtt.models import MqttClientConfig
 
@@ -77,6 +77,10 @@ async def create_span_client(
     Raises:
         SpanPanelAuthError: Neither mqtt_config nor passphrase provided,
             or serial_number could not be determined.
+        SpanPanelPassphraseUnavailableError: Registration was attempted and the panel
+            cannot read its own passphrase, so it issued no broker password.
+        SpanPanelServerError: Registration was attempted and the panel is not ready
+            to register clients yet; retryable.
         SpanPanelConnectionError: Cannot reach panel during detection or registration.
         SpanPanelTimeoutError: Timeout during detection or registration.
         SpanPanelSchemaVersionError: The panel reports a data-model-version whose
@@ -90,6 +94,11 @@ async def create_span_client(
         auth_response = await register_v2(
             host, _V2_CLIENT_NAME, passphrase, port=port, httpx_client=httpx_client, ssl_context=ssl_context
         )
+        if auth_response.ebus_broker_password is None:
+            raise SpanPanelPassphraseUnavailableError(
+                "Panel registration returned no MQTT broker password because the panel cannot read "
+                "its passphrase; the broker cannot be reached until that is resolved"
+            )
         mqtt_config = MqttClientConfig(
             broker_host=auth_response.ebus_broker_host,
             username=auth_response.ebus_broker_username,