span-panel-api 3.1.1__tar.gz → 3.3.0__tar.gz

{span_panel_api-3.1.1 → span_panel_api-3.3.0}/.gitignore

@@ -40,8 +40,3 @@ coverage_output.log
 # of which belongs in a repository. The differential that reads them commits its
 # *verdict* only, never the capture, and skips when the file is absent.
 tests/fixtures/live_*.json
-
-# Peer checkouts. CI clones the eBus specification and SpanPanel/panelbench here so
-# the provenance checks have something to compare vendored bytes against; the same
-# layout works locally if you would rather not point .env at siblings.
-/peers/

{span_panel_api-3.1.1 → span_panel_api-3.3.0}/CHANGELOG.md

@@ -7,6 +7,31 @@ 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.3.0]
+
+A pinned panel that has moved is no longer reported the same way as a panel whose clock reset, so a consumer can put the remedy in front of a user instead of retrying in silence.
+
+### Added
+
+- **`LeafNameMismatch` reports a broker whose certificate the pinned CA validates and which names somewhere other than the configured address**, carrying that address and the names the certificate does carry.
+- **`register_leaf_mismatch_callback` delivers that report**, at most once per outage and re-armed by the next successful connect, returning an unregister function like the other callback channels.
+
+### Changed
+
+- **The warning logged when a pinned handshake fails against an unchanged CA now names which failure it is** — an expired or otherwise rejected certificate, an unreachable broker, or a certificate that names somewhere else — instead of saying it could be
+  either.
+- **A moved panel is still retried and never terminal**, because the address can come back on its own and the report exists to make the alternative remedy visible rather than to stop the transport.
+
+## [3.2.0]
+
+A consumer pinned to a panel's CA cannot currently tell a panel that has moved from something impersonating one, because the two produce the same verification failure. This release splits the question.
+
+### Added
+
+- **`build_panel_ssl_context` takes `check_hostname`**, so a caller can verify that a peer holds a key the pinned CA signed without also asserting that the certificate names the address it was dialled by.
+- **`leaf_names_host` decides the name binding on its own**, hand-written against `getpeercert()` because `ssl.match_hostname` was removed in Python 3.12, and stricter than that function was: no wildcards, no `commonName` fallback, and DNS and IP entries
+  that never stand in for one another.
+
 ## [3.1.1]
 
 A follow-up to 3.1.0's security work, with no API change and no adapter move required.

