wbauth-sdk 0.2.0__py3-none-any.whl

wbauth/__init__.py

@@ -0,0 +1,45 @@
+"""wbauth: Web Bot Auth (RFC 9421) Python SDK.
+
+Phase 1 (current): identity + signer + JWKS + CLI keygen.
+Phase 2: HTTP-client adapters + policy inspector.
+"""
+from .adapters import (
+    WebBotAuth,
+    WebBotAuthAdapter,
+    WebBotAuthTransport,
+    attach_signing,
+    signed_session,
+)
+from .identity import Identity, KeyPair
+from .normalized_request import NormalizedRequest
+from .policy import (
+    AiTxtResult,
+    LlmsTxtResult,
+    RobotsResult,
+    SigningDirectoryResult,
+    SitePolicy,
+    inspect,
+)
+from .signer import SignatureHeaders, sign
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AiTxtResult",
+    "Identity",
+    "KeyPair",
+    "LlmsTxtResult",
+    "NormalizedRequest",
+    "RobotsResult",
+    "SignatureHeaders",
+    "SigningDirectoryResult",
+    "SitePolicy",
+    "WebBotAuth",
+    "WebBotAuthAdapter",
+    "WebBotAuthTransport",
+    "__version__",
+    "attach_signing",
+    "inspect",
+    "sign",
+    "signed_session",
+]

wbauth/_http_server/__init__.py

@@ -0,0 +1,7 @@
+"""Internal HTTP server submodule for `wbauth serve` (CLI-05, D-50).
+
+Stdlib http.server only — NO Flask, NO FastAPI, NO Starlette.
+The 30-LOC executable budget is enforced by the plan's acceptance gate.
+This module is internal (leading underscore) so it doesn't show up in
+`from wbauth import *` and isn't part of the public API surface.
+"""

wbauth/_http_server/jwks_server.py

@@ -0,0 +1,44 @@
+"""Tiny static JWKS server for self-hosters (D-50 — ≤30 LOC executable)."""
+# Serves a single JWKS file at /.well-known/http-message-signatures-directory/{kid}
+# with content-type per draft-meunier-http-message-signatures-directory-05.
+# NO registration, NO list endpoints — the hosted Worker
+# (https://wbauth.silov801.workers.dev) is the full directory.
+from __future__ import annotations
+import http.server
+import json
+import re
+from pathlib import Path
+
+CONTENT_TYPE = "application/http-message-signatures-directory+json"
+PATH_RE = re.compile(r"^/\.well-known/http-message-signatures-directory/([^/]+)$")
+
+
+def make_handler(jwks_path: Path):
+    jwks_bytes = jwks_path.read_bytes()
+    jwks = json.loads(jwks_bytes)
+    served_kids = {k["kid"] for k in jwks.get("keys", [])}
+
+    class JWKSHandler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):
+            m = PATH_RE.match(self.path)
+            if not m or m.group(1) not in served_kids:
+                self.send_error(404, "kid not served by this JWKS")
+                return
+            self.send_response(200)
+            self.send_header("content-type", CONTENT_TYPE)
+            self.send_header("content-length", str(len(jwks_bytes)))
+            self.send_header("cache-control", "public, max-age=300")
+            self.end_headers()
+            self.wfile.write(jwks_bytes)
+
+        def log_message(self, format, *args):
+            pass  # quiet stdlib request log
+
+    return JWKSHandler
+
+
+def serve(jwks_path: str | Path, port: int = 8080) -> None:
+    handler = make_handler(Path(jwks_path))
+    server = http.server.ThreadingHTTPServer(("0.0.0.0", port), handler)
+    print(f"Serving JWKS from {jwks_path} on port {port}")
+    server.serve_forever()

wbauth/_redaction.py

@@ -0,0 +1,19 @@
+"""Helpers for REDACTED repr/str on objects holding key material.
+
+Greppable for security review: anywhere __repr__/__str__ touch keys, reuse this.
+The literal string "REDACTED" appears in the produced repr so log scrapers can
+flag it (and so test_repr_returns_REDACTED can assert on it).
+"""
+from __future__ import annotations
+
+
+def redacted_repr(class_name: str, **public_fields: object) -> str:
+    """Build a `<ClassName REDACTED key1='v1' key2='v2'>` style repr.
+
+    Pass only NON-secret fields as kwargs. The output:
+    - Always begins with `<{class_name} REDACTED ` so the literal token is
+      detectable by log filters and unit tests.
+    - Renders each public field via `!r` so quotes/escapes are explicit.
+    """
+    parts = " ".join(f"{k}={v!r}" for k, v in public_fields.items())
+    return f"<{class_name} REDACTED {parts}>"

wbauth/_smoke/__init__.py

@@ -0,0 +1,13 @@
+"""Internal smoke tests for live conformance against external services.
+
+Not part of the public API. Submodules are intended to be runnable as
+``python -m wbauth._smoke.<name>`` from CI workflows. They exit non-zero on
+any failure (so a CI step fails loudly).
+
+Currently:
+
+- ``cloudflare_debug``: signs a request via :class:`wbauth.Identity` (using
+  the publicly-known RFC 9421 Appendix B.1.4 test key) and POSTs it to
+  Cloudflare's ``crawltest.com/cdn-cgi/web-bot-auth`` debug verifier.
+  Asserts HTTP 200. This is the Phase 1 hard exit criterion (IDENT-05).
+"""

wbauth/_smoke/cloudflare_debug.py

@@ -0,0 +1,224 @@
+"""Sign a request with the publicly-known RFC 9421 test key, hit Cloudflare's
+OPEN-spec verifier at ``http-message-signatures-example.research.cloudflare.com/``,
+assert HTTP 200 + success banner.
+
+Designed to be run as ``python -m wbauth._smoke.cloudflare_debug``. Exits
+non-zero on any failure (CI gate per IDENT-05). Prints diagnostic information
+to stderr on failure so the CI log is self-explanatory.
+
+Plan 02-03 refactor (preserves Phase-1 behavior):
+
+The original ``run() -> int`` did sign + GET + parse-banner inline. Plan 02-03
+introduces ``wbauth verify --domain <domain>`` (CLI-03), which needs the
+same machinery returning a structured dict instead of printing diagnostics.
+We split the shared probe into ``_probe_verifier(identity) -> dict`` and add
+``run_against_domain(domain, identity_path) -> dict`` for the CLI; ``run()``
+is preserved 1:1 for the daily cron at ``.github/workflows/cloudflare-debug.yml``
+(it now calls ``_probe_verifier`` internally and produces identical output).
+
+Why NOT crawltest.com (the original plan choice):
+====================================================
+
+RESEARCH §6 and CONTEXT.md both pointed at ``https://crawltest.com/cdn-cgi/web-bot-auth``
+as the exit gate. Empirical investigation during Plan 04 implementation
+(2026-05-03) revealed that endpoint is the **closed verified-bots** verifier
+which requires the kid to be registered via Cloudflare's Bot Submission Form
+(manual dashboard step + Cloudflare-side approval — out of Phase 1 scope).
+
+  $ curl https://crawltest.com/cdn-cgi/web-bot-auth -H 'Signature: <valid-sig>' \\
+                                                    -H 'Signature-Input: <...>' \\
+                                                    -H 'Signature-Agent: "<jwks>"'
+  HTTP/2 401
+  unknown public key or unknown verified bot ID for keyid
+
+This 401 happens even though the cryptographic signature is valid AND the kid
+is published in the Signature-Agent JWKS — Cloudflare's verified-bots gate
+also requires the kid to be in their internal allowlist. Per Cloudflare's
+docs (https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/
+step 3): "Register your bot and key directory" via Bot Submission Form.
+
+The CORRECT open-spec verifier (verified live):
+================================================
+
+``https://http-message-signatures-example.research.cloudflare.com/`` validates
+incoming requests against the published RFC 9421 Appendix B.1.4 test key:
+
+- No signature             → 200 + default homepage
+- VALID signed request     → 200 + banner "You successfully authenticated as
+                              owning the test public key"
+- INVALID signed request   → 200 + banner "The Signature you sent does not
+                              validate against test public key"
+
+So the verifier ALWAYS returns 200; success/failure is in the response BODY.
+This module checks for the success banner and exits non-zero if absent. This
+is the actual open-spec exit gate that proves end-to-end RFC 9421 + Web Bot
+Auth conformance without depending on Cloudflare's closed verified-bots gate.
+
+Phase 1 hard exit criterion (IDENT-05) restated:
+================================================
+
+"Cloudflare's OPEN-SPEC research verifier accepts a request signed by our SDK"
+(redirected from crawltest.com to the research server because crawltest.com
+is the closed verified-bots gate; verified-bots registration is out of Phase 1
+scope and tracked separately in the deferred work).
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime
+import sys
+
+import httpx
+
+from wbauth import Identity, NormalizedRequest, sign
+
+CF_RESEARCH_VERIFIER_URL = (
+    "https://http-message-signatures-example.research.cloudflare.com/"
+)
+SUCCESS_BANNER = "You successfully authenticated as owning the test public key"
+FAILURE_BANNER = "The Signature you sent does not validate against test public key"
+
+
+async def _probe_verifier(identity: Identity) -> dict:
+    """Sign a probe request with ``identity`` and check Cloudflare's research verifier.
+
+    Returns a structured result dict consumed by both ``run()`` (for the daily
+    cron diagnostic output) and ``run_against_domain()`` (for the CLI).
+
+    The dict carries ``signature_input`` / ``signature`` / ``signature_agent``
+    so ``run()`` can print them on failure for diagnostics; CLI callers
+    (``wbauth verify --json``) MUST strip those keys before emitting JSON
+    (see T-02-03-02 in the plan's threat model — handled in ``cli.py``).
+
+    Result shape:
+      {
+        "result":          "pass" | "fail",
+        "exit_code":       0 | 2,
+        "kid":             "<identity.kid>",
+        "status":          <int>,
+        "banner":          "<SUCCESS|FAILURE|(no banner)>",
+        "verifier_url":    CF_RESEARCH_VERIFIER_URL,
+        "signature_input": <str — internal-only, callers must strip>,
+        "signature":       <str — internal-only, callers must strip>,
+        "signature_agent": <str — internal-only, callers must strip>,
+      }
+    """
+    req = NormalizedRequest(method="GET", url=CF_RESEARCH_VERIFIER_URL, headers={})
+    sig = sign(req, identity, created=datetime.datetime.now(datetime.timezone.utc))
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        response = await client.get(
+            CF_RESEARCH_VERIFIER_URL,
+            headers={
+                "Signature": sig.signature,
+                "Signature-Input": sig.signature_input,
+                "Signature-Agent": sig.signature_agent,
+            },
+        )
+
+    # Pass only when the verifier explicitly says success AND status is 200.
+    # Anything else — failure banner, neither banner, or non-200 — is a fail.
+    if response.status_code == 200 and SUCCESS_BANNER in response.text:
+        result_kind = "pass"
+        banner = SUCCESS_BANNER
+    elif FAILURE_BANNER in response.text:
+        result_kind = "fail"
+        banner = FAILURE_BANNER
+    else:
+        result_kind = "fail"
+        banner = "(no banner)"
+
+    return {
+        "result": result_kind,
+        "exit_code": {"pass": 0, "fail": 2}[result_kind],
+        "kid": identity.kid,
+        "status": response.status_code,
+        "banner": banner,
+        "verifier_url": CF_RESEARCH_VERIFIER_URL,
+        "signature_input": sig.signature_input,
+        "signature": sig.signature,
+        "signature_agent": sig.signature_agent,
+    }
+
+
+async def run_against_domain(
+    domain: str, identity_path: str | None = None
+) -> dict:
+    """Async helper for ``wbauth verify --domain <domain>`` (CLI-03).
+
+    v1: ALWAYS uses ``Identity.from_test_key`` regardless of ``identity_path``
+    (open question #5 resolution). The Cloudflare research verifier only
+    validates the RFC 9421 Appendix B.1.4 test key; using a real user key
+    produces the FAILURE banner. ``identity_path`` is preserved in the
+    signature for forward compatibility — Phase 3+ wires it to a
+    domain-specific verifier path after directory registration.
+
+    The ``domain`` arg is informational in v1: surfaced in the result dict
+    (so ``--json`` consumers see it) but does NOT change the HTTP target
+    (always CF_RESEARCH_VERIFIER_URL). The CLI prints a clarifying note.
+    """
+    identity = Identity.from_test_key(signature_agent_url=CF_RESEARCH_VERIFIER_URL)
+    result = await _probe_verifier(identity)
+    result["domain"] = domain
+    return result
+
+
+def run() -> int:
+    """Phase-1 daily-cron entry. Preserved 1:1 modulo the internal refactor.
+
+    Calls ``_probe_verifier`` and reproduces the original Phase-1 stdout/stderr
+    diagnostic shape so ``.github/workflows/cloudflare-debug.yml`` keeps
+    working unchanged. Returns 0 on pass, 1 on fail (matches the Phase-1
+    contract — NOT the Plan 02-03 CLI exit-code matrix; this entry is for the
+    cron, not the user-facing CLI).
+    """
+    identity = Identity.from_test_key(signature_agent_url=CF_RESEARCH_VERIFIER_URL)
+    result = asyncio.run(_probe_verifier(identity))
+
+    # Pass: same OK line as Phase 1 — keeps the cron log shape stable.
+    if result["result"] == "pass":
+        print(
+            f"OK: Cloudflare research verifier accepted (status={result['status']}, "
+            f"kid={result['kid']}, banner='{SUCCESS_BANNER}')"
+        )
+        return 0
+
+    # Fail diagnostics — three sub-cases preserved from the Phase-1 module so
+    # the CI log keeps the same self-explanatory shape on regression.
+    if result["status"] != 200:
+        print(
+            "FAIL: Cloudflare research verifier returned non-200 (network or CDN issue?).\n"
+            f"  status={result['status']}\n"
+            f"  kid={result['kid']}\n"
+            f"  Signature-Input={result['signature_input']}\n"
+            f"  Signature={result['signature']}\n"
+            f"  Signature-Agent={result['signature_agent']}",
+            file=sys.stderr,
+        )
+    elif result["banner"] == FAILURE_BANNER:
+        print(
+            "FAIL: Cloudflare research verifier rejected our signature.\n"
+            "  banner: 'The Signature you sent does not validate against test public key'\n"
+            f"  kid={result['kid']}\n"
+            f"  Signature-Input={result['signature_input']}\n"
+            f"  Signature={result['signature']}\n"
+            f"  Signature-Agent={result['signature_agent']}\n"
+            "  Diagnosis: signer regression. Check RESEARCH Pitfalls 1, 2, 6.\n"
+            "  Re-run pytest test_signer to confirm regression detection.",
+            file=sys.stderr,
+        )
+    else:
+        # Neither banner — verifier may have changed shape.
+        print(
+            "FAIL: Cloudflare research verifier response unexpected (no success or "
+            "failure banner). Verifier may have changed; investigate.\n"
+            f"  status={result['status']}\n"
+            f"  kid={result['kid']}",
+            file=sys.stderr,
+        )
+    # Phase-1 contract: 1 on fail (not 2 — the CLI matrix is separate).
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(run())

wbauth/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Public adapter surface for wbauth (Phase 2).
+
+Re-exports the three drop-in adapters so users can write:
+    from wbauth.adapters import WebBotAuth, WebBotAuthAdapter, attach_signing
+"""
+from .httpx_auth import WebBotAuth
+from .playwright import attach_signing
+from .requests_adapter import WebBotAuthAdapter, WebBotAuthTransport, signed_session
+
+__all__ = [
+    "WebBotAuth",
+    "WebBotAuthAdapter",
+    "WebBotAuthTransport",
+    "attach_signing",
+    "signed_session",
+]

wbauth/adapters/_utils.py

@@ -0,0 +1,74 @@
+"""Shared adapter helpers (internal — not part of the public surface).
+
+The signer auto-includes ``content-digest`` in covered components for
+POST/PUT/PATCH with a body; adapters call :func:`ensure_content_digest`
+before ``sign()`` so that precondition is met. RFC 9530 sha-256 in
+structured-fields form (``sha-256=:<b64>:``).
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+from collections.abc import Iterable, MutableMapping
+
+_DIGEST_METHODS = ("POST", "PUT", "PATCH")
+
+# Default UAs set by HTTP libraries. An Identity UA replaces these, but an
+# explicit caller-supplied UA always wins.
+_LIBRARY_DEFAULT_UA = re.compile(r"^(python-requests|python-httpx|python-urllib)/", re.I)
+
+
+def ensure_content_digest(method: str, headers: dict, body: bytes | None) -> None:
+    """Add ``Content-Digest`` for POST/PUT/PATCH with a non-empty body.
+
+    No-op when the body is empty, the method carries no body, or the caller
+    already supplied a Content-Digest (case-insensitive).
+    """
+    if not body:
+        return
+    if method.upper() not in _DIGEST_METHODS:
+        return
+    if any(k.lower() == "content-digest" for k in headers):
+        return
+    if not isinstance(body, (bytes, bytearray, memoryview)):
+        raise TypeError(
+            f"body must be bytes to compute Content-Digest, got {type(body).__name__}"
+        )
+    digest = hashlib.sha256(body).digest()
+    b64 = base64.b64encode(digest).decode("ascii")
+    headers["Content-Digest"] = f"sha-256=:{b64}:"
+
+
+def should_apply_user_agent(current: str | None) -> bool:
+    """True when the current UA is absent or a library default."""
+    return not current or bool(_LIBRARY_DEFAULT_UA.match(current))
+
+
+def apply_user_agent(headers: MutableMapping[str, str], user_agent: str | None) -> None:
+    """Set ``User-Agent`` unless the caller explicitly chose a non-default one."""
+    if not user_agent:
+        return
+    key = next((k for k in headers if k.lower() == "user-agent"), None)
+    current = headers[key] if key is not None else None
+    if should_apply_user_agent(current):
+        if key is not None:
+            del headers[key]
+        headers["User-Agent"] = user_agent
+
+
+def host_matches(hostname: str, allow: Iterable[str]) -> bool:
+    """Match ``hostname`` against exact hosts or ``*.example.com`` wildcards.
+
+    A wildcard also matches the bare apex (``*.example.com`` ⊇ ``example.com``).
+    """
+    h = hostname.lower().rstrip(".")
+    for raw in allow:
+        a = raw.lower().rstrip(".")
+        if a.startswith("*."):
+            base = a[2:]
+            if h == base or h.endswith("." + base):
+                return True
+        elif h == a:
+            return True
+    return False

wbauth/adapters/httpx_auth.py

@@ -0,0 +1,49 @@
+"""httpx ``Auth`` adapter: signs every request (sync and async clients).
+
+    client = httpx.Client(auth=WebBotAuth(identity))
+
+Each redirect hop is re-signed for its own ``@authority``; stale signature
+headers from the previous hop are replaced, never merged.
+"""
+from __future__ import annotations
+
+import httpx
+
+from wbauth.adapters._utils import ensure_content_digest, should_apply_user_agent
+from wbauth.normalized_request import NormalizedRequest
+from wbauth.signer import sign
+
+
+class WebBotAuth(httpx.Auth):
+    """Drop-in ``httpx.Auth`` that adds Web Bot Auth signatures."""
+
+    requires_request_body = True  # body must be readable for content-digest
+
+    def __init__(self, identity):
+        self._identity = identity
+
+    def sync_auth_flow(self, request):
+        self._sign(request)
+        yield request
+
+    async def async_auth_flow(self, request):
+        self._sign(request)
+        yield request  # signing is pure CPU
+
+    def _sign(self, request: httpx.Request) -> None:
+        body = request.content if request.content else None
+        headers = dict(request.headers)
+        ensure_content_digest(request.method, headers, body)
+        if "Content-Digest" in headers:
+            request.headers["Content-Digest"] = headers["Content-Digest"]
+        normalized = NormalizedRequest(
+            method=request.method, url=str(request.url),
+            headers=headers, body=body,
+        )
+        sig = sign(normalized, self._identity)
+        request.headers["Signature"] = sig.signature
+        request.headers["Signature-Input"] = sig.signature_input
+        request.headers["Signature-Agent"] = sig.signature_agent
+        ua = getattr(self._identity, "user_agent", None)
+        if ua and should_apply_user_agent(request.headers.get("user-agent")):
+            request.headers["User-Agent"] = ua

wbauth/adapters/playwright.py

@@ -0,0 +1,80 @@
+"""Playwright async helper for Web Bot Auth (ADAPT-03).
+
+Registers a page.route handler that intercepts outgoing requests, signs the
+matching ones via wbauth.sign(), and continues with the signed headers.
+Stateless per D-15; async-only per D-13.
+
+Privacy: without ``hosts`` every http(s) request is signed — including
+third-party analytics / CDN hosts, which then learn your agent identity.
+Restrict signing to the sites you target::
+
+    await attach_signing(page, identity, hosts=["example.com", "*.example.org"])
+
+Non-http(s) requests (data:, blob:, chrome-extension:) are never signed.
+Playwright disables the HTTP cache while a route is active.
+
+PITFALL 6: Call attach_signing(page, identity) BEFORE the first
+page.goto()/page.click() that should produce signed requests.
+
+PITFALL 7 (iframe coverage): page.route("**/*", handler) covers all
+sub-frame requests by default. If the target site uses Service Workers,
+set serviceWorkers="block" on the BrowserContext (Playwright option).
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from urllib.parse import urlsplit
+
+from wbauth.adapters._utils import apply_user_agent, ensure_content_digest, host_matches
+from wbauth.normalized_request import NormalizedRequest
+from wbauth.signer import sign
+
+
+async def attach_signing(
+    page,
+    identity,
+    *,
+    hosts: Iterable[str] | None = None,
+    should_sign: Callable[[str], bool] | None = None,
+    pattern: str = "**/*",
+) -> None:
+    """Register a route handler on ``page`` that signs matching requests.
+
+    Args:
+        hosts: Only sign requests to these hosts (``example.com``,
+            ``*.example.com``). ``None`` = sign every http(s) request.
+        should_sign: Custom predicate on the request URL; overrides ``hosts``.
+        pattern: Route glob passed to ``page.route``.
+    """
+    allow = list(hosts) if hosts is not None else None
+
+    def _decide(url: str) -> bool:
+        parts = urlsplit(url)
+        if parts.scheme not in ("http", "https") or not parts.hostname:
+            return False
+        if should_sign is not None:
+            return bool(should_sign(url))
+        if allow is not None:
+            return host_matches(parts.hostname, allow)
+        return True
+
+    async def _handler(route, request):
+        if not _decide(request.url):
+            fallback = getattr(route, "fallback", None)
+            await (fallback() if fallback is not None else route.continue_())
+            return
+        headers = dict(await request.all_headers())
+        body = request.post_data_buffer
+        ensure_content_digest(request.method, headers, body)
+        normalized = NormalizedRequest(
+            method=request.method, url=request.url,
+            headers=headers, body=body,
+        )
+        sig = sign(normalized, identity)
+        headers["Signature"] = sig.signature
+        headers["Signature-Input"] = sig.signature_input
+        headers["Signature-Agent"] = sig.signature_agent
+        apply_user_agent(headers, getattr(identity, "user_agent", None))
+        await route.continue_(headers=headers)
+
+    await page.route(pattern, _handler)

wbauth/adapters/requests_adapter.py

@@ -0,0 +1,93 @@
+"""requests ``AuthBase`` adapter: signs every prepared request.
+
+    requests.get(url, auth=WebBotAuthAdapter(identity))
+    session.auth = WebBotAuthAdapter(identity)
+
+Streaming bodies (generators, file objects) are buffered once so the
+Content-Digest can be computed; the buffered bytes are what gets sent.
+
+**Redirects.** ``requests`` does not re-run per-request ``auth=`` on
+redirect hops, so the first hop's signature (bound to the first host's
+``@authority``) would be replayed to the redirect target. Use
+:func:`signed_session` — or mount :class:`WebBotAuthTransport` yourself —
+to re-sign every hop::
+
+    session = signed_session(identity)
+    session.get("https://example.com/")
+"""
+from __future__ import annotations
+
+import requests
+from requests.adapters import HTTPAdapter
+from requests.auth import AuthBase
+
+from wbauth.adapters._utils import ensure_content_digest, should_apply_user_agent
+from wbauth.normalized_request import NormalizedRequest
+from wbauth.signer import sign
+
+
+def _buffer_body(prepared_request) -> bytes | None:
+    body = prepared_request.body
+    if body is None or isinstance(body, bytes):
+        return body
+    if isinstance(body, str):
+        return body.encode("utf-8")
+    if isinstance(body, (bytearray, memoryview)):
+        return bytes(body)
+    if hasattr(body, "read"):
+        data = body.read()
+    else:  # iterable of chunks (generator, list, …)
+        data = b"".join(c.encode("utf-8") if isinstance(c, str) else bytes(c) for c in body)
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    prepared_request.body = data
+    prepared_request.headers.pop("Transfer-Encoding", None)
+    prepared_request.headers["Content-Length"] = str(len(data))
+    return data
+
+
+class WebBotAuthAdapter(AuthBase):
+    """Drop-in ``requests`` auth that adds Web Bot Auth signatures."""
+
+    def __init__(self, identity):
+        self._identity = identity
+
+    def __call__(self, prepared_request):
+        body = _buffer_body(prepared_request)
+        headers = dict(prepared_request.headers)
+        ensure_content_digest(prepared_request.method, headers, body)
+        if "Content-Digest" in headers:
+            prepared_request.headers["Content-Digest"] = headers["Content-Digest"]
+        normalized = NormalizedRequest(
+            method=prepared_request.method, url=prepared_request.url,
+            headers=headers, body=body,
+        )
+        sig = sign(normalized, self._identity)
+        prepared_request.headers["Signature"] = sig.signature
+        prepared_request.headers["Signature-Input"] = sig.signature_input
+        prepared_request.headers["Signature-Agent"] = sig.signature_agent
+        ua = getattr(self._identity, "user_agent", None)
+        if ua and should_apply_user_agent(prepared_request.headers.get("User-Agent")):
+            prepared_request.headers["User-Agent"] = ua
+        return prepared_request
+
+
+class WebBotAuthTransport(HTTPAdapter):
+    """Transport adapter that signs at send time — covers every redirect hop."""
+
+    def __init__(self, identity, *args, **kwargs):
+        self._auth = WebBotAuthAdapter(identity)
+        super().__init__(*args, **kwargs)
+
+    def send(self, request, *args, **kwargs):  # type: ignore[override]
+        self._auth(request)
+        return super().send(request, *args, **kwargs)
+
+
+def signed_session(identity, session: requests.Session | None = None) -> requests.Session:
+    """Return a ``requests.Session`` whose every request (and redirect) is signed."""
+    s = session or requests.Session()
+    transport = WebBotAuthTransport(identity)
+    s.mount("https://", transport)
+    s.mount("http://", transport)
+    return s