PyEVP 0.1.0__py3-none-any.whl

pyevp/issuer/keys.py

@@ -0,0 +1,140 @@
+"""Issuer signing keys.
+
+:class:`Signer` is the boundary for keys that never leave a KMS or HSM: implement
+``sign`` with the service's raw-signature call.  :class:`SigningKey` is the
+in-process implementation backed by a private JWK.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Protocol, runtime_checkable
+
+from joserfc.errors import JoseError
+from joserfc.jwk import ECKey, OKPKey
+
+from pyevp import _jose
+
+__all__ = ["SIGNING_ALGORITHMS", "Signer", "SigningKey", "public_jwk"]
+
+SIGNING_ALGORITHMS = frozenset({"Ed25519", "ES256"})
+"""Fully specified algorithms an issuer may sign EVTs with."""
+
+_CURVES = {"Ed25519": ("OKP", "Ed25519"), "ES256": ("EC", "P-256")}
+_PRIVATE_MEMBERS = ("d", "p", "q", "dp", "dq", "qi", "k")
+
+
+@runtime_checkable
+class Signer(Protocol):
+    alg: str
+    """``Ed25519`` or ``ES256`` (fully specified, so never the polymorphic ``EdDSA``)."""
+    kid: str
+
+    @property
+    def public_jwk(self) -> Mapping[str, Any]:
+        """The verification key as published in the JWKS (with ``kid`` and ``alg``)."""
+        ...
+
+    def sign(self, signing_input: bytes) -> bytes:
+        """Sign in JWS encoding (raw ``r || s`` for ES256)."""
+        ...
+
+
+def public_jwk(key: Mapping[str, Any], *, kid: str, alg: str) -> dict[str, Any]:
+    """Normalise a public key for publication: no private members, ``kid``, ``alg``, use."""
+    if alg not in SIGNING_ALGORITHMS:
+        raise ValueError(f"unsupported signing algorithm {alg!r}; use one of Ed25519, ES256")
+    if not kid:
+        raise ValueError("issuer keys need a non-empty kid")
+    jwk = {k: v for k, v in key.items() if k not in _PRIVATE_MEMBERS}
+    jwk.update(kid=kid, alg=alg, use="sig", key_ops=["verify"])
+    if (jwk.get("kty"), jwk.get("crv")) != _CURVES[alg]:
+        raise ValueError(f"key type does not match {alg}")
+    if _jose.import_public(jwk) is None:
+        raise ValueError("invalid public key material")
+    return jwk
+
+
+class SigningKey:
+    """A private key held in process memory."""
+
+    def __init__(self, key: OKPKey | ECKey, *, kid: str, alg: str) -> None:
+        self._key = key
+        self.kid = kid
+        self.alg = alg
+        self._public = public_jwk(_derived_public(key), kid=kid, alg=alg)
+
+    @classmethod
+    def generate(cls, alg: str = "Ed25519", *, kid: str) -> SigningKey:
+        if alg == "Ed25519":
+            return cls(OKPKey.generate_key("Ed25519", private=True), kid=kid, alg=alg)
+        if alg == "ES256":
+            return cls(ECKey.generate_key("P-256", private=True), kid=kid, alg=alg)
+        raise ValueError(f"unsupported signing algorithm {alg!r}; use one of Ed25519, ES256")
+
+    @classmethod
+    def from_jwk(cls, jwk: Mapping[str, Any]) -> SigningKey:
+        """Load a private JWK; it must carry ``kid``, and ``alg`` unless the curve implies it."""
+        kid = jwk.get("kid")
+        if not isinstance(kid, str) or not kid:
+            raise ValueError("issuer keys need a non-empty kid")
+        alg = jwk.get("alg") or {v: k for k, v in _CURVES.items()}.get(
+            (jwk.get("kty"), jwk.get("crv"))
+        )
+        if alg not in SIGNING_ALGORITHMS:
+            raise ValueError(f"unsupported signing algorithm {alg!r}; use one of Ed25519, ES256")
+        if "d" not in jwk:
+            raise ValueError("not a private key")
+        material = {k: v for k, v in jwk.items() if k not in ("alg", "key_ops", "use", "kid")}
+        cls_ = OKPKey if alg == "Ed25519" else ECKey
+        try:
+            key = cls_.import_key(material)
+        except (JoseError, ValueError, TypeError) as exc:
+            raise ValueError(f"invalid private key: {exc}") from None
+        # joserfc signs with ``d`` but reports the ``x`` it was given; a mismatch would
+        # publish a key that verifies none of our signatures.
+        derived = _derived_public(key)
+        if any(material.get(m) != derived[m] for m in ("x", "y") if m in derived):
+            raise ValueError("invalid private key: public key does not match the private key")
+        return cls(key, kid=kid, alg=alg)
+
+    @classmethod
+    def from_pem(cls, pem: str | bytes, *, kid: str) -> SigningKey:
+        """Load an Ed25519 or P-256 private key in PEM, as key stores and IdPs keep them."""
+        for key_cls in (OKPKey, ECKey):
+            try:
+                key = key_cls.import_key(pem)
+            except (JoseError, ValueError, TypeError):
+                continue
+            if not key.is_private:
+                break
+            jwk = key.as_dict(private=True)
+            if (jwk["kty"], jwk["crv"]) not in _CURVES.values():
+                raise ValueError(f"unsupported curve {jwk['crv']}; use Ed25519 or P-256")
+            return cls.from_jwk({**jwk, "kid": kid})
+        raise ValueError("not an Ed25519 or P-256 private key in PEM")
+
+    def private_jwk(self) -> dict[str, Any]:
+        """The private key as a JWK, for writing to a secret store."""
+        return {**self._key.as_dict(private=True), "kid": self.kid, "alg": self.alg}
+
+    @property
+    def public_jwk(self) -> Mapping[str, Any]:
+        return self._public
+
+    def sign(self, signing_input: bytes) -> bytes:
+        return _jose.sign_raw(signing_input, self._key, self.alg)
+
+    def __repr__(self) -> str:
+        return f"SigningKey(kid={self.kid!r}, alg={self.alg!r})"
+
+
+def _derived_public(key: OKPKey | ECKey) -> dict[str, Any]:
+    """The public JWK computed from the private key, ignoring any stored public members."""
+    if isinstance(key, OKPKey):
+        assert key.private_key is not None
+        public: OKPKey | ECKey = OKPKey.import_key(key.private_key.public_key())
+    else:
+        assert key.private_key is not None
+        public = ECKey.import_key(key.private_key.public_key())
+    return dict(public.as_dict(private=False))

pyevp/issuer/profile.py

@@ -0,0 +1,96 @@
+"""Issuance profiles: what an issuer accepts from browsers and how it writes EVTs.
+
+Like :mod:`pyevp.profile` on the verifying side, every point where browsers and the
+drafts disagree is a field here, and following a change usually means adding a
+preset rather than changing an existing one.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timedelta
+from types import MappingProxyType
+from typing import Self, TypedDict, Unpack
+
+__all__ = [
+    "DEFAULT_ISSUANCE_PROFILE",
+    "ISSUANCE_PROFILES",
+    "IssuanceProfile",
+    "IssuanceProfileChanges",
+]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class IssuanceProfile:
+    name: str
+    request_algorithms: frozenset[str]
+    """Algorithms accepted for the browser's request signature (also limited by metadata)."""
+    require_request_key_alg: bool
+    """Require ``alg`` in the ``hwk`` Signature-Key; otherwise it is implied by the curve."""
+    max_request_age: timedelta
+    """How far the signature's ``created`` may lie from now, either way."""
+    require_sec_fetch_dest: bool
+    evt_type: str = "evt+jwt"
+    polymorphic_eddsa_header: bool = False
+    """Write ``"alg": "EdDSA"`` in EVT headers signed with Ed25519 (as Gmail did in 2026)."""
+
+    @classmethod
+    def chrome_153(cls) -> Self:
+        """What Chrome 153+ sends and accepts (verified end to end with 154.0.8037.92).
+
+        Chrome signs requests with ``hwk`` keys that omit ``alg``, and it rejects EVTs
+        whose header says ``"alg": "Ed25519"``: it only accepts ``EdDSA``, ``ES256``
+        and ``RS256``.  Ed25519-signed EVTs therefore carry ``EdDSA``, as Gmail's do.
+        """
+        return cls(
+            name="chrome-153",
+            request_algorithms=frozenset({"Ed25519", "ES256"}),
+            require_request_key_alg=False,
+            max_request_age=timedelta(seconds=300),
+            require_sec_fetch_dest=True,
+            polymorphic_eddsa_header=True,
+        )
+
+    @classmethod
+    def draft_hardt_02(cls) -> Self:
+        """Strict reading of draft-hardt-email-verification-02 and signature-key-09."""
+        return cls(
+            name="draft-hardt-02",
+            request_algorithms=frozenset({"Ed25519", "ES256"}),
+            require_request_key_alg=True,
+            max_request_age=timedelta(seconds=300),
+            require_sec_fetch_dest=True,
+        )
+
+    @staticmethod
+    def named(name: str) -> IssuanceProfile:
+        try:
+            return ISSUANCE_PROFILES[name]
+        except KeyError:
+            known = ", ".join(ISSUANCE_PROFILES)
+            raise ValueError(f"unknown issuance profile {name!r}; known: {known}") from None
+
+    def replace(self, **changes: Unpack[IssuanceProfileChanges]) -> Self:
+        """Return a copy with some fields changed (``dataclasses.replace``)."""
+        return dataclasses.replace(self, **changes)
+
+
+class IssuanceProfileChanges(TypedDict, total=False):
+    """The fields of :class:`IssuanceProfile`, as keyword arguments of its ``replace``."""
+
+    name: str
+    request_algorithms: frozenset[str]
+    require_request_key_alg: bool
+    max_request_age: timedelta
+    require_sec_fetch_dest: bool
+    evt_type: str
+    polymorphic_eddsa_header: bool
+
+
+ISSUANCE_PROFILES: Mapping[str, IssuanceProfile] = MappingProxyType(
+    {p.name: p for p in (IssuanceProfile.chrome_153(), IssuanceProfile.draft_hardt_02())}
+)
+
+DEFAULT_ISSUANCE_PROFILE = ISSUANCE_PROFILES["chrome-153"]

