devnomads 0.2.5__tar.gz → 0.3.1__tar.gz

{devnomads-0.2.5 → devnomads-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devnomads
-Version: 0.2.5
+Version: 0.3.1
 Summary: Python client library for the DevNomads API (transport, DNS, ACME)
 Project-URL: Homepage, https://devnomads.nl
 Author-email: DevNomads <support@devnomads.nl>
@@ -13,6 +13,7 @@ Requires-Dist: acme>=2.11; extra == 'acme'
 Requires-Dist: cryptography>=42; extra == 'acme'
 Requires-Dist: dnspython>=2.6; extra == 'acme'
 Requires-Dist: josepy>=1.14; extra == 'acme'
+Requires-Dist: requests>=2.31; extra == 'acme'
 Description-Content-Type: text/markdown
 
 # devnomads

{devnomads-0.2.5 → devnomads-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devnomads"
-version = "0.2.5"
+version = "0.3.1"
 description = "Python client library for the DevNomads API (transport, DNS, ACME)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,7 +17,13 @@ dependencies = ["httpx>=0.27"]
 # The ACME client pulls in the only heavy dependencies in the project, so
 # it lives behind an extra: `pip install devnomads[acme]`. Without it,
 # `import devnomads.acme` raises a clear, actionable ImportError.
-acme = ["acme>=2.11", "josepy>=1.14", "cryptography>=42", "dnspython>=2.6"]
+acme = [
+    "acme>=2.11",
+    "josepy>=1.14",
+    "cryptography>=42",
+    "dnspython>=2.6",
+    "requests>=2.31",
+]
 
 [project.urls]
 Homepage = "https://devnomads.nl"

{devnomads-0.2.5 → devnomads-0.3.1}/src/devnomads/acme/__init__.py

@@ -26,7 +26,7 @@ try:
         AcmeClient,
     )
     from .dns01 import DevNomadsDnsProvider, DnsProvider
-    from .errors import AcmeError
+    from .errors import AcmeError, TransientAcmeError
     from .http01 import Http01Solver, StandaloneSolver, WebrootSolver
     from .keys import (
         build_csr,
@@ -52,6 +52,7 @@ __all__ = [
     "ZEROSSL_DIRECTORY_URL",
     "CA_DIRECTORIES",
     "AcmeError",
+    "TransientAcmeError",
     "DnsProvider",
     "DevNomadsDnsProvider",
     "Http01Solver",

{devnomads-0.2.5 → devnomads-0.3.1}/src/devnomads/acme/client.py

@@ -3,16 +3,18 @@
 from __future__ import annotations
 
 import logging
+from contextlib import contextmanager
 from datetime import datetime, timedelta
 from time import sleep, time
 
+import requests
 from acme import challenges
 from acme import client as acme_client
 from acme import errors as acme_errors
 from acme import messages
 
 from .dns01 import DnsProvider
-from .errors import AcmeError
+from .errors import AcmeError, TransientAcmeError
 from .http01 import Http01Solver
 from .keys import (
     PrivateKey,
@@ -45,6 +47,35 @@ CA_DIRECTORIES = {
 # account registration.
 _EAB_REQUIRED_PROVIDERS = frozenset({"zerossl"})
 
+# ACME problem-document codes that mean "the CA had a problem", not "the
+# subject is broken". These are retry-safe: back off and try again later.
+_TRANSIENT_ACME_CODES = {"serverInternal", "rateLimited", "badNonce"}
+
+
+@contextmanager
+def _reraise_transient(step: str):
+    """Re-raise infrastructure-level failures as :class:`TransientAcmeError`.
+
+    Wraps a network-facing ACME step. Structural ACME errors (validation
+    failures, unauthorized, CAA, ...) pass through untouched so callers can
+    still treat them as permanent.
+    """
+
+    try:
+        yield
+    except requests.exceptions.RequestException as exc:
+        raise TransientAcmeError(f"{step}: CA unreachable: {exc}") from exc
+    except messages.Error as exc:
+        if exc.code in _TRANSIENT_ACME_CODES:
+            raise TransientAcmeError(f"{step}: {exc}", code=exc.code) from exc
+        raise
+    except (
+        acme_errors.TimeoutError,
+        acme_errors.PollError,
+        acme_errors.NonceError,
+    ) as exc:
+        raise TransientAcmeError(f"{step}: {exc}") from exc
+
 
 def _challenge_for_authz(challenge_types_map: dict[str, str], authz_body) -> str | None:
     """Resolve the configured challenge type for one authorization.
@@ -57,6 +88,9 @@ def _challenge_for_authz(challenge_types_map: dict[str, str], authz_body) -> str
     ident = getattr(getattr(authz_body, "identifier", None), "value", None)
     if ident is None:
         return None
+    # The map is keyed by lowercased identifiers; lowercase the authz value
+    # too (belt and braces — CAs already lowercase it) so the lookup matches.
+    ident = ident.lower()
     lookup = f"*.{ident}" if getattr(authz_body, "wildcard", False) else ident
     return challenge_types_map.get(lookup)
 
@@ -139,7 +173,8 @@ class AcmeClient:
         net = acme_client.ClientNetwork(
             account_key, alg=jws_alg(account_key), user_agent=self.user_agent
         )
-        directory = messages.Directory.from_json(net.get(self.directory_url).json())
+        with _reraise_transient("directory fetch"):
+            directory = messages.Directory.from_json(net.get(self.directory_url).json())
         client = acme_client.ClientV2(directory, net)
 
         registration_kwargs = dict(
@@ -161,14 +196,15 @@ class AcmeClient:
         new_account = messages.NewRegistration(**registration_kwargs)
 
         account = None
-        try:
-            account = client.new_account(new_account)
-        except acme_errors.ConflictError as exc:
-            uri = getattr(exc, "location", None) or getattr(
-                getattr(exc, "response", None), "headers", {}
-            ).get("Location")
-            if uri:
-                account = messages.RegistrationResource(body=None, uri=uri)
+        with _reraise_transient("account registration"):
+            try:
+                account = client.new_account(new_account)
+            except acme_errors.ConflictError as exc:
+                uri = getattr(exc, "location", None) or getattr(
+                    getattr(exc, "response", None), "headers", {}
+                ).get("Location")
+                if uri:
+                    account = messages.RegistrationResource(body=None, uri=uri)
 
         if account is None:
             account = getattr(client.net, "account", None)
@@ -183,13 +219,14 @@ class AcmeClient:
     def _wait_for_authz(self, client, authz, timeout: int = 300):
         deadline = time() + timeout
         while time() < deadline:
-            authz, _ = client.poll(authz)
+            with _reraise_transient("authorization poll"):
+                authz, _ = client.poll(authz)
             if authz.body.status == messages.STATUS_VALID:
                 return authz
             if authz.body.status == messages.STATUS_INVALID:
                 raise AcmeError(_authz_failure(authz.body))
             sleep(2)
-        raise AcmeError("authorization polling timed out")
+        raise TransientAcmeError("authorization polling timed out")
 
     def _fetch_order_authorizations(self, client, order):
         raw = getattr(order, "authorizations", None) or []
@@ -235,7 +272,8 @@ class AcmeClient:
         csr_pem = build_csr(domain_key, identifiers)
         log.info("requesting certificate for: %s", ", ".join(identifiers))
 
-        order = client.new_order(csr_pem)
+        with _reraise_transient("new order"):
+            order = client.new_order(csr_pem)
         authzs = self._fetch_order_authorizations(client, order)
 
         http_tokens: list[str] = []
@@ -258,9 +296,10 @@ class AcmeClient:
                     client, dns_challenges, dns_propagation_delay
                 )
 
-            order = client.poll_and_finalize(
-                order, deadline=datetime.now() + timedelta(seconds=300)
-            )
+            with _reraise_transient("finalize order"):
+                order = client.poll_and_finalize(
+                    order, deadline=datetime.now() + timedelta(seconds=300)
+                )
         finally:
             self._cleanup(http01_solver, http_tokens, dns_provider, dns_challenges)
 
@@ -308,7 +347,12 @@ class AcmeClient:
             if dns_challenges:
                 sleep(1)  # space out API calls to avoid rate limiting
             log.info("planting dns-01 challenge for %s", fqdn)
-            dns_provider.create_challenge(fqdn, validation)
+            try:
+                dns_provider.create_challenge(fqdn, validation)
+            except Exception as exc:  # noqa: BLE001
+                raise TransientAcmeError(
+                    f"dns provider failed to create challenge for {fqdn}: {exc}"
+                ) from exc
             dns_challenges.append((fqdn, challb, response, authz, validation))
         else:
             if not http01_solver:
@@ -317,7 +361,8 @@ class AcmeClient:
             log.info("serving http-01 challenge for %s", ident)
             http01_solver.set(token, validation)
             http_tokens.append(token)
-            client.answer_challenge(challb, response)
+            with _reraise_transient("answer challenge"):
+                client.answer_challenge(challb, response)
             self._wait_for_authz(client, authz)
 
     def _answer_dns_challenges(self, client, dns_challenges, delay: int) -> None:
@@ -329,13 +374,14 @@ class AcmeClient:
             if not verify_txt_record(
                 fqdn, validation, nameservers=self.recursive_nameservers
             ):
-                raise AcmeError(
+                raise TransientAcmeError(
                     f"DNS challenge verification failed for {fqdn}: "
                     "TXT record not found at authoritative nameservers"
                 )
         for fqdn, challb, response, authz, _ in dns_challenges:
             log.info("answering dns-01 challenge for %s", fqdn)
-            client.answer_challenge(challb, response)
+            with _reraise_transient("answer challenge"):
+                client.answer_challenge(challb, response)
             self._wait_for_authz(client, authz)
 
     def _cleanup(
@@ -372,7 +418,17 @@ class AcmeClient:
 
 
 def _normalize_identifiers(names: list[str]) -> list[str]:
-    """IDNA-encode and de-duplicate identifiers, preserving order."""
+    """IDNA-encode, lowercase and de-duplicate identifiers, preserving order.
+
+    DNS names are case-insensitive and ACME servers (Let's Encrypt) echo
+    authorization identifiers back lowercased. Python's IDNA codec, however,
+    preserves the case of plain-ASCII labels, so a mixed-case config entry
+    like ``www.Example.com`` would otherwise key the challenge-type map in a
+    case the CA never uses — the challenge lookup at answer time then misses
+    and issuance fails with "no challenge type configured". Lowercasing here
+    keeps every identifier canonical (punycode output is already lowercase,
+    so this is a no-op for internationalised names).
+    """
 
     identifiers: list[str] = []
     seen: set[str] = set()
@@ -380,7 +436,7 @@ def _normalize_identifiers(names: list[str]) -> list[str]:
         if not name:
             continue
         try:
-            ascii_name = name.encode("idna").decode("ascii")
+            ascii_name = name.encode("idna").decode("ascii").lower()
         except Exception:  # noqa: BLE001  # nosec B112
             continue
         if ascii_name not in seen:
@@ -399,11 +455,14 @@ def _normalize_challenge_types(
 
     result: dict[str, str] = {}
     for ident in identifiers:
+        # ``identifiers`` are already IDNA-normalised and lowercased; resolve
+        # each against the caller's map case-insensitively so a mixed-case
+        # key (``www.Example.com``) still matches its lowercased identifier.
         ct = challenge_types.get(ident)
         if ct is None:
             for key, value in challenge_types.items():
                 try:
-                    if key.encode("idna").decode("ascii") == ident:
+                    if key.encode("idna").decode("ascii").lower() == ident:
                         ct = value
                         break
                 except Exception:  # noqa: BLE001  # nosec B112

devnomads-0.3.1/src/devnomads/acme/errors.py

@@ -0,0 +1,27 @@
+"""ACME-specific exceptions."""
+
+from __future__ import annotations
+
+from ..api.errors import DevNomadsError
+
+
+class AcmeError(DevNomadsError):
+    """An ACME issuance step failed."""
+
+
+class TransientAcmeError(AcmeError):
+    """A retry-safe ACME failure (CA unreachable, rate limit,
+    propagation timeout, DNS provider outage). The operation may
+    succeed if simply retried later; callers should back off and
+    retry rather than treat the subject as permanently broken.
+
+    ``code`` carries the bare ACME error code when one is known
+    (e.g. ``"rateLimited"``, ``"serverInternal"``) so callers can
+    apply per-code retry policy without string-matching the
+    message. None when the failure was not an ACME problem
+    document (network error, propagation timeout, ...).
+    """
+
+    def __init__(self, message: str, *, code: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code

{devnomads-0.2.5 → devnomads-0.3.1}/tests/test_acme_client.py

@@ -6,11 +6,12 @@ from types import SimpleNamespace
 
 import pytest
 
-from devnomads.acme import AcmeError
+from devnomads.acme import AcmeError, TransientAcmeError
 from devnomads.acme.client import (
     _challenge_for_authz,
     _normalize_challenge_types,
     _normalize_identifiers,
+    _reraise_transient,
     _split_fullchain,
 )
 
@@ -50,6 +51,29 @@ def test_challenge_for_authz_wildcard_reprefixes():
     assert _challenge_for_authz({"*.example.com": "dns-01"}, body) == "dns-01"
 
 
+def test_normalize_identifiers_lowercases():
+    # DNS is case-insensitive and CAs lowercase identifiers; a mixed-case
+    # ASCII label must not survive with its original case (Python's IDNA
+    # codec would otherwise preserve it).
+    assert _normalize_identifiers(["www.Ahlersbuilding.BE"]) == [
+        "www.ahlersbuilding.be"
+    ]
+
+
+def test_mixed_case_challenge_map_resolves_against_lowercased_authz():
+    """Regression: a mixed-case config entry keyed the challenge-type map in
+    a case the CA never uses, so the challenge lookup missed and issuance
+    failed with "no challenge type configured". The map must resolve against
+    the lowercased authorization identifier the CA echoes back."""
+    # certmonger builds the map keyed by the original (mixed) case:
+    challenge_types = {"www.Ahlersbuilding.be": "dns-01"}
+    identifiers = _normalize_identifiers(["www.Ahlersbuilding.be"])
+    types_map = _normalize_challenge_types(challenge_types, identifiers)
+    # LE hands back the identifier lowercased:
+    body = _authz("www.ahlersbuilding.be", False)
+    assert _challenge_for_authz(types_map, body) == "dns-01"
+
+
 def test_split_fullchain():
     leaf = "-----BEGIN CERTIFICATE-----\nAAA\n-----END CERTIFICATE-----\n"
     rest = "-----BEGIN CERTIFICATE-----\nBBB\n-----END CERTIFICATE-----\n"
@@ -227,3 +251,132 @@ def test_partial_eab_credentials_raise(tmp_path):
 
     with pytest.raises(AcmeError):
         client_mod.AcmeClient(str(tmp_path / "a.pem"), eab_kid="kid-only")
+
+
+# -- WI-1: transient/structural ACME failure classification ---------------
+
+
+def test_transient_error_is_acme_error_subclass():
+    """Callers that catch AcmeError must still catch the transient variant,
+    so the outer 'blacklist everything' net keeps working if a caller has
+    not yet special-cased transients."""
+
+    assert issubclass(TransientAcmeError, AcmeError)
+    exc = TransientAcmeError("boom", code="rateLimited")
+    assert exc.code == "rateLimited"
+    assert TransientAcmeError("boom").code is None
+
+
+def test_reraise_transient_wraps_request_exception():
+    import requests
+
+    with pytest.raises(TransientAcmeError) as ei:
+        with _reraise_transient("directory fetch"):
+            raise requests.exceptions.ConnectTimeout("no route to CA")
+    assert ei.value.code is None
+    assert "directory fetch" in str(ei.value)
+
+
+@pytest.mark.parametrize("code", ["serverInternal", "rateLimited", "badNonce"])
+def test_reraise_transient_wraps_transient_acme_codes(code):
+    from acme import messages
+
+    with pytest.raises(TransientAcmeError) as ei:
+        with _reraise_transient("new order"):
+            raise messages.Error.with_code(code)
+    assert ei.value.code == code
+
+
+@pytest.mark.parametrize("code", ["unauthorized", "caa", "rejectedIdentifier"])
+def test_reraise_transient_passes_structural_acme_codes(code):
+    """Structural ACME problem documents must escape as plain messages.Error
+    (not TransientAcmeError) so the caller still blacklists the domain."""
+
+    from acme import messages
+
+    err = messages.Error.with_code(code)
+    with pytest.raises(messages.Error) as ei:
+        with _reraise_transient("new order"):
+            raise err
+    assert not isinstance(ei.value, TransientAcmeError)
+    assert ei.value is err
+
+
+@pytest.mark.parametrize("exc_name", ["TimeoutError", "PollError", "NonceError"])
+def test_reraise_transient_wraps_acme_poll_errors(exc_name):
+    from acme import errors as acme_errors
+
+    exc_cls = getattr(acme_errors, exc_name)
+    try:
+        raised = exc_cls("boom")
+    except TypeError:
+        # PollError's constructor signature differs across acme versions.
+        raised = exc_cls(set(), {})
+
+    with pytest.raises(TransientAcmeError):
+        with _reraise_transient("authorization poll"):
+            raise raised
+
+
+def test_reraise_transient_passes_unrelated_exceptions():
+    with pytest.raises(ValueError):
+        with _reraise_transient("new order"):
+            raise ValueError("not an acme failure")
+
+
+def _dns01_authz(ident):
+    from acme import challenges
+
+    challb = SimpleNamespace(
+        chall=challenges.DNS01(token=b"\x00" * 32),
+        response_and_validation=lambda key: (SimpleNamespace(), "validation-string"),
+    )
+    body = SimpleNamespace(
+        identifier=SimpleNamespace(value=ident),
+        status=SimpleNamespace(name="pending"),
+        challenges=[challb],
+        wildcard=False,
+    )
+    return SimpleNamespace(body=body)
+
+
+def test_setup_authz_dns_provider_failure_is_transient(tmp_path):
+    """A DNS provider outage (API down, bad credentials, network) is an
+    infrastructure problem, never a statement about the domain."""
+
+    from devnomads.acme import client as client_mod
+
+    class BadProvider:
+        def create_challenge(self, fqdn, validation):
+            raise RuntimeError("dns api down")
+
+    ac = client_mod.AcmeClient(str(tmp_path / "a.pem"))
+    authz = _dns01_authz("example.com")
+
+    with pytest.raises(TransientAcmeError) as ei:
+        ac._setup_authz(
+            client=None,
+            account_key=None,
+            authz=authz,
+            types_map={"example.com": "dns-01"},
+            dns_provider=BadProvider(),
+            http01_solver=None,
+            http_tokens=[],
+            dns_challenges=[],
+        )
+    assert "dns provider failed" in str(ei.value)
+
+
+def test_answer_dns_challenges_txt_timeout_is_transient(monkeypatch, tmp_path):
+    """Slow TXT propagation is retry-safe, not a permanent failure."""
+
+    from devnomads.acme import client as client_mod
+
+    monkeypatch.setattr(client_mod, "verify_txt_record", lambda *a, **k: False)
+
+    ac = client_mod.AcmeClient(str(tmp_path / "a.pem"))
+    dns_challenges = [("example.com", object(), object(), object(), "validation")]
+
+    with pytest.raises(TransientAcmeError) as ei:
+        ac._answer_dns_challenges(client=None, dns_challenges=dns_challenges, delay=0)
+    assert "TXT record not found" in str(ei.value)

{devnomads-0.2.5 → devnomads-0.3.1}/uv.lock

@@ -468,7 +468,7 @@ wheels = [
 
 [[package]]
 name = "devnomads"
-version = "0.2.4"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
@@ -480,6 +480,7 @@ acme = [
     { name = "cryptography" },
     { name = "dnspython" },
     { name = "josepy" },
+    { name = "requests" },
 ]
 
 [package.dev-dependencies]
@@ -502,6 +503,7 @@ requires-dist = [
     { name = "dnspython", marker = "extra == 'acme'", specifier = ">=2.6" },
     { name = "httpx", specifier = ">=0.27" },
     { name = "josepy", marker = "extra == 'acme'", specifier = ">=1.14" },
+    { name = "requests", marker = "extra == 'acme'", specifier = ">=2.31" },
 ]
 
 [package.metadata.requires-dev]

devnomads-0.2.5/src/devnomads/acme/errors.py

@@ -1,9 +0,0 @@
-"""ACME-specific exceptions."""
-
-from __future__ import annotations
-
-from ..api.errors import DevNomadsError
-
-
-class AcmeError(DevNomadsError):
-    """An ACME issuance step failed."""