PyEVP 0.1.0__py3-none-any.whl

pyevp/adapters/dnspython.py

@@ -0,0 +1,79 @@
+"""TXT resolvers backed by dnspython (``pip install pyevp[dns]``)."""
+
+from __future__ import annotations
+
+import dns.asyncresolver
+import dns.flags
+import dns.resolver
+from dns.resolver import Answer
+
+__all__ = ["AsyncDnsPythonResolver", "DnsPythonResolver", "DnssecError"]
+
+_EMPTY = (dns.resolver.NXDOMAIN, dns.resolver.NoAnswer)
+
+
+class DnssecError(Exception):
+    """The answer was not marked authenticated (AD) by the resolver."""
+
+
+def _configure(resolver: dns.resolver.BaseResolver, require_dnssec: bool) -> None:
+    if require_dnssec:
+        resolver.use_edns(0, dns.flags.DO, 1232)
+        # ``None`` means dnspython's default query flags, which set RD; keep it.
+        base = dns.flags.RD if resolver.flags is None else resolver.flags
+        resolver.flags = base | dns.flags.AD
+
+
+def _records(answer: Answer, name: str, require_dnssec: bool) -> list[str]:
+    if require_dnssec and not (answer.response.flags & dns.flags.AD):
+        raise DnssecError(f"TXT answer for {name} is not DNSSEC-authenticated")
+    return [b"".join(rdata.strings).decode("utf-8", "replace") for rdata in answer]
+
+
+class DnsPythonResolver:
+    """Synchronous resolver.
+
+    With ``require_dnssec=True`` the answer must carry the AD flag, which is only
+    meaningful when the configured upstream resolver validates DNSSEC and the
+    path to it is trusted (e.g. a local validating resolver).
+    """
+
+    def __init__(
+        self,
+        resolver: dns.resolver.Resolver | None = None,
+        *,
+        require_dnssec: bool = False,
+        lifetime: float = 5.0,
+    ) -> None:
+        self._resolver = resolver or dns.resolver.Resolver()
+        self._resolver.lifetime = lifetime
+        self._require_dnssec = require_dnssec
+        _configure(self._resolver, require_dnssec)
+
+    def resolve_txt(self, name: str) -> list[str]:
+        try:
+            answer = self._resolver.resolve(name, "TXT")
+        except _EMPTY:
+            return []
+        return _records(answer, name, self._require_dnssec)
+
+
+class AsyncDnsPythonResolver:
+    def __init__(
+        self,
+        resolver: dns.asyncresolver.Resolver | None = None,
+        *,
+        require_dnssec: bool = False,
+        lifetime: float = 5.0,
+    ) -> None:
+        self._resolver = resolver or dns.asyncresolver.Resolver()
+        self._resolver.lifetime = lifetime
+        self._require_dnssec = require_dnssec
+        _configure(self._resolver, require_dnssec)
+
+    async def resolve_txt(self, name: str) -> list[str]:
+        try:
+            answer = await self._resolver.resolve(name, "TXT")
+        except _EMPTY:
+            return []
+        return _records(answer, name, self._require_dnssec)

pyevp/adapters/doh.py