pyevp/nonce.py

@@ -0,0 +1,25 @@
+"""Nonce helpers.
+
+The RP puts a fresh nonce on the form (``<input ... nonce="...">``), stores it
+in the user's session, and passes it to ``verify``.  Storing and consuming the
+nonce exactly once is the application's job; see the examples.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+
+__all__ = ["generate_nonce", "nonces_equal"]
+
+
+def generate_nonce(nbytes: int = 32) -> str:
+    """Return a URL-safe nonce with ``nbytes`` of entropy (at least 16)."""
+    if nbytes < 16:
+        raise ValueError("a nonce needs at least 128 bits of entropy")
+    return secrets.token_urlsafe(nbytes)
+
+
+def nonces_equal(a: str, b: str) -> bool:
+    """Compare two nonces in constant time."""
+    return hmac.compare_digest(a.encode(), b.encode())

pyevp/observability.py

@@ -0,0 +1,89 @@
+"""Hooks for logging and metrics.
+
+Pass ``observer=`` to a verifier to receive one :class:`VerificationEvent` per
+``verify`` call.  Observers must be fast and must not raise; exceptions are
+logged and swallowed so that monitoring can never break authentication.
+
+A Prometheus counter, for example::
+
+    VERIFICATIONS = Counter("evp_verifications_total", "EVP verifications", ["result", "issuer"])
+
+    def observe(event: VerificationEvent) -> None:
+        VERIFICATIONS.labels(event.code or "ok", event.issuer or "").inc()
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import TypeAlias
+
+from pyevp import discovery
+from pyevp.errors import ErrorCode
+from pyevp.token import parse_token
+
+__all__ = ["LoggingObserver", "Observer", "VerificationEvent", "claimed_email_domain"]
+
+
+@dataclass(frozen=True, slots=True)
+class VerificationEvent:
+    ok: bool
+    code: ErrorCode | None
+    """Set when verification failed with an :class:`~pyevp.EVPError`."""
+    issuer: str | None
+    """Canonical issuer; only known after a successful verification."""
+    email_domain: str | None
+    """Domain of the ``email`` claim, read from the token *before* verification."""
+    profile: str
+    duration: timedelta
+
+
+# TODO(py3.12): back to a ``type`` statement once 3.11 support is dropped.
+Observer: TypeAlias = Callable[[VerificationEvent], None]
+"""Receives one :class:`VerificationEvent` per verification; must not block or raise."""
+
+
+# What ``email_domain`` returns for a name DNS could hold.  Anything else (spaces, line
+# breaks, ...) comes from an unverified token and must not reach logs or metric labels.
+_DNS_NAME = re.compile(r"[a-z0-9_-]+(?:\.[a-z0-9_-]+)*")
+
+
+def claimed_email_domain(token: str) -> str | None:
+    """Best-effort domain of the (unverified) ``email`` claim, for grouping metrics.
+
+    ``None`` unless the claim holds an address whose domain is a plausible DNS name.
+    """
+    try:
+        email = parse_token(token, allow_disclosures=True).evt.claims.get("email")
+        domain = discovery.email_domain(email) if isinstance(email, str) else None
+    except Exception:
+        return None
+    return domain if domain is not None and _DNS_NAME.fullmatch(domain) else None
+
+
+class LoggingObserver:
+    """Log one line per verification to the ``pyevp`` logger (or ``logger``)."""
+
+    def __init__(self, logger: logging.Logger | None = None, *, level: int = logging.INFO) -> None:
+        self._logger = logger or logging.getLogger("pyevp")
+        self._level = level
+
+    def __call__(self, event: VerificationEvent) -> None:
+        self._logger.log(
+            self._level,
+            "EVP verification %s code=%s issuer=%s domain=%s profile=%s duration_ms=%.1f",
+            "succeeded" if event.ok else "failed",
+            event.code,
+            _escaped(event.issuer),
+            _escaped(event.email_domain),
+            _escaped(event.profile),
+            event.duration.total_seconds() * 1000,
+        )
+
+
+def _escaped(value: str | None) -> str | None:
+    """``value``, or its ``repr`` if it holds a line break or another unprintable character."""
+    return value if value is None or value.isprintable() else repr(value)

