python-netgear-switch-library 0.0.post154__py3-none-any.whl

netgear_switch/protocols/http/endpoints.py

@@ -0,0 +1,165 @@
+"""Per-model web-UI endpoint/CGI definitions (pure data).
+
+Each ``HttpModelSpec`` records how one model logs in and which page each read
+op scrapes. ``scheme_verified``/``reads_verified`` mark whether that model's
+flows are grounded in captured prior art or still
+``UNVERIFIED-pending-capture``:
+
+- ``gs305ep`` (Plus PoE): login, dashboard/stats, PoE, VLAN/PVID, and reboot
+  endpoints are GROUNDED in ``py_netgear_plus/models.py`` (GS30xSeries /
+  GS30xEPxSeries: ``CRYPT_FUNCTION="merge_hash"``, ``LOGIN_TEMPLATE``,
+  PoE/VLAN CGI paths) and in ``rcfiles/bin/netgear-smp-vlan`` (identical
+  ``merge`` hash scheme observed on GS105PE; ``8021qCf.cgi`` /
+  ``8021qMembe.cgi`` / ``portPVID.cgi`` field shapes and wire codes). Both
+  ``scheme_verified`` and ``reads_verified`` are ``True``.
+- ``gsm7228ps`` (Smart Managed Pro / S3300): the plaintext cheetah login form
+  is GROUNDED in ``certbot-hook-netgear-switches/netgear-updater.py``
+  (``S3300Updater``), so ``scheme_verified`` is ``True``. SNMP is the
+  preferred read/write path for this model; no web-UI read/write flow has
+  been captured, so ``reads_verified`` is ``False`` and the reader/writer
+  refuse rather than fabricate.
+- ``gs110emx`` (Plus EMx / Gambit): the login hash function and Gambit-token
+  extraction are NOT grounded in a captured session (only partially
+  corroborated by ``py_netgear_plus/models.py`` EMxSeries/GS110EMX). Both
+  ``scheme_verified`` and ``reads_verified`` are ``False``.
+"""
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from ...errors import UnsupportedCapabilityError
+from ...registry import Backend
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from ...registry import SwitchModel
+
+
+class LoginScheme(enum.Enum):
+    MERGE_HASH_CGI = "merge_hash_cgi"   # Plus SID scheme (gs305ep) — GROUNDED
+    GAMBIT = "gambit"                   # EMx scheme (gs110emx) — UNVERIFIED
+    CHEETAH_FORM = "cheetah_form"       # Pro/S3300 (gsm7228ps) — plaintext form
+
+
+@dataclass(frozen=True)
+class HttpModelSpec:
+    model_key: str
+    scheme: LoginScheme
+    scheme_verified: bool
+    login_path: str
+    password_field: str
+    cookie_name: str
+    needs_rand: bool
+    dashboard_path: str | None
+    stats_path: str | None
+    poe_config_path: str | None
+    poe_status_path: str | None
+    vlan_config_path: str | None
+    vlan_membership_path: str | None
+    pvid_path: str | None
+    reboot_path: str | None
+    logout_path: str | None
+    is_epx_poe: bool
+    reads_verified: bool
+
+
+# GROUNDED: py_netgear_plus/models.py GS30xSeries/GS30xEPxSeries
+# (CRYPT_FUNCTION="merge_hash", ALLOWED_COOKIE_TYPES=["SID"],
+# check_login_form_rand=True, LOGIN_TEMPLATE url=/login.cgi
+# params={password:_password_hash}; PoE/VLAN CGI paths) plus
+# rcfiles/bin/netgear-smp-vlan (identical merge-hash login observed on
+# GS105PE; 8021qCf.cgi/8021qMembe.cgi/portPVID.cgi field shapes and the
+# 1=Untagged/2=Tagged/3=Excluded membership wire codes). Fully grounded.
+_GS305EP = HttpModelSpec(
+    model_key="gs305ep",
+    scheme=LoginScheme.MERGE_HASH_CGI,
+    scheme_verified=True,
+    login_path="/login.cgi",
+    password_field="password",
+    cookie_name="SID",
+    needs_rand=True,
+    dashboard_path="/dashboard.cgi",
+    stats_path="/portStatistics.cgi",
+    poe_config_path="/PoEPortConfig.cgi",
+    poe_status_path="/getPoePortStatus.cgi",
+    vlan_config_path="/8021qCf.cgi",
+    vlan_membership_path="/8021qMembe.cgi",
+    pvid_path="/portPVID.cgi",
+    reboot_path="/device_reboot.cgi",
+    logout_path="/logout.cgi",
+    is_epx_poe=True,
+    reads_verified=True,
+)
+
+# UNVERIFIED-pending-capture: Gambit login hash + /iss/specific pages not
+# grounded in a captured session. Endpoints from py_netgear_plus EMxSeries.
+_GS110EMX = HttpModelSpec(
+    model_key="gs110emx",
+    scheme=LoginScheme.GAMBIT,
+    scheme_verified=False,
+    login_path="/homepage.html",
+    password_field="LoginPassword",
+    cookie_name="gambitCookie",
+    needs_rand=True,
+    dashboard_path="/iss/specific/sysInfo.html",
+    stats_path="/iss/specific/interface_stats.html",
+    poe_config_path=None,
+    poe_status_path=None,
+    vlan_config_path=None,
+    vlan_membership_path=None,
+    pvid_path=None,
+    reboot_path=None,
+    logout_path="/iss/specific/logout.html",
+    is_epx_poe=False,
+    reads_verified=False,
+)
+
+# Login is GROUNDED: certbot-hook-netgear-switches/netgear-updater.py
+# S3300Updater posts plaintext pwd= to /base/cheetah_login.html and reads
+# back a SID cookie. SNMP is the preferred read/write path for this model;
+# no web-UI read/write flow has been captured, so reads/writes are
+# UNVERIFIED-pending-capture and only login + reboot/logout are populated.
+_GSM7228PS = HttpModelSpec(
+    model_key="gsm7228ps",
+    scheme=LoginScheme.CHEETAH_FORM,
+    scheme_verified=True,
+    login_path="/base/cheetah_login.html",
+    password_field="pwd",
+    cookie_name="SID",
+    needs_rand=False,
+    dashboard_path=None,
+    stats_path=None,
+    poe_config_path=None,
+    poe_status_path=None,
+    vlan_config_path=None,
+    vlan_membership_path=None,
+    pvid_path=None,
+    reboot_path=None,
+    logout_path=None,
+    is_epx_poe=False,
+    reads_verified=False,
+)
+
+_SPECS: dict[str, HttpModelSpec] = {
+    s.model_key: s for s in (_GS305EP, _GS110EMX, _GSM7228PS)
+}
+
+HTTP_SPECS: Mapping[str, HttpModelSpec] = MappingProxyType(_SPECS)
+
+
+def http_spec(model: SwitchModel) -> HttpModelSpec:
+    """Return the web-UI spec for ``model`` or raise if it has no HTTP backend."""
+    if Backend.HTTP not in model.backends:
+        raise UnsupportedCapabilityError(
+            f"model {model.key!r} has no HTTP backend"
+        )
+    try:
+        return _SPECS[model.key]
+    except KeyError:
+        raise UnsupportedCapabilityError(
+            f"model {model.key!r} has an HTTP backend but no endpoint spec"
+        ) from None

