PyEVP 0.1.0__py3-none-any.whl

pyevp/verifier.py

@@ -0,0 +1,486 @@
+"""Drivers that run :func:`pyevp.core.verification_steps` against real ports."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import AsyncExitStack, ExitStack, contextmanager
+from datetime import datetime, timedelta
+from types import TracebackType
+from typing import Self
+from urllib.parse import urlsplit
+
+from pyevp.cache import AsyncCache, Cache, CacheEntry, InMemoryCache
+from pyevp.core import Effect, FetchJson, MarkUsed, ResolveTxt, Steps, verification_steps
+from pyevp.errors import DiscoveryError, ErrorCode, EVPError, TokenError
+from pyevp.observability import Observer, VerificationEvent, claimed_email_domain
+from pyevp.ports import (
+    AsyncJsonFetcher,
+    AsyncTxtResolver,
+    Clock,
+    JsonFetcher,
+    TxtResolver,
+    system_clock,
+)
+from pyevp.profile import DEFAULT_PROFILE, Profile
+from pyevp.replay import AsyncReplayGuard, ReplayGuard
+from pyevp.types import VerifiedEmail
+
+__all__ = ["AsyncVerifier", "Verifier"]
+
+logger = logging.getLogger("pyevp")
+
+
+def _validate_origin(origin: str) -> str:
+    parts = urlsplit(origin)
+    if (
+        parts.scheme not in ("https", "http")
+        or not parts.hostname
+        or parts.path
+        or parts.query
+        or parts.fragment
+        or parts.username
+    ):
+        raise ValueError(
+            f"audience must be a serialized origin like 'https://rp.example': {origin!r}"
+        )
+    return origin
+
+
+class _Base:
+    def __init__(
+        self,
+        *,
+        audience: str,
+        profile: Profile,
+        clock: Clock,
+        cache_ttl: timedelta,
+        min_refresh_interval: timedelta,
+        replay_protection: bool,
+        observer: Observer | None,
+    ) -> None:
+        self.audience = _validate_origin(audience)
+        self._replay_protection = replay_protection
+        self._observer = observer
+        self.profile = profile
+        self._clock = clock
+        self._cache_ttl = cache_ttl
+        self._min_refresh_interval = min_refresh_interval
+        self._refresh_lock = threading.Lock()
+        self._refresh_attempts: dict[str, datetime] = {}
+        # Ports created by default(); ports passed in belong to the caller.
+        self._owned: tuple[object, ...] = ()
+
+    def _steps(self, token: str, nonce: str, email: str | None, audience: str | None) -> Steps:
+        return verification_steps(
+            token,
+            audience=_validate_origin(audience) if audience is not None else self.audience,
+            nonce=nonce,
+            now=self._clock(),
+            profile=self.profile,
+            email=email,
+            replay_protection=self._replay_protection,
+        )
+
+    def _notify(
+        self, token: str, result: VerifiedEmail | None, error: Exception | None, started: float
+    ) -> None:
+        if self._observer is None:
+            return
+        try:
+            self._observer(
+                VerificationEvent(
+                    ok=result is not None,
+                    code=error.code if isinstance(error, EVPError) else None,
+                    issuer=result.issuer if result is not None else None,
+                    email_domain=claimed_email_domain(token),
+                    profile=self.profile.name,
+                    duration=timedelta(seconds=time.perf_counter() - started),
+                )
+            )
+        except Exception:
+            logger.exception("EVP observer raised; ignoring")
+
+    def _reuse(self, effect: FetchJson, entry: CacheEntry | None) -> CacheEntry | None:
+        """Decide whether the cached ``entry`` for ``effect.url`` answers the fetch."""
+        if entry is None or not effect.refresh:
+            return entry
+        # A forced refresh is reserved before fetching, so failed fetches and concurrent
+        # verifications count against min_refresh_interval too.  Within it, keep the cached
+        # value.
+        now = self._clock()
+        with self._refresh_lock:
+            last = max(entry.stored_at, self._refresh_attempts.get(effect.url, entry.stored_at))
+            if now - last < self._min_refresh_interval:
+                return entry
+            self._refresh_attempts = {
+                url: at
+                for url, at in self._refresh_attempts.items()
+                if now - at < self._min_refresh_interval
+            }
+            self._refresh_attempts[effect.url] = now
+        return None
+
+    def _check_marked(self, effect: MarkUsed, marked: bool) -> bool:
+        # Freshness was judged when verification started.  If the token expired since,
+        # the record just written may already be gone, and a replay would find nothing.
+        if marked and self._clock() >= effect.expires_at:
+            raise TokenError(ErrorCode.TOKEN_EXPIRED, "token expired during verification")
+        return marked
+
+    def _entry(self, value: object) -> CacheEntry:
+        return CacheEntry(value, self._clock())
+
+
+@contextmanager
+def _issuer_io(effect: ResolveTxt | FetchJson) -> Iterator[None]:
+    """Report a failed DNS or HTTP request to the issuer as ``ISSUER_UNREACHABLE``."""
+    try:
+        yield
+    except EVPError:
+        raise
+    except Exception as exc:
+        raise _unreachable(effect, exc) from exc
+
+
+def _unreachable(effect: ResolveTxt | FetchJson, exc: Exception) -> DiscoveryError:
+    target = effect.name if isinstance(effect, ResolveTxt) else effect.url
+    err = DiscoveryError(ErrorCode.ISSUER_UNREACHABLE, f"lookup of {target} failed: {exc}")
+    err.__cause__ = exc
+    return err
+
+
+def _missing_extras(cls: type, what: str) -> ImportError:
+    return ImportError(
+        f"{cls.__name__}.default() needs {what}: pip install 'pyevp[dns,httpx2]', or pass "
+        "resolver= and fetcher= yourself (pyevp.adapters.urllib needs no extra dependencies)"
+    )
+
+
+class Verifier(_Base):
+    """Synchronous verifier (Django, Flask, scripts).
+
+    Thread-safe as long as the injected ports and cache are.  A context manager:
+    leaving it calls :meth:`close`.
+    """
+
+    def __init__(
+        self,
+        *,
+        audience: str,
+        resolver: TxtResolver,
+        fetcher: JsonFetcher,
+        profile: Profile = DEFAULT_PROFILE,
+        cache: Cache | None = None,
+        clock: Clock = system_clock,
+        cache_ttl: timedelta = timedelta(minutes=10),
+        min_refresh_interval: timedelta = timedelta(minutes=1),
+        replay_guard: ReplayGuard | None = None,
+        observer: Observer | None = None,
+    ) -> None:
+        super().__init__(
+            audience=audience,
+            profile=profile,
+            clock=clock,
+            cache_ttl=cache_ttl,
+            min_refresh_interval=min_refresh_interval,
+            replay_protection=replay_guard is not None,
+            observer=observer,
+        )
+        self._resolver = resolver
+        self._fetcher = fetcher
+        self._replay_guard = replay_guard
+        self._cache = cache if cache is not None else InMemoryCache(clock=clock)
+
+    @classmethod
+    def default(
+        cls,
+        *,
+        audience: str,
+        resolver: TxtResolver | None = None,
+        fetcher: JsonFetcher | None = None,
+        profile: Profile = DEFAULT_PROFILE,
+        cache: Cache | None = None,
+        clock: Clock = system_clock,
+        cache_ttl: timedelta = timedelta(minutes=10),
+        min_refresh_interval: timedelta = timedelta(minutes=1),
+        replay_guard: ReplayGuard | None = None,
+        observer: Observer | None = None,
+    ) -> Self:
+        """Build a verifier using dnspython and httpx2 or httpx (``pyevp[dns,httpx2]``).
+
+        ``resolver`` and ``fetcher`` default to those adapters, which :meth:`close` closes;
+        the other arguments are the constructor's.
+        """
+        owned: list[object] = []
+        if resolver is None:
+            try:
+                from pyevp.adapters.dnspython import DnsPythonResolver  # noqa: PLC0415
+            except ImportError as exc:
+                raise _missing_extras(cls, "dnspython") from exc
+            resolver = DnsPythonResolver()
+            owned.append(resolver)
+        if fetcher is None:
+            try:
+                from pyevp.adapters.httpx import HttpxFetcher  # noqa: PLC0415
+            except ImportError as exc:
+                raise _missing_extras(cls, "httpx2 or httpx") from exc
+            fetcher = HttpxFetcher()
+            owned.append(fetcher)
+        verifier = cls(
+            audience=audience,
+            resolver=resolver,
+            fetcher=fetcher,
+            profile=profile,
+            cache=cache,
+            clock=clock,
+            cache_ttl=cache_ttl,
+            min_refresh_interval=min_refresh_interval,
+            replay_guard=replay_guard,
+            observer=observer,
+        )
+        verifier._owned = tuple(owned)
+        return verifier
+
+    def close(self) -> None:
+        """Close the resolver and fetcher that :meth:`default` created.
+
+        Ports passed in belong to the caller, who closes them.  Safe to call twice.
+        """
+        owned, self._owned = self._owned, ()
+        with ExitStack() as stack:
+            for port in owned:
+                if callable(close := getattr(port, "close", None)):
+                    stack.callback(close)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def verify(
+        self, token: str, *, nonce: str, email: str | None, audience: str | None = None
+    ) -> VerifiedEmail:
+        """Verify a presentation token.
+
+        :param nonce: the nonce this server put on the form (from the session).
+        :param email: the address the user submitted; checked against the token.  Pass
+            ``None`` explicitly to skip the check and use the asserted address instead.
+        :param audience: override the configured origin (multi-host deployments).
+        :raises pyevp.TokenError: the token is malformed, stale, mis-bound or badly signed.
+        :raises pyevp.PolicyError: the token does not satisfy the profile, e.g. it asserts
+            another address.  Raised before the issuer's signature is checked, so it says
+            nothing about authenticity.
+        :raises pyevp.DiscoveryError: the issuer could not be used.  ``ISSUER_UNREACHABLE``
+            means its DNS or HTTPS failed and may be transient; other codes mean its
+            records, metadata or keys are unusable.
+        :raises Exception: anything raised by the cache or the replay guard, unchanged:
+            a failure of your own infrastructure, not a verdict on the token.
+
+        Any :class:`~pyevp.EVPError` means "do not trust this token".
+        """
+        started, result, error = time.perf_counter(), None, None
+        try:
+            result = self._run(self._steps(token, nonce, email, audience))
+            return result
+        except Exception as exc:
+            error = exc
+            raise
+        finally:
+            self._notify(token, result, error, started)
+
+    def _run(self, steps: Steps) -> VerifiedEmail:
+        try:
+            effect = next(steps)
+            while True:
+                effect = steps.send(self._perform(effect))
+        except StopIteration as stop:
+            return stop.value
+        finally:
+            steps.close()
+
+    def _perform(self, effect: Effect) -> object:
+        # Failures of the application's own replay store and cache propagate unchanged.
+        match effect:
+            case MarkUsed():
+                assert self._replay_guard is not None
+                return self._check_marked(
+                    effect, self._replay_guard.mark_used(effect.key, effect.expires_at)
+                )
+            case ResolveTxt(name=name):
+                with _issuer_io(effect):
+                    return self._resolver.resolve_txt(name)
+            case FetchJson(url=url):
+                if (entry := self._reuse(effect, self._cache.get(url))) is not None:
+                    return entry.value
+                with _issuer_io(effect):
+                    value = self._fetcher.fetch_json(url)
+                self._cache.set(url, self._entry(value), self._cache_ttl)
+                return value
+
+
+class AsyncVerifier(_Base):
+    """Asynchronous verifier (FastAPI, Starlette, Django async views).
+
+    An async context manager: leaving it calls :meth:`aclose`.
+    """
+
+    def __init__(
+        self,
+        *,
+        audience: str,
+        resolver: AsyncTxtResolver,
+        fetcher: AsyncJsonFetcher,
+        profile: Profile = DEFAULT_PROFILE,
+        cache: Cache | AsyncCache | None = None,
+        clock: Clock = system_clock,
+        cache_ttl: timedelta = timedelta(minutes=10),
+        min_refresh_interval: timedelta = timedelta(minutes=1),
+        replay_guard: ReplayGuard | AsyncReplayGuard | None = None,
+        observer: Observer | None = None,
+    ) -> None:
+        super().__init__(
+            audience=audience,
+            profile=profile,
+            clock=clock,
+            cache_ttl=cache_ttl,
+            min_refresh_interval=min_refresh_interval,
+            replay_protection=replay_guard is not None,
+            observer=observer,
+        )
+        self._resolver = resolver
+        self._fetcher = fetcher
+        self._replay_guard = replay_guard
+        self._cache = cache if cache is not None else InMemoryCache(clock=clock)
+
+    @classmethod
+    def default(
+        cls,
+        *,
+        audience: str,
+        resolver: AsyncTxtResolver | None = None,
+        fetcher: AsyncJsonFetcher | None = None,
+        profile: Profile = DEFAULT_PROFILE,
+        cache: Cache | AsyncCache | None = None,
+        clock: Clock = system_clock,
+        cache_ttl: timedelta = timedelta(minutes=10),
+        min_refresh_interval: timedelta = timedelta(minutes=1),
+        replay_guard: ReplayGuard | AsyncReplayGuard | None = None,
+        observer: Observer | None = None,
+    ) -> Self:
+        """Build a verifier using dnspython and httpx2 or httpx (``pyevp[dns,httpx2]``).
+
+        ``resolver`` and ``fetcher`` default to those adapters, which :meth:`aclose` closes;
+        the other arguments are the constructor's.
+        """
+        owned: list[object] = []
+        if resolver is None:
+            try:
+                from pyevp.adapters.dnspython import AsyncDnsPythonResolver  # noqa: PLC0415
+            except ImportError as exc:
+                raise _missing_extras(cls, "dnspython") from exc
+            resolver = AsyncDnsPythonResolver()
+            owned.append(resolver)
+        if fetcher is None:
+            try:
+                from pyevp.adapters.httpx import AsyncHttpxFetcher  # noqa: PLC0415
+            except ImportError as exc:
+                raise _missing_extras(cls, "httpx2 or httpx") from exc
+            fetcher = AsyncHttpxFetcher()
+            owned.append(fetcher)
+        verifier = cls(
+            audience=audience,
+            resolver=resolver,
+            fetcher=fetcher,
+            profile=profile,
+            cache=cache,
+            clock=clock,
+            cache_ttl=cache_ttl,
+            min_refresh_interval=min_refresh_interval,
+            replay_guard=replay_guard,
+            observer=observer,
+        )
+        verifier._owned = tuple(owned)
+        return verifier
+
+    async def aclose(self) -> None:
+        """Close the resolver and fetcher that :meth:`default` created.
+
+        Ports passed in belong to the caller, who closes them.  Safe to call twice.
+        """
+        owned, self._owned = self._owned, ()
+        async with AsyncExitStack() as stack:
+            for port in owned:
+                if callable(aclose := getattr(port, "aclose", None)):
+                    stack.push_async_callback(aclose)
+                elif callable(close := getattr(port, "close", None)):
+                    stack.callback(close)
+
+    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()
+
+    async def verify(
+        self, token: str, *, nonce: str, email: str | None, audience: str | None = None
+    ) -> VerifiedEmail:
+        """Async counterpart of :meth:`Verifier.verify`."""
+        started, result, error = time.perf_counter(), None, None
+        try:
+            result = await self._run(self._steps(token, nonce, email, audience))
+            return result
+        except Exception as exc:
+            error = exc
+            raise
+        finally:
+            self._notify(token, result, error, started)
+
+    async def _run(self, steps: Steps) -> VerifiedEmail:
+        try:
+            effect = next(steps)
+            while True:
+                effect = steps.send(await self._perform(effect))
+        except StopIteration as stop:
+            return stop.value
+        finally:
+            steps.close()
+
+    async def _perform(self, effect: Effect) -> object:
+        # Failures of the application's own replay store and cache propagate unchanged.
+        match effect:
+            case MarkUsed():
+                assert self._replay_guard is not None
+                marked = self._replay_guard.mark_used(effect.key, effect.expires_at)
+                return self._check_marked(
+                    effect, await marked if inspect.isawaitable(marked) else marked
+                )
+            case ResolveTxt(name=name):
+                with _issuer_io(effect):
+                    return await self._resolver.resolve_txt(name)
+            case FetchJson(url=url):
+                cached = self._cache.get(url)
+                if inspect.isawaitable(cached):
+                    cached = await cached
+                if (entry := self._reuse(effect, cached)) is not None:
+                    return entry.value
+                with _issuer_io(effect):
+                    value = await self._fetcher.fetch_json(url)
+                stored = self._cache.set(url, self._entry(value), self._cache_ttl)
+                if inspect.isawaitable(stored):
+                    await stored
+                return value

pyevp-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: PyEVP
+Version: 0.1.0
+Summary: Python library for the Email Verification Protocol (EVP): verify tokens as a relying party, or issue them for your own email domains
+Keywords: email,verification,evp,sd-jwt,jose,authentication
+Author: Gakuto Furuya
+Author-email: Gakuto Furuya <g.furuya@gaato.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Dist: idna>=3.7
+Requires-Dist: joserfc>=1.7
+Requires-Dist: pyevp[dns,httpx2,django,cli] ; extra == 'all'
+Requires-Dist: pyevp[dns,httpx2] ; extra == 'cli'
+Requires-Dist: typer>=0.27 ; extra == 'cli'
+Requires-Dist: django>=4.2 ; extra == 'django'
+Requires-Dist: dnspython>=2.7 ; extra == 'dns'
+Requires-Dist: anyio>=4.5 ; extra == 'httpx'
+Requires-Dist: httpx>=0.28 ; extra == 'httpx'
+Requires-Dist: anyio>=4.5 ; extra == 'httpx2'
+Requires-Dist: httpx2>=2.13 ; extra == 'httpx2'
+Requires-Python: >=3.11
+Project-URL: Documentation, https://docs.pyevp.dev/
+Project-URL: Repository, https://github.com/gaato/pyevp
+Project-URL: Changelog, https://github.com/gaato/pyevp/blob/main/CHANGELOG.md
+Provides-Extra: all
+Provides-Extra: cli
+Provides-Extra: django
+Provides-Extra: dns
+Provides-Extra: httpx
+Provides-Extra: httpx2
+Description-Content-Type: text/markdown
+
+# PyEVP
+
+[![Documentation](https://app.readthedocs.org/projects/pyevp/badge/?version=latest)](https://docs.pyevp.dev/en/latest/)
+[![CI](https://github.com/gaato/pyevp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gaato/pyevp/actions/workflows/ci.yml)
+[![Spec drift](https://github.com/gaato/pyevp/actions/workflows/drift.yml/badge.svg)](https://github.com/gaato/pyevp/actions/workflows/drift.yml)
+[![spec: draft-hardt-02](https://img.shields.io/badge/spec-draft--hardt--02-blue)](https://github.com/dickhardt/email-verification)
+![status: alpha](https://img.shields.io/badge/status-alpha-orange)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/gaato/pyevp/blob/main/LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gaato/pyevp)
+
+[日本語](https://github.com/gaato/pyevp/blob/main/README.ja.md)
+
+Python library for the **Email Verification Protocol** (EVP): verify tokens as a relying party,
+or issue them for your own email domains. With EVP, the browser obtains a token from the user's
+email provider proving they control an address, and your server verifies it, with no confirmation
+email round-trip.
+
+**Documentation: <https://docs.pyevp.dev/>**
+
+> **Status: alpha.** The protocol ([draft-hardt-email-verification], [WICG Email Verification API])
+> and browser support (Chrome origin trial) are still changing. This library isolates every
+> moving part in a versioned `Profile` so it can follow along.
+
+[draft-hardt-email-verification]: https://github.com/dickhardt/email-verification
+[WICG Email Verification API]: https://github.com/WICG/email-verification
+
+## Install
+
+```sh
+pip install "pyevp[dns,httpx2]"   # core + the DNS and HTTP adapters
+```
+
+The core depends only on [joserfc] and idna. DNS and HTTP are pluggable; `[dns,httpx2]` installs
+the default adapters used by `Verifier.default()`. `[all]` installs every optional dependency,
+including the Django integration and the command line.
+
+The HTTP adapters work with [httpx2] (pydantic's maintained fork of httpx) or httpx and prefer
+httpx2 when both are installed, so `pip install "pyevp[dns,httpx]"` works too. A client from either
+library can be passed explicitly, e.g. `HttpxFetcher(httpx.Client(...))`.
+
+[httpx2]: https://github.com/pydantic/httpx2
+
+[joserfc]: https://jose.authlib.org/
+
+## How it works
+
+1. Render a form with a fresh nonce stored in the user's session:
+
+   ```html
+   <input type="email" name="email" autocomplete="email">
+   <input type="hidden" name="evt" autocomplete="email-verification-token" nonce="{{ nonce }}">
+   ```
+
+2. When the user picks an address, the browser fills `evt` with `<EVT>~<KB-JWT>`.
+3. On submit, verify it:
+
+   ```python
+   from pyevp import Verifier, EVPError, generate_nonce
+
+   verifier = Verifier.default(audience="https://example.com")  # your origin
+
+   try:
+       result = verifier.verify(form["evt"], nonce=session.pop("evp_nonce"), email=form["email"])
+   except EVPError as exc:
+       ...  # exc.code is an ErrorCode, e.g. "nonce_mismatch"; fall back to email confirmation
+   else:
+       result.email, result.issuer  # verified
+   ```
+
+   `AsyncVerifier` has the same API with `await verifier.verify(...)`.
+
+Verification checks the key-binding JWT (audience, nonce, freshness, `sd_hash`, holder signature)
+before doing any I/O. It then discovers the issuer from DNS (`_email-verification.<domain>`
+TXT `iss=…`), fetches its metadata and JWKS (cached), and verifies the issuer's signature. Only
+hosts derived from DNS are ever contacted, never hosts named in the token. Before connecting, the
+default fetchers also check that the host resolves only to public addresses; see
+[private networks](https://docs.pyevp.dev/en/latest/guides/transport.html#ssrf) for what this check
+does not catch.
+
+Every rejected token raises an `EVPError` with an `ErrorCode`. The safe default is to fall back to your existing
+verification flow; the [error table](https://docs.pyevp.dev/en/latest/quickstart.html#handle-failures) tells which codes
+the user can retry and which point at your configuration.
+
+## Command line
+
+`pyevp[cli]` installs a `pyevp` command for relying-party developers and operators, and for
+issuer operators checking their own setup. It runs without installing anything into your project:
+
+```sh
+uvx --from "pyevp[cli]" pyevp discover gmail.com           # DNS record, metadata, keys vs. profile
+pbpaste | uvx --from "pyevp[cli]" pyevp inspect            # decode a token offline (no signature checks)
+uvx --from "pyevp[cli]" pyevp verify "$TOKEN" --audience https://example.com --nonce "$NONCE"
+```
+
+See the [CLI guide](https://docs.pyevp.dev/en/latest/guides/cli.html) for every command and option.
+
+## More
+
+- [Frameworks](https://docs.pyevp.dev/en/latest/guides/frameworks.html): FastAPI, Flask, fastapi-users, AuthX and Django
+- [Testing your application](https://docs.pyevp.dev/en/latest/guides/testing.html): `FakeIssuer` and `FakeBrowser`, no network needed
+- [Replay protection](https://docs.pyevp.dev/en/latest/guides/replay.html), [logging and metrics](https://docs.pyevp.dev/en/latest/guides/observability.html)
+- [DNS, HTTP and caching](https://docs.pyevp.dev/en/latest/guides/transport.html): DNS over HTTPS, a standard-library-only setup, private networks
+- [Profiles](https://docs.pyevp.dev/en/latest/concepts.html#profiles): how PyEVP follows a protocol that is still changing
+- [Running an issuer](https://docs.pyevp.dev/en/latest/guides/issuer-operations.html) for your own mail domains
+- [Compatibility policy](https://docs.pyevp.dev/en/latest/compatibility.html)
+
+## Examples
+
+Each example is a standalone project with its own tests:
+
+- [`examples/fastapi`](https://github.com/gaato/pyevp/blob/main/examples/fastapi/app.py): FastAPI with session nonces
+- [`examples/flask`](https://github.com/gaato/pyevp/blob/main/examples/flask/app.py): the same flow with the synchronous `Verifier`
+- [`examples/fastapi_spa`](https://github.com/gaato/pyevp/blob/main/examples/fastapi_spa/app.py): a JSON API for a single-page app, without server sessions, with password recovery
+- [`examples/fastapi_users`](https://github.com/gaato/pyevp/blob/main/examples/fastapi_users/app.py): fastapi-users registration that falls back to the usual verification email
+- [`examples/authx`](https://github.com/gaato/pyevp/blob/main/examples/authx/app.py): passwordless login with AuthX
+- [`examples/django`](https://github.com/gaato/pyevp/blob/main/examples/django/views.py): plain Django with the template tag and `verify_request`
+- [`examples/django_allauth`](https://github.com/gaato/pyevp/blob/main/examples/django_allauth/evp_allauth.py): a django-allauth adapter
+- [`examples/issuer_fastapi`](https://github.com/gaato/pyevp/blob/main/examples/issuer_fastapi/app.py): an issuer for your own domains
+- [`examples/issuer_django`](https://github.com/gaato/pyevp/blob/main/examples/issuer_django/urls.py): the same issuer on Django, with Django's own users
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/gaato/pyevp/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/gaato/pyevp/blob/main/LICENSE)