PyEVP

日本語

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.

Install

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(...)).

How it works

1. Render a form with a fresh nonce stored in the user's session:

   <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:

   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 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 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:

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 for every command and option.

More

• Frameworks: FastAPI, Flask, fastapi-users, AuthX and Django
• Testing your application: FakeIssuer and FakeBrowser, no network needed
• Replay protection, logging and metrics
• DNS, HTTP and caching: DNS over HTTPS, a standard-library-only setup, private networks
• Profiles: how PyEVP follows a protocol that is still changing
• Running an issuer for your own mail domains
• Compatibility policy

Examples

Each example is a standalone project with its own tests:

• examples/fastapi: FastAPI with session nonces
• examples/flask: the same flow with the synchronous Verifier
• examples/fastapi_spa: a JSON API for a single-page app, without server sessions, with password recovery
• examples/fastapi_users: fastapi-users registration that falls back to the usual verification email
• examples/authx: passwordless login with AuthX
• examples/django: plain Django with the template tag and verify_request
• examples/django_allauth: a django-allauth adapter
• examples/issuer_fastapi: an issuer for your own domains
• examples/issuer_django: the same issuer on Django, with Django's own users

Contributing

See CONTRIBUTING.md.

License

MIT