@@ -0,0 +1,130 @@
+"""TXT resolvers over DNS-over-HTTPS JSON APIs (``pip install pyevp[httpx2]`` or ``pyevp[httpx]``).
+
+Useful where plain DNS is unavailable or untrusted (serverless platforms,
+locked-down networks).  Only an HTTP client is needed; dnspython is not.
+
+``require_dnssec`` checks the resolver's ``AD`` flag, which only means that the
+DoH provider validated the answer: you are trusting that provider over TLS.
+Unsigned zones (gmail.com, for example) never pass this check.
+
+If you already use ``dnspython[doh]``, an RFC 8484 resolver is also possible::
+
+    resolver = dns.resolver.Resolver(configure=False)
+    resolver.nameservers = ["https://cloudflare-dns.com/dns-query"]
+    DnsPythonResolver(resolver)
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TYPE_CHECKING, Self
+
+from pyevp.adapters._doh import (
+    CLOUDFLARE,
+    GOOGLE,
+    DnssecError,
+    DohError,
+)
+from pyevp.adapters._doh import HEADERS as _HEADERS
+from pyevp.adapters._doh import params as _params
+from pyevp.adapters._doh import records as _records
+from pyevp.adapters._http import http
+
+if TYPE_CHECKING:
+    from pyevp.adapters._http import AsyncClient, Client, Response
+
+__all__ = [
+    "CLOUDFLARE",
+    "GOOGLE",
+    "AsyncDohResolver",
+    "DnssecError",
+    "DohError",
+    "DohResolver",
+]
+
+
+def _check(response: Response, name: str) -> object:
+    if response.status_code != 200:
+        raise DohError(f"DoH lookup of {name} returned HTTP {response.status_code}")
+    try:
+        return response.json()
+    except (ValueError, RecursionError) as exc:
+        raise DohError(f"DoH lookup of {name} did not return JSON") from exc
+
+
+class DohResolver:
+    """Synchronous DoH TXT resolver (Google by default; pass ``endpoint=CLOUDFLARE`` etc.)."""
+
+    def __init__(
+        self,
+        endpoint: str = GOOGLE,
+        *,
+        client: Client | None = None,
+        require_dnssec: bool = False,
+        timeout: float = 5.0,
+    ) -> None:
+        self.endpoint = endpoint
+        self._owns_client = client is None
+        self._client: Client = client or http.Client(timeout=timeout, follow_redirects=False)
+        self._require_dnssec = require_dnssec
+
+    def resolve_txt(self, name: str) -> list[str]:
+        response = self._client.get(
+            self.endpoint, params=_params(name), headers=_HEADERS, follow_redirects=False
+        )
+        return _records(_check(response, name), name, self._require_dnssec)
+
+    def close(self) -> None:
+        """Close the client this resolver created; a client passed in stays open."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncDohResolver:
+    def __init__(
+        self,
+        endpoint: str = GOOGLE,
+        *,
+        client: AsyncClient | None = None,
+        require_dnssec: bool = False,
+        timeout: float = 5.0,
+    ) -> None:
+        self.endpoint = endpoint
+        self._owns_client = client is None
+        self._client: AsyncClient = client or http.AsyncClient(
+            timeout=timeout, follow_redirects=False
+        )
+        self._require_dnssec = require_dnssec
+
+    async def resolve_txt(self, name: str) -> list[str]:
+        response = await self._client.get(
+            self.endpoint, params=_params(name), headers=_HEADERS, follow_redirects=False
+        )
+        return _records(_check(response, name), name, self._require_dnssec)
+
+    async def aclose(self) -> None:
+        """Close the client this resolver created; a client passed in stays open."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

pyevp/adapters/httpx.py

@@ -0,0 +1,147 @@
+"""JSON fetchers backed by httpx2 or httpx (``pip install pyevp[httpx2]`` / ``pyevp[httpx]``).
+
+httpx2 is used for default clients when it is installed; a client from either
+library can be passed in explicitly.
+"""
+
+from __future__ import annotations
+
+import socket
+from types import TracebackType
+from typing import TYPE_CHECKING, Self
+
+import anyio
+
+from pyevp.adapters import _fetch
+from pyevp.adapters._fetch import HEADERS as _HEADERS
+from pyevp.adapters._fetch import (
+    MAX_DOCUMENT_BYTES,
+    AsyncResolveHost,
+    FetchError,
+    ResolveHost,
+)
+from pyevp.adapters._fetch import decode as _decode
+from pyevp.adapters._http import http
+
+if TYPE_CHECKING:
+    from pyevp.adapters._http import AsyncClient, Client, Response
+
+__all__ = ["AsyncHttpxFetcher", "FetchError", "HttpxFetcher"]
+
+
+def _check(response: Response) -> None:
+    if response.status_code != 200:
+        raise FetchError(f"GET {response.request.url} returned HTTP {response.status_code}")
+    if response.headers.get("Content-Encoding", "identity").strip().lower() != "identity":
+        raise FetchError(f"GET {response.request.url} returned a compressed response")
+
+
+async def _anyio_resolve_host(host: str) -> list[str]:
+    infos = await anyio.getaddrinfo(host, 443, type=socket.SOCK_STREAM)
+    return [str(info[4][0]) for info in infos]
+
+
+class HttpxFetcher:
+    """Synchronous fetcher.
+
+    Redirects are not followed, compressed responses are refused and bodies are size-capped.
+    Before each request the host is resolved and refused unless every address is globally
+    routable; pass ``require_global_addresses=False`` to reach an issuer on a private network
+    (local development) or when an egress proxy enforces that policy and resolves names
+    itself.  ``resolve_host`` replaces the system resolver used for that check.
+    """
+
+    def __init__(
+        self,
+        client: Client | None = None,
+        *,
+        timeout: float = 5.0,
+        require_global_addresses: bool = True,
+        resolve_host: ResolveHost = _fetch.system_resolve_host,
+    ) -> None:
+        self._owns_client = client is None
+        self._client: Client = client or http.Client(timeout=timeout, follow_redirects=False)
+        self._require_global = require_global_addresses
+        self._resolve_host = resolve_host
+
+    def fetch_json(self, url: str) -> object:
+        if self._require_global:
+            _fetch.require_global(url, self._resolve_host)
+        with self._client.stream("GET", url, headers=_HEADERS, follow_redirects=False) as response:
+            _check(response)
+            body = bytearray()
+            for chunk in response.iter_raw():
+                body += chunk
+                if len(body) > MAX_DOCUMENT_BYTES:
+                    raise FetchError(f"GET {url} response is too large")
+        return _decode(bytes(body), url)
+
+    def close(self) -> None:
+        """Close the client this fetcher created; a client passed in stays open."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncHttpxFetcher:
+    """Asynchronous counterpart of :class:`HttpxFetcher` (asyncio or trio)."""
+
+    def __init__(
+        self,
+        client: AsyncClient | None = None,
+        *,
+        timeout: float = 5.0,
+        require_global_addresses: bool = True,
+        resolve_host: AsyncResolveHost = _anyio_resolve_host,
+    ) -> None:
+        self._owns_client = client is None
+        self._client: AsyncClient = client or http.AsyncClient(
+            timeout=timeout, follow_redirects=False
+        )
+        self._require_global = require_global_addresses
+        self._resolve_host = resolve_host
+
+    async def fetch_json(self, url: str) -> object:
+        if self._require_global:
+            host = _fetch.host_of(url)
+            try:
+                addresses = list(await self._resolve_host(host))
+            except OSError as exc:
+                raise FetchError(f"GET {url}: cannot resolve {host}: {exc}") from exc
+            _fetch.check_global_addresses(url, host, addresses)
+        async with self._client.stream(
+            "GET", url, headers=_HEADERS, follow_redirects=False
+        ) as response:
+            _check(response)
+            body = bytearray()
+            async for chunk in response.aiter_raw():
+                body += chunk
+                if len(body) > MAX_DOCUMENT_BYTES:
+                    raise FetchError(f"GET {url} response is too large")
+        return _decode(bytes(body), url)
+
+    async def aclose(self) -> None:
+        """Close the client this fetcher created; a client passed in stays open."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

pyevp/adapters/urllib.py

@@ -0,0 +1,170 @@
+"""A JSON fetcher and a DoH TXT resolver using only the standard library.
+
+Nothing beyond PyEVP's core dependencies is needed, which suits applications
+that already pick their own HTTP stack and do not want httpx or dnspython::
+
+    from pyevp import Verifier
+    from pyevp.adapters.urllib import UrllibDohResolver, UrllibFetcher
+
+    verifier = Verifier(audience=..., resolver=UrllibDohResolver(), fetcher=UrllibFetcher())
+
+Both are synchronous; async applications should use the httpx adapters.
+Like those, they never follow redirects, refuse compressed responses and
+cap body sizes.  Proxies from the environment (``HTTPS_PROXY``) are honoured
+as usual for urllib; pass ``handlers`` to configure proxies or TLS differently::
+
+    UrllibFetcher(handlers=[urllib.request.HTTPSHandler(context=my_ssl_context)])
+"""
+
+from __future__ import annotations
+
+import http.client
+import urllib.error
+import urllib.request
+from collections.abc import Mapping, Sequence
+from email.message import Message
+from typing import IO
+from urllib.parse import urlencode, urlsplit, urlunsplit
+
+from pyevp.adapters import _fetch
+from pyevp.adapters._doh import CLOUDFLARE, GOOGLE, DnssecError, DohError, params, records
+from pyevp.adapters._doh import HEADERS as _DOH_HEADERS
+from pyevp.adapters._fetch import FetchError
+
+# The DoH names are re-exported because pyevp.adapters.doh needs httpx.
+__all__ = [
+    "CLOUDFLARE",
+    "GOOGLE",
+    "DnssecError",
+    "DohError",
+    "FetchError",
+    "UrllibDohResolver",
+    "UrllibFetcher",
+]
+
+
+class _NoRedirects(urllib.request.HTTPRedirectHandler):
+    """Turn every redirect into an ``HTTPError`` instead of following it."""
+
+    def redirect_request(self, *args: object, **kwargs: object) -> None:
+        return None
+
+
+def _opener(handlers: Sequence[urllib.request.BaseHandler]) -> urllib.request.OpenerDirector:
+    # Our handler replaces urllib's default redirect handler; drop any the caller passed.
+    kept = [h for h in handlers if not isinstance(h, urllib.request.HTTPRedirectHandler)]
+    return urllib.request.build_opener(*kept, _NoRedirects())
+
+
+def _get(
+    opener: urllib.request.OpenerDirector,
+    url: str,
+    headers: Mapping[str, str],
+    timeout: float,
+    error: type[Exception],
+) -> bytes:
+    """GET ``url`` and return the raw body of a 200, uncompressed response."""
+    request = urllib.request.Request(url, headers=dict(headers), method="GET")
+    try:
+        with opener.open(request, timeout=timeout) as response:
+            return _read(response, response.status, response.headers, url, error)
+    except urllib.error.HTTPError as exc:
+        exc.close()
+        raise error(f"GET {url} returned HTTP {exc.code}") from None
+    # HTTPException covers IncompleteRead from truncated chunked bodies.
+    except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
+        raise error(f"GET {url} failed: {exc}") from exc
+
+
+def _read(
+    response: IO[bytes], status: int, headers: Message, url: str, error: type[Exception]
+) -> bytes:
+    if status != 200:
+        raise error(f"GET {url} returned HTTP {status}")
+    if headers.get("Content-Encoding", "identity").strip().lower() != "identity":
+        raise error(f"GET {url} returned a compressed response")
+    declared = _content_length(headers)
+    if declared is not None and declared > _fetch.MAX_DOCUMENT_BYTES:
+        raise error(f"GET {url} response is too large")
+    body = response.read(_fetch.MAX_DOCUMENT_BYTES + 1)
+    if len(body) > _fetch.MAX_DOCUMENT_BYTES:
+        raise error(f"GET {url} response is too large")
+    # read(n) returns short when the server closes early; httpx would raise here.
+    if declared is not None and len(body) != declared:
+        raise error(f"GET {url} response is incomplete")
+    return body
+
+
+def _content_length(headers: Message) -> int | None:
+    value = headers.get("Content-Length")
+    if value is None or headers.get("Transfer-Encoding"):
+        return None
+    try:
+        length = int(value)
+    except ValueError:
+        return None
+    return length if length >= 0 else None
+
+
+def _with_query(endpoint: str, extra: Mapping[str, str]) -> str:
+    """Append ``extra`` to whatever query ``endpoint`` already has, as httpx's ``params`` do."""
+    parts = urlsplit(endpoint)
+    query = "&".join(q for q in (parts.query, urlencode(extra)) if q)
+    return urlunsplit(parts._replace(query=query))
+
+
+class UrllibFetcher:
+    """Synchronous :class:`~pyevp.JsonFetcher` built on :mod:`urllib.request`.
+
+    Like :class:`~pyevp.adapters.httpx.HttpxFetcher`, it refuses hosts that do not resolve
+    exclusively to globally routable addresses unless ``require_global_addresses=False``.
+    """
+
+    def __init__(
+        self,
+        *,
+        timeout: float = 5.0,
+        handlers: Sequence[urllib.request.BaseHandler] = (),
+        require_global_addresses: bool = True,
+        resolve_host: _fetch.ResolveHost = _fetch.system_resolve_host,
+    ) -> None:
+        self._timeout = timeout
+        self._opener = _opener(handlers)
+        self._require_global = require_global_addresses
+        self._resolve_host = resolve_host
+
+    def fetch_json(self, url: str) -> object:
+        if self._require_global:
+            _fetch.require_global(url, self._resolve_host)
+        body = _get(self._opener, url, _fetch.HEADERS, self._timeout, FetchError)
+        return _fetch.decode(body, url)
+
+
+class UrllibDohResolver:
+    """Synchronous DoH TXT resolver (Google by default; pass ``CLOUDFLARE`` etc.).
+
+    ``require_dnssec=True`` checks the provider's ``AD`` flag, so it means trusting that
+    provider over TLS; unsigned zones (gmail.com, for example) never pass it.
+    """
+
+    def __init__(
+        self,
+        endpoint: str = GOOGLE,
+        *,
+        require_dnssec: bool = False,
+        timeout: float = 5.0,
+        handlers: Sequence[urllib.request.BaseHandler] = (),
+    ) -> None:
+        self.endpoint = endpoint
+        self._require_dnssec = require_dnssec
+        self._timeout = timeout
+        self._opener = _opener(handlers)
+
+    def resolve_txt(self, name: str) -> list[str]:
+        url = _with_query(self.endpoint, params(name))
+        body = _get(self._opener, url, _DOH_HEADERS, self._timeout, DohError)
+        try:
+            document = _fetch.decode(body, url)
+        except FetchError as exc:
+            raise DohError(f"DoH lookup of {name} did not return JSON") from exc
+        return records(document, name, self._require_dnssec)

