PyEVP 0.1.0__tar.gz → 0.2.0__tar.gz

{pyevp-0.1.0 → pyevp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyEVP
-Version: 0.1.0
+Version: 0.2.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
@@ -59,11 +59,15 @@ or issue them for your own email domains. With EVP, the browser obtains a token
 email provider proving they control an address, and your server verifies it, with no confirmation
 email round-trip.
 
-**Documentation: <https://docs.pyevp.dev/>**
+**Documentation: <https://docs.pyevp.dev/>** · **Live demo: <https://pyevp.dev/demo>**
 
 > **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.
+> is still changing. PyEVP keeps every moving part in a versioned `Profile` so it can follow along.
+
+- **Browsers:** Chrome, with `chrome://flags/#email-verification-protocol` enabled or on a site
+  registered for the origin trial. Tested with Chrome 154. Other browsers send no token.
+- **Email providers:** Gmail issues tokens today. Your own domains can too, with `pyevp.issuer`.
+- **Python:** 3.11 or newer.
 
 [draft-hardt-email-verification]: https://github.com/dickhardt/email-verification
 [WICG Email Verification API]: https://github.com/WICG/email-verification
@@ -74,77 +78,64 @@ email round-trip.
 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
+The core depends only on [joserfc] and idna. `[dns,httpx2]` adds the adapters
+`Verifier.default()` uses; httpx works too (see [DNS, HTTP and caching]). `[all]` adds the Django
+integration and the command line.
 
 [joserfc]: https://jose.authlib.org/
+[DNS, HTTP and caching]: https://docs.pyevp.dev/en/latest/guides/transport.html
 
 ## How it works
 
-1. Render a form with a fresh nonce stored in the user's session:
+1. Render a form with a nonce kept in the user's session:
+
+   ```python
+   from pyevp import SessionNonces, token_input
+
+   nonce = SessionNonces(session).issue()  # Flask, Starlette and Django sessions all work
+   ```
 
    ```html
    <input type="email" name="email" autocomplete="email">
    <input type="hidden" name="evt" autocomplete="email-verification-token" nonce="{{ nonce }}">
    ```
 
+   (`token_input(nonce)` renders the hidden input.)
+
 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
+   from pyevp import EVPError, SessionNonces, Verifier
 
    verifier = Verifier.default(audience="https://example.com")  # your origin
 
    try:
-       result = verifier.verify(form["evt"], nonce=session.pop("evp_nonce"), email=form["email"])
+       result = verifier.verify_submission(
+           form.get("evt"), nonces=SessionNonces(session), email=form["email"]
+       )
    except EVPError as exc:
-       ...  # exc.code is an ErrorCode, e.g. "nonce_mismatch"; fall back to email confirmation
+       ...  # exc.code says why, e.g. "nonce_mismatch"; fall back to email confirmation
    else:
-       result.email, result.issuer  # verified
+       if result is None:
+           ...  # no token: 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"
-```
+   `AsyncVerifier` has the same API with `await`.
 
-See the [CLI guide](https://docs.pyevp.dev/en/latest/guides/cli.html) for every command and option.
+Everything that can be checked offline is checked first, and only hosts found through DNS are
+ever contacted, never hosts named in the token. Every rejection raises an `EVPError` with an
+[error code](https://docs.pyevp.dev/en/latest/quickstart.html#handle-failures).
 
 ## More
 
+- [Quickstart](https://docs.pyevp.dev/en/latest/quickstart.html) and [concepts](https://docs.pyevp.dev/en/latest/concepts.html)
 - [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
+- [Testing your application](https://docs.pyevp.dev/en/latest/guides/testing.html) without network access
 - [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
+- [Command line](https://docs.pyevp.dev/en/latest/guides/cli.html): `uvx --from "pyevp[cli]" pyevp discover gmail.com` checks a domain's issuer
 - [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)
 
@@ -154,13 +145,12 @@ 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/fastapi_spa`](https://github.com/gaato/pyevp/blob/main/examples/fastapi_spa/app.py): a JSON API for a single-page app, with password recovery
+- [`examples/fastapi_users`](https://github.com/gaato/pyevp/blob/main/examples/fastapi_users/app.py): fastapi-users registration
 - [`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`](https://github.com/gaato/pyevp/blob/main/examples/django/views.py): Django with the template tag
 - [`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
+- [`examples/issuer_fastapi`](https://github.com/gaato/pyevp/blob/main/examples/issuer_fastapi/app.py), [`examples/issuer_django`](https://github.com/gaato/pyevp/blob/main/examples/issuer_django/urls.py): an issuer for your own domains
 
 ## Contributing
 

{pyevp-0.1.0 → pyevp-0.2.0}/README.md

@@ -16,11 +16,15 @@ or issue them for your own email domains. With EVP, the browser obtains a token
 email provider proving they control an address, and your server verifies it, with no confirmation
 email round-trip.
 
-**Documentation: <https://docs.pyevp.dev/>**
+**Documentation: <https://docs.pyevp.dev/>** · **Live demo: <https://pyevp.dev/demo>**
 
 > **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.
+> is still changing. PyEVP keeps every moving part in a versioned `Profile` so it can follow along.
+
+- **Browsers:** Chrome, with `chrome://flags/#email-verification-protocol` enabled or on a site
+  registered for the origin trial. Tested with Chrome 154. Other browsers send no token.
+- **Email providers:** Gmail issues tokens today. Your own domains can too, with `pyevp.issuer`.
+- **Python:** 3.11 or newer.
 
 [draft-hardt-email-verification]: https://github.com/dickhardt/email-verification
 [WICG Email Verification API]: https://github.com/WICG/email-verification
@@ -31,77 +35,64 @@ email round-trip.
 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
+The core depends only on [joserfc] and idna. `[dns,httpx2]` adds the adapters
+`Verifier.default()` uses; httpx works too (see [DNS, HTTP and caching]). `[all]` adds the Django
+integration and the command line.
 
 [joserfc]: https://jose.authlib.org/
+[DNS, HTTP and caching]: https://docs.pyevp.dev/en/latest/guides/transport.html
 
 ## How it works
 
-1. Render a form with a fresh nonce stored in the user's session:
+1. Render a form with a nonce kept in the user's session:
+
+   ```python
+   from pyevp import SessionNonces, token_input
+
+   nonce = SessionNonces(session).issue()  # Flask, Starlette and Django sessions all work
+   ```
 
    ```html
    <input type="email" name="email" autocomplete="email">
    <input type="hidden" name="evt" autocomplete="email-verification-token" nonce="{{ nonce }}">
    ```
 
+   (`token_input(nonce)` renders the hidden input.)
+
 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
+   from pyevp import EVPError, SessionNonces, Verifier
 
    verifier = Verifier.default(audience="https://example.com")  # your origin
 
    try:
-       result = verifier.verify(form["evt"], nonce=session.pop("evp_nonce"), email=form["email"])
+       result = verifier.verify_submission(
+           form.get("evt"), nonces=SessionNonces(session), email=form["email"]
+       )
    except EVPError as exc:
-       ...  # exc.code is an ErrorCode, e.g. "nonce_mismatch"; fall back to email confirmation
+       ...  # exc.code says why, e.g. "nonce_mismatch"; fall back to email confirmation
    else:
-       result.email, result.issuer  # verified
+       if result is None:
+           ...  # no token: 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"
-```
+   `AsyncVerifier` has the same API with `await`.
 
-See the [CLI guide](https://docs.pyevp.dev/en/latest/guides/cli.html) for every command and option.
+Everything that can be checked offline is checked first, and only hosts found through DNS are
+ever contacted, never hosts named in the token. Every rejection raises an `EVPError` with an
+[error code](https://docs.pyevp.dev/en/latest/quickstart.html#handle-failures).
 
 ## More
 
+- [Quickstart](https://docs.pyevp.dev/en/latest/quickstart.html) and [concepts](https://docs.pyevp.dev/en/latest/concepts.html)
 - [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
+- [Testing your application](https://docs.pyevp.dev/en/latest/guides/testing.html) without network access
 - [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
+- [Command line](https://docs.pyevp.dev/en/latest/guides/cli.html): `uvx --from "pyevp[cli]" pyevp discover gmail.com` checks a domain's issuer
 - [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)
 
@@ -111,13 +102,12 @@ 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/fastapi_spa`](https://github.com/gaato/pyevp/blob/main/examples/fastapi_spa/app.py): a JSON API for a single-page app, with password recovery
+- [`examples/fastapi_users`](https://github.com/gaato/pyevp/blob/main/examples/fastapi_users/app.py): fastapi-users registration
 - [`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`](https://github.com/gaato/pyevp/blob/main/examples/django/views.py): Django with the template tag
 - [`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
+- [`examples/issuer_fastapi`](https://github.com/gaato/pyevp/blob/main/examples/issuer_fastapi/app.py), [`examples/issuer_django`](https://github.com/gaato/pyevp/blob/main/examples/issuer_django/urls.py): an issuer for your own domains
 
 ## Contributing
 

{pyevp-0.1.0 → pyevp-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "PyEVP"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python library for the Email Verification Protocol (EVP): verify tokens as a relying party, or issue them for your own email domains"
 readme = "README.md"
 license = "MIT"

{pyevp-0.1.0 → pyevp-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "PyEVP"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python library for the Email Verification Protocol (EVP): verify tokens as a relying party, or issue them for your own email domains"
 readme = "README.md"
 authors = [

{pyevp-0.1.0 → pyevp-0.2.0}/src/pyevp/__init__.py

@@ -3,7 +3,14 @@
 from pyevp._email import emails_match
 from pyevp.cache import AsyncCache, Cache, CacheEntry, InMemoryCache, NullCache
 from pyevp.errors import DiscoveryError, ErrorCode, EVPError, PolicyError, TokenError
-from pyevp.nonce import generate_nonce, nonces_equal
+from pyevp.nonce import (
+    AsyncNonceStore,
+    NonceStore,
+    SessionNonces,
+    generate_nonce,
+    nonces_equal,
+    token_input,
+)
 from pyevp.observability import LoggingObserver, Observer, VerificationEvent
 from pyevp.ports import AsyncJsonFetcher, AsyncTxtResolver, Clock, JsonFetcher, TxtResolver
 from pyevp.profile import DEFAULT_PROFILE, EmailComparison, IssuerFormat, Profile
@@ -15,6 +22,7 @@ __all__ = [
     "DEFAULT_PROFILE",
     "AsyncCache",
     "AsyncJsonFetcher",
+    "AsyncNonceStore",
     "AsyncReplayGuard",
     "AsyncTxtResolver",
     "AsyncVerifier",
@@ -31,11 +39,13 @@ __all__ = [
     "IssuerMetadata",
     "JsonFetcher",
     "LoggingObserver",
+    "NonceStore",
     "NullCache",
     "Observer",
     "PolicyError",
     "Profile",
     "ReplayGuard",
+    "SessionNonces",
     "TokenError",
     "TxtResolver",
     "VerificationEvent",
@@ -44,4 +54,5 @@ __all__ = [
     "emails_match",
     "generate_nonce",
     "nonces_equal",
+    "token_input",
 ]

pyevp-0.2.0/src/pyevp/_drive.py

@@ -0,0 +1,132 @@
+"""Drivers that answer the effects a sans-I/O flow yields, synchronously or asynchronously.
+
+A flow is a generator: it yields an effect, is sent the answer, and finally returns its
+result.  ``perform`` answers one effect, with a value or, for asynchronous ports, an
+awaitable.  The two drivers differ only in what they do with an awaitable: :func:`adrive`
+awaits it, and :func:`drive` refuses it, because a synchronous caller cannot wait for it
+and taking it as the answer would be wrong (a coroutine is truthy).
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Generator
+from typing import Any, TypeAlias, TypeVar
+
+from pyevp.core import FetchJson, ResolveTxt
+from pyevp.errors import DiscoveryError, ErrorCode, EVPError
+from pyevp.ports import AsyncJsonFetcher, AsyncTxtResolver, JsonFetcher, TxtResolver
+
+E = TypeVar("E")
+R = TypeVar("R")
+
+# TODO(py3.12): back to ``type`` statements once 3.11 support is dropped.
+Translate: TypeAlias = Callable[[Any, Exception], Exception | None]
+"""Maps an exception raised while answering an effect to the one to raise, or ``None``."""
+
+
+def is_async(function: object) -> bool:
+    """Whether calling ``function`` returns a coroutine, as far as can be told beforehand."""
+    return inspect.iscoroutinefunction(function) or inspect.iscoroutinefunction(
+        getattr(function, "__call__", None)  # noqa: B004  (a callable object)
+    )
+
+
+def drive(
+    steps: Generator[E, Any, R],
+    perform: Callable[[E], object],
+    *,
+    hint: str,
+    translate: Translate | None = None,
+) -> R:
+    """Run ``steps`` to completion, answering each effect with ``perform``.
+
+    An awaitable answer is a :class:`TypeError` that ends with ``hint``, such as
+    ``"use AsyncVerifier"``.
+    """
+    try:
+        effect = next(steps)
+        while True:
+            reply = _answer(effect, perform, translate)
+            if inspect.isawaitable(reply):
+                if inspect.iscoroutine(reply):
+                    reply.close()
+                raise TypeError(
+                    f"the port answering {type(effect).__name__.lstrip('_')} returned an "
+                    f"awaitable, which a synchronous call cannot wait for; {hint}"
+                )
+            effect = steps.send(reply)
+    except StopIteration as stop:  # the flow's own: a port's is a RuntimeError by now
+        return stop.value
+    finally:
+        steps.close()
+
+
+async def adrive(
+    steps: Generator[E, Any, R],
+    perform: Callable[[E], object],
+    *,
+    translate: Translate | None = None,
+) -> R:
+    """Run ``steps`` to completion, awaiting the answers that are awaitable."""
+    try:
+        effect = next(steps)
+        while True:
+            effect = steps.send(await _aanswer(effect, perform, translate))
+    except StopIteration as stop:  # the flow's own: a port's is a RuntimeError by now
+        return stop.value
+    finally:
+        steps.close()
+
+
+def _answer(effect: E, perform: Callable[[E], object], translate: Translate | None) -> object:
+    try:
+        return perform(effect)
+    except Exception as exc:
+        raise _failure(effect, exc, translate) from exc
+
+
+def _failure(effect: object, exc: Exception, translate: Translate | None) -> Exception:
+    mapped = translate(effect, exc) if translate is not None else None
+    if mapped is not None:
+        return mapped
+    if isinstance(exc, StopIteration):
+        # Would otherwise look like the flow finishing, with the port's value as its result.
+        return RuntimeError(f"the port answering {type(effect).__name__} raised StopIteration")
+    return exc
+
+
+async def _aanswer(
+    effect: E, perform: Callable[[E], object], translate: Translate | None
+) -> object:
+    try:
+        reply = perform(effect)
+        return await reply if inspect.isawaitable(reply) else reply
+    except Exception as exc:
+        raise _failure(effect, exc, translate) from exc
+
+
+def lookup(
+    effect: object,
+    *,
+    resolver: TxtResolver | AsyncTxtResolver,
+    fetcher: JsonFetcher | AsyncJsonFetcher,
+) -> object:
+    """Answer a DNS or HTTP lookup with the ports, as a value or an awaitable."""
+    if isinstance(effect, ResolveTxt):
+        return resolver.resolve_txt(effect.name)
+    if isinstance(effect, FetchJson):
+        return fetcher.fetch_json(effect.url)
+    raise TypeError(f"unexpected effect {effect!r}")
+
+
+def unreachable(effect: object, exc: Exception) -> DiscoveryError | None:
+    """A failed DNS or HTTP request to the issuer, as ``ISSUER_UNREACHABLE``.
+
+    ``None`` for anything else, which then propagates unchanged: a verdict already
+    reached (:class:`~pyevp.EVPError`), or a failure of the cache, store or guard.
+    """
+    if isinstance(exc, EVPError) or not isinstance(effect, ResolveTxt | FetchJson):
+        return None
+    target = effect.name if isinstance(effect, ResolveTxt) else effect.url
+    return DiscoveryError(ErrorCode.ISSUER_UNREACHABLE, f"lookup of {target} failed: {exc}")

{pyevp-0.1.0 → pyevp-0.2.0}/src/pyevp/_httpsig.py

@@ -54,6 +54,8 @@ class SignedRequest:
     public_jwk: dict[str, str]
     """The signer's key as a JWK, always with ``alg``."""
     created: datetime
+    deadline: datetime
+    """The last moment the request is fresh: ``created`` plus the maximum age, or ``expires``."""
     signature: bytes
     base: bytes
     """The signature base that ``signature`` was verified over."""
@@ -231,6 +233,9 @@ def verify_request(
         not isinstance(expires, int) or isinstance(expires, bool) or expires < now.timestamp()
     ):
         raise SignatureError("invalid_signature", "signature has expired")
+    deadline = created_at + max_age
+    if expires is not None and expires < deadline.timestamp():
+        deadline = datetime.fromtimestamp(expires, UTC)
 
     base = _signature_base(components, method=method, endpoint=endpoint, lines=lines)
     if not _jose.verify_raw(base, signature.value, jwk, alg):
@@ -239,7 +244,7 @@ def verify_request(
         raise SignatureError("invalid_signature", "HTTP Message Signature verification failed")
     # Only now that the body is known to be what was signed is the digest worth checking.
     _check_digest(lines.get("content-digest"), body)
-    return SignedRequest(label, alg, jwk, created_at, signature.value, base)
+    return SignedRequest(label, alg, jwk, created_at, deadline, signature.value, base)
 
 
 def sign_request(
@@ -251,6 +256,7 @@ def sign_request(
     public_jwk: Mapping[str, Any],
     alg: str,
     created: datetime,
+    expires: datetime | None = None,
     label: str = "sig",
     include_alg: bool = True,
     signature_key: str | None = None,
@@ -272,9 +278,10 @@ def sign_request(
         "Content-Digest": content_digest(body) if digest is None else digest,
         "Signature-Key": signature_key,
     }
-    components = _sf.InnerList(
-        tuple(_sf.Item(c) for c in REQUIRED_COMPONENTS), {"created": int(created.timestamp())}
-    )
+    params: dict[str, Any] = {"created": int(created.timestamp())}
+    if expires is not None:
+        params["expires"] = int(expires.timestamp())
+    components = _sf.InnerList(tuple(_sf.Item(c) for c in REQUIRED_COMPONENTS), params)
     base = _signature_base(
         components, method=method, endpoint=endpoint, lines=_field_lines(headers)
     )

{pyevp-0.1.0 → pyevp-0.2.0}/src/pyevp/cli/__init__.py

@@ -22,6 +22,7 @@ from joserfc import jwk
 from rich.console import Console
 from rich.table import Table
 
+from pyevp import discovery
 from pyevp.diagnostics import IssuerReport, discover
 from pyevp.errors import EVPError
 from pyevp.issuer import SIGNING_ALGORITHMS, Issuer, SigningKey
@@ -239,7 +240,7 @@ def _issuer_app() -> typer.Typer:
             raise typer.BadParameter(str(exc)) from None
         _json(
             {
-                "metadata_url": f"{built.issuer}/.well-known/email-verification",
+                "metadata_url": discovery.metadata_url(built.issuer),
                 "metadata": built.metadata_document(),
                 "jwks_uri": built.jwks_uri,
                 "jwks": built.jwks_document(),