PyEVP 0.1.0__py3-none-any.whl

pyevp/cli/__init__.py

@@ -0,0 +1,348 @@
+"""Command-line tools for relying parties and issuer operators.
+
+- ``pyevp discover``: check a domain's issuer as a relying party would see it.
+- ``pyevp inspect``: decode a presentation token offline (signatures not checked).
+- ``pyevp verify``: run the full verification of a token.
+- ``pyevp issuer keygen`` / ``pyevp issuer documents``: set up an issuer.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections.abc import Callable
+from dataclasses import asdict
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from joserfc import jwk
+from rich.console import Console
+from rich.table import Table
+
+from pyevp.diagnostics import IssuerReport, discover
+from pyevp.errors import EVPError
+from pyevp.issuer import SIGNING_ALGORITHMS, Issuer, SigningKey
+from pyevp.ports import JsonFetcher, TxtResolver
+from pyevp.profile import DEFAULT_PROFILE, PROFILES, Profile
+from pyevp.token import ParsedToken, compute_sd_hash, parse_token
+from pyevp.verifier import Verifier
+
+__all__ = ["app", "make_app"]
+
+FAILED = 1
+MISSING_EXTRA = 3
+
+ResolverFactory = Callable[[str | None], TxtResolver]
+"""Builds a resolver; the argument is a DoH endpoint, or ``None`` for plain DNS."""
+FetcherFactory = Callable[[], JsonFetcher]
+
+
+def _default_resolver(doh_endpoint: str | None) -> TxtResolver:
+    if doh_endpoint is not None:
+        from pyevp.adapters.doh import DohResolver  # noqa: PLC0415
+
+        return DohResolver(doh_endpoint)
+    from pyevp.adapters.dnspython import DnsPythonResolver  # noqa: PLC0415
+
+    return DnsPythonResolver()
+
+
+def _default_fetcher() -> JsonFetcher:
+    from pyevp.adapters.httpx import HttpxFetcher  # noqa: PLC0415
+
+    return HttpxFetcher()
+
+
+def _profile(name: str) -> Profile:
+    try:
+        return Profile.named(name)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from None
+
+
+def _json(data: Any) -> None:
+    typer.echo(json.dumps(data, indent=2, default=str, ensure_ascii=False))
+
+
+def _age(timestamp: Any, now: datetime) -> str:
+    if isinstance(timestamp, bool) or not isinstance(timestamp, int | float):
+        return "-"
+    try:
+        seconds = int((now - datetime.fromtimestamp(timestamp, UTC)).total_seconds())
+    except (OverflowError, OSError, ValueError):
+        return "-"
+    return f"{seconds}s ago" if seconds >= 0 else f"in {-seconds}s"
+
+
+ProfileOption = Annotated[
+    str, typer.Option("--profile", "-p", help=f"Profile preset: {', '.join(PROFILES)}.")
+]
+DohOption = Annotated[
+    bool, typer.Option("--doh", help="Resolve DNS over HTTPS instead of the system resolver.")
+]
+DohEndpointOption = Annotated[str, typer.Option("--doh-endpoint", help="DoH JSON API endpoint.")]
+JsonOption = Annotated[bool, typer.Option("--json", help="Machine-readable output.")]
+
+
+def make_app(
+    *,
+    resolver_factory: ResolverFactory = _default_resolver,
+    fetcher_factory: FetcherFactory = _default_fetcher,
+    console: Console | None = None,
+) -> typer.Typer:
+    """Build the CLI; tests inject in-memory ports through the factories."""
+    app = typer.Typer(
+        help="Email Verification Protocol tools.",
+        no_args_is_help=True,
+        add_completion=False,
+        pretty_exceptions_enable=False,
+    )
+    out = console or Console()
+
+    def ports(doh: bool, doh_endpoint: str) -> tuple[TxtResolver, JsonFetcher]:
+        try:
+            return resolver_factory(doh_endpoint if doh else None), fetcher_factory()
+        except ImportError as exc:
+            typer.echo(f'Missing dependency {exc.name!r}: pip install "pyevp[cli]"', err=True)
+            raise typer.Exit(MISSING_EXTRA) from None
+
+    @app.command("discover")
+    def discover_cmd(
+        target: Annotated[str, typer.Argument(help="Email address or domain.")],
+        profile: ProfileOption = DEFAULT_PROFILE.name,
+        doh: DohOption = False,
+        doh_endpoint: DohEndpointOption = "https://dns.google/resolve",
+        as_json: JsonOption = False,
+    ) -> None:
+        """Check a domain's issuer: DNS record, metadata and keys."""
+        resolver, fetcher = ports(doh, doh_endpoint)
+        try:
+            report = discover(target, resolver=resolver, fetcher=fetcher, profile=_profile(profile))
+        except EVPError as exc:
+            _fail(out, as_json, exc)
+        finally:
+            _close(resolver, fetcher)
+        if as_json:
+            _json(asdict(report) | {"ok": report.ok})
+        else:
+            _print_report(out, report)
+        if not report.ok:
+            raise typer.Exit(FAILED)
+
+    @app.command("inspect")
+    def inspect_cmd(
+        token: Annotated[str, typer.Argument(help="Presentation token, or - for stdin.")] = "-",
+        as_json: JsonOption = False,
+    ) -> None:
+        """Decode a token offline.  Signatures are NOT verified."""
+        raw = sys.stdin.read() if token == "-" else token
+        try:
+            parsed = parse_token(raw, allow_disclosures=True)
+        except EVPError as exc:
+            _fail(out, as_json, exc)
+        data = _inspection(parsed, datetime.now(UTC))
+        if as_json:
+            _json(data)
+        else:
+            _print_inspection(out, data)
+
+    @app.command("verify")
+    def verify_cmd(
+        token: Annotated[str, typer.Argument(help="Presentation token, or - for stdin.")],
+        audience: Annotated[str, typer.Option(help="Your origin, e.g. https://example.com.")],
+        nonce: Annotated[str, typer.Option(help="The nonce that was put on the form.")],
+        email: Annotated[str | None, typer.Option(help="Submitted address to compare.")] = None,
+        profile: ProfileOption = DEFAULT_PROFILE.name,
+        doh: DohOption = False,
+        doh_endpoint: DohEndpointOption = "https://dns.google/resolve",
+        as_json: JsonOption = False,
+    ) -> None:
+        """Fully verify a token, as a relying party would."""
+        raw = sys.stdin.read() if token == "-" else token
+        resolver, fetcher = ports(doh, doh_endpoint)
+        try:
+            verifier = Verifier(
+                audience=audience, resolver=resolver, fetcher=fetcher, profile=_profile(profile)
+            )
+            result = verifier.verify(raw.strip(), nonce=nonce, email=email)
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from None
+        except EVPError as exc:
+            _fail(out, as_json, exc)
+        finally:
+            _close(resolver, fetcher)
+        if as_json:
+            _json({"ok": True} | asdict(result))
+        else:
+            out.print(f"[green]verified[/green] {result.email} (issuer {result.issuer})")
+
+    app.add_typer(_issuer_app(), name="issuer")
+    return app
+
+
+def _issuer_app() -> typer.Typer:
+    app = typer.Typer(help="Set up an issuer for your own email domains.", no_args_is_help=True)
+
+    @app.command("keygen")
+    def keygen_cmd(
+        kid: Annotated[str, typer.Option(help="Key id, e.g. the date: 2026-10.")],
+        out_path: Annotated[
+            Path, typer.Option("--out", help="Private JWK file to create (mode 0600).")
+        ],
+        alg: Annotated[str, typer.Option(help="Ed25519 or ES256.")] = "Ed25519",
+    ) -> None:
+        """Generate a signing key.  Prints the public JWK; the private one goes to --out."""
+        if alg not in SIGNING_ALGORITHMS:
+            choices = ", ".join(sorted(SIGNING_ALGORITHMS))
+            raise typer.BadParameter(f"--alg must be one of {choices}")
+        try:
+            key = SigningKey.generate(alg, kid=kid)
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from None
+        try:
+            fd = os.open(out_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        except FileExistsError:
+            raise typer.BadParameter(f"{out_path} exists; refusing to overwrite a key") from None
+        with os.fdopen(fd, "w") as file:
+            json.dump(key.private_jwk(), file, indent=2)
+            file.write("\n")
+        _json(dict(key.public_jwk))
+
+    @app.command("documents")
+    def documents_cmd(
+        issuer: Annotated[str, typer.Option(help="Issuer identifier, https://host.")],
+        issuance_endpoint: Annotated[str, typer.Option(help="URL browsers POST requests to.")],
+        jwks_uri: Annotated[str, typer.Option(help="URL the JWKS is served at.")],
+        key: Annotated[Path, typer.Option(help="Private JWK file of the active key.")],
+        domain: Annotated[list[str], typer.Option(help="Email domain served (repeatable).")],
+        publish: Annotated[
+            list[Path] | None,
+            typer.Option(help="Extra JWK file to publish: next or retired key (repeatable)."),
+        ] = None,
+    ) -> None:
+        """Print the metadata document, JWKS and DNS records to publish, as JSON."""
+        try:
+            signer = SigningKey.from_jwk(_read_json(key))
+            extra = [_public_part(_read_json(p)) for p in publish or ()]
+            built = Issuer(
+                issuer=issuer,
+                issuance_endpoint=issuance_endpoint,
+                jwks_uri=jwks_uri,
+                signer=signer,
+                email_domains=domain,
+                published_keys=extra,
+            )
+        except (OSError, ValueError) as exc:
+            raise typer.BadParameter(str(exc)) from None
+        _json(
+            {
+                "metadata_url": f"{built.issuer}/.well-known/email-verification",
+                "metadata": built.metadata_document(),
+                "jwks_uri": built.jwks_uri,
+                "jwks": built.jwks_document(),
+                "dns_txt": built.dns_txt_records(),
+            }
+        )
+
+    return app
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    value = json.loads(path.read_text())
+    if not isinstance(value, dict):
+        raise ValueError(f"{path} does not hold a JSON object")
+    return value
+
+
+def _public_part(jwk_: dict[str, Any]) -> dict[str, Any]:
+    if "d" in jwk_:
+        return dict(SigningKey.from_jwk(jwk_).public_jwk)
+    return jwk_
+
+
+def _close(*resources: object) -> None:
+    for resource in resources:
+        close = getattr(resource, "close", None)
+        if callable(close):
+            close()
+
+
+def _fail(out: Console, as_json: bool, exc: EVPError) -> Any:
+    if as_json:
+        _json({"ok": False, "code": exc.code, "message": exc.args[0]})
+    else:
+        out.print(f"[red]{exc.code}[/red] {exc.args[0]}")
+    raise typer.Exit(FAILED)
+
+
+def _inspection(parsed: ParsedToken, now: datetime) -> dict[str, Any]:
+    cnf = parsed.evt.claims.get("cnf")
+    holder = cnf.get("jwk") if isinstance(cnf, dict) else None
+    thumbprint = None
+    if isinstance(holder, dict):
+        try:
+            thumbprint = jwk.thumbprint(holder)
+        except Exception:
+            thumbprint = None
+    return {
+        "signatures_verified": False,
+        "evt": {"header": dict(parsed.evt.header), "claims": dict(parsed.evt.claims)},
+        "disclosures": list(parsed.disclosures),
+        "kb": {"header": dict(parsed.kb.header), "claims": dict(parsed.kb.claims)},
+        "checks": {
+            "evt_issued": _age(parsed.evt.claims.get("iat"), now),
+            "kb_issued": _age(parsed.kb.claims.get("iat"), now),
+            "sd_hash_matches": parsed.kb.claims.get("sd_hash")
+            == compute_sd_hash(parsed.sd_hash_input),
+            "holder_key_thumbprint": thumbprint,
+        },
+    }
+
+
+def _table(title: str, columns: int) -> Table:
+    table = Table(title=title, show_header=False, title_justify="left")
+    for i in range(columns):
+        table.add_column(style="bold" if i < columns - 1 else None, overflow="fold")
+    return table
+
+
+def _print_report(out: Console, report: IssuerReport) -> None:
+    table = _table(f"Issuer for {report.domain}", 2)
+    table.add_row("profile", report.profile)
+    table.add_row("DNS name", report.dns_name)
+    table.add_row("TXT records", "\n".join(report.records) or "[dim](none)[/dim]")
+    table.add_row("issuer", report.issuer or "-")
+    if report.metadata is not None:
+        table.add_row("jwks_uri", report.metadata.jwks_uri)
+        algs = report.metadata.signing_alg_values_supported
+        table.add_row(
+            "algorithms", "(not advertised)" if algs is None else ", ".join(algs) or "(none)"
+        )
+    for key in report.keys:
+        table.add_row("key", f"{key.kty}/{key.crv} alg={key.alg} kid={key.kid!r}")
+    out.print(table)
+    for problem in report.problems:
+        out.print(f"[red]✗[/red] {problem}")
+    if report.ok:
+        out.print("[green]✓ usable with this profile[/green]")
+
+
+def _print_inspection(out: Console, data: dict[str, Any]) -> None:
+    out.print("[yellow]Signatures are NOT verified; use `pyevp verify` for that.[/yellow]")
+    for part in ("evt", "kb"):
+        table = _table(part.upper(), 3)
+        for section in ("header", "claims"):
+            for name, value in data[part][section].items():
+                table.add_row(section, name, json.dumps(value, ensure_ascii=False))
+        out.print(table)
+    checks = data["checks"]
+    table = _table("checks", 2)
+    for name, value in checks.items():
+        table.add_row(name, str(value))
+    out.print(table)
+
+
+app = make_app()

pyevp/contrib/__init__.py

@@ -0,0 +1,4 @@
+"""Integrations with third-party frameworks.
+
+Import the submodules explicitly; they require the matching extras.
+"""

pyevp/contrib/django/__init__.py

@@ -0,0 +1,306 @@
+"""Django integration (``pip install pyevp[django]``).
+
+Add ``"pyevp.contrib.django"`` to ``INSTALLED_APPS`` and run ``migrate``.
+
+- ``{% load pyevp %}`` and ``{% evp_token_input %}`` render the hidden token input, and
+  :func:`verify_request` / :func:`averify_request` verify what the form submitted.
+- :class:`EVPCache` / :class:`AsyncEVPCache` share issuer metadata and key
+  sets between workers through Django's cache framework.
+- :class:`EVPReplayGuard` / :class:`AsyncEVPReplayGuard` remember accepted
+  tokens in a database table.
+
+::
+
+    from pyevp import EVPError, Verifier
+    from pyevp.contrib.django import EVPCache, EVPReplayGuard, verify_request
+
+    verifier = Verifier.default(
+        audience=settings.EVP_ORIGIN, cache=EVPCache(), replay_guard=EVPReplayGuard()
+    )
+
+    # In the view that handles the form:
+    try:
+        verified = verify_request(request, verifier, email=form.cleaned_data["email"])
+    except EVPError:
+        verified = None  # fall back to a confirmation email
+
+Caches and databases are looked up on every call, so these can be created at
+import time, before Django's settings are configured.
+
+For running an issuer, see :mod:`pyevp.contrib.django.issuer`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+from asgiref.sync import sync_to_async
+from django.conf import settings
+from django.core.cache import caches
+from django.db import IntegrityError, transaction
+from django.http import HttpRequest
+
+from pyevp.cache import CacheEntry
+from pyevp.nonce import generate_nonce
+from pyevp.ports import Clock, system_clock
+from pyevp.types import VerifiedEmail
+from pyevp.verifier import AsyncVerifier, Verifier
+
+if TYPE_CHECKING:
+    from django.contrib.sessions.backends.base import SessionBase
+
+__all__ = [
+    "AsyncEVPCache",
+    "AsyncEVPReplayGuard",
+    "EVPCache",
+    "EVPReplayGuard",
+    "aget_nonce",
+    "averify_request",
+    "get_nonce",
+    "verify_request",
+]
+
+_SESSION_KEY = "evp_nonce"
+# The nonce handed out during the current request, so that every form on a page gets it.
+_REQUEST_KEY = "_pyevp_nonce"
+
+
+def get_nonce(request: HttpRequest) -> str:
+    """Return the nonce for the forms on this page, keeping it in the session.
+
+    The session holds one nonce, so all forms rendered in a request share it: the
+    first call creates it and later calls return the same value.  Opening the
+    page in another tab replaces it, and the older tab's forms then fall back to
+    your usual flow.  ``{% evp_token_input %}`` calls this for you.
+
+    It replaces the nonce in the session, so in a view that handles a submission,
+    call :func:`verify_request` before rendering a form again.
+
+    Every call writes the session, so render the token input only on pages that
+    have a form: anywhere else it gives each visitor a session for nothing.
+    """
+    nonce = request.__dict__.get(_REQUEST_KEY)
+    if nonce is None:
+        nonce = generate_nonce()
+        _session(request)[_SESSION_KEY] = nonce
+        request.__dict__[_REQUEST_KEY] = nonce
+    return nonce
+
+
+async def aget_nonce(request: HttpRequest) -> str:
+    """:func:`get_nonce` for async views.
+
+    Django refuses session access from async code, including from a template
+    tag.  Call this before rendering; ``{% evp_token_input %}`` then reuses the
+    nonce without touching the session.
+    """
+    return await sync_to_async(get_nonce, thread_sensitive=True)(request)
+
+
+def verify_request(
+    request: HttpRequest,
+    verifier: Verifier,
+    *,
+    email: str | None,
+    field: str = "evt",
+    audience: str | None = None,
+) -> VerifiedEmail | None:
+    """Verify the token that a form submitted, if it carried one.
+
+    Returns ``None`` when the ``field`` is empty: the browser does not support
+    EVP, or the email provider does not issue tokens.  The nonce then stays in
+    the session, so a form that is not rendered again (one sent with ``fetch()``)
+    can still be verified on the next submission.
+
+    Otherwise the nonce is consumed and the token checked with
+    :meth:`pyevp.Verifier.verify`, which raises :class:`~pyevp.EVPError` on
+    failure.  If the session has no nonce, for example because it expired, that
+    is ``nonce_mismatch``.
+
+    :param email: the address the user submitted, as for :meth:`~pyevp.Verifier.verify`.
+    :param field: the name of the hidden input (``{% evp_token_input field=... %}``).
+    """
+    taken = _take_nonce(request, field)
+    if taken is None:
+        return None
+    token, nonce = taken
+    return verifier.verify(token, nonce=nonce, email=email, audience=audience)
+
+
+async def averify_request(
+    request: HttpRequest,
+    verifier: AsyncVerifier,
+    *,
+    email: str | None,
+    field: str = "evt",
+    audience: str | None = None,
+) -> VerifiedEmail | None:
+    """:func:`verify_request` for async views and :class:`~pyevp.AsyncVerifier`."""
+    taken = await sync_to_async(_take_nonce, thread_sensitive=True)(request, field)
+    if taken is None:
+        return None
+    token, nonce = taken
+    return await verifier.verify(token, nonce=nonce, email=email, audience=audience)
+
+
+def _take_nonce(request: HttpRequest, field: str) -> tuple[str, str] | None:
+    token = request.POST.get(field, "")
+    if not token:
+        return None
+    # The nonce is consumed: a form rendered later in this request needs a new one.
+    request.__dict__.pop(_REQUEST_KEY, None)
+    # Without a nonce in the session, a throwaway one makes the verifier fail with
+    # nonce_mismatch, so observers see it like any other rejection.
+    nonce = _session(request).pop(_SESSION_KEY, None) or generate_nonce()
+    return token, nonce
+
+
+def _session(request: HttpRequest) -> SessionBase:
+    # Added by SessionMiddleware, which Django's types do not model.
+    return request.session  # ty: ignore[unresolved-attribute]
+
+
+def _digest(key: str) -> str:
+    # Fixed length, so long URLs stay within Memcached's 250-byte key limit.
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+# Part of every cache key.  Bump it when the stored value changes shape, so that workers
+# running different versions during a deploy ignore each other's entries.
+_CACHE_FORMAT = "1:"
+
+
+def _dump(entry: CacheEntry) -> tuple[object, datetime]:
+    # Built-in types only: a pickled CacheEntry would break if the class ever moved.
+    return (entry.value, entry.stored_at)
+
+
+def _load(stored: object) -> CacheEntry | None:
+    if isinstance(stored, tuple) and len(stored) == 2 and isinstance(stored[1], datetime):
+        return CacheEntry(stored[0], stored[1])
+    return None
+
+
+class _CacheBase:
+    def __init__(self, alias: str = "default", *, prefix: str = "evp:") -> None:
+        self.alias = alias
+        self.prefix = prefix
+
+    def _key(self, key: str) -> str:
+        return self.prefix + _CACHE_FORMAT + _digest(key)
+
+
+class EVPCache(_CacheBase):
+    """A :class:`~pyevp.Cache` backed by one of Django's ``CACHES``.
+
+    Use a backend shared between workers (Redis, Memcached, database) for the
+    cache to help; ``locmem`` is per process like :class:`~pyevp.InMemoryCache`.
+    An evicted entry is simply fetched again.  With :class:`~pyevp.AsyncVerifier`,
+    use :class:`AsyncEVPCache`, which does not block the event loop.
+    """
+
+    def get(self, key: str) -> CacheEntry | None:
+        return _load(caches[self.alias].get(self._key(key)))
+
+    def set(self, key: str, entry: CacheEntry, ttl: timedelta) -> None:
+        caches[self.alias].set(self._key(key), _dump(entry), timeout=ttl.total_seconds())
+
+
+class AsyncEVPCache(_CacheBase):
+    """An :class:`~pyevp.AsyncCache` using Django's async cache API (``aget`` / ``aset``).
+
+    Takes the same arguments as :class:`EVPCache` and shares its entries.
+    """
+
+    async def get(self, key: str) -> CacheEntry | None:
+        return _load(await caches[self.alias].aget(self._key(key)))
+
+    async def set(self, key: str, entry: CacheEntry, ttl: timedelta) -> None:
+        await caches[self.alias].aset(self._key(key), _dump(entry), timeout=ttl.total_seconds())
+
+
+class _GuardBase:
+    def __init__(self, using: str = "default", *, clock: Clock = system_clock) -> None:
+        self.using = using
+        self._clock = clock
+
+    def _mark(self, key: str, expires_at: datetime) -> bool:
+        from pyevp.contrib.django.models import UsedToken  # noqa: PLC0415
+
+        connection = transaction.get_connection(self.using)
+        # Outside an atomic block but with autocommit off, Django would treat the caller's
+        # manual transaction as the outer block: nothing commits and a rollback forgets the
+        # token.  (Inside an atomic block autocommit is off too; durable=True handles that.)
+        if not connection.in_atomic_block and not connection.get_autocommit():
+            raise RuntimeError(_MANUAL.format(using=self.using))
+        rows = UsedToken.objects.using(self.using)
+        try:
+            # Durable: the record is committed here, not with (or rolled back with) the
+            # caller's transaction.  Nested in one, Django raises instead.
+            with transaction.atomic(using=self.using, durable=True):
+                rows.filter(expires_at__lte=_db_time(self._clock())).delete()
+                rows.create(key=_digest(key), expires_at=_db_time(expires_at))
+        except IntegrityError:
+            return False
+        except RuntimeError as exc:
+            if connection.in_atomic_block:
+                raise RuntimeError(_NESTED.format(using=self.using)) from exc
+            raise
+        return True
+
+
+_NESTED = (
+    "EVPReplayGuard must commit its record on its own, but database {using!r} is inside "
+    "an atomic block (ATOMIC_REQUESTS or transaction.atomic()); a rollback there would "
+    "forget the token.  Give the guard its own alias for the same database with "
+    "ATOMIC_REQUESTS off, e.g. EVPReplayGuard(using='evp'), or verify outside the "
+    "transaction."
+)
+
+
+_MANUAL = (
+    "EVPReplayGuard must commit its record on its own, but autocommit is off on "
+    "database {using!r} (AUTOCOMMIT=False or transaction.set_autocommit(False)); a "
+    "rollback there would forget the token.  Give the guard its own alias for the same "
+    "database with AUTOCOMMIT on, e.g. EVPReplayGuard(using='evp')."
+)
+
+
+class EVPReplayGuard(_GuardBase):
+    """A :class:`~pyevp.ReplayGuard` storing accepted tokens in the database.
+
+    Each token is a row keyed by its digest until the token expires; a second
+    insert of the same key fails on the primary key, so concurrent workers
+    cannot both accept a token.  Unlike a cache, the table never evicts rows
+    early, and database errors propagate, so verification fails closed.
+    Expired rows are deleted as new tokens are recorded.
+
+    Each record is committed immediately in its own transaction, so a later
+    rollback of the request cannot undo it.  Called inside a transaction on
+    the same database (``ATOMIC_REQUESTS``, ``transaction.atomic()``, or with
+    autocommit off) it raises ``RuntimeError`` instead; point ``using`` at a
+    second alias for the same database with ``ATOMIC_REQUESTS`` off and
+    autocommit on.  Django's ``TestCase`` transactions are exempt.
+
+    Requires ``"pyevp.contrib.django"`` in ``INSTALLED_APPS`` and ``migrate``.
+    """
+
+    def mark_used(self, key: str, expires_at: datetime) -> bool:
+        return self._mark(key, expires_at)
+
+
+class AsyncEVPReplayGuard(_GuardBase):
+    """:class:`EVPReplayGuard` for :class:`~pyevp.AsyncVerifier`.
+
+    The database work runs in Django's thread for synchronous code.
+    """
+
+    async def mark_used(self, key: str, expires_at: datetime) -> bool:
+        return await sync_to_async(self._mark, thread_sensitive=True)(key, expires_at)
+
+
+def _db_time(value: datetime) -> datetime:
+    # Without USE_TZ, Django stores naive datetimes (and SQLite / MySQL reject aware ones).
+    return value if settings.USE_TZ else value.astimezone(UTC).replace(tzinfo=None)

pyevp/contrib/django/apps.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+from django.core import checks
+
+
+class PyevpConfig(AppConfig):
+    name = "pyevp.contrib.django"
+    label = "pyevp"
+    verbose_name = "Email Verification Protocol"
+
+    def ready(self) -> None:
+        from pyevp.contrib.django.issuer import check_session_cookie  # noqa: PLC0415
+
+        # Like Django's own cookie checks, only for `check --deploy`: development servers
+        # usually run without HTTPS.
+        checks.register(check_session_cookie, checks.Tags.security, deploy=True)