netgear_switch/protocols/http/forms.py

@@ -0,0 +1,77 @@
+"""Pure (I/O-free) web-UI write-form encoders.
+
+Field names/values are GROUNDED against ``py_netgear_plus`` GS30xSeries
+``get_switch_poe_port_data``/``get_power_cycle_poe_port_data`` and
+``rcfiles/bin/netgear-smp-vlan`` (8021q/PVID forms). Each op requires the
+page's CSRF ``hash`` (scraped just before the POST by the writer).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ...models import VlanMode
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_WIRE = {VlanMode.UNTAGGED: "1", VlanMode.TAGGED: "2", VlanMode.EXCLUDED: "3"}
+
+
+def poe_apply_form(
+    *, port: int, on: bool, is_epx: bool, csrf_hash: str
+) -> dict[str, str]:
+    return {
+        "ACTION": "Apply",
+        "portID": str(port - 1),
+        "ADMIN_MODE": "1" if on else "0",
+        "PORT_PRIO": "0",
+        "POW_MOD": "3",
+        "POW_LIMT_TYP": "2" if is_epx else "0",
+        "DETEC_TYP": "2",
+        "DISCONNECT_TYP": "2",
+        "hash": csrf_hash,
+    }
+
+
+def poe_reset_form(*, port: int, csrf_hash: str) -> dict[str, str]:
+    return {"ACTION": "Reset", f"port{port - 1}": "checked", "hash": csrf_hash}
+
+
+def pvid_form(*, port: int, vlan: int, csrf_hash: str) -> dict[str, str]:
+    return {f"port{port - 1}": "checked", "pvid": str(vlan), "hash": csrf_hash}
+
+
+def membership_hidden_mem(states: Mapping[int, VlanMode], port_count: int) -> str:
+    return "".join(
+        _WIRE[states.get(p, VlanMode.EXCLUDED)] for p in range(1, port_count + 1)
+    )
+
+
+def membership_form(
+    *, vlan: int, hidden_mem: str, csrf_hash: str
+) -> dict[str, str]:
+    return {"VLAN_ID": str(vlan), "hiddenMem": hidden_mem, "hash": csrf_hash}
+
+
+def vlan_add_form(*, vlan: int, csrf_hash: str) -> dict[str, str]:
+    return {
+        "ACTION": "Add",
+        "ADD_VLANID": str(vlan),
+        "status": "Enable",
+        "hash": csrf_hash,
+    }
+
+
+def vlan_delete_form(
+    *, vlan: int, checkbox_index: int, csrf_hash: str
+) -> dict[str, str]:
+    return {
+        "ACTION": "Delete",
+        f"vlanck{checkbox_index}": str(vlan),
+        "status": "Enable",
+        "hash": csrf_hash,
+    }
+
+
+def reboot_form(*, csrf_hash: str) -> dict[str, str]:
+    return {"hash": csrf_hash}

netgear_switch/protocols/http/parse.py

@@ -0,0 +1,238 @@
+"""Pure (I/O-free) parsers mapping web-UI HTML -> shared ``models`` types.
+
+Regex-based (no ``lxml``/``bs4`` dependency), matching the documented HTML
+shape the virtual renderer (``virtual/web.py``, Slice 6 Task 10) emits and
+that the captured/synthetic fixtures under ``tests/fixtures/http/`` mirror.
+Real-device column offsets are UNVERIFIED-pending-capture; confirm against
+captured HTML before production use (each such fixture is headed
+``UNVERIFIED-pending-capture``).
+
+Two different failure shapes are deliberate:
+
+- A *token* scrape (``parse_login_rand``/``parse_csrf_hash``/
+  ``parse_selected_vlan``) returns ``None`` when the value is absent. The
+  reader (Task 4) is the one with enough context to know whether that is
+  fatal, and raises ``HttpAuthError``/``HttpUnexpectedPageError`` itself —
+  this module never guesses.
+- A *table/page* parser that cannot find the structure the page is
+  documented to always contain (e.g. no ``portID`` rows on dashboard.cgi, no
+  ``hiddenMem`` on 8021qMembe.cgi) raises ``HttpUnexpectedPageError`` naming
+  what was expected. These pages are never legitimately empty on a real
+  switch (port tables always list every physical port), so a missing
+  structure means the wrong page came back, not "empty switch" -> never
+  silently swallowed into an empty list/dict.
+"""
+from __future__ import annotations
+
+import re
+
+from ...errors import HttpUnexpectedPageError
+from ...models import PoEDetect, PoEStatus, PortStats, PortStatus, VlanMode
+
+_ROW_RE = re.compile(r'<tr\s+class="portID">(.*?)</tr>', re.DOTALL | re.IGNORECASE)
+_TD_RE = re.compile(r"<td[^>]*>(.*?)</td>", re.DOTALL | re.IGNORECASE)
+_TAG_RE = re.compile(r"<[^>]+>")
+
+_WIRE_TO_MODE = {"1": VlanMode.UNTAGGED, "2": VlanMode.TAGGED, "3": VlanMode.EXCLUDED}
+_DETECT_TEXT = {
+    "delivering": PoEDetect.DELIVERING,
+    "searching": PoEDetect.SEARCHING,
+    "disabled": PoEDetect.DISABLED,
+    "fault": PoEDetect.FAULT,
+}
+
+
+def _cells(row_html: str) -> list[str]:
+    return [_TAG_RE.sub("", c).strip() for c in _TD_RE.findall(row_html)]
+
+
+def _int(text: str) -> int | None:
+    m = re.search(r"-?\d+", text)
+    return int(m.group()) if m else None
+
+
+def parse_login_rand(html: str) -> str | None:
+    """Scrape the login nonce from ``<input id="rand" ... value="...">``."""
+    m = re.search(r'id=["\']rand["\'][^>]*value=["\']([^"\']*)["\']', html)
+    return m.group(1) if m else None
+
+
+def parse_csrf_hash(html: str) -> str | None:
+    """Scrape the CSRF token from ``<input name="hash" value="...">``."""
+    m = re.search(r'name=["\']hash["\'][^>]*value=["\']([^"\']*)["\']', html)
+    return m.group(1) if m else None
+
+
+def parse_port_status(html: str) -> list[PortStatus]:
+    """dashboard.cgi ``portID`` rows: [2]=port,[3]=link/speed,[4]=admin,[5]=name."""
+    rows = _ROW_RE.findall(html)
+    if not rows:
+        raise HttpUnexpectedPageError(
+            'dashboard.cgi: expected <tr class="portID"> rows, found none'
+        )
+    out: list[PortStatus] = []
+    for row in rows:
+        c = _cells(row)
+        if len(c) < 5:
+            raise HttpUnexpectedPageError(
+                f"dashboard.cgi: expected >=5 <td> columns per portID row, got {len(c)}"
+            )
+        port = _int(c[1])
+        if port is None:
+            raise HttpUnexpectedPageError(
+                f"dashboard.cgi: could not parse a port number from column {c[1]!r}"
+            )
+        link_text = c[2].lower()
+        link_up = "up" in link_text
+        speed = _int(c[2]) if link_up else None
+        out.append(
+            PortStatus(
+                port=port,
+                name=c[4] or None,
+                admin_enabled=c[3].lower().startswith("enable"),
+                link_up=link_up,
+                speed_mbps=speed,
+            )
+        )
+    return out
+
+
+def parse_port_stats(html: str) -> list[PortStats]:
+    """portStatistics.cgi ``portID`` rows: [1]=port,[2]=rx,[3]=tx,[4]=crc."""
+    rows = _ROW_RE.findall(html)
+    if not rows:
+        raise HttpUnexpectedPageError(
+            'portStatistics.cgi: expected <tr class="portID"> rows, found none'
+        )
+    out: list[PortStats] = []
+    for row in rows:
+        c = _cells(row)
+        if len(c) < 4:
+            raise HttpUnexpectedPageError(
+                f"portStatistics.cgi: expected >=4 <td> columns per portID "
+                f"row, got {len(c)}"
+            )
+        port = _int(c[0])
+        if port is None:
+            raise HttpUnexpectedPageError(
+                f"portStatistics.cgi: could not parse a port number from "
+                f"column {c[0]!r}"
+            )
+        out.append(
+            PortStats(
+                port=port,
+                rx_bytes=_int(c[1]),
+                tx_bytes=_int(c[2]),
+                rx_packets=None,
+                tx_packets=None,
+                rx_errors=_int(c[3]),
+                tx_errors=None,
+            )
+        )
+    return out
+
+
+def parse_poe_status(html: str) -> list[PoEStatus]:
+    """getPoePortStatus.cgi ``portID`` rows: [1]=port,[2]=state,[3]=power_mw."""
+    rows = _ROW_RE.findall(html)
+    if not rows:
+        raise HttpUnexpectedPageError(
+            'getPoePortStatus.cgi: expected <tr class="portID"> rows, found none'
+        )
+    out: list[PoEStatus] = []
+    for row in rows:
+        c = _cells(row)
+        if len(c) < 3:
+            raise HttpUnexpectedPageError(
+                f"getPoePortStatus.cgi: expected >=3 <td> columns per "
+                f"portID row, got {len(c)}"
+            )
+        port = _int(c[0])
+        if port is None:
+            raise HttpUnexpectedPageError(
+                f"getPoePortStatus.cgi: could not parse a port number "
+                f"from column {c[0]!r}"
+            )
+        detect = _DETECT_TEXT.get(c[1].lower(), PoEDetect.UNKNOWN)
+        out.append(
+            PoEStatus(
+                port=port,
+                admin_enabled=detect is not PoEDetect.DISABLED,
+                detect=detect,
+                power_mw=_int(c[2]),
+            )
+        )
+    return out
+
+
+def parse_pvids(html: str) -> list[tuple[int, int]]:
+    """portPVID.cgi rows: ``sel="text"`` cell = port, ``sel="input"`` cell = PVID."""
+    rows = _ROW_RE.findall(html)
+    if not rows:
+        raise HttpUnexpectedPageError(
+            'portPVID.cgi: expected <tr class="portID"> rows, found none'
+        )
+    out: list[tuple[int, int]] = []
+    for m in re.finditer(
+        r'<td[^>]*sel="text"[^>]*>(\d+).*?</td>\s*<td[^>]*sel="input"[^>]*>(\d+)</td>',
+        html,
+        re.DOTALL,
+    ):
+        out.append((int(m.group(1)), int(m.group(2))))
+    if not out:
+        raise HttpUnexpectedPageError(
+            'portPVID.cgi: expected <td sel="text"> and <td sel="input"> '
+            "cells in portID rows, found none matching"
+        )
+    return out
+
+
+def parse_vlan_ids(html: str) -> list[int]:
+    """8021qCf.cgi VLAN checkboxes: ``name="vlanckN" value="VID"``."""
+    matches = list(re.finditer(r'name="vlanck\d+"[^>]*value="(\d+)"', html))
+    if not matches:
+        raise HttpUnexpectedPageError(
+            '8021qCf.cgi: expected at least one name="vlanckN" checkbox, found none'
+        )
+    return sorted({int(m.group(1)) for m in matches})
+
+
+def parse_selected_vlan(html: str) -> int | None:
+    """8021qMembe.cgi selected VLAN in the dropdown."""
+    m = re.search(r'<option[^>]*selected[^>]*value="(\d+)"', html)
+    if m:
+        return int(m.group(1))
+    m = re.search(r'<option[^>]*value="(\d+)"[^>]*selected', html)
+    return int(m.group(1)) if m else None
+
+
+def parse_membership(html: str, port_count: int) -> dict[int, VlanMode]:
+    """8021qMembe.cgi ``hiddenMem`` string: per-port 1=Untagged/2=Tagged/3=Excluded."""
+    m = re.search(r'id="hiddenMem"[^>]*value="([^"]*)"', html) or re.search(
+        r'name="hiddenMem"[^>]*value="([^"]*)"', html
+    )
+    if not m:
+        raise HttpUnexpectedPageError(
+            "8021qMembe.cgi: expected a hiddenMem input with the per-port wire "
+            "codes, found none"
+        )
+    raw = m.group(1)
+    if len(raw) < port_count:
+        raise HttpUnexpectedPageError(
+            f"8021qMembe.cgi: hiddenMem value {raw!r} has fewer than "
+            f"port_count={port_count} codes"
+        )
+    result: dict[int, VlanMode] = {}
+    for i, ch in enumerate(raw[:port_count]):
+        mode = _WIRE_TO_MODE.get(ch)
+        if mode is None:
+            raise HttpUnexpectedPageError(
+                f"8021qMembe.cgi: unknown VLAN wire code {ch!r} at port {i + 1}"
+            )
+        result[i + 1] = mode
+    return result
+
+
+def parse_reboot_ok(html: str) -> bool:
+    """A reboot response that does not contain an error banner."""
+    return "error" not in html.lower()

netgear_switch/protocols/http/session.py

@@ -0,0 +1,29 @@
+"""Transport-agnostic web-UI session seam (Protocols only, no I/O).
+
+Both the sync (``httpx.Client``) and async (``httpx.AsyncClient``) transports
+implement these. Readers/writers depend only on these three methods, so the
+pure protocol layer is the single shared codebase across sync and async.
+"""
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class HttpSession(Protocol):
+    """Synchronous authenticated web-UI session for one switch."""
+
+    def login(self) -> None: ...
+
+    def get_page(self, path: str) -> str: ...
+
+    def post_form(self, path: str, data: dict[str, str]) -> str: ...
+
+
+class AsyncHttpSession(Protocol):
+    """Asynchronous authenticated web-UI session for one switch."""
+
+    async def login(self) -> None: ...
+
+    async def get_page(self, path: str) -> str: ...
+
+    async def post_form(self, path: str, data: dict[str, str]) -> str: ...

netgear_switch/protocols/nsdp/__init__.py

@@ -0,0 +1,7 @@
+"""Pure, zero-dependency NSDP wire protocol package.
+
+Lifted from the standalone ``gdoc2netcfg/src/nsdp`` package (protocol/types/
+parsers) and extended with a write path. No network here: sockets live in
+``transport/{sync,aio}/nsdp_udp.py``. NSDP needs no third-party dependency.
+"""
+from __future__ import annotations

netgear_switch/protocols/nsdp/auth.py

@@ -0,0 +1,33 @@
+"""NSDP authentication.
+
+v1 auth (older Plus firmware, incl. the GS110EMX/GS305EP this slice targets)
+sends the admin password in a ``PASSWORD`` (0x000A) TLV "encrypted" by a
+repeating XOR against the 19-byte key ``NtgrSmartSwitchRock`` (the only detail
+the source spec ``gdoc2netcfg/docs/nsdp-protocol.md`` gives — no worked example,
+no padding rule). XOR is its own inverse, so ``encode_password_v1`` both encodes
+outgoing and decodes an incoming PASSWORD TLV.
+
+UNVERIFIED / NOT IMPLEMENTED: v2 salt+hash auth (tags AUTH_V2_SALT 0x0017 /
+AUTH_V2_PASSWORD 0x001A, newer firmware). The source spec names ONLY the two tag
+numbers and gives no algorithm (no hash function, no salt ordering), so there is
+nothing to implement honestly without a hardware capture. A switch that rejects
+v1 auth returns result 0x0700 (bad password); the transport surfaces that as an
+NsdpError telling the caller v2 is required (see Task 4).
+"""
+from __future__ import annotations
+
+V1_KEY = b"NtgrSmartSwitchRock"
+
+AUTH_V2_UNSUPPORTED = (
+    "NSDP v2 salt/hash auth (tags 0x0017/0x001A) is unverified and not "
+    "implemented; this backend supports only v1 XOR auth"
+)
+
+
+def encode_password_v1(password: str) -> bytes:
+    """Repeating-XOR the ASCII password with ``NtgrSmartSwitchRock`` (its own
+    inverse). UNVERIFIED: no padding/truncation rule is documented; if a real
+    switch rejects this, a hardware capture is needed to confirm the exact
+    byte handling (see module docstring)."""
+    pw = password.encode("ascii")
+    return bytes(b ^ V1_KEY[i % len(V1_KEY)] for i, b in enumerate(pw))

netgear_switch/protocols/nsdp/client.py

@@ -0,0 +1,67 @@
+"""Shared NSDP transport seam: error, result check, and client Protocols.
+
+Pure and transport-agnostic (mirrors ``protocols/snmp/client.py``). ``NsdpError``
+lives here beside the protocol rather than in ``errors.py``, matching the
+``SnmpError`` precedent; both subclass the shared ``NetgearSwitchError`` base so
+callers can still catch the library-wide root.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+from ...errors import NetgearSwitchError
+from .auth import AUTH_V2_UNSUPPORTED
+from .write import RESULT_BAD_PASSWORD, RESULT_SUCCESS
+
+if TYPE_CHECKING:
+    from .protocol import NSDPPacket, Tag, TLVEntry
+
+
+class NsdpError(NetgearSwitchError):
+    """An NSDP transport operation failed (timeout, malformed, bad password)."""
+
+
+def read_interface_mac(interface: str) -> bytes:
+    """Read a network interface's 6-byte MAC from sysfs (Linux)."""
+    text = Path(f"/sys/class/net/{interface}/address").read_text().strip()
+    raw = bytes.fromhex(text.replace(":", ""))
+    if len(raw) != 6:
+        raise NsdpError(f"interface {interface!r} MAC is not 6 bytes: {text!r}")
+    return raw
+
+
+def check_result(packet: NSDPPacket) -> None:
+    """Raise ``NsdpError`` unless the response reports success (result 0x0000)."""
+    if packet.result == RESULT_SUCCESS:
+        return
+    if packet.result == RESULT_BAD_PASSWORD:
+        raise NsdpError(
+            "NSDP write rejected: bad password (result 0x0700). "
+            f"{AUTH_V2_UNSUPPORTED}"
+        )
+    raise NsdpError(f"NSDP request failed with result 0x{packet.result:04x}")
+
+
+class NsdpClient(Protocol):
+    """Synchronous NSDP read client for a single switch."""
+
+    def read(self, tags: list[Tag]) -> NSDPPacket: ...
+
+
+class NsdpWriteClient(NsdpClient, Protocol):
+    """Synchronous NSDP read+write client for a single switch."""
+
+    def write(self, tlvs: list[TLVEntry], *, password: str) -> NSDPPacket: ...
+
+
+class AsyncNsdpClient(Protocol):
+    """Asynchronous NSDP read client for a single switch."""
+
+    async def read(self, tags: list[Tag]) -> NSDPPacket: ...
+
+
+class AsyncNsdpWriteClient(AsyncNsdpClient, Protocol):
+    """Asynchronous NSDP read+write client for a single switch."""
+
+    async def write(self, tlvs: list[TLVEntry], *, password: str) -> NSDPPacket: ...