pyevp/ports.py

@@ -0,0 +1,54 @@
+"""I/O boundaries.  Implement these to plug in your own DNS / HTTP / clock."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Protocol, TypeAlias, runtime_checkable
+
+__all__ = [
+    "AsyncJsonFetcher",
+    "AsyncTxtResolver",
+    "Clock",
+    "JsonFetcher",
+    "TxtResolver",
+    "system_clock",
+]
+
+# TODO(py3.12): back to a ``type`` statement once 3.11 support is dropped.
+Clock: TypeAlias = Callable[[], datetime]
+"""Returns the current time as an aware ``datetime``."""
+
+
+def system_clock() -> datetime:
+    return datetime.now(UTC)
+
+
+@runtime_checkable
+class TxtResolver(Protocol):
+    def resolve_txt(self, name: str) -> list[str]:
+        """Return each TXT record as one string (character-strings concatenated).
+
+        Return an empty list for NXDOMAIN / NODATA; raise for other failures.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncTxtResolver(Protocol):
+    async def resolve_txt(self, name: str) -> list[str]: ...
+
+
+@runtime_checkable
+class JsonFetcher(Protocol):
+    def fetch_json(self, url: str) -> object:
+        """GET ``url`` (no redirects to other origins) and return the decoded JSON.
+
+        Raise on transport errors, non-200 responses or invalid JSON.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncJsonFetcher(Protocol):
+    async def fetch_json(self, url: str) -> object: ...

pyevp/profile.py

@@ -0,0 +1,153 @@
+"""Verification profiles.
+
+The protocol is still moving (algorithm names, ``iss`` format, ``kid`` rules, …)
+and deployed issuers lag behind the drafts.  Every such knob lives here so that
+following a spec change usually means adding a new preset rather than changing an
+existing one or the verification code.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timedelta
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Self, TypedDict, Unpack
+
+from pyevp._email import EmailComparison, emails_match
+
+__all__ = [
+    "DEFAULT_PROFILE",
+    "PROFILES",
+    "EmailComparison",
+    "IssuerFormat",
+    "Profile",
+    "ProfileChanges",
+]
+
+
+class IssuerFormat(StrEnum):
+    """Accepted spellings of an issuer identifier (token ``iss`` / DNS ``iss=``)."""
+
+    HOST = "host"
+    """Bare host, e.g. ``accounts.google.com`` (early drafts)."""
+    ORIGIN = "origin"
+    """HTTPS origin, e.g. ``https://accounts.google.com`` (draft-hardt -02)."""
+    ANY = "any"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Profile:
+    name: str
+    evt_types: frozenset[str]
+    kb_types: frozenset[str]
+    evt_algorithms: frozenset[str]
+    kb_algorithms: frozenset[str]
+    require_kid: bool
+    """When false, an absent or empty ``kid`` tries every compatible issuer key."""
+    require_cnf_alg: bool
+    """Require ``cnf.jwk.alg`` and that it equals the KB-JWT ``alg``."""
+    issuer_format: IssuerFormat
+    email_comparison: EmailComparison
+    max_token_age: timedelta
+    clock_skew: timedelta
+    require_exp: bool
+    allow_disclosures: bool
+    """Accept SD-JWT disclosures between the EVT and the KB-JWT (``MALFORMED_TOKEN`` otherwise).
+
+    They are covered by ``sd_hash`` but never decoded, so they add no claims.
+    """
+    dns_label: str = "_email-verification"
+    metadata_path: str = "/.well-known/email-verification"
+
+    @classmethod
+    def compat_2026_10(cls) -> Self:
+        """Accept both the -02 draft and what Chrome + Gmail ship as of 2026-10.
+
+        Gmail signs with ``EdDSA`` and publishes keys without ``kid``.
+        """
+        return cls(
+            name="compat-2026-10",
+            evt_types=frozenset({"evt+jwt"}),
+            kb_types=frozenset({"kb+jwt"}),
+            evt_algorithms=frozenset({"Ed25519", "EdDSA", "ES256"}),
+            kb_algorithms=frozenset({"Ed25519", "EdDSA", "ES256"}),
+            require_kid=False,
+            require_cnf_alg=False,
+            issuer_format=IssuerFormat.ANY,
+            email_comparison=EmailComparison.CASE_INSENSITIVE,
+            max_token_age=timedelta(minutes=5),
+            clock_skew=timedelta(minutes=1),
+            require_exp=False,
+            allow_disclosures=False,
+        )
+
+    @classmethod
+    def draft_hardt_02(cls) -> Self:
+        """Strict reading of draft-hardt-email-verification editor's copy (-02)."""
+        return cls(
+            name="draft-hardt-02",
+            evt_types=frozenset({"evt+jwt"}),
+            kb_types=frozenset({"kb+jwt"}),
+            evt_algorithms=frozenset({"Ed25519", "ES256"}),
+            kb_algorithms=frozenset({"Ed25519", "ES256"}),
+            require_kid=True,
+            require_cnf_alg=True,
+            issuer_format=IssuerFormat.ORIGIN,
+            email_comparison=EmailComparison.EXACT,
+            max_token_age=timedelta(minutes=5),
+            clock_skew=timedelta(minutes=1),
+            require_exp=False,
+            allow_disclosures=False,
+        )
+
+    @staticmethod
+    def named(name: str) -> Profile:
+        """Look up a preset by name (e.g. ``"draft-hardt-02"``)."""
+        try:
+            return PROFILES[name]
+        except KeyError:
+            raise ValueError(f"unknown profile {name!r}; known: {', '.join(PROFILES)}") from None
+
+    def emails_match(self, asserted: str, submitted: str) -> bool:
+        """Compare two addresses the way verification does (see :class:`EmailComparison`).
+
+        Use it when looking up the account for a verified address, so that lookup and
+        verification agree on which addresses are the same.
+        """
+        return emails_match(asserted, submitted, self.email_comparison)
+
+    def replace(self, **changes: Unpack[ProfileChanges]) -> Self:
+        """Return a copy with some fields changed (``dataclasses.replace``)."""
+        return dataclasses.replace(self, **changes)
+
+
+class ProfileChanges(TypedDict, total=False):
+    """The fields of :class:`Profile`, as keyword arguments of :meth:`Profile.replace`."""
+
+    name: str
+    evt_types: frozenset[str]
+    kb_types: frozenset[str]
+    evt_algorithms: frozenset[str]
+    kb_algorithms: frozenset[str]
+    require_kid: bool
+    require_cnf_alg: bool
+    issuer_format: IssuerFormat
+    email_comparison: EmailComparison
+    max_token_age: timedelta
+    clock_skew: timedelta
+    require_exp: bool
+    allow_disclosures: bool
+    dns_label: str
+    metadata_path: str
+
+
+PROFILES: Mapping[str, Profile] = MappingProxyType(
+    {p.name: p for p in (Profile.compat_2026_10(), Profile.draft_hardt_02())}
+)
+"""All presets by name."""
+
+DEFAULT_PROFILE = PROFILES["compat-2026-10"]
+"""The profile verifiers use unless told otherwise."""

pyevp/replay.py

@@ -0,0 +1,69 @@
+"""Replay protection.
+
+The single-use nonce is the primary defence against replay, but it only works
+when the nonce lives server-side.  With client-side sessions (e.g. Starlette's
+signed-cookie ``SessionMiddleware``) an attacker who captured a token can resend
+it together with the old session cookie.  A replay guard closes that gap by
+remembering every accepted token until it would expire anyway.
+
+Implementations must make :meth:`ReplayGuard.mark_used` an atomic
+"add if absent", shared by every worker that verifies tokens, for example:
+
+- Redis: ``SET evp:<key> 1 NX PXAT <expires_at in ms>``, with
+  ``maxmemory-policy noeviction``
+- A database table with the key as primary key, as
+  :class:`pyevp.contrib.django.EVPReplayGuard` does
+
+The store must keep every record until ``expires_at``: caches that evict
+entries under memory pressure (Memcached, Django's cache backends) do not.
+
+``expires_at`` can already be past when verification took long; guards need not
+handle that specially, because the verifier rejects the token afterwards.
+"""
+
+from __future__ import annotations
+
+import threading
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+from pyevp.ports import Clock, system_clock
+
+__all__ = ["AsyncReplayGuard", "InMemoryReplayGuard", "ReplayGuard"]
+
+
+@runtime_checkable
+class ReplayGuard(Protocol):
+    def mark_used(self, key: str, expires_at: datetime) -> bool:
+        """Remember ``key`` until ``expires_at``.
+
+        Return ``True`` if the key was not already present, ``False`` otherwise.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncReplayGuard(Protocol):
+    async def mark_used(self, key: str, expires_at: datetime) -> bool: ...
+
+
+class InMemoryReplayGuard:
+    """Process-local guard.
+
+    Only correct when a single process verifies tokens; with several workers a
+    token can be replayed against another worker.  Use a shared store there.
+    """
+
+    def __init__(self, *, clock: Clock = system_clock) -> None:
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._seen: dict[str, datetime] = {}
+
+    def mark_used(self, key: str, expires_at: datetime) -> bool:
+        now = self._clock()
+        with self._lock:
+            self._seen = {k: exp for k, exp in self._seen.items() if exp > now}
+            if key in self._seen:
+                return False
+            self._seen[key] = expires_at
+            return True