testprotocols 0.1.0__py3-none-any.whl

testprotocols/wifi_bss.py

@@ -0,0 +1,197 @@
+"""WiFi / WifiBss template.
+
+Defines the abstract contract for per-SSID / per-VAP configuration on a
+WiFi-capable device: lifecycle, security, MAC ACL authorization,
+broadcast suppression, VLAN binding, max-clients, DTIM, and captive-portal
+admin.
+
+A BSS is identified by a stable logical *name* the test supplies at
+creation time (matching the RadiusClient.add_server pattern). The SSID
+broadcast string can change later via set_ssid without affecting the
+identity of the BSS in the contract.
+
+802.1X / Enterprise security references RADIUS servers by *name* — the
+referenced server must be registered via the RadiusClient template
+composed on the same device. Drivers whose device does not compose
+RadiusClient cannot satisfy EAP modes — they raise on those
+*security_mode* values.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.wifi import WifiAcl, WifiBssConfig
+
+
+@runtime_checkable
+class WifiBss(Protocol):
+    """Abstract contract for per-SSID / per-VAP WiFi configuration."""
+
+    # --- Lifecycle ---
+
+    def create_bss(
+        self,
+        name: str,
+        band: str,
+        ssid: str,
+        security_mode: str,
+        *,
+        passphrase: str | None = None,
+        radius_server_name: str | None = None,
+        mfp: str = "optional",
+        vlan_id: int | None = None,
+        max_clients: int | None = None,
+        broadcast_enabled: bool = True,
+        dtim_period: int = 2,
+    ) -> None:
+        """Create a new BSS on *band*, identified by *name*.
+
+        *security_mode* is one of: ``"Open"``, ``"OWE"``, ``"WPA2-PSK"``,
+        ``"WPA2-EAP"``, ``"WPA3-SAE"``, ``"WPA3-EAP"``,
+        ``"WPA2-WPA3-PSK-Mixed"``, ``"WPA2-WPA3-EAP-Mixed"``.
+
+        *mfp* is one of ``"off"``, ``"optional"``, ``"required"``.
+
+        Required arguments per security_mode:
+        - PSK / SAE / mixed-PSK modes: *passphrase* required
+        - EAP / mixed-EAP modes: *radius_server_name* required, must
+          reference a server registered via RadiusClient on this device
+        - Open / OWE: neither required
+
+        Raises ValueError on a duplicate *name* or on missing
+        mode-required arguments.
+        """
+        ...
+
+    def delete_bss(self, name: str) -> None:
+        """Delete the BSS identified by *name*. Raises KeyError if absent."""
+        ...
+
+    def list_bss(self) -> list[WifiBssConfig]:
+        """Return all BSS configurations on the device (without secrets)."""
+        ...
+
+    def get_bss_config(self, name: str) -> WifiBssConfig:
+        """Return the full configuration of the BSS identified by *name* (without secret).
+
+        Raises KeyError if absent.
+        """
+        ...
+
+    # --- Admin state ---
+
+    def set_enabled(self, name: str, enabled: bool) -> None:
+        """Enable or disable the BSS without deleting it.
+
+        The radio stays up (DFS continues, neighbour scanning continues);
+        only the BSS stops broadcasting and accepting clients.
+        """
+        ...
+
+    # --- SSID broadcast ---
+
+    def set_ssid(self, name: str, ssid: str) -> None:
+        """Change the broadcast SSID string of the BSS identified by *name*.
+
+        Does not change the logical *name* (which remains the contract handle).
+        """
+        ...
+
+    def set_broadcast_enabled(self, name: str, enabled: bool) -> None:
+        """Suppress or restore SSID broadcast in beacons (hidden SSID)."""
+        ...
+
+    # --- Security ---
+
+    def set_security(
+        self,
+        name: str,
+        mode: str,
+        *,
+        passphrase: str | None = None,
+        radius_server_name: str | None = None,
+        mfp: str = "optional",
+    ) -> None:
+        """Reconfigure the security of an existing BSS.
+
+        Same value space and required-argument rules as ``create_bss``.
+        Reconfiguration disconnects currently associated clients on most
+        drivers; tests should expect re-association.
+        """
+        ...
+
+    # --- MAC ACL — per-BSS authorization scheme ---
+
+    def set_acl_mode(self, name: str, mode: str) -> None:
+        """Set the per-BSS MAC ACL mode.
+
+        *mode* is one of:
+        - ``"disabled"`` — no MAC filtering; the BSS's ACL list is ignored
+        - ``"allow"`` — allow-list (whitelist); only MACs in the ACL may associate
+        - ``"deny"`` — deny-list (blacklist); MACs in the ACL are blocked
+
+        Raises KeyError if *name* is not registered.
+        """
+        ...
+
+    def add_acl_entry(self, name: str, mac: str) -> None:
+        """Add *mac* to the BSS's ACL list. No-op if already present.
+
+        Effective filtering depends on the current ACL mode.
+        Raises KeyError if *name* is not registered.
+        """
+        ...
+
+    def remove_acl_entry(self, name: str, mac: str) -> None:
+        """Remove *mac* from the BSS's ACL list. No-op if absent.
+
+        Raises KeyError if *name* is not registered.
+        """
+        ...
+
+    def clear_acl(self, name: str) -> None:
+        """Remove all entries from the BSS's ACL list. Mode is unchanged.
+
+        Raises KeyError if *name* is not registered.
+        """
+        ...
+
+    def get_acl(self, name: str) -> WifiAcl:
+        """Return the BSS's MAC ACL state (mode + entries).
+
+        Raises KeyError if *name* is not registered.
+        """
+        ...
+
+    # --- VLAN binding ---
+
+    def set_vlan(self, name: str, vlan_id: int | None) -> None:
+        """Bind the BSS to *vlan_id*, or pass None to remove the binding (untagged)."""
+        ...
+
+    # --- Capacity / timing ---
+
+    def set_max_clients(self, name: str, max_clients: int | None) -> None:
+        """Cap concurrent associations at *max_clients*, or pass None to remove the cap."""
+        ...
+
+    def set_dtim_period(self, name: str, period: int) -> None:
+        """Set the DTIM period (number of beacons between DTIM transmissions). Typical: 1-5."""
+        ...
+
+    # --- Captive portal (minimal on-AP surface) ---
+
+    def set_captive_portal(
+        self,
+        name: str,
+        enabled: bool,
+        redirect_url: str | None = None,
+    ) -> None:
+        """Enable or disable the per-BSS captive portal.
+
+        When enabled, *redirect_url* is the splash page clients are
+        redirected to. Voucher / local-account / splash-HTML upload are
+        out of scope here — they belong to WifiController.
+        """
+        ...

testprotocols/wifi_client.py

@@ -0,0 +1,72 @@
+"""WiFi / WifiClient template.
+
+Defines the abstract contract for WiFi client operations including
+association, scanning, and monitor-mode management.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WifiClient(Protocol):
+    """Abstract contract for WiFi client operations."""
+
+    def reset_wifi_iface(self) -> None:
+        """Reset the WiFi interface to its default state."""
+        ...
+
+    def disable_wifi(self) -> None:
+        """Disable the WiFi radio."""
+        ...
+
+    def enable_wifi(self) -> None:
+        """Enable the WiFi radio."""
+        ...
+
+    def wifi_client_connect(
+        self,
+        ssid_name: str,
+        password: str | None = None,
+        security_mode: str | None = None,
+        bssid: str | None = None,
+    ) -> None:
+        """Connect to *ssid_name* using the supplied credentials and security mode."""
+        ...
+
+    def wifi_disconnect(self) -> None:
+        """Disconnect from the current WiFi network."""
+        ...
+
+    def is_wlan_connected(self) -> bool:
+        """Return True if the WLAN interface is currently connected."""
+        ...
+
+    def list_wifi_ssids(self) -> list[str]:
+        """Return a list of visible SSIDs from a scan."""
+        ...
+
+    def set_wlan_scan_channel(self, channel: str) -> None:
+        """Set the WiFi scan channel to *channel*."""
+        ...
+
+    def iwlist_supported_channels(self, wifi_band: str) -> list[str]:
+        """Return the list of channels supported by the adapter for *wifi_band*."""
+        ...
+
+    def change_wifi_region(self, country: str) -> None:
+        """Change the regulatory domain to *country* (ISO 3166-1 alpha-2)."""
+        ...
+
+    def enable_monitor_mode(self) -> None:
+        """Enable monitor mode on the WiFi interface."""
+        ...
+
+    def disable_monitor_mode(self) -> None:
+        """Disable monitor mode and return the interface to managed mode."""
+        ...
+
+    def is_monitor_mode_enabled(self) -> bool:
+        """Return True if the WiFi interface is in monitor mode."""
+        ...

testprotocols/wifi_mesh.py

@@ -0,0 +1,259 @@
+"""WiFi / WifiMesh template.
+
+Defines the abstract contract for WiFi mesh participation: role
+inspection, mesh enable/disable, topology read, backhaul-link
+control (band / channel), agent onboarding (configurator and enrollee
+sides), agent removal, and cross-mesh client steering.
+
+Composed onto any device that participates in or will participate in a
+wireless mesh. A pre-onboarding device (about to be added as an agent)
+composes WifiMesh with its role reading "uncommissioned"; after
+onboarding via the controller's add_agent, role becomes "agent".
+
+Vendor uniformity for mesh is low — enterprise stacks use proprietary
+multi-AP protocols; EasyMesh R1/R2/R3 lives in prpl, OneWiFi (RDK-B),
+OpenWrt prplMesh, and select carrier-grade SKUs. Each driver translates
+the uniform contract here to its underlying vendor RPCs (EasyMesh M1/M2,
+proprietary controller add-agent calls, vendor-specific steering APIs).
+Drivers without support for specific operations raise NotImplementedError.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.wifi import WifiMeshStatus, WifiMeshTopology
+
+
+@runtime_checkable
+class WifiMesh(Protocol):
+    """Abstract contract for WiFi mesh participation."""
+
+    # --- Admin state ---
+
+    def set_enabled(self, enabled: bool) -> None:
+        """Enable or disable this device's participation in the mesh.
+
+        When disabled, the device retains its role configuration but stops
+        forwarding mesh frames and stops responding to mesh control messages.
+        """
+        ...
+
+    # --- Status and topology ---
+
+    def get_mesh_status(self) -> WifiMeshStatus:
+        """Return this device's local mesh status.
+
+        Includes role, enabled state, parent, hop count, and backhaul link.
+        Lightweight read — does not query other agents.
+        """
+        ...
+
+    def get_topology(self) -> WifiMeshTopology:
+        """Return the full mesh topology as known to this device.
+
+        Heavier read — for a controller, returns the full list of known
+        agents with their parents and roles. For an agent, returns the
+        agent's local view (typically just its parent and any peers it
+        directly observes).
+        """
+        ...
+
+    # --- Backhaul control (agent-side) ---
+
+    def set_backhaul_band(self, band: str | None) -> None:
+        """Force the backhaul radio to *band* (e.g. ``"5GHz"``), or pass None to
+        release the constraint.
+
+        Releasing returns the device to whatever band-selection policy
+        the mesh controller / driver default uses. Drivers without
+        backhaul-band override (typical of controller-only nodes that
+        have no uplink) raise NotImplementedError.
+        """
+        ...
+
+    def set_backhaul_channel(self, channel: int | None) -> None:
+        """Force the backhaul radio to *channel*, or pass None to release the constraint.
+
+        Drivers without backhaul-channel override raise NotImplementedError.
+        Raises ValueError if *channel* is not supported on the current
+        backhaul band.
+        """
+        ...
+
+    # --- Agent management (typically controller-side) ---
+
+    def add_agent(
+        self,
+        agent_mac: str,
+        *,
+        dpp_uri: str | None = None,
+        psk: str | None = None,
+        wps_pin: str | None = None,
+        wps_pbc: bool = False,
+        timeout: float = 60.0,
+    ) -> None:
+        """Onboard a new agent identified by *agent_mac* into the mesh.
+
+        Exactly one onboarding credential must be passed:
+        - *dpp_uri* — the agent's Device Provisioning Protocol URI
+        - *psk* — pre-shared key the agent is preconfigured with
+        - *wps_pin* — WPS PIN displayed on or assigned to the agent
+        - *wps_pbc=True* — WPS Push-Button onboarding (controller starts PBC window)
+
+        Blocks until the agent has joined the mesh (M1/M2 exchange complete
+        and the agent appears in get_topology) or *timeout* seconds elapse.
+
+        Raises ValueError if zero or multiple credentials are passed.
+        Raises TimeoutError if onboarding does not complete within *timeout*.
+        Drivers that do not support an onboarding method raise
+        NotImplementedError when that credential is passed.
+        """
+        ...
+
+    def remove_agent(self, agent_mac: str) -> None:
+        """Remove the agent identified by *agent_mac* from the mesh.
+
+        The agent is told to leave (mesh-leave message in EasyMesh, vendor
+        equivalent otherwise), and is removed from the controller's
+        topology.
+
+        Raises KeyError if no agent with that MAC is currently in the mesh.
+        """
+        ...
+
+    # --- DPP enrollee (typically agent-side, before onboarding) ---
+
+    def get_dpp_uri(self) -> str:
+        """Return this device's DPP bootstrap URI for use by a configurator.
+
+        The URI encodes the device's DPP public key and supported channels
+        (e.g. ``DPP:C:81/1;K:MDkw...;;``). Tests fetch it from the new agent,
+        then pass it to the controller's ``add_agent(dpp_uri=...)``.
+
+        Drivers without DPP enrollee support raise NotImplementedError.
+        """
+        ...
+
+    def start_dpp_enrollee(self, timeout: float = 120.0) -> None:
+        """Put the device into DPP-enrollee listening mode.
+
+        Returns immediately. The device listens for DPP authentication
+        from a configurator for *timeout* seconds (standard DPP window
+        is 120s); after that, the listener closes whether or not
+        onboarding completed.
+
+        Drivers without DPP enrollee support raise NotImplementedError.
+        Drivers where the enrollee listener is always-on (no explicit
+        trigger needed) implement this as a no-op.
+        """
+        ...
+
+    # --- WPS / PSK enrollee (agent-side) ---
+
+    def trigger_wps_enrollee(
+        self,
+        *,
+        pin: str | None = None,
+        window_seconds: float = 120.0,
+    ) -> None:
+        """Put the device into WPS enrollee mode for mesh-agent onboarding.
+
+        Returns immediately. The device listens for WPS handshake from a
+        controller for *window_seconds* (standard WPS window is 120s).
+
+        When *pin* is None, the device opens a WPS-PBC window — a
+        controller in PBC mode within the same window completes the join.
+        When *pin* is provided, the device opens a WPS-PIN window expecting
+        a controller to present that PIN.
+
+        *pin* is 4 or 8 digits per WPS spec, as ``str`` (preserves leading zeros).
+        Drivers raise ValueError on malformed PINs.
+
+        Drivers without WPS enrollee support raise NotImplementedError.
+        """
+        ...
+
+    def set_mesh_psk_for_enrollment(self, psk: str | None) -> None:
+        """Configure (or clear) the pre-shared key this device presents when joining a mesh.
+
+        Used for PSK-based mesh enrollment, where an agent is preconfigured
+        with the mesh PSK and the controller accepts agents presenting that
+        PSK. Pass None to clear a previously-set PSK.
+
+        Drivers without PSK-based mesh enrollment raise NotImplementedError.
+        Read-side intentionally omitted: PSK is write-only across the contract.
+        """
+        ...
+
+    # --- Cross-mesh client steering (typically controller-side) ---
+
+    def steer_client(
+        self,
+        client_mac: str,
+        target_agent_mac: str,
+        *,
+        disassoc_imminent: bool = False,
+    ) -> None:
+        """Steer the associated client *client_mac* toward agent *target_agent_mac*.
+
+        The controller looks up which agent the client is currently on,
+        sends an 802.11v BSS Transition Management Request from that agent
+        suggesting the target, and (when *disassoc_imminent* is True) sets
+        the disassoc-imminent bit so the client must roam or be disassociated.
+
+        Fire-and-forget: returns once the BTM Request has been sent. Tests
+        verify the outcome by polling ``WifiStations.get_station(client_mac).bss_name``
+        on the target agent (or reading the controller's topology / association
+        events).
+
+        Raises KeyError if the client is not currently associated to any agent
+        in the mesh, or if *target_agent_mac* is not a known agent.
+        """
+        ...
+
+
+@runtime_checkable
+class WifiMeshWhiteBox(WifiMesh, Protocol):
+    """White-box extension of WifiMesh for raw 1905.1 / EasyMesh introspection.
+
+    Drivers running an open-source EasyMesh stack (prplMesh, hostapd-based
+    controllers, etc.) and able to shell into the controller / agent satisfy
+    this extension. Closed-source vendor controllers typically satisfy only
+    the base ``WifiMesh`` Protocol; tests requiring raw 1905 / EasyMesh state
+    verification should pin against ``WifiMeshWhiteBox`` and accept the
+    collection-skip on drivers that don't satisfy it (per the ``@white_box``
+    scenario tag rule).
+    """
+
+    def get_raw_ieee1905_state(self) -> str:
+        """Return the IEEE 1905.1 AL-entity state of this device verbatim.
+
+        Format is driver-dependent — typically the output of the
+        controller / agent's CLI dump command (e.g. ``prplmeshcli al-entity-info``,
+        vendor equivalents). Tests parse for AL MAC, neighbour AL MACs,
+        topology-discovery counters, and link metrics.
+        """
+        ...
+
+    def get_raw_easymesh_tlvs(self, message_type: str | None = None) -> str:
+        """Return raw EasyMesh TLVs observed on the 1905 control plane.
+
+        With *message_type* None, returns all recently-observed TLVs (driver
+        chooses the window — typically the controller's transient cache).
+        With *message_type* set (e.g. ``"AP-Capability-Report"``,
+        ``"Topology-Notification"``), returns only TLVs from messages of
+        that type. Format is driver-dependent (often hex-encoded TLV with
+        a parsed annotation per line).
+        """
+        ...
+
+    def get_controller_logs(self, since_seconds: float = 60.0) -> str:
+        """Return recent controller-side log output covering EasyMesh activity.
+
+        *since_seconds* bounds the lookback window. Format is the controller's
+        native log format (typically a timestamped text stream). Tests grep
+        for specific event signatures: agent onboarding messages, channel-
+        selection decisions, steering events, link-metric updates.
+        """
+        ...

testprotocols/wifi_onboarding.py

@@ -0,0 +1,105 @@
+"""WiFi / WifiOnboarding template.
+
+Defines the abstract contract for WPS and DPP (EasyConnect) client
+onboarding on a WiFi-capable device: per-BSS WPS enable, PBC / PIN
+trigger, device-PIN read, and DPP-based client enrollment.
+
+Vendor uniformity is low-medium: residential / RDK-B / prpl / OpenWrt
+stacks expose all of these as first-class operations; enterprise stacks
+commonly disable WPS entirely and offer DPP only sporadically. Drivers
+without support for a specific onboarding method raise
+NotImplementedError.
+
+Mesh agent onboarding (M1/M2 / DPP between APs) lives on WifiMesh;
+this template is exclusively for STA-side (client) onboarding.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WifiOnboarding(Protocol):
+    """Abstract contract for WPS and DPP client onboarding."""
+
+    # --- WPS — per-BSS admin state ---
+
+    def set_wps_enabled(self, bss_name: str, enabled: bool) -> None:
+        """Enable or disable WPS support on *bss_name*.
+
+        Raises KeyError if *bss_name* is not registered.
+        """
+        ...
+
+    def get_wps_enabled(self, bss_name: str) -> bool:
+        """Return True if WPS is currently enabled on *bss_name*.
+
+        Raises KeyError if *bss_name* is not registered.
+        """
+        ...
+
+    # --- WPS — session triggers ---
+
+    def trigger_wps_pbc(self, bss_name: str, window_seconds: float = 120.0) -> None:
+        """Open a WPS Push-Button Configuration window on *bss_name*.
+
+        Returns immediately after the window opens. The AP accepts WPS-PBC
+        joins for *window_seconds* (standard WPS window is 120s); after
+        that, the window closes whether or not a client joined. Tests
+        verify joins by polling ``WifiStations.list_associated_stations``.
+
+        Raises KeyError if *bss_name* is not registered.
+        Raises RuntimeError if WPS is currently disabled on *bss_name*.
+        """
+        ...
+
+    def trigger_wps_pin(self, bss_name: str, pin: str, window_seconds: float = 120.0) -> None:
+        """Open a WPS PIN-mode window on *bss_name* expecting *pin*.
+
+        Returns immediately. The AP accepts a WPS-PIN join from any client
+        presenting *pin* for *window_seconds*. *pin* is 4 or 8 digits per
+        WPS spec; drivers raise ValueError on malformed PINs.
+
+        Raises KeyError if *bss_name* is not registered.
+        Raises RuntimeError if WPS is currently disabled on *bss_name*.
+        """
+        ...
+
+    def get_wps_device_pin(self, bss_name: str) -> str:
+        """Return the AP's own WPS device PIN for *bss_name*.
+
+        The device PIN is the 8-digit PIN burned into the AP that a client
+        can use to enroll without an explicitly-set PIN session. Useful in
+        tests where the client drives WPS-PIN onboarding and needs to know
+        the AP's PIN.
+
+        Raises KeyError if *bss_name* is not registered.
+        """
+        ...
+
+    # --- DPP / EasyConnect — AP as configurator ---
+
+    def enroll_client_via_dpp(
+        self,
+        client_dpp_uri: str,
+        bss_name: str,
+        timeout: float = 60.0,
+    ) -> None:
+        """Provision a new client onto *bss_name* via DPP, acting as configurator.
+
+        *client_dpp_uri* is the client's DPP bootstrap URI (typically scanned
+        from the client's QR code or obtained via NFC / out-of-band channel).
+        The AP performs the DPP authentication and configuration exchange,
+        delivering the SSID + credentials for *bss_name* to the client.
+
+        Blocks until the DPP exchange completes (driver has confirmed
+        configuration delivery to the client) or *timeout* seconds elapse.
+        The client's subsequent association is asynchronous — tests verify
+        via ``WifiStations.list_associated_stations``.
+
+        Raises KeyError if *bss_name* is not registered.
+        Raises ValueError if *client_dpp_uri* is malformed.
+        Raises TimeoutError if the DPP exchange does not complete within *timeout*.
+        """
+        ...