xms-dns 0.1.0__tar.gz

xms_dns-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/

xms_dns-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Creative Commons Attribution-NonCommercial 4.0 International
+
+Copyright (c) 2026 Sergio Garcia <soukron@gmbros.net>
+
+This work is licensed under the Creative Commons Attribution-NonCommercial
+4.0 International License.
+
+You are free to:
+  - Share — copy and redistribute the material in any medium or format
+  - Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+  - Attribution — You must give appropriate credit, provide a link to the
+    license, and indicate if changes were made.
+  - NonCommercial — You may not use the material for commercial purposes.
+
+No additional restrictions — You may not apply legal terms or technological
+measures that legally restrict others from doing anything the license permits.
+
+Full license text: https://creativecommons.org/licenses/by-nc/4.0/legalcode

xms_dns-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: xms-dns
+Version: 0.1.0
+Summary: Cliente Python para gestionar DNS en el panel XMS (Digital Value). CLI, biblioteca y servidor dyndns2/checkip compatible con ddclient. A, AAAA y TXT.
+Project-URL: Homepage, https://github.com/soukron/xms-dns
+Project-URL: Repository, https://github.com/soukron/xms-dns
+Project-URL: Issues, https://github.com/soukron/xms-dns/issues
+Author-email: Sergio Garcia <soukron@gmbros.net>
+Maintainer-email: Sergio Garcia <soukron@gmbros.net>
+License-Expression: CC-BY-NC-4.0
+License-File: LICENSE
+Keywords: ddclient,digitalvalue,dns,dyndns,xms
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: Free for non-commercial use
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: fastapi>=0.100
+Requires-Dist: httpx>=0.27
+Requires-Dist: lxml>=5.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
+Requires-Dist: uvicorn>=0.23
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# xms-dns
+
+Cliente Python para gestionar DNS en el panel XMS (Digital Value). Incluye CLI (`xms-dns`), biblioteca y servidor dyndns2/checkip (`xms-dns-server`) compatible con ddclient. Soporta registros A, AAAA y TXT.
+
+## Setup
+
+```bash
+pip install xms-dns
+```
+
+For development:
+
+```bash
+git clone https://github.com/soukron/xms-dns.git
+cd xms-dns
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Config file (optional, no secrets)
+
+Create `~/.config/xms-dns/config` with non-sensitive settings only:
+
+```bash
+mkdir -p ~/.config/xms-dns
+cat > ~/.config/xms-dns/config <<'EOF'
+XMS_BASE_URL=https://xms.digitalvalue.es
+XMS_LOGIN=admin#example.test
+EOF
+chmod 600 ~/.config/xms-dns/config
+```
+
+Passwords are **not** read from this file. Use `xms-dns login` instead.
+
+Environment variables override the config file. Override paths with `XMS_CONFIG_DIR` or `XMS_CACHE_DIR`.
+
+### Login
+
+```bash
+xms-dns login
+```
+
+Resolves settings in this order:
+
+1. Environment variables (`XMS_BASE_URL`, `XMS_LOGIN`, `XMS_PASSWORD`)
+2. Config file (`XMS_BASE_URL`, `XMS_LOGIN` only)
+3. Interactive prompts for anything still missing (password always prompted unless in env)
+
+Connection type is always `siempre` (permanent session). On success, the session cookie is saved to `~/.cache/xms-dns/auth.cache`.
+
+### HTTP calls
+
+Login and operations are separate executions:
+
+- **`xms-dns login`** — authenticates against the panel and saves the session (its own HTTP calls; not counted against other commands).
+- **Any other command** — exactly **one** HTTP request to the panel, using the cached session. Credentials are never sent again.
+
+Example: `xms-dns domains` is a single `GET` to `Operacion=Dominios`. `xms-dns list` is a single `GET` to load the zone.
+
+The only exception is **`upsert` when the value changes**: XMS has no inline edit, so the client deletes and recreates the record (two or three requests).
+
+## CLI
+
+Global flags:
+
+- `-o` / `--output` — output format: `table` (default), `csv`, `json`, or `yaml`
+- `-v` / `--verbose` — log HTTP requests to stderr
+- `--debug` — log requests and response bodies to stderr (includes verbose)
+
+```bash
+xms-dns login
+xms-dns list gmbros.net
+xms-dns -o csv list gmbros.net
+xms-dns -o json domains
+xms-dns -v list gmbros.net
+xms-dns --debug upsert gmbros.net dyndns-test A 203.0.113.10
+```
+
+DNS commands use the cached session only. If not logged in or session expired:
+
+```
+error: Not logged in. Run: xms-dns login
+```
+
+## Server (dyndns2 + checkip)
+
+Start the dynamic DNS server:
+
+```bash
+xms-dns-server
+```
+
+Environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `XMS_BASE_URL` | `https://xms.digitalvalue.es` | XMS panel URL |
+| `XMS_SERVER_HOST` | `127.0.0.1` | Bind address |
+| `XMS_SERVER_PORT` | `8080` | Bind port |
+| `XMS_TRUST_PROXY` | unset | Set to `1` to trust `X-Forwarded-For` for client IP |
+| `XMS_CACHE_DIR` | `~/.cache/xms-dns` | Session cache directory |
+
+> **Reverse proxy (production):** if `xms-dns-server` runs behind nginx, Caddy, Traefik, etc., set **`XMS_TRUST_PROXY=1`**. Otherwise `/checkip` and updates without `myip` see the proxy IP (`127.0.0.1`) instead of the client. Only enable this when a trusted proxy overwrites `X-Forwarded-For` — do not expose the server directly to the internet with this flag on.
+
+### Authentication
+
+The server does **not** use `xms-dns login`. Each dyndns2 client sends XMS credentials via HTTP Basic auth:
+
+- `username` → XMS login (e.g. `admin#example.test`)
+- `password` → XMS password
+
+The session cookie is cached per user in `~/.cache/xms-dns/server/{sha256}.cache` (separate from the CLI `auth.cache`). If the cached session expires, the server re-authenticates with the credentials from the current request.
+
+### Endpoints
+
+- `GET /nic/update?hostname=home.example.test&myip=...` — dyndns2 update. Returns `good {value}`, `nochg {value}`, `badauth`, etc. Always HTTP 200.
+- Record types: **A** (default), **AAAA**, **TXT**.
+  - A / AAAA: pass the address in `myip`, or omit it to use the client IP (`X-Forwarded-For` when `XMS_TRUST_PROXY=1`).
+  - AAAA: set `type=AAAA`, or pass an IPv6 address in `myip` (auto-detected).
+  - TXT: set `type=TXT` and pass the record data in `txt=` (or `value=`).
+- `GET /checkip` — returns the caller's public IPv4. Optional `?format=pfsense` for legacy pfSense.
+
+If `myip` is omitted, the client IP is used (see `X-Forwarded-For` when `XMS_TRUST_PROXY=1`).
+
+### ddclient example
+
+```
+protocol=dyndns2
+server=dyndns.example.test
+login=admin#example.test
+password=your-xms-password
+home.example.test
+```
+
+Put TLS termination on a reverse proxy in production; bind locally by default. Remember **`XMS_TRUST_PROXY=1`** on the server process (see above).
+
+## Library
+
+```python
+from xms_dns import XmsClient
+
+# Login once (CLI does this via `xms-dns login`)
+with XmsClient(base_url="...", login="...", password="...") as client:
+    client.authenticate()
+
+# Later operations reuse auth.cache
+with XmsClient.from_env() as client:
+    client.ensure_session()
+    client.upsert_record("gmbros.net", "home", "A", "203.0.113.10")
+```
+
+## Tests
+
+All default tests use mocked HTTP responses and **do not** contact the live XMS panel:
+
+```bash
+pytest
+```
+
+## Live smoke test
+
+```bash
+xms-dns login   # or set XMS_PASSWORD for one-shot login inside the script
+XMS_LIVE=1 python scripts/smoke_test.py
+```
+
+## Security
+
+- Do not store passwords in the config file
+- Keep `~/.cache/xms-dns/auth.cache` private (`chmod 600`)
+- Keep server session caches private too: `~/.cache/xms-dns/server/*.cache` (`chmod 600`)
+
+## License
+
+Copyright (c) 2026 Sergio Garcia.
+
+Licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use with attribution required.

xms_dns-0.1.0/README.md

@@ -0,0 +1,178 @@
+# xms-dns
+
+Cliente Python para gestionar DNS en el panel XMS (Digital Value). Incluye CLI (`xms-dns`), biblioteca y servidor dyndns2/checkip (`xms-dns-server`) compatible con ddclient. Soporta registros A, AAAA y TXT.
+
+## Setup
+
+```bash
+pip install xms-dns
+```
+
+For development:
+
+```bash
+git clone https://github.com/soukron/xms-dns.git
+cd xms-dns
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Config file (optional, no secrets)
+
+Create `~/.config/xms-dns/config` with non-sensitive settings only:
+
+```bash
+mkdir -p ~/.config/xms-dns
+cat > ~/.config/xms-dns/config <<'EOF'
+XMS_BASE_URL=https://xms.digitalvalue.es
+XMS_LOGIN=admin#example.test
+EOF
+chmod 600 ~/.config/xms-dns/config
+```
+
+Passwords are **not** read from this file. Use `xms-dns login` instead.
+
+Environment variables override the config file. Override paths with `XMS_CONFIG_DIR` or `XMS_CACHE_DIR`.
+
+### Login
+
+```bash
+xms-dns login
+```
+
+Resolves settings in this order:
+
+1. Environment variables (`XMS_BASE_URL`, `XMS_LOGIN`, `XMS_PASSWORD`)
+2. Config file (`XMS_BASE_URL`, `XMS_LOGIN` only)
+3. Interactive prompts for anything still missing (password always prompted unless in env)
+
+Connection type is always `siempre` (permanent session). On success, the session cookie is saved to `~/.cache/xms-dns/auth.cache`.
+
+### HTTP calls
+
+Login and operations are separate executions:
+
+- **`xms-dns login`** — authenticates against the panel and saves the session (its own HTTP calls; not counted against other commands).
+- **Any other command** — exactly **one** HTTP request to the panel, using the cached session. Credentials are never sent again.
+
+Example: `xms-dns domains` is a single `GET` to `Operacion=Dominios`. `xms-dns list` is a single `GET` to load the zone.
+
+The only exception is **`upsert` when the value changes**: XMS has no inline edit, so the client deletes and recreates the record (two or three requests).
+
+## CLI
+
+Global flags:
+
+- `-o` / `--output` — output format: `table` (default), `csv`, `json`, or `yaml`
+- `-v` / `--verbose` — log HTTP requests to stderr
+- `--debug` — log requests and response bodies to stderr (includes verbose)
+
+```bash
+xms-dns login
+xms-dns list gmbros.net
+xms-dns -o csv list gmbros.net
+xms-dns -o json domains
+xms-dns -v list gmbros.net
+xms-dns --debug upsert gmbros.net dyndns-test A 203.0.113.10
+```
+
+DNS commands use the cached session only. If not logged in or session expired:
+
+```
+error: Not logged in. Run: xms-dns login
+```
+
+## Server (dyndns2 + checkip)
+
+Start the dynamic DNS server:
+
+```bash
+xms-dns-server
+```
+
+Environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `XMS_BASE_URL` | `https://xms.digitalvalue.es` | XMS panel URL |
+| `XMS_SERVER_HOST` | `127.0.0.1` | Bind address |
+| `XMS_SERVER_PORT` | `8080` | Bind port |
+| `XMS_TRUST_PROXY` | unset | Set to `1` to trust `X-Forwarded-For` for client IP |
+| `XMS_CACHE_DIR` | `~/.cache/xms-dns` | Session cache directory |
+
+> **Reverse proxy (production):** if `xms-dns-server` runs behind nginx, Caddy, Traefik, etc., set **`XMS_TRUST_PROXY=1`**. Otherwise `/checkip` and updates without `myip` see the proxy IP (`127.0.0.1`) instead of the client. Only enable this when a trusted proxy overwrites `X-Forwarded-For` — do not expose the server directly to the internet with this flag on.
+
+### Authentication
+
+The server does **not** use `xms-dns login`. Each dyndns2 client sends XMS credentials via HTTP Basic auth:
+
+- `username` → XMS login (e.g. `admin#example.test`)
+- `password` → XMS password
+
+The session cookie is cached per user in `~/.cache/xms-dns/server/{sha256}.cache` (separate from the CLI `auth.cache`). If the cached session expires, the server re-authenticates with the credentials from the current request.
+
+### Endpoints
+
+- `GET /nic/update?hostname=home.example.test&myip=...` — dyndns2 update. Returns `good {value}`, `nochg {value}`, `badauth`, etc. Always HTTP 200.
+- Record types: **A** (default), **AAAA**, **TXT**.
+  - A / AAAA: pass the address in `myip`, or omit it to use the client IP (`X-Forwarded-For` when `XMS_TRUST_PROXY=1`).
+  - AAAA: set `type=AAAA`, or pass an IPv6 address in `myip` (auto-detected).
+  - TXT: set `type=TXT` and pass the record data in `txt=` (or `value=`).
+- `GET /checkip` — returns the caller's public IPv4. Optional `?format=pfsense` for legacy pfSense.
+
+If `myip` is omitted, the client IP is used (see `X-Forwarded-For` when `XMS_TRUST_PROXY=1`).
+
+### ddclient example
+
+```
+protocol=dyndns2
+server=dyndns.example.test
+login=admin#example.test
+password=your-xms-password
+home.example.test
+```
+
+Put TLS termination on a reverse proxy in production; bind locally by default. Remember **`XMS_TRUST_PROXY=1`** on the server process (see above).
+
+## Library
+
+```python
+from xms_dns import XmsClient
+
+# Login once (CLI does this via `xms-dns login`)
+with XmsClient(base_url="...", login="...", password="...") as client:
+    client.authenticate()
+
+# Later operations reuse auth.cache
+with XmsClient.from_env() as client:
+    client.ensure_session()
+    client.upsert_record("gmbros.net", "home", "A", "203.0.113.10")
+```
+
+## Tests
+
+All default tests use mocked HTTP responses and **do not** contact the live XMS panel:
+
+```bash
+pytest
+```
+
+## Live smoke test
+
+```bash
+xms-dns login   # or set XMS_PASSWORD for one-shot login inside the script
+XMS_LIVE=1 python scripts/smoke_test.py
+```
+
+## Security
+
+- Do not store passwords in the config file
+- Keep `~/.cache/xms-dns/auth.cache` private (`chmod 600`)
+- Keep server session caches private too: `~/.cache/xms-dns/server/*.cache` (`chmod 600`)
+
+## License
+
+Copyright (c) 2026 Sergio Garcia.
+
+Licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use with attribution required.

xms_dns-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xms-dns"
+version = "0.1.0"
+description = "Cliente Python para gestionar DNS en el panel XMS (Digital Value). CLI, biblioteca y servidor dyndns2/checkip compatible con ddclient. A, AAAA y TXT."
+readme = "README.md"
+license = "CC-BY-NC-4.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [
+    { name = "Sergio Garcia", email = "soukron@gmbros.net" },
+]
+maintainers = [
+    { name = "Sergio Garcia", email = "soukron@gmbros.net" },
+]
+keywords = ["dns", "dyndns", "xms", "digitalvalue", "ddclient"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "License :: Free for non-commercial use",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: Name Service (DNS)",
+    "Topic :: System :: Networking",
+]
+dependencies = [
+    "httpx>=0.27",
+    "beautifulsoup4>=4.12",
+    "lxml>=5.0",
+    "PyYAML>=6.0",
+    "fastapi>=0.100",
+    "uvicorn>=0.23",
+    "typing_extensions>=4.0; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/soukron/xms-dns"
+Repository = "https://github.com/soukron/xms-dns"
+Issues = "https://github.com/soukron/xms-dns/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+xms-dns = "xms_dns.cli:main"
+xms-dns-server = "xms_dns.server.main:main"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/xms_dns"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/xms_dns" = "xms_dns"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "live: hits the real XMS panel (requires XMS_LIVE=1)",
+]

xms_dns-0.1.0/scripts/smoke_test.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Manual smoke test against the live XMS panel.
+
+Requires explicit opt-in to avoid accidental hits to the real panel:
+  XMS_LIVE=1 python scripts/smoke_test.py
+
+Run `xms-dns login` first, or set XMS_PASSWORD for this script to log in.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from xms_dns import XmsClient
+from xms_dns.config import load_config
+from xms_dns.credentials import resolve_login_credentials
+
+DOMAIN = os.environ.get("XMS_SMOKE_DOMAIN", "gmbros.net")
+HOST = os.environ.get("XMS_SMOKE_HOST", "dyndns-test")
+IP1 = os.environ.get("XMS_SMOKE_IP1", "1.2.3.4")
+IP2 = os.environ.get("XMS_SMOKE_IP2", "5.6.7.8")
+
+
+def main() -> int:
+    load_config()
+
+    if os.environ.get("XMS_LIVE") != "1":
+        print(
+            "Refusing to contact the live XMS panel.\n"
+            "Run with: XMS_LIVE=1 python scripts/smoke_test.py",
+            file=sys.stderr,
+        )
+        return 2
+
+    print(f"Smoke test on {HOST}.{DOMAIN}")
+
+    with XmsClient.from_env() as client:
+        try:
+            client.ensure_session()
+        except Exception:
+            base_url, login, password = resolve_login_credentials()
+            client.base_url = base_url.rstrip("/")
+            client.login = login
+            client.password = password
+            client._client.base_url = base_url.rstrip("/")
+            client.authenticate()
+
+        domains = client.list_domains()
+        print(f"domains ({len(domains)}): {', '.join(item.domain for item in domains[:5])}...")
+        assert any(item.domain == DOMAIN for item in domains), f"{DOMAIN} not in account"
+
+        print(f"upsert {HOST} A -> {IP1}")
+        record = client.upsert_record(DOMAIN, HOST, "A", IP1)
+        print(f"  -> {record.host} {record.type} {record.value} ({record.reg_id})")
+
+        print(f"upsert {HOST} A -> {IP2} (delete+create)")
+        record = client.upsert_record(DOMAIN, HOST, "A", IP2)
+        print(f"  -> {record.host} {record.type} {record.value} ({record.reg_id})")
+
+        print(f"upsert {HOST} A -> {IP2} (no-op)")
+        record = client.upsert_record(DOMAIN, HOST, "A", IP2)
+        assert record.value == IP2
+
+        print(f"delete {HOST} A")
+        client.delete_record(DOMAIN, HOST, "A")
+        print("done")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as exc:
+        print(f"smoke test failed: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc

xms_dns-0.1.0/src/xms_dns/__init__.py

@@ -0,0 +1,13 @@
+from xms_dns.client import XmsClient
+from xms_dns.exceptions import AuthError, OperationError, RecordNotFoundError, XmsError
+from xms_dns.records import DnsRecord, DomainInfo
+
+__all__ = [
+    "AuthError",
+    "DnsRecord",
+    "DomainInfo",
+    "OperationError",
+    "RecordNotFoundError",
+    "XmsClient",
+    "XmsError",
+]

xms_dns-0.1.0/src/xms_dns/_browser.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+# Captured from real XMS panel usage (Chrome on macOS).
+BROWSER_USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/149.0.0.0 Safari/537.36"
+)
+
+
+def browser_headers(base_url: str) -> dict[str, str]:
+    return {
+        "User-Agent": BROWSER_USER_AGENT,
+        "Accept": (
+            "text/html,application/xhtml+xml,application/xml;q=0.9,"
+            "image/avif,image/webp,image/apng,*/*;q=0.8"
+        ),
+        "Accept-Language": "en-US,en;q=0.7",
+        "Accept-Encoding": "gzip, deflate",
+        # httpx needs this for the old XMS Apache; browsers use keep-alive.
+        "Connection": "close",
+    }
+
+
+def form_post_headers(base_url: str) -> dict[str, str]:
+    return {
+        "Origin": base_url,
+        "Referer": f"{base_url}/cgi-bin/xms3.cgi",
+        "Cache-Control": "max-age=0",
+    }

xms_dns-0.1.0/src/xms_dns/_http_log.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import sys
+from typing import TextIO
+from urllib.parse import parse_qsl, urlencode
+
+import httpx
+
+SENSITIVE_KEYS = {"passwd", "password", "token", "secret"}
+REDACTED = "***"
+MAX_DEBUG_BODY = 4000
+
+
+def _redact_form_body(body: str) -> str:
+    pairs = parse_qsl(body, keep_blank_values=True)
+    redacted = [
+        (key, REDACTED if key.lower() in SENSITIVE_KEYS else value)
+        for key, value in pairs
+    ]
+    return urlencode(redacted)
+
+
+def format_request(request: httpx.Request) -> str:
+    lines = [f">>> {request.method} {request.url}"]
+    content_type = request.headers.get("content-type", "")
+    if request.content:
+        body = request.content.decode("utf-8", errors="replace")
+        if "application/x-www-form-urlencoded" in content_type:
+            body = _redact_form_body(body)
+        lines.append(f">>> body: {body}")
+    cookie = request.headers.get("cookie")
+    if cookie:
+        lines.append(f">>> cookie: {cookie}")
+    return "\n".join(lines)
+
+
+def format_response(response: httpx.Response) -> str:
+    lines = [f"<<< {response.status_code} {response.request.method} {response.request.url}"]
+    body = response.text
+    if len(body) > MAX_DEBUG_BODY:
+        body = body[:MAX_DEBUG_BODY] + f"\n... ({len(response.text)} bytes total)"
+    lines.append(f"<<< body:\n{body}")
+    return "\n".join(lines)
+
+
+def emit_http_log(message: str, stream: TextIO | None = None) -> None:
+    target = stream or sys.stderr
+    print(message, file=target)