PyEVP 0.1.0__py3-none-any.whl

pyevp/__init__.py

@@ -0,0 +1,47 @@
+"""Relying-party verification for the Email Verification Protocol (EVP)."""
+
+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.observability import LoggingObserver, Observer, VerificationEvent
+from pyevp.ports import AsyncJsonFetcher, AsyncTxtResolver, Clock, JsonFetcher, TxtResolver
+from pyevp.profile import DEFAULT_PROFILE, EmailComparison, IssuerFormat, Profile
+from pyevp.replay import AsyncReplayGuard, InMemoryReplayGuard, ReplayGuard
+from pyevp.types import IssuerMetadata, VerifiedEmail
+from pyevp.verifier import AsyncVerifier, Verifier
+
+__all__ = [
+    "DEFAULT_PROFILE",
+    "AsyncCache",
+    "AsyncJsonFetcher",
+    "AsyncReplayGuard",
+    "AsyncTxtResolver",
+    "AsyncVerifier",
+    "Cache",
+    "CacheEntry",
+    "Clock",
+    "DiscoveryError",
+    "EVPError",
+    "EmailComparison",
+    "ErrorCode",
+    "InMemoryCache",
+    "InMemoryReplayGuard",
+    "IssuerFormat",
+    "IssuerMetadata",
+    "JsonFetcher",
+    "LoggingObserver",
+    "NullCache",
+    "Observer",
+    "PolicyError",
+    "Profile",
+    "ReplayGuard",
+    "TokenError",
+    "TxtResolver",
+    "VerificationEvent",
+    "VerifiedEmail",
+    "Verifier",
+    "emails_match",
+    "generate_nonce",
+    "nonces_equal",
+]

pyevp/__main__.py

@@ -0,0 +1,28 @@
+"""``pyevp`` command / ``python -m pyevp``.  Requires ``pip install "pyevp[cli]"``."""
+
+from __future__ import annotations
+
+import sys
+
+MISSING_EXTRA = 3
+
+
+def main() -> None:
+    try:
+        from pyevp.cli import app  # noqa: PLC0415
+    except ImportError as exc:
+        if exc.name not in {"typer", "click", "rich"}:
+            raise
+        print(
+            'The pyevp command needs the "cli" extra:\n'
+            '  pip install "pyevp[cli]"\n'
+            "or run it without installing:\n"
+            '  uvx --from "pyevp[cli]" pyevp --help',
+            file=sys.stderr,
+        )
+        raise SystemExit(MISSING_EXTRA) from None
+    app()
+
+
+if __name__ == "__main__":
+    main()

pyevp/_email.py

@@ -0,0 +1,65 @@
+"""Email address normalisation and comparison shared by verification and account lookup."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+import idna
+
+__all__ = ["EmailComparison", "email_domain", "emails_match"]
+
+
+class EmailComparison(StrEnum):
+    """How a submitted address is compared with the asserted one."""
+
+    EXACT = "exact"
+    """Byte for byte (IETF draft)."""
+    CASE_INSENSITIVE = "case_insensitive"
+    """Local part Unicode case-folded, domain compared in IDNA2008 A-label form.
+
+    Follows the W3C Email Verification API, without letting case folding merge two
+    DNS names: ``a@faß.example`` does not match ``a@fass.example``.
+    """
+
+
+def _split(email: str) -> tuple[str, str]:
+    local, sep, domain = email.rpartition("@")
+    if not sep or not local or not domain:
+        raise ValueError(f"not an email address: {email!r}")
+    return local, domain
+
+
+def email_domain(email: str) -> str:
+    """Return the DNS (A-label) form of the domain part of ``email``.
+
+    Internationalised domains are mapped with UTS #46 / IDNA2008, as browsers do.
+    Python's ``"idna"`` codec implements IDNA2003, which maps some names onto other
+    domains (``faß.example`` → ``fass.example``).  Raises :class:`UnicodeError` for
+    invalid internationalised domains.
+    """
+    domain = _split(email)[1].rstrip(".")
+    if domain.isascii():
+        return domain.lower()
+    return idna.encode(domain, uts46=True).decode("ascii")
+
+
+def emails_match(asserted: str, submitted: str, comparison: EmailComparison) -> bool:
+    """Whether two addresses name the same mailbox under ``comparison``.
+
+    ``EXACT`` compares the strings byte for byte.  ``CASE_INSENSITIVE`` case-folds the
+    local part and compares domains in their IDNA2008 A-label form, so that case
+    folding never merges two DNS names (``faß.example`` is not ``fass.example``).
+    Invalid addresses never match.
+    """
+    if comparison is EmailComparison.EXACT:
+        return asserted == submitted
+    try:
+        (a_local, a_domain), (s_local, s_domain) = _split(asserted), _split(submitted)
+        same_domain = email_domain(asserted) == email_domain(submitted)
+    except (ValueError, UnicodeError):
+        return False
+    return (
+        same_domain
+        and a_domain.endswith(".") == s_domain.endswith(".")
+        and a_local.casefold() == s_local.casefold()
+    )

pyevp/_httpsig.py

@@ -0,0 +1,284 @@
+"""HTTP Message Signatures (RFC 9421) with an ``hwk`` Signature-Key, as browsers send them.
+
+Only what EVP issuance needs is implemented: one signature per request, carrying
+its public key in ``Signature-Key: <label>=hwk;…`` (draft-hardt-httpbis-signature-key),
+over a body bound by ``Content-Digest: sha-256=…`` (RFC 9530).  Derived components
+are computed from the issuance endpoint the issuer is configured with, never from
+the ``Host`` header, so a signature made for another endpoint does not verify.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any, TypeAlias, cast
+from urllib.parse import urlsplit
+
+from pyevp import _jose, _sf
+
+__all__ = [
+    "Headers",
+    "SignatureError",
+    "SignedRequest",
+    "content_digest",
+    "sign_request",
+    "verify_request",
+]
+
+# TODO(py3.12): back to a ``type`` statement once 3.11 support is dropped.
+Headers: TypeAlias = Mapping[str, str] | Iterable[tuple[str, str]]
+"""Request headers: a mapping, or ``(name, value)`` pairs that may repeat a name."""
+
+REQUIRED_COMPONENTS = ("@method", "@authority", "@path", "content-digest", "signature-key")
+_DERIVED = frozenset({"@method", "@authority", "@path", "@scheme", "@target-uri"})
+# Curve -> the fully specified algorithm a key without ``alg`` is taken to use.
+_IMPLIED_ALG = {("OKP", "Ed25519"): "Ed25519", ("EC", "P-256"): "ES256"}
+_HWK_MEMBERS = {"OKP": ("kty", "crv", "x"), "EC": ("kty", "crv", "x", "y")}
+
+
+class SignatureError(Exception):
+    """Verification failed.  ``code`` is a Signature-Error code (signature-key draft)."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True, slots=True)
+class SignedRequest:
+    label: str
+    alg: str
+    public_jwk: dict[str, str]
+    """The signer's key as a JWK, always with ``alg``."""
+    created: datetime
+    signature: bytes
+    base: bytes
+    """The signature base that ``signature`` was verified over."""
+
+
+def header_pairs(headers: Headers) -> list[tuple[str, str]]:
+    """``headers`` as a list, so that an iterator can be read more than once."""
+    # A Mapping is also an Iterable of its keys, so narrowing the union confuses type checkers.
+    pairs = cast("Mapping[str, str]", headers).items() if isinstance(headers, Mapping) else headers
+    return list(pairs)
+
+
+def _field_lines(headers: Headers) -> dict[str, list[str]]:
+    lines: dict[str, list[str]] = {}
+    for name, value in header_pairs(headers):
+        lines.setdefault(name.lower(), []).append(value.strip(" \t"))
+    return lines
+
+
+def content_digest(body: bytes) -> str:
+    return _sf.serialize_dictionary({"sha-256": _sf.Item(hashlib.sha256(body).digest())})
+
+
+def _check_digest(lines: Sequence[str] | None, body: bytes) -> None:
+    if not lines:
+        raise SignatureError("invalid_input", "missing Content-Digest")
+    try:
+        digests = _sf.parse_dictionary(lines)
+    except _sf.SFError as exc:
+        raise SignatureError("invalid_request", f"malformed Content-Digest: {exc}") from None
+    member = digests.get("sha-256")
+    if not isinstance(member, _sf.Item) or not isinstance(member.value, bytes):
+        raise SignatureError("invalid_request", "Content-Digest has no sha-256 digest")
+    if not hmac.compare_digest(member.value, hashlib.sha256(body).digest()):
+        raise SignatureError("invalid_signature", "Content-Digest does not match the body")
+
+
+def _derived(name: str, method: str, endpoint: str) -> str:
+    url = urlsplit(endpoint)
+    host = (url.hostname or "").lower()
+    authority = host if url.port in (None, 443) else f"{host}:{url.port}"
+    return {
+        "@method": method,
+        "@authority": authority,
+        "@path": url.path or "/",
+        "@scheme": url.scheme.lower(),
+        "@target-uri": endpoint,
+    }[name]
+
+
+def _signature_base(
+    components: _sf.InnerList,
+    *,
+    method: str,
+    endpoint: str,
+    lines: Mapping[str, list[str]],
+    required: Sequence[str] = REQUIRED_COMPONENTS,
+) -> bytes:
+    out: list[str] = []
+    seen: set[str] = set()
+    for component in components.items:
+        name = component.value
+        if not isinstance(name, str) or isinstance(name, _sf.Token) or component.params:
+            raise SignatureError("invalid_input", f"unsupported component {component!r}")
+        if name in seen:
+            raise SignatureError("invalid_input", f"component {name!r} is covered twice")
+        seen.add(name)
+        if name in _DERIVED:
+            value = _derived(name, method, endpoint)
+        elif name.startswith("@") or name != name.lower():
+            raise SignatureError("invalid_input", f"unsupported component {name!r}")
+        elif name not in lines:
+            raise SignatureError("invalid_input", f"covered field {name!r} is missing")
+        else:
+            value = ", ".join(lines[name])
+        out.append(f'"{name}": {value}')
+    if missing := [c for c in required if c not in seen]:
+        raise SignatureError("invalid_input", f"components not covered: {', '.join(missing)}")
+    out.append(f'"@signature-params": {_sf.serialize_inner_list(components)}')
+    try:
+        return "\n".join(out).encode("ascii")
+    except UnicodeEncodeError:
+        raise SignatureError("invalid_input", "covered field is not ASCII") from None
+
+
+def _hwk_jwk(member: _sf.Item | _sf.InnerList, *, require_alg: bool) -> dict[str, str]:
+    if not isinstance(member, _sf.Item) or not isinstance(member.value, _sf.Token):
+        raise SignatureError("unsupported_scheme", "Signature-Key member is not a scheme token")
+    if member.value != "hwk":
+        raise SignatureError("unsupported_scheme", "only the hwk Signature-Key scheme is supported")
+    params = member.params
+    if "kid" in params:
+        raise SignatureError("invalid_key", "hwk keys must not carry kid")
+    kty = params.get("kty")
+    if not isinstance(kty, str) or kty not in _HWK_MEMBERS:
+        raise SignatureError("invalid_key", "unsupported or missing kty")
+    jwk: dict[str, str] = {}
+    for name in _HWK_MEMBERS[kty]:
+        value = params.get(name)
+        if not isinstance(value, str) or isinstance(value, _sf.Token):
+            raise SignatureError("invalid_key", f"hwk {name} must be a string")
+        jwk[name] = value
+    alg = params.get("alg")
+    if alg is None and not require_alg:
+        alg = _IMPLIED_ALG.get((kty, jwk["crv"]))
+    if not isinstance(alg, str) or isinstance(alg, _sf.Token):
+        raise SignatureError("invalid_key", "hwk alg is missing or not a string")
+    jwk["alg"] = alg
+    return jwk
+
+
+def _single_label(lines: Mapping[str, list[str]]) -> tuple[str, Any, Any, Any]:
+    parsed = {}
+    for name in ("signature-input", "signature", "signature-key"):
+        if not lines.get(name):
+            raise SignatureError("invalid_signature", f"missing {name} header")
+        try:
+            parsed[name] = _sf.parse_dictionary(lines[name])
+        except _sf.SFError as exc:
+            raise SignatureError("invalid_signature", f"malformed {name}: {exc}") from None
+    keys = parsed["signature-key"]
+    if len(keys) != 1:
+        raise SignatureError("invalid_signature", "expected exactly one Signature-Key")
+    (label,) = keys
+    if label not in parsed["signature-input"] or label not in parsed["signature"]:
+        raise SignatureError("invalid_signature", f"no signature labelled {label!r}")
+    return label, parsed["signature-input"][label], parsed["signature"][label], keys[label]
+
+
+def verify_request(
+    *,
+    method: str,
+    endpoint: str,
+    headers: Headers,
+    body: bytes,
+    now: datetime,
+    max_age: timedelta,
+    algorithms: frozenset[str],
+    require_key_alg: bool,
+) -> SignedRequest:
+    """Verify the signature on a request to ``endpoint`` (the configured issuance URL).
+
+    ``algorithms`` are the fully specified algorithms accepted for the signer's key.
+    """
+    lines = _field_lines(headers)
+    label, components, signature, key_member = _single_label(lines)
+    if not isinstance(components, _sf.InnerList):
+        raise SignatureError("invalid_signature", "Signature-Input member is not an inner list")
+    if not isinstance(signature, _sf.Item) or not isinstance(signature.value, bytes):
+        raise SignatureError("invalid_signature", "Signature member is not a byte sequence")
+
+    jwk = _hwk_jwk(key_member, require_alg=require_key_alg)
+    alg = jwk["alg"]
+    if alg not in algorithms:
+        raise SignatureError("unsupported_algorithm", f"signature algorithm {alg!r} not accepted")
+    params = components.params
+    if "alg" in params and params["alg"] != alg:
+        raise SignatureError("invalid_signature", "Signature-Input alg contradicts the key")
+
+    created = params.get("created")
+    if not isinstance(created, int) or isinstance(created, bool):
+        raise SignatureError("invalid_signature", "Signature-Input has no integer created")
+    try:
+        created_at = datetime.fromtimestamp(created, UTC)
+    except (OverflowError, OSError, ValueError):
+        raise SignatureError(
+            "invalid_signature", "Signature-Input created is out of range"
+        ) from None
+    if created_at > now + max_age:
+        raise SignatureError("clock_skew", "signature created in the future")
+    if created_at < now - max_age:
+        raise SignatureError("invalid_signature", "signature is too old")
+    expires = params.get("expires")
+    if expires is not None and (
+        not isinstance(expires, int) or isinstance(expires, bool) or expires < now.timestamp()
+    ):
+        raise SignatureError("invalid_signature", "signature has expired")
+
+    base = _signature_base(components, method=method, endpoint=endpoint, lines=lines)
+    if not _jose.verify_raw(base, signature.value, jwk, alg):
+        if _jose.import_public(jwk) is None:
+            raise SignatureError("invalid_key", "the hwk public key is not valid")
+        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)
+
+
+def sign_request(
+    *,
+    method: str,
+    endpoint: str,
+    body: bytes,
+    private_key: Any,
+    public_jwk: Mapping[str, Any],
+    alg: str,
+    created: datetime,
+    label: str = "sig",
+    include_alg: bool = True,
+    signature_key: str | None = None,
+    digest: str | None = None,
+) -> dict[str, str]:
+    """Return the headers a browser adds to sign an issuance request (for tests).
+
+    ``signature_key`` and ``digest`` replace the generated ``Signature-Key`` and
+    ``Content-Digest`` values verbatim.
+    """
+    if signature_key is None:
+        members: dict[str, Any] = {k: public_jwk[k] for k in _HWK_MEMBERS[public_jwk["kty"]]}
+        if include_alg:
+            members["alg"] = alg
+        signature_key = _sf.serialize_dictionary({label: _sf.Item(_sf.Token("hwk"), members)})
+    headers = {
+        "Content-Type": "application/json",
+        "Sec-Fetch-Dest": "email-verification",
+        "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())}
+    )
+    base = _signature_base(
+        components, method=method, endpoint=endpoint, lines=_field_lines(headers)
+    )
+    signature = _jose.sign_raw(base, private_key, alg)
+    headers["Signature-Input"] = _sf.serialize_dictionary({label: components})
+    headers["Signature"] = _sf.serialize_dictionary({label: _sf.Item(signature)})
+    return headers

pyevp/_jose.py

@@ -0,0 +1,145 @@
+"""Thin wrappers over joserfc.  Nothing outside this module imports joserfc for verifying."""
+
+from __future__ import annotations
+
+import base64
+import json
+import warnings
+from collections.abc import Mapping
+from typing import Any
+
+from joserfc import jwk, jws
+from joserfc.errors import JoseError, SecurityWarning
+from joserfc.jws import JWSRegistry
+
+from pyevp.types import JSONObject
+
+# Never acceptable regardless of profile.
+FORBIDDEN_ALGORITHMS = frozenset({"none", "HS256", "HS384", "HS512"})
+
+_EC_CURVES = {"ES256": "P-256", "ES384": "P-384", "ES512": "P-521", "ES256K": "secp256k1"}
+_OKP_CURVES = {"Ed25519": {"Ed25519"}, "Ed448": {"Ed448"}, "EdDSA": {"Ed25519", "Ed448"}}
+_EDDSA_FAMILY = frozenset({"EdDSA", "Ed25519", "Ed448"})
+
+
+def b64url_decode(segment: str) -> bytes:
+    return base64.urlsafe_b64decode(segment + "=" * (-len(segment) % 4))
+
+
+def b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def decode_json_segment(segment: str) -> dict[str, Any]:
+    """Decode a base64url JSON object.  Raises ``ValueError`` on any problem."""
+    try:
+        value = json.loads(b64url_decode(segment))
+    except (ValueError, UnicodeDecodeError, RecursionError) as exc:
+        raise ValueError("segment is not base64url-encoded JSON") from exc
+    if not isinstance(value, dict):
+        raise ValueError("segment is not a JSON object")
+    try:
+        # JSON escapes can produce lone surrogates, which no string operation downstream expects.
+        json.dumps(value, ensure_ascii=False).encode()
+    except UnicodeEncodeError as exc:
+        raise ValueError("segment contains invalid Unicode") from exc
+    return value
+
+
+def algorithms_compatible(a: str, b: str) -> bool:
+    """Whether two ``alg`` values may name the same algorithm.
+
+    The polymorphic ``EdDSA`` (RFC 8037) covers the fully specified ``Ed25519`` and
+    ``Ed448`` (RFC 9864), but those two are different algorithms.
+    """
+    return a == b or ("EdDSA" in (a, b) and a in _EDDSA_FAMILY and b in _EDDSA_FAMILY)
+
+
+def key_supports(alg: str, key: Mapping[str, Any]) -> bool:
+    """Whether a public JWK can verify signatures made with ``alg``."""
+    if alg in FORBIDDEN_ALGORITHMS or not has_valid_members(key):
+        return False
+    if key.get("use") not in (None, "sig"):
+        return False
+    if "key_ops" in key and "verify" not in key["key_ops"]:
+        return False
+    key_alg = key.get("alg")
+    if isinstance(key_alg, str) and not algorithms_compatible(alg, key_alg):
+        return False
+    kty, crv = key.get("kty"), key.get("crv")
+    if alg in _OKP_CURVES:
+        # The key's own alg narrows the curve too: "EdDSA" against an Ed448-only key.
+        curves = _OKP_CURVES[alg] & _OKP_CURVES.get(key_alg, _OKP_CURVES[alg])
+        return kty == "OKP" and crv in curves
+    if alg in _EC_CURVES:
+        return kty == "EC" and crv == _EC_CURVES[alg]
+    if alg[:2] in ("RS", "PS"):
+        return kty == "RSA"
+    return False
+
+
+_STRING_MEMBERS = ("alg", "crv", "kid", "use")
+
+
+def has_valid_members(key: Mapping[str, Any]) -> bool:
+    """Whether the JWK members this library reads have the types RFC 7517 gives them."""
+    if not isinstance(key.get("kty"), str):
+        return False
+    if any(m in key and not isinstance(key[m], str) for m in _STRING_MEMBERS):
+        return False
+    if "key_ops" not in key:
+        return True
+    ops = key["key_ops"]
+    return isinstance(ops, list) and all(isinstance(o, str) for o in ops)
+
+
+def is_public_jwk(key: Mapping[str, Any]) -> bool:
+    return has_valid_members(key) and not any(p in key for p in ("d", "p", "q", "k"))
+
+
+def import_public(key: Mapping[str, Any]) -> Any | None:
+    """Import a public JWK, or return ``None`` if its key material is invalid."""
+    # joserfc enforces the JWK "alg" literally; alias handling is done by key_supports,
+    # which also checks "key_ops".
+    material = {k: v for k, v in key.items() if k not in ("alg", "key_ops")}
+    try:
+        return jwk.import_key(material)
+    except (JoseError, ValueError, TypeError):
+        return None
+
+
+def verify_compact(compact: str, key: JSONObject, alg: str) -> bool:
+    """Verify a compact JWS signature with a single public JWK."""
+    if not key_supports(alg, key) or (imported := import_public(key)) is None:
+        return False
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", SecurityWarning)
+            jws.deserialize_compact(compact, imported, algorithms=[alg])
+    except (JoseError, ValueError, TypeError):
+        return False
+    return True
+
+
+def sign_compact(header: JSONObject, claims: JSONObject, private_key: Any) -> str:
+    payload = json.dumps(dict(claims), separators=(",", ":")).encode()
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", SecurityWarning)
+        return jws.serialize_compact(dict(header), payload, private_key, algorithms=[header["alg"]])
+
+
+def verify_raw(message: bytes, signature: bytes, key: JSONObject, alg: str) -> bool:
+    """Verify a bare signature (JWS encoding: raw ``r || s`` for ECDSA) with a public JWK."""
+    if not key_supports(alg, key) or (imported := import_public(key)) is None:
+        return False
+    try:
+        return bool(JWSRegistry.algorithms[alg].verify(message, signature, imported))
+    except (JoseError, ValueError, TypeError):
+        return False
+
+
+def sign_raw(message: bytes, private_key: Any, alg: str) -> bytes:
+    """Sign ``message`` with a joserfc private key, in JWS signature encoding."""
+    if alg in FORBIDDEN_ALGORITHMS:
+        raise ValueError(f"refusing to sign with {alg!r}")
+    return JWSRegistry.algorithms[alg].sign(message, private_key)