{span_panel_api-3.1.1 → span_panel_api-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.1.1
+Version: 3.3.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
@@ -420,9 +420,25 @@ context = build_panel_ssl_context(stored_pem)
 fingerprint = ca_fingerprint(stored_pem)
 ```
 
-Leaving `ca_pem` unset keeps the previous behaviour, with one `WARNING` per bridge recording that the anchor was obtained unauthenticated. With it set, a certificate-verification failure is diagnosed rather than assumed: an expired leaf after a panel's
-clock reset and a hostname mismatch after the panel moved both produce the identical error, so the library refetches the advertised CA for comparison only and keeps retrying unless the fingerprint has actually changed — at which point it raises
-`SpanPanelCAChangedError` carrying both fingerprints and stops. Register `register_fatal_error_callback` to be told; a consumer that registers nothing still cannot mistake a dead bridge for a healthy one, because `ping()` and `get_snapshot()` re-raise.
+Leaving `ca_pem` unset keeps the previous behaviour, with one `WARNING` per bridge recording that the anchor was obtained unauthenticated. With it set, a certificate-verification failure is diagnosed rather than assumed, in two steps — a rotated CA, an
+expired leaf and a panel that has moved all raise the identical error, and the failed handshake carries no evidence about which.
+
+First the library refetches the advertised CA, for comparison only. If the fingerprint has changed it raises `SpanPanelCAChangedError` carrying both fingerprints and stops. Register `register_fatal_error_callback` to be told; a consumer that registers
+nothing still cannot mistake a dead bridge for a healthy one, because `ping()` and `get_snapshot()` re-raise.
+
+If the fingerprint matches, the panel is still the panel and the library asks one further question: a second handshake to the broker with hostname checking relaxed — the chain, the signature and the expiry still verified against the pin — to see whether
+the certificate names the address being dialled.
+
+```python
+def moved(mismatch: LeafNameMismatch) -> None:
+    print(f"configured as {mismatch.host}, certificate names {', '.join(mismatch.leaf_names)}")
+
+unregister = client.register_leaf_mismatch_callback(moved)
+```
+
+**This is not fatal and the transport keeps retrying**, because a returning DHCP lease fixes it without anyone's help; what the callback is for is putting the other remedy — re-point the configuration at one of the names reported — in front of a user who
+would otherwise see only an outage. It fires at most once per outage and is re-armed by the next successful connect. An expired leaf reports nothing, because nothing anyone does helps and the panel recovers on its own once it has the time again. Neither
+handshake can re-anchor anything: both are diagnostic, and the pin is the pin whatever the panel served.
 
 The bootstrap REST calls take an `ssl_context` for the same purpose. `download_ca_cert` is the one exception and stays on plain HTTP — it fetches the anchor everything else is checked against, so it has nothing to check itself against, and its result must
 be fingerprint-confirmed out of band before it is trusted.
@@ -554,11 +570,25 @@ The `PanelCapability` flag enum advertises transport features at runtime:
 
 ## Reference Payloads
 
-Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — live in [`tests/reference_payloads/`](tests/reference_payloads/README.md), with their provenance.
+Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — ship as package data of the adapter that parses each, and their provenance is documented in
+[`tests/reference_payloads/`](tests/reference_payloads/README.md) beside the loaders that read them.
+
+| Capture                  | Read from                                                  |
+| ------------------------ | ---------------------------------------------------------- |
+| `homie_schema.json`      | `span_panel_api_schema_0/reference/homie_schema.json`      |
+| `parent_child_tree.json` | `span_panel_api_schema_1/reference/parent_child_tree.json` |
+
+**Test-support data, and no runtime path reads either.** They ship so a downstream test suite pinned to a version of an adapter reads the same bytes that version was tested against, out of its own site-packages:
+
+```python
+from importlib.resources import files
+import json
+
+schema = json.loads((files("span_panel_api_schema_0") / "reference" / "homie_schema.json").read_text(encoding="utf-8"))
+```
 
-**They are fixtures of this repository, not package data.** Until 3.1.0 they sat inside the two source packages and were therefore carried in the wheels, which no runtime path ever read. `span_panel_api.reference_payloads` and
-`span_panel_api_schema_1.reference_payloads` no longer exist; a consumer that was importing them should vendor the bytes it needs and record the release it took them from, asserting that against `importlib.metadata.version(...)` so a moved pin that outruns
-the copy fails loudly instead of testing against a schema no panel runs.
+The bootstrap distribution ships neither: it registers no adapter and parses nothing. `span_panel_api.reference_payloads` and `span_panel_api_schema_1.reference_payloads` — the importable modules that existed until 3.1.0 — are still gone; these are data
+files read through `importlib.resources`, not an import surface.
 
 ## Project Structure
 
@@ -589,13 +619,15 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 
 packages/schema-0/           # distribution: span-panel-api-schema-0
 └── src/span_panel_api_schema_0/
-                             # Flat parser: HomiePropertyAccumulator, HomieLifecycle,
+    ├── reference/           # homie_schema.json — test-support package data, not read at runtime
+    └── ...                  # Flat parser: HomiePropertyAccumulator, HomieLifecycle,
                              # HomieDeviceConsumer, field metadata, SCHEMA_ANCHOR
 
 packages/schema-1/           # distribution: span-panel-api-schema-1
-├── spec/                    # eBus capability catalogs, byte-copied; checked against, never parsed
+├── spec/                    # eBus capability catalogs, byte-copied from the emitter wheel; checked against, never parsed
 └── src/span_panel_api_schema_1/
-                             # Parent/child parser: ControllerRoutes, snapshot mapper,
+    ├── reference/           # parent_child_tree.json — test-support package data, not read at runtime
+    └── ...                  # Parent/child parser: ControllerRoutes, snapshot mapper,
                              # adoption, catalog validator, spec_lock.json
 ```
 

{span_panel_api-3.1.1 → span_panel_api-3.3.0}/README.md

@@ -393,9 +393,25 @@ context = build_panel_ssl_context(stored_pem)
 fingerprint = ca_fingerprint(stored_pem)
 ```
 
-Leaving `ca_pem` unset keeps the previous behaviour, with one `WARNING` per bridge recording that the anchor was obtained unauthenticated. With it set, a certificate-verification failure is diagnosed rather than assumed: an expired leaf after a panel's
-clock reset and a hostname mismatch after the panel moved both produce the identical error, so the library refetches the advertised CA for comparison only and keeps retrying unless the fingerprint has actually changed — at which point it raises
-`SpanPanelCAChangedError` carrying both fingerprints and stops. Register `register_fatal_error_callback` to be told; a consumer that registers nothing still cannot mistake a dead bridge for a healthy one, because `ping()` and `get_snapshot()` re-raise.
+Leaving `ca_pem` unset keeps the previous behaviour, with one `WARNING` per bridge recording that the anchor was obtained unauthenticated. With it set, a certificate-verification failure is diagnosed rather than assumed, in two steps — a rotated CA, an
+expired leaf and a panel that has moved all raise the identical error, and the failed handshake carries no evidence about which.
+
+First the library refetches the advertised CA, for comparison only. If the fingerprint has changed it raises `SpanPanelCAChangedError` carrying both fingerprints and stops. Register `register_fatal_error_callback` to be told; a consumer that registers
+nothing still cannot mistake a dead bridge for a healthy one, because `ping()` and `get_snapshot()` re-raise.
+
+If the fingerprint matches, the panel is still the panel and the library asks one further question: a second handshake to the broker with hostname checking relaxed — the chain, the signature and the expiry still verified against the pin — to see whether
+the certificate names the address being dialled.
+
+```python
+def moved(mismatch: LeafNameMismatch) -> None:
+    print(f"configured as {mismatch.host}, certificate names {', '.join(mismatch.leaf_names)}")
+
+unregister = client.register_leaf_mismatch_callback(moved)
+```
+
+**This is not fatal and the transport keeps retrying**, because a returning DHCP lease fixes it without anyone's help; what the callback is for is putting the other remedy — re-point the configuration at one of the names reported — in front of a user who
+would otherwise see only an outage. It fires at most once per outage and is re-armed by the next successful connect. An expired leaf reports nothing, because nothing anyone does helps and the panel recovers on its own once it has the time again. Neither
+handshake can re-anchor anything: both are diagnostic, and the pin is the pin whatever the panel served.
 
 The bootstrap REST calls take an `ssl_context` for the same purpose. `download_ca_cert` is the one exception and stays on plain HTTP — it fetches the anchor everything else is checked against, so it has nothing to check itself against, and its result must
 be fingerprint-confirmed out of band before it is trusted.
@@ -527,11 +543,25 @@ The `PanelCapability` flag enum advertises transport features at runtime:
 
 ## Reference Payloads
 
-Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — live in [`tests/reference_payloads/`](tests/reference_payloads/README.md), with their provenance.
+Captures of what a panel actually serves — the `GET /api/v2/homie/schema` document and a full 40-space parent/child retained-topic tree — ship as package data of the adapter that parses each, and their provenance is documented in
+[`tests/reference_payloads/`](tests/reference_payloads/README.md) beside the loaders that read them.
+
+| Capture                  | Read from                                                  |
+| ------------------------ | ---------------------------------------------------------- |
+| `homie_schema.json`      | `span_panel_api_schema_0/reference/homie_schema.json`      |
+| `parent_child_tree.json` | `span_panel_api_schema_1/reference/parent_child_tree.json` |
+
+**Test-support data, and no runtime path reads either.** They ship so a downstream test suite pinned to a version of an adapter reads the same bytes that version was tested against, out of its own site-packages:
+
+```python
+from importlib.resources import files
+import json
+
+schema = json.loads((files("span_panel_api_schema_0") / "reference" / "homie_schema.json").read_text(encoding="utf-8"))
+```
 
-**They are fixtures of this repository, not package data.** Until 3.1.0 they sat inside the two source packages and were therefore carried in the wheels, which no runtime path ever read. `span_panel_api.reference_payloads` and
-`span_panel_api_schema_1.reference_payloads` no longer exist; a consumer that was importing them should vendor the bytes it needs and record the release it took them from, asserting that against `importlib.metadata.version(...)` so a moved pin that outruns
-the copy fails loudly instead of testing against a schema no panel runs.
+The bootstrap distribution ships neither: it registers no adapter and parses nothing. `span_panel_api.reference_payloads` and `span_panel_api_schema_1.reference_payloads` — the importable modules that existed until 3.1.0 — are still gone; these are data
+files read through `importlib.resources`, not an import surface.
 
 ## Project Structure
 
@@ -562,13 +592,15 @@ src/span_panel_api/          # distribution: span-panel-api (no parser)
 
 packages/schema-0/           # distribution: span-panel-api-schema-0
 └── src/span_panel_api_schema_0/
-                             # Flat parser: HomiePropertyAccumulator, HomieLifecycle,
+    ├── reference/           # homie_schema.json — test-support package data, not read at runtime
+    └── ...                  # Flat parser: HomiePropertyAccumulator, HomieLifecycle,
                              # HomieDeviceConsumer, field metadata, SCHEMA_ANCHOR
 
 packages/schema-1/           # distribution: span-panel-api-schema-1
-├── spec/                    # eBus capability catalogs, byte-copied; checked against, never parsed
+├── spec/                    # eBus capability catalogs, byte-copied from the emitter wheel; checked against, never parsed
 └── src/span_panel_api_schema_1/
-                             # Parent/child parser: ControllerRoutes, snapshot mapper,
+    ├── reference/           # parent_child_tree.json — test-support package data, not read at runtime
+    └── ...                  # Parent/child parser: ControllerRoutes, snapshot mapper,
                              # adoption, catalog validator, spec_lock.json
 ```
 

{span_panel_api-3.1.1 → span_panel_api-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.1.1"
+version = "3.3.0"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -78,6 +78,12 @@ dev = [
     # two distributions together, which is the configuration users will run.
     "span-panel-api-schema-0",
     "span-panel-api-schema-1",
+    # The producer of `span_panel_api_schema_1/reference/parent_child_tree.json`, pinned
+    # exactly because a reference capture is only evidence if what made it is
+    # known. Dependabot raises the bump on its own; the bump PR re-runs
+    # `scripts/capture_parent_child_reference.py` and the suite then says whether
+    # the wire moved.
+    "ebus-panel-sim==0.8.0",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "pytest-cov",
@@ -102,7 +108,7 @@ dev = [
     # transitive of `twine -> keyring -> secretstorage`, which is marked
     # `sys_platform == 'linux'` -- so the whole module ran in CI and silently
     # skipped on every macOS checkout, which reads in the summary line exactly
-    # like passing. See DEVELOPMENT.md, "A skip here is not a pass".
+    # like passing. See DEVELOPMENT.md, "A skip is still not a pass".
     #
     # Floored at 50.0.0 rather than at whatever the lock happens to hold: four
     # advisories cover the range below it (the highest first patched in 50.0.0),
@@ -153,8 +159,20 @@ include = [
 
 [tool.ruff]
 line-length = 125
+# `scripts/` is excluded file by file rather than as a directory, so that a new
+# script is linted by default and only the ones written before that was true are
+# grandfathered out. `capture_parent_child_reference.py` is the one in scope: it
+# produces a fixture the whole schema_1 suite is written against, and the rest are
+# hand-run tools.
 exclude = [
-    "scripts/",
+    "scripts/capture_flat_reference.py",
+    "scripts/capture_live_flat.py",
+    "scripts/coverage.py",
+    "scripts/format_markdown.py",
+    "scripts/test_live_auth.py",
+    "scripts/validate_lug_derivation/",
+    "scripts/verify_adapterless_install.py",
+    "scripts/verify_reconnect.py",
     ".*_cache/",
     "dist/",
     "venv/",
@@ -164,6 +182,10 @@ exclude = [
 [tool.ruff.lint.per-file-ignores]
 # Exclude tests from ALL linting checks (formatting still applies)
 "tests/**/*.py" = ["ALL"]
+# Its whole output is a report on stdout naming the producer, the device count and
+# where the capture landed, which is what an operator reads to decide whether to
+# adopt it. T20 is right for the library and wrong for a hand-run tool.
+"scripts/capture_parent_child_reference.py" = ["T201"]
 
 [tool.ruff.format]
 quote-style = "double"
@@ -217,8 +239,18 @@ warn_unused_configs = true
 disallow_untyped_defs = true
 explicit_package_bases = true
 mypy_path = "src"
+# Excluded by name for the reason `[tool.ruff]` gives above: the capture script is
+# checked like the library, and the hand-run tools written before that was expected
+# are not.
 exclude = [
-    "scripts/",
+    "scripts/capture_flat_reference.py",
+    "scripts/capture_live_flat.py",
+    "scripts/coverage.py",
+    "scripts/format_markdown.py",
+    "scripts/test_live_auth.py",
+    "scripts/validate_lug_derivation/",
+    "scripts/verify_adapterless_install.py",
+    "scripts/verify_reconnect.py",
     "tests/",
     "docs/",
     ".*_cache/",

{span_panel_api-3.1.1 → span_panel_api-3.3.0}/src/span_panel_api/__init__.py

@@ -6,7 +6,7 @@ supporting MQTT/Homie (v2) transport.
 
 from importlib.metadata import version as _pkg_version
 
-from ._ssl import build_panel_ssl_context, ca_fingerprint
+from ._ssl import LeafNameMismatch, build_panel_ssl_context, ca_fingerprint, leaf_names_host
 from .auth import (
     delete_fqdn,
     download_ca_cert,
@@ -154,6 +154,15 @@ __all__ = [  # noqa: RUF022
     # both live here rather than being reimplemented on the other side.
     "build_panel_ssl_context",
     "ca_fingerprint",
+    # Added 2026-08-28: the hostname half of verification, split out so a
+    # caller using a relaxed context can still establish the name binding.
+    "leaf_names_host",
+    # Added 2026-08-28 (3.3.0): what the transport reports when the pinned CA
+    # validates the broker's certificate and that certificate names somewhere
+    # else. Purely additive -- a consumer that registers no leaf-mismatch
+    # callback never receives one, and the reconnect behaviour it accompanies is
+    # unchanged.
+    "LeafNameMismatch",
     "delete_fqdn",
     "download_ca_cert",
     "get_fqdn",