span-panel-api 3.1.0__tar.gz → 3.2.0__tar.gz

{span_panel_api-3.1.0 → span_panel_api-3.2.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.0 → span_panel_api-3.2.0}/CHANGELOG.md

@@ -7,6 +7,32 @@ 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.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.
+
+### Fixed
+
+- **A rejected passphrase no longer reaches the debug log**, closing the shape of validation response that reports the field that failed in one place and the value it rejected in another, under a key that says nothing about what it holds.
+- **A panel that fails part-way through answering is reported as unreachable**, rather than as an error from the HTTP layer that a consumer catching this library's own errors would not catch.
+- **A response this library cannot read is reported as an API error naming the endpoint and the missing field**, instead of a raw parsing error raised out of the call.
+- **`get_v2_status` reports whether the panel proved proximity**, which until now only the detection path had read, so the same panel answered differently depending on which call had asked.
+
+### Added
+
+- **A warning when a panel's bootstrap traffic is unencrypted**, raised by the transport so that every call carrying a credential is covered, logged once per panel, never repeating the credential it warns about, and leaving plaintext the default it has
+  always been.
+
 ## [3.1.0]
 
 A security release. Three things a caller could not previously find out — whether a control command was delivered, whether the panel's bootstrap traffic was encrypted, and whether the CA behind the MQTT broker is still the one that was there yesterday —

{span_panel_api-3.1.0 → span_panel_api-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.1.0
+Version: 3.2.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
@@ -554,11 +554,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.
 
-**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.
+| 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"))
+```
+
+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 +603,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.0 → span_panel_api-3.2.0}/README.md

@@ -527,11 +527,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.
 
-**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.
+| 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"))
+```
+
+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 +576,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.0 → span_panel_api-3.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.1.0"
+version = "3.2.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.0 → span_panel_api-3.2.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 build_panel_ssl_context, ca_fingerprint, leaf_names_host
 from .auth import (
     delete_fqdn,
     download_ca_cert,
@@ -154,6 +154,9 @@ __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",
     "delete_fqdn",
     "download_ca_cert",
     "get_fqdn",

span_panel_api-3.2.0/src/span_panel_api/_http.py

@@ -0,0 +1,318 @@
+"""Shared HTTP helpers for SPAN Panel bootstrap REST calls."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+import logging
+import ssl
+from typing import Literal
+
+import httpx
+
+from .exceptions import SpanPanelAPIError, SpanPanelConnectionError, SpanPanelTimeoutError, SpanPanelValidationError
+
+_LOGGER = logging.getLogger(__name__)
+
+#: What a bootstrap URL resolves to when the caller names no port. HTTP without a
+#: context, HTTPS with one -- so a caller that pins the panel CA and leaves the
+#: port alone reaches the right place rather than the plaintext one.
+DEFAULT_HTTP_PORT = 80
+DEFAULT_HTTPS_PORT = 443
+
+#: The one bootstrap path two modules request: the detector probes it to decide
+#: whether the panel speaks v2 at all, and `get_v2_status` reads the same answer
+#: for a caller that already knows it does. Named here rather than spelled out in
+#: each, so the two cannot drift apart the way their parsers had.
+V2_STATUS_PATH = "/api/v2/status"
+
+#: The verbs the bootstrap API uses. Spelled as a `Literal` rather than passed
+#: through to `client.request()` so the dispatch below stays exhaustive and each
+#: call still reaches the named httpx method.
+type _Method = Literal["GET", "POST", "PUT", "DELETE"]
+
+
+@dataclass
+class _SSLCache:
+    """Mutable container for the cached SSLContext and its async lock."""
+
+    context: ssl.SSLContext | None = None
+    lock: asyncio.Lock | None = field(default=None, repr=False)
+
+    def get_lock(self) -> asyncio.Lock:
+        """Return the async lock, creating it lazily."""
+        if self.lock is None:
+            self.lock = asyncio.Lock()
+        return self.lock
+
+
+_ssl_cache = _SSLCache()
+
+
+def _build_url(host: str, port: int | None, path: str, ssl_context: ssl.SSLContext | None = None) -> str:
+    """Build a bootstrap URL, choosing the scheme from whether a CA was supplied.
+
+    ``port`` is ``None`` for "the caller did not say", which is the whole reason
+    it is nullable: with a plain ``int = 80`` there is no way to tell an omitted
+    port from one the caller deliberately set to 80, and the two need opposite
+    answers here.
+
+    An explicit ``port=80`` alongside an ``ssl_context`` is refused rather than
+    reinterpreted. It is not a hypothetical combination -- a consumer that
+    persisted a port before it pinned a CA produces exactly this on its first
+    HTTPS call -- and both readings are defensible: the caller may mean "HTTPS on
+    the unusual port 80" or may simply not have migrated the stored value.
+    Guessing either way is a security control that silently does something other
+    than what it was asked to.
+
+    Raises:
+        SpanPanelValidationError: ``ssl_context`` supplied with an explicit port 80.
+    """
+    if ssl_context is None:
+        resolved = DEFAULT_HTTP_PORT if port is None else port
+        return f"http://{host}{path}" if resolved == DEFAULT_HTTP_PORT else f"http://{host}:{resolved}{path}"
+
+    if port == DEFAULT_HTTP_PORT:
+        raise SpanPanelValidationError(
+            f"port={DEFAULT_HTTP_PORT} was passed together with an ssl_context for {host}. "
+            f"Port {DEFAULT_HTTP_PORT} is the plaintext default and {DEFAULT_HTTPS_PORT} is the TLS one; "
+            "pass the panel's HTTPS port explicitly, or omit port to take the default."
+        )
+    resolved = DEFAULT_HTTPS_PORT if port is None else port
+    return f"https://{host}{path}" if resolved == DEFAULT_HTTPS_PORT else f"https://{host}:{resolved}{path}"
+
+
+async def _create_ssl_context() -> ssl.SSLContext:
+    """Return a cached default SSL context, creating it in an executor on first call.
+
+    ``ssl.create_default_context()`` calls ``load_verify_locations`` which
+    performs blocking file I/O on the system CA bundle.  The resulting context
+    is thread-safe and reusable, so we cache it for the lifetime of the process.
+    """
+    cached = _ssl_cache.context
+    if cached is not None:
+        return cached
+    async with _ssl_cache.get_lock():
+        # Double-check after acquiring the lock.
+        cached = _ssl_cache.context
+        if cached is not None:
+            return cached
+        # Read back through a local rather than returning the field again. The
+        # field is `SSLContext | None` and another task may clear or replace it
+        # between the assignment and the return, so returning it a second time
+        # is a read this function cannot promise is non-None -- which is what a
+        # strict checker objects to, correctly. The value that was just built is
+        # the value to hand back.
+        loop = asyncio.get_running_loop()
+        context = await loop.run_in_executor(None, ssl.create_default_context)
+        _ssl_cache.context = context
+        return context
+
+
+@asynccontextmanager
+async def _get_client(
+    httpx_client: httpx.AsyncClient | None,
+    timeout: float,
+    ssl_context: ssl.SSLContext | None = None,
+) -> AsyncIterator[httpx.AsyncClient]:
+    """Yield the client this call should use, honouring both arguments truthfully.
+
+    **A supplied ``ssl_context`` wins over an injected client, deliberately.**
+    httpx fixes ``verify=`` at construction, so a context cannot be applied to a
+    client somebody else built. This function used to yield an injected client
+    untouched, which meant a caller passing both would have got a plaintext-or-
+    system-trust connection while believing it had pinned the panel CA -- a
+    security control that appears to be on and is off. The only two honest
+    options are to refuse the combination or to build a dedicated client, and
+    building one keeps the pin working for the consumer that motivated it: Home
+    Assistant injects its shared client at every bootstrap call site.
+
+    The cost is named rather than hidden: these calls lose the shared connection
+    pool and the injected client's timeout and header policy, and take this
+    function's ``timeout`` instead. Acceptable because every caller here is
+    bootstrap -- registration, detection, schema, FQDN, status -- made a handful
+    of times per config entry, not a hot path. The injected client is never
+    closed by this function on any path; the dedicated one always is.
+    """
+    if ssl_context is not None:
+        async with httpx.AsyncClient(timeout=timeout, verify=ssl_context) as client:
+            yield client
+        return
+    if httpx_client is not None:
+        yield httpx_client
+        return
+    ctx = await _create_ssl_context()
+    async with httpx.AsyncClient(timeout=timeout, verify=ctx) as client:
+        yield client
+
+
+#: Panels already warned about over plaintext, so the warning is said once each.
+#: Process-wide, once per panel host: wider than the MQTT bridge's unpinned-CA
+#: warning, which is per bridge instance and so repeats when a config entry is
+#: reloaded. See `_warn_plaintext_transport` for why the client object is the
+#: wrong key.
+_warned_plaintext_hosts: set[str] = set()
+
+
+def _reset_plaintext_warnings() -> None:
+    """Test hook. Not public API."""
+    _warned_plaintext_hosts.clear()
+
+
+def _warn_plaintext_transport(host: str, ssl_context: ssl.SSLContext | None) -> None:
+    """Say out loud, once per panel, that its bootstrap traffic is not encrypted.
+
+    In the same voice as the MQTT bridge's unpinned-CA warning, and for the same
+    reason: a security property that is off by default is only a decision if the
+    operator can tell it is off. ``ssl_context=None`` puts the request on
+    plaintext ``http://``, and two of these calls carry credentials --
+    registration sends the panel passphrase and brings the broker password back,
+    and passphrase rotation sends a bearer token and brings the new broker
+    password back -- so anything on the path reads all of it.
+
+    **Called from the transport, not from the calls that bootstrap a client.**
+    Warning at the call sites meant each new call site had to remember to, and
+    passphrase rotation did not: the one call a consumer reaches for when
+    reauthenticating went out in the clear and said nothing. There is one
+    mechanism here so there is nothing to remember.
+
+    **Scoped to the panel, not to the request or the client object.** Per
+    request is a line somebody filters out. Per client object looks tighter and
+    is worse, because the CA download runs on every MQTT reconnect and builds a
+    fresh client each time -- so that key would produce a warning per reconnect,
+    which is precisely what the bridge's own once-per-bridge warning exists to
+    avoid. The panel is the thing the warning is actually about.
+
+    The credential itself is never named. This is a warning *about* a secret,
+    not a place to put one.
+    """
+    if ssl_context is not None:
+        return
+    if host in _warned_plaintext_hosts:
+        return
+    _warned_plaintext_hosts.add(host)
+    _LOGGER.warning(
+        "Bootstrap traffic for %s is being sent over plaintext HTTP: no ssl_context was supplied, so "
+        "these requests and their responses -- including any credential they carry, such as the panel "
+        "passphrase and the broker password -- are readable by anything on the path between here and "
+        "the panel. Pin the panel's CA certificate and pass it as ssl_context.",
+        host,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class _Reply:
+    """One panel answer, with the decoding every caller of it needs.
+
+    Status classification stays with the caller, because it is genuinely
+    per-endpoint: 412 means "no passphrase is set" on the rotation path and
+    nothing anywhere else, and 404 means "no FQDN configured" on one call and
+    "not a v2 panel" on another. The two steps *around* that classification are
+    the same everywhere and had been written out once per endpoint -- translating
+    a failed connection, and turning a body into an object with the fields the
+    caller is about to read. Both live here.
+    """
+
+    host: str
+    endpoint: str
+    response: httpx.Response
+
+    @property
+    def status_code(self) -> int:
+        """The status the panel answered with."""
+        return self.response.status_code
+
+    @property
+    def text(self) -> str:
+        """The body as text, for the one endpoint that answers with a PEM."""
+        return self.response.text
+
+    @property
+    def headers(self) -> httpx.Headers:
+        """The response headers, for ``Retry-After`` and content-type."""
+        return self.response.headers
+
+    def json_object(self, *required: str, on_malformed: type[SpanPanelAPIError] = SpanPanelAPIError) -> dict[str, object]:
+        """Decode the body as a JSON object and confirm the fields about to be read.
+
+        A 200 is not a promise of a body. A panel part-way through starting
+        answers one with nothing in it; a proxy in front of one answers with an
+        HTML error page under a 200; and firmware is free to omit a field this
+        library treats as mandatory. Untranslated those surfaced as
+        ``JSONDecodeError`` and ``KeyError`` -- neither of them a
+        ``SpanPanelError``, so neither caught by a caller holding this library's
+        contract, and both escaping the retry clauses built on it.
+
+        ``on_malformed`` exists for the one endpoint where an unreadable body is
+        "not ready yet" rather than "wrong": the schema fetch, whose caller
+        retries a booting panel. Every other endpoint here is asked once.
+        """
+        try:
+            parsed = self.response.json()
+        except ValueError as exc:
+            raise on_malformed(
+                f"{self.host} answered HTTP {self.status_code} for {self.endpoint} with a body that is not JSON",
+                status_code=self.status_code,
+            ) from exc
+        if not isinstance(parsed, dict):
+            raise on_malformed(
+                f"{self.host} answered HTTP {self.status_code} for {self.endpoint} "
+                f"with {type(parsed).__name__}, not a JSON object",
+                status_code=self.status_code,
+            )
+        body: dict[str, object] = parsed
+        missing = sorted(key for key in required if key not in body)
+        if missing:
+            raise on_malformed(
+                f"{self.host} answered HTTP {self.status_code} for {self.endpoint} "
+                f"without the required field(s) {', '.join(missing)}",
+                status_code=self.status_code,
+            )
+        return body
+
+
+async def _request(
+    method: _Method,
+    host: str,
+    port: int | None,
+    path: str,
+    *,
+    timeout: float,
+    httpx_client: httpx.AsyncClient | None = None,
+    ssl_context: ssl.SSLContext | None = None,
+    json: dict[str, str] | None = None,
+    headers: dict[str, str] | None = None,
+) -> _Reply:
+    """Make one bootstrap request and translate everything that is not an answer.
+
+    The whole ``httpx.TransportError`` family, not just a refused connect:
+    ``ReadError`` and ``WriteError`` when a rebooting panel resets mid-request,
+    and ``RemoteProtocolError`` when its proxy closes without answering, which is
+    what a proxy restarting under load produces. ``TimeoutException`` is itself a
+    ``TransportError``, so it has to be caught first to keep its own class.
+
+    The verb is dispatched to the named httpx method rather than handed to
+    ``client.request()``: the URL stays the first positional argument of a
+    recognisable call, which is what makes an injected client inspectable by the
+    caller that supplied it.
+    """
+    url = _build_url(host, port, path, ssl_context)
+    _warn_plaintext_transport(host, ssl_context)
+    try:
+        async with _get_client(httpx_client, timeout, ssl_context) as client:
+            match method:
+                case "GET":
+                    response = await client.get(url, headers=headers)
+                case "POST":
+                    response = await client.post(url, json=json, headers=headers)
+                case "PUT":
+                    response = await client.put(url, json=json, headers=headers)
+                case "DELETE":
+                    response = await client.delete(url, headers=headers)
+    except httpx.TimeoutException as exc:
+        raise SpanPanelTimeoutError(f"Timed out connecting to {host}") from exc
+    except httpx.TransportError as exc:
+        raise SpanPanelConnectionError(f"Cannot reach panel at {host}: {exc}") from exc
+    return _Reply(host=host, endpoint=path, response=response)