pyevp/cache.py

@@ -0,0 +1,83 @@
+"""Caching of issuer metadata and key sets."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Protocol
+
+from pyevp.ports import Clock, system_clock
+
+__all__ = ["AsyncCache", "Cache", "CacheEntry", "InMemoryCache", "NullCache"]
+
+
+@dataclass(frozen=True, slots=True)
+class CacheEntry:
+    value: object
+    stored_at: datetime
+
+
+class Cache(Protocol):
+    """Key/value store for decoded JSON documents.
+
+    Implementations may be backed by Django's cache, Redis, … ; they are called
+    from both sync and async drivers so must not block for long.
+    """
+
+    def get(self, key: str) -> CacheEntry | None: ...
+
+    def set(self, key: str, entry: CacheEntry, ttl: timedelta) -> None: ...
+
+
+class AsyncCache(Protocol):
+    """:class:`Cache` with coroutine methods, for stores that must not block the event loop.
+
+    :class:`~pyevp.AsyncVerifier` accepts either kind.
+    """
+
+    async def get(self, key: str) -> CacheEntry | None: ...
+
+    async def set(self, key: str, entry: CacheEntry, ttl: timedelta) -> None: ...
+
+
+class NullCache:
+    """A cache that stores nothing: every verification fetches metadata and keys."""
+
+    def get(self, key: str) -> CacheEntry | None:
+        return None
+
+    def set(self, key: str, entry: CacheEntry, ttl: timedelta) -> None:
+        return None
+
+
+class InMemoryCache:
+    """Process-local TTL cache (not shared between workers).
+
+    Safe to share between threads, e.g. one ``Verifier`` used by a threaded server.
+    """
+
+    def __init__(self, *, clock: Clock = system_clock, max_entries: int = 256) -> None:
+        self._clock = clock
+        self._max_entries = max_entries
+        self._data: dict[str, tuple[datetime, CacheEntry]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> CacheEntry | None:
+        now = self._clock()  # outside the lock: the clock is user code
+        with self._lock:
+            item = self._data.get(key)
+            if item is None:
+                return None
+            expires_at, entry = item
+            if now >= expires_at:
+                del self._data[key]
+                return None
+            return entry
+
+    def set(self, key: str, entry: CacheEntry, ttl: timedelta) -> None:
+        expires_at = self._clock() + ttl
+        with self._lock:
+            if len(self._data) >= self._max_entries and key not in self._data:
+                del self._data[min(self._data, key=lambda k: self._data[k][0])]
+            self._data[key] = (expires_at, entry)