routerless 0.1.0__tar.gz

routerless-0.1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: ["dependencies"]
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: ["dependencies"]

routerless-0.1.0/.github/prompts/add-adapter.prompt.md

@@ -0,0 +1,152 @@
+---
+mode: agent
+description: "Add a new router adapter (new router brand/model) with full CLI support"
+---
+
+# Add a New Router Adapter
+
+Use this prompt to scaffold a complete new adapter for a router brand or model not yet supported.
+
+> **Before writing any code**, read the current versions of:
+> - `routerless/adapters/base.py` — source of truth for abstract methods and optional overrides
+> - `routerless/cli.py` — source of truth for `_ADAPTER_MAP` and which CLI commands exist
+>
+> Use their actual content rather than the examples below, which may lag behind.
+
+## What you need to provide
+
+- **Router name / brand** (e.g. "FritzBox", "Asus Merlin", "Synology Router")
+- **Communication protocol** (REST API, SSH + CLI, SNMP, Telnet…)
+- **Authentication method** (cookie, token, basic auth, SSH key…)
+- **Base URL or access method** (e.g. `http://192.168.1.1/api`, SSH to port 22)
+
+---
+
+## Checklist — 5 files to create or modify
+
+### 1. `routerless/models/config.py` — Add TargetType enum value
+
+```python
+class TargetType(str, Enum):
+    BBOX_ULTIM = "bbox_ultim"
+    OPENWRT    = "openwrt"
+    QNAP_QHORA = "qnap_qhora"
+    MY_ROUTER  = "my_router"   # ← add this
+```
+
+Also ensure `TargetConfig` has any new required fields (e.g. `api_key: str | None = None`).
+
+### 2. `routerless/adapters/my_router.py` — New adapter class
+
+```python
+"""MyRouter adapter."""
+from __future__ import annotations
+
+from routerless.adapters.base import BaseAdapter
+from routerless.models.config import (
+    DHCPConfig, FirewallConfig, NATConfig, NetworkConfig, TargetType,
+)
+from routerless.models.status import AdapterStatus, ConnectedDevice, WifiRadio
+
+
+class MyRouterAdapter(BaseAdapter):
+    TARGET_TYPE = TargetType.MY_ROUTER
+
+    # ── Abstract (mandatory) — inspect base.py for current list ─────────
+
+    def apply_dhcp(self, config: DHCPConfig) -> None: ...
+    def apply_nat(self, config: NATConfig) -> None: ...
+    def apply_firewall(self, config: FirewallConfig) -> None: ...
+    def dump(self) -> NetworkConfig: ...
+
+    # ── Optional overrides (default: raise NotImplementedError) ─────────
+    # Implement only if the router supports the feature.
+    # Inspect base.py for the current list and exact signatures.
+
+    def get_status(self) -> AdapterStatus: ...
+    def get_devices(self, only_active: bool = True) -> list[ConnectedDevice]: ...
+    def get_wifi(self) -> list[WifiRadio]: ...
+    def wifi_enable(self, enable: bool) -> None: ...
+```
+
+**Patterns to follow:**
+- **REST API** → copy `bbox_ultim.py`: httpx client, `_make_client()`, `_login()`, `_logout()`, `with _make_client() as client`
+- **SSH + CLI** → copy `openwrt.py`: paramiko, `@contextmanager _ssh()`, `_run(client, cmd)` raising on non-zero exit
+- Use `_extract_list(data, *keys)` pattern for nested API responses
+- Declarative sync in `apply_*`: read current state → delete stale → create new → update changed
+
+### 3. `routerless/cli.py` — Register in adapter map
+
+```python
+from routerless.adapters.my_router import MyRouterAdapter
+
+_ADAPTER_MAP: dict[TargetType, type[BaseAdapter]] = {
+    TargetType.BBOX_ULTIM:  BboxUltimAdapter,
+    TargetType.OPENWRT:     OpenWrtAdapter,
+    TargetType.QNAP_QHORA:  QnapQhoraAdapter,
+    TargetType.MY_ROUTER:   MyRouterAdapter,  # ← add this
+}
+```
+
+No other CLI changes are needed. All commands work generically through `BaseAdapter`:
+- `apply`, `dump`, `diff` — available once the 4 abstract methods are implemented
+- `plan` — compares local config against `dump()` output; free for any adapter
+- `status`, `devices`, `wifi` — available if the optional methods are overridden
+
+Verify the full command list in `cli.py` (`@cli.command(...)`) in case new commands were added since this prompt was written.
+
+### 4. `config/configuration.yaml` — Add a target example
+
+```yaml
+targets:
+  myrouter:
+    type: my_router
+    host: !secret myrouter_host
+    password: !secret myrouter_password
+```
+
+Add the corresponding secrets to `config/secrets.yaml`.
+
+### 5. `tests/test_my_router.py` — Tests (all I/O mocked)
+
+```python
+"""Tests for MyRouterAdapter — all network calls mocked."""
+from __future__ import annotations
+from unittest.mock import MagicMock, patch
+import pytest
+from routerless.adapters.my_router import MyRouterAdapter
+from routerless.models.config import DHCPConfig, NATConfig, StaticLease, TargetConfig, TargetType
+
+TARGET = TargetConfig(type=TargetType.MY_ROUTER, host="192.168.1.1", password="secret")
+
+def _adapter() -> MyRouterAdapter:
+    return MyRouterAdapter(TARGET)
+
+# For REST adapters — mock httpx:
+# p_make, p_login, p_logout = _mock_http(adapter, mock_client)
+# with p_make, p_login, p_logout:
+#     adapter.apply_dhcp(config)
+
+# For SSH adapters — mock paramiko:
+# with patch.object(adapter, "_ssh", return_value=_ssh_ctx(mock_client)):
+#     adapter.apply_dhcp(config)
+```
+
+---
+
+## AGENTS.md — Update adapter notes
+
+Add a section to `AGENTS.md` under the appropriate heading describing:
+- Auth method and base URL
+- Confirmed endpoints
+- Any quirks (rate limits, SSL, redirect behaviour)
+
+---
+
+## Validation
+
+```bash
+pytest                                          # must stay green
+routerless validate config/configuration.yaml  # config parses
+routerless status --target myrouter config/configuration.yaml  # live test
+```

routerless-0.1.0/.github/prompts/add-feature.prompt.md

@@ -0,0 +1,148 @@
+---
+mode: agent
+description: "Add a new CLI command, option, or feature and implement it on all configured adapters"
+---
+
+# Add a New Feature / CLI Command
+
+Use this prompt to add a new capability to routerless — a new command, a new option on an existing command, or a new section type — and wire it up across all adapters.
+
+## What you need to provide
+
+- **Feature description**: what the command does (e.g. "reboot router", "show bandwidth stats", "backup config")
+- **CLI shape**: command name, options, arguments (e.g. `routerless reboot --target bbox`)
+- **Scope**: which adapters should implement it (all / bbox only / openwrt only)
+
+---
+
+## Architecture reminder
+
+```
+CLI command (cli.py)
+  └── adapter.new_method()          ← defined in BaseAdapter (raises NotImplementedError)
+        ├── BboxUltimAdapter        ← implements via HTTPS REST
+        ├── OpenWrtAdapter          ← implements via SSH + UCI / shell commands
+        └── QnapQhoraAdapter        ← delegates to self._openwrt.new_method()
+```
+
+If the feature returns structured data, put its dataclass in `routerless/models/status.py`.
+
+---
+
+## Step-by-step
+
+### 1. Define the data model (if needed)
+
+In `routerless/models/status.py`, add a dataclass for the return value:
+
+```python
+@dataclass
+class MyFeatureResult:
+    field_a: str
+    field_b: int
+    optional_c: str = ""
+```
+
+### 2. Add the method to `BaseAdapter`
+
+In `routerless/adapters/base.py`, add a concrete method with a clear `NotImplementedError`:
+
+```python
+def my_feature(self, param: str) -> MyFeatureResult:
+    raise NotImplementedError(
+        f"{type(self).__name__} does not implement my_feature()."
+    )
+```
+
+Import `MyFeatureResult` at the top of `base.py` alongside `AdapterStatus` etc.
+
+### 3. Implement in each adapter
+
+**BboxUltimAdapter** (`bbox_ultim.py`) — REST pattern:
+```python
+def my_feature(self, param: str) -> MyFeatureResult:
+    with self._make_client() as client:
+        self._login(client)
+        try:
+            data = self._get(client, "/some/endpoint")
+        finally:
+            self._logout(client)
+    # parse data → return MyFeatureResult(...)
+```
+
+**OpenWrtAdapter** (`openwrt.py`) — SSH pattern:
+```python
+def my_feature(self, param: str) -> MyFeatureResult:
+    with self._ssh() as client:
+        out = self._run(client, "some-command")
+    # parse out → return MyFeatureResult(...)
+```
+
+**QnapQhoraAdapter** (`qnap_qhora.py`) — delegate:
+```python
+def my_feature(self, param: str) -> MyFeatureResult:
+    self._assert_uci_available()
+    return self._openwrt.my_feature(param)
+```
+
+### 4. Add the CLI command in `cli.py`
+
+```python
+@cli.command("my-feature")
+@click.argument("config", default="configuration.yaml", type=click.Path(exists=True))
+@click.option("--target", "-t", required=True, help="Target name")
+@click.option("--param", default="", help="Description of param")
+def cmd_my_feature(config: str, target: str, param: str) -> None:
+    """One-line description shown in --help."""
+    cfg = _load(config)
+    adapter = _get_adapter(cfg, target)
+    try:
+        result = adapter.my_feature(param)
+    except NotImplementedError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f"Result: {result.field_a}  ({result.field_b})")
+```
+
+If it belongs in a group (e.g. `wifi on/off`), use `@cli.group` + `@grp.command`.
+
+### 5. Write tests
+
+**For Bbox** (`tests/test_bbox.py`) — mock HTTP:
+```python
+class TestMyFeature:
+    def test_returns_result(self) -> None:
+        adapter = _adapter()
+        mock_client = MagicMock()
+        mock_client.get.return_value = _bbox_resp([{"section": {"key": "value"}}])
+        p_make, p_login, p_logout = _mock_http(adapter, mock_client)
+        with p_make, p_login, p_logout:
+            result = adapter.my_feature("param")
+        assert result.field_a == "value"
+```
+
+**For OpenWrt** (`tests/test_openwrt.py`) — mock SSH:
+```python
+class TestMyFeature:
+    def test_returns_result(self) -> None:
+        adapter = _make_adapter()
+        mock_client = _mock_ssh_client({"some-command": b"output"})
+        with patch.object(adapter, "_ssh", return_value=_ssh_ctx(mock_client)):
+            result = adapter.my_feature("param")
+        assert result.field_b == 42
+```
+
+### 6. Validate
+
+```bash
+pytest                    # all tests green
+routerless my-feature --target bbox config/configuration.yaml   # live smoke test
+routerless my-feature --target openwrt config/configuration.yaml
+```
+
+---
+
+## Notes
+
+- Features that only one adapter supports: implement in that adapter, let `BaseAdapter.my_feature()` raise `NotImplementedError` — the CLI already handles it gracefully.
+- New **section types** (beyond dhcp/nat/firewall): also add the Pydantic model to `routerless/models/config.py`, add the field to `NetworkConfig`, and add `apply_<section>` to `BaseAdapter` as an abstract method.
+- Keep `AGENTS.md` updated with any new confirmed endpoints or adapter-specific behaviour.

routerless-0.1.0/.github/prompts/discover-bbox-interface.prompt.md

@@ -0,0 +1,128 @@
+---
+mode: agent
+description: "Capture Bbox XHR endpoints via mitmproxy to implement unknown API features (firewall, etc.)"
+---
+
+# Discover Bbox API Endpoints via mitmproxy
+
+This prompt guides you through setting up a local HTTPS proxy to intercept Bbox web-interface XHR traffic and identify undocumented REST endpoints.
+
+## Prerequisites
+
+Install mitmproxy in the project virtualenv:
+
+```bash
+pip install mitmproxy
+```
+
+## Step 1 — Start the intercepting proxy
+
+Run this script to start mitmproxy and log all Bbox API calls:
+
+```python
+# scripts/bbox_intercept.py
+"""mitmproxy addon: log all Bbox API requests to bbox_captured.jsonl"""
+import json
+from pathlib import Path
+from mitmproxy import http
+
+LOG_FILE = Path("bbox_captured.jsonl")
+BBOX_HOST = "mabbox.bytel.fr"
+
+
+class BboxCapture:
+    def request(self, flow: http.HTTPFlow) -> None:
+        if BBOX_HOST not in flow.request.pretty_host:
+            return
+        if "/api/v1/" not in flow.request.path:
+            return
+        entry = {
+            "method": flow.request.method,
+            "path": flow.request.path,
+            "query": dict(flow.request.query),
+            "content_type": flow.request.headers.get("content-type", ""),
+            "body": flow.request.text,
+        }
+        with LOG_FILE.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+        print(f"[bbox] {entry['method']} {entry['path']}  body={entry['body'][:120]}")
+
+    def response(self, flow: http.HTTPFlow) -> None:
+        if BBOX_HOST not in flow.request.pretty_host:
+            return
+        if "/api/v1/" not in flow.request.path:
+            return
+        entry = {
+            "path": flow.request.path,
+            "status": flow.response.status_code,
+            "response_body": flow.response.text[:500],
+        }
+        with LOG_FILE.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+
+
+addons = [BboxCapture()]
+```
+
+Launch it:
+
+```bash
+mitmdump -s scripts/bbox_intercept.py --listen-port 8080 --ssl-insecure
+```
+
+## Step 2 — Route browser traffic through the proxy
+
+**Firefox / Chrome:** Set HTTP proxy to `127.0.0.1:8080`, then visit `http://mitm.it` and install the mitmproxy CA certificate.
+
+**Or use curl for targeted probing:**
+
+```bash
+# All requests via the proxy, trusting mitmproxy CA
+export https_proxy=http://127.0.0.1:8080
+curl -k https://mabbox.bytel.fr/api/v1/firewall/rules
+```
+
+## Step 3 — Trigger the feature in the Bbox UI
+
+1. Open `http://mabbox.bytel.fr` in the proxied browser
+2. Log in, navigate to the relevant section (e.g. Firewall → Rules)
+3. Add, modify, or delete a rule to trigger POST/PUT/DELETE requests
+4. Watch the mitmproxy terminal output and `bbox_captured.jsonl`
+
+## Step 4 — Analyse captured requests
+
+```python
+# scripts/analyse_capture.py
+import json
+from pathlib import Path
+
+for line in Path("bbox_captured.jsonl").read_text().splitlines():
+    e = json.loads(line)
+    if "method" in e and e["method"] in ("POST", "PUT", "DELETE", "PATCH"):
+        print(f"{e['method']:6} {e['path']}")
+        if e["body"]:
+            print(f"       body: {e['body'][:200]}")
+```
+
+## Step 5 — Implement the discovered endpoint
+
+Once you have confirmed the endpoint, implement it in `routerless/adapters/bbox_ultim.py`:
+
+1. Add a private `_list_<feature>()`, `_create_<feature>()`, `_delete_<feature>()` method
+2. Implement `apply_<feature>(config)` following the same declarative-sync pattern as `apply_dhcp()`
+3. Remove the `NotImplementedError` from the existing stub
+4. Add the endpoint details to the `AGENTS.md` confirmed endpoints list
+5. Add tests in `tests/test_bbox.py` using `_mock_http` + `_bbox_resp`
+
+## Current stubs needing discovery
+
+| Method | Status | Notes |
+|--------|--------|-------|
+| `apply_firewall()` | `NotImplementedError` | Guessed: `GET/POST/DELETE /firewall/rules` |
+
+## Safety
+
+- **Never use this proxy on a shared/production network** — it is a MITM proxy
+- The script only logs requests to `mabbox.bytel.fr` to minimise exposure
+- Captured files may contain session cookies — delete `bbox_captured.jsonl` after analysis
+- The Bbox rate-limits login: 3 failures → 300–1200 s lockout; do not probe `/login` repeatedly

routerless-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+      - name: Audit dependencies
+        # Ignore CVEs in the runner's bootstrap pip (not part of our shipped
+        # dependencies). Skip editable installs so the unpublished routerless
+        # package isn't audited.
+        run: pip-audit --skip-editable --ignore-vuln CVE-2026-3219 --ignore-vuln CVE-2026-6357

routerless-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Verify tag matches package version
+        run: |
+          TAG=${GITHUB_REF#refs/tags/v}
+          PKG=$(python -c "exec(open('routerless/version.py').read()); print(__version__)")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Tag v$TAG does not match routerless/version.py version $PKG"
+            exit 1
+          fi
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          files: dist/*

routerless-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+secrets.yaml
+.env
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.venv/
+.my-network
+_patch_tests.py

routerless-0.1.0/AGENTS.md

@@ -0,0 +1,120 @@
+# Routerless — Agent Instructions
+
+Router-agnostic network configuration manager. Declarative YAML config → applied to Bbox Ultim, OpenWrt, and QNAP Qhora routers via adapter plugins.
+
+## Quick Start
+
+```bash
+# Setup (Python 3.13+ required)
+pip install -e ".[dev]"
+
+# Run all tests (must stay green before and after any change)
+pytest
+
+# Run CLI
+routerless validate config/configuration.yaml
+routerless apply --target bbox --section dhcp config/configuration.yaml
+routerless status --target bbox config/configuration.yaml
+```
+
+## Project Layout
+
+```
+routerless/
+  cli.py             # Click CLI: validate, apply, dump, diff, status, devices, wifi
+  yaml_loader.py     # Custom YAML loader: !include, !secret, !include_dir_*
+  models/config.py   # Pydantic v2 models: NetworkConfig, DHCPConfig, NATConfig, FirewallConfig
+  adapters/
+    base.py          # BaseAdapter ABC — defines the contract
+    bbox_ultim.py    # Bbox Ultim via HTTPS REST (cookie auth + btoken CSRF)
+    openwrt.py       # OpenWrt via SSH + UCI commands
+    qnap_qhora.py    # QNAP Qhora 301W — delegates to OpenWrtAdapter
+config/
+  configuration.yaml # Main config (targets + !include sections)
+  secrets.yaml       # NOT committed — copy from secrets.yaml.example
+tests/               # pytest, all HTTP mocked via unittest.mock.patch
+```
+
+## Architecture
+
+```
+CLI → load_config (yaml_loader) → parse_config (Pydantic) → NetworkConfig
+    → _get_adapter(cfg, target_name) → BaseAdapter subclass
+    → adapter.apply_dhcp / apply_nat / apply_firewall / dump()
+```
+
+Adapter registry is in `cli.py → _ADAPTER_MAP`. Adding a new adapter requires:
+1. New `TargetType` enum value in `models/config.py`
+2. New class in `adapters/` inheriting `BaseAdapter` (implement 4 abstract methods)
+3. Register in `_ADAPTER_MAP` in `cli.py`
+4. Tests mocking device I/O
+
+## Config System (YAML Custom Tags)
+
+| Tag | Behaviour |
+|-----|-----------|
+| `!include <file>` | Inline another YAML file (relative to current file) |
+| `!include_dir_merge_list <dir>` | Merge all `*.yaml` in dir as a list — each file must be a list |
+| `!include_dir_named <dir>` | Dict keyed by filename stem |
+| `!secret <key>` | Resolve from `secrets.yaml`, searching upward, stopping at config root |
+
+`!secret` always resolves relative to the config root directory (the directory of `configuration.yaml`), even when used inside an included sub-file.
+
+## Bbox Ultim Adapter — Critical Notes
+
+- **Auth:** Cookie-based. `POST /login` with `password` + `remember=1` and `Referer`/`Origin` headers.
+  After login, `GET /device/token` returns a CSRF **btoken** stored as `self._btoken`.
+  Every mutating request appends `?btoken=<token>` to the URL.
+- **Base URL:** `https://mabbox.bytel.fr/api/v1` — the router redirects its local HTTP to this cloud relay.
+- **Endpoints confirmed (reverse-engineered):**
+  - `GET/POST/DELETE /dhcp/clients` — static DHCP reservations
+  - `PUT /dhcp/clients/<id>` — update existing reservation in-place (avoids IP conflict vs delete+create)
+  - `PUT /dhcp` — update dynamic pool range; fields: `dhcp.minaddress`, `dhcp.maxaddress`, `dhcp.leasetime`
+  - `GET/POST/DELETE /nat/rules` — port-forward rules
+  - `GET /firewall/rules` — firewall rules (**GET confirmed**; POST/DELETE not yet captured)
+  - `GET /wan/ip`, `/lan/ip`, `/device`, `/wireless`, `/voip`, `/hosts` — read-only status
+  - `PUT /wireless` with `radio.enable=1|0` — WiFi on/off
+- **Response shape:** `[{"<section>": {"<subsection>": {"list": [...]}}}]` — use `_extract_list(data, *keys)`.
+- **Rate limit:** 3 failed logins → 300 s (or 1200 s) lockout. Don't iterate passwords.
+- **Firewall:** `GET /firewall/rules` is confirmed working (returns live rules with `description`, `direction`, `src`, `dest`, `action` fields). `POST`/`DELETE` endpoints not yet captured — use mitmproxy to discover (see `.github/prompts/discover-bbox-interface.prompt.md`). `apply_firewall()` raises `NotImplementedError` until then.
+- **Protocol mapping:** `Protocol.BOTH` → `"all"` in NAT form body (not `"tcpudp"` — confirmed from GET response).
+- **DHCP hostname vs name:**
+  - `StaticLease.name` — friendly label (spaces allowed). Sent as `device` in POST/PUT (write-only, **not returned by GET**).
+  - `StaticLease.hostname` — DNS-safe identifier (no spaces). Sent as `hostname` in POST/PUT and **returned by GET**.
+  - `apply_dhcp` compares `lease.hostname or lease.name` against `existing["hostname"]` to decide create/update/skip.
+  - `_plan_dhcp` compares `lease.hostname or lease.name` against `d.hostname or d.name`; reports `hostname: 'old' → 'new'`.
+  - A `hostname` with spaces causes Bbox to return 400 "Invalid parameter" — always use `lease.hostname or lease.name`.
+
+## OpenWrt / QNAP Qhora Adapter
+
+- Communicates over **SSH + UCI commands** via `paramiko`.
+- Host key policy: `RejectPolicy` (rejects unknown hosts).
+- Idempotent: reads existing state before writing; adds/updates only changed entries.
+- Qhora default SSH port: **22200**. SSH access requires WPS button hold (12 s).
+
+## Testing Conventions
+
+All tests in `tests/`. HTTP is mocked — never make real network calls in tests.
+
+```python
+# Helpers defined in tests/test_bbox.py
+_adapter()                          # Creates BboxUltimAdapter with test target
+_mock_http(adapter, mock_client)    # Returns (p_make, p_login, p_logout) patches
+_bbox_resp(data, status=200)        # MagicMock response with .json() + .raise_for_status()
+
+# Pattern
+mock_client = MagicMock()
+mock_client.get.return_value = _bbox_resp([{"dhcp": {"clients": {"list": [], "number": 0}}}])
+p_make, p_login, p_logout = _mock_http(adapter, mock_client)
+with p_make, p_login, p_logout:
+    adapter.apply_dhcp(config)
+mock_client.post.assert_called_once()
+```
+
+## Key Conventions
+
+- **Python 3.13+** — use modern syntax: `str | None`, `list[...]`, `dict[...]`. No `Optional`, `List`, `Dict`.
+- **Pydantic v2** — `model_dump(exclude_none=True, exclude_unset=True)` for serialization.
+- **MAC addresses** normalized to uppercase colon-separated in Pydantic validators.
+- **Secrets** never logged or printed. `secrets.yaml` is gitignored.
+- Apply only what is requested — don't add docstrings, comments, or error handling for impossible scenarios beyond what exists.