devnomads 0.2.4__tar.gz → 0.3.0__tar.gz

devnomads-0.2.4/README.md → devnomads-0.3.0/PKG-INFO

@@ -1,3 +1,21 @@
+Metadata-Version: 2.4
+Name: devnomads
+Version: 0.3.0
+Summary: Python client library for the DevNomads API (transport, DNS, ACME)
+Project-URL: Homepage, https://devnomads.nl
+Author-email: DevNomads <support@devnomads.nl>
+License: MIT
+Keywords: acme,api,devnomads,dns,powerdns
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: acme
+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
 
 Python client library for the [DevNomads](https://devnomads.nl) API:
@@ -303,9 +321,16 @@ AcmeClient(
     preferred_chain=None,                   # match alternate chain by CN
     recursive_nameservers=None,             # resolvers for propagation
     user_agent="devnomads",
+    eab_kid=None,                           # external account binding key id
+    eab_hmac_key=None,                      # external account binding HMAC key
+    eab_hmac_alg="HS256",                   # HS256/HS384/HS512
 )
 ```
 
+Let's Encrypt remains the default CA. Any ACME v2 CA works by passing its
+`directory_url`; CAs that mandate External Account Binding (such as ZeroSSL)
+also need `eab_kid` and `eab_hmac_key`.
+
 The account key at `account_key_path` is loaded if present and created
 (mode 0600) otherwise.
 
@@ -402,6 +427,34 @@ acme = AcmeClient(
 )
 ```
 
+### Providers (Let's Encrypt, ZeroSSL)
+
+`for_provider` resolves a named CA from `CA_DIRECTORIES`
+(`letsencrypt`, `letsencrypt-staging`, `zerossl`) so you do not have to
+remember directory URLs. Let's Encrypt stays the default everywhere else.
+
+```python
+from devnomads.acme import AcmeClient
+
+# Let's Encrypt (default CA) - no EAB needed.
+acme = AcmeClient.for_provider("letsencrypt", "/etc/devnomads/account.key")
+
+# ZeroSSL - requires External Account Binding credentials from your
+# ZeroSSL account (Developer -> EAB Credentials, or the REST API).
+acme = AcmeClient.for_provider(
+    "zerossl",
+    "/etc/devnomads/zerossl-account.key",
+    contact_email="ops@example.com",
+    eab_kid="...",        # EAB key id
+    eab_hmac_key="...",   # base64url EAB HMAC key
+)
+```
+
+Issuance is otherwise identical - the same `obtain_certificate` calls,
+DNS-01/HTTP-01 solvers, and chain selection apply to every provider. The
+directory URL and EAB fields can also be passed straight to the
+`AcmeClient(...)` constructor if you prefer not to use the alias.
+
 ### Key helpers
 
 ```python

devnomads-0.2.4/PKG-INFO → devnomads-0.3.0/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.4
-Name: devnomads
-Version: 0.2.4
-Summary: Python client library for the DevNomads API (transport, DNS, ACME)
-Project-URL: Homepage, https://devnomads.nl
-Author-email: DevNomads <support@devnomads.nl>
-License: MIT
-Keywords: acme,api,devnomads,dns,powerdns
-Requires-Python: >=3.10
-Requires-Dist: httpx>=0.27
-Provides-Extra: acme
-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'
-Description-Content-Type: text/markdown
-
 # devnomads
 
 Python client library for the [DevNomads](https://devnomads.nl) API:
@@ -320,9 +303,16 @@ AcmeClient(
     preferred_chain=None,                   # match alternate chain by CN
     recursive_nameservers=None,             # resolvers for propagation
     user_agent="devnomads",
+    eab_kid=None,                           # external account binding key id
+    eab_hmac_key=None,                      # external account binding HMAC key
+    eab_hmac_alg="HS256",                   # HS256/HS384/HS512
 )
 ```
 
+Let's Encrypt remains the default CA. Any ACME v2 CA works by passing its
+`directory_url`; CAs that mandate External Account Binding (such as ZeroSSL)
+also need `eab_kid` and `eab_hmac_key`.
+
 The account key at `account_key_path` is loaded if present and created
 (mode 0600) otherwise.
 
@@ -419,6 +409,34 @@ acme = AcmeClient(
 )
 ```
 
+### Providers (Let's Encrypt, ZeroSSL)
+
+`for_provider` resolves a named CA from `CA_DIRECTORIES`
+(`letsencrypt`, `letsencrypt-staging`, `zerossl`) so you do not have to
+remember directory URLs. Let's Encrypt stays the default everywhere else.
+
+```python
+from devnomads.acme import AcmeClient
+
+# Let's Encrypt (default CA) - no EAB needed.
+acme = AcmeClient.for_provider("letsencrypt", "/etc/devnomads/account.key")
+
+# ZeroSSL - requires External Account Binding credentials from your
+# ZeroSSL account (Developer -> EAB Credentials, or the REST API).
+acme = AcmeClient.for_provider(
+    "zerossl",
+    "/etc/devnomads/zerossl-account.key",
+    contact_email="ops@example.com",
+    eab_kid="...",        # EAB key id
+    eab_hmac_key="...",   # base64url EAB HMAC key
+)
+```
+
+Issuance is otherwise identical - the same `obtain_certificate` calls,
+DNS-01/HTTP-01 solvers, and chain selection apply to every provider. The
+directory URL and EAB fields can also be passed straight to the
+`AcmeClient(...)` constructor if you prefer not to use the alias.
+
 ### Key helpers
 
 ```python

{devnomads-0.2.4 → devnomads-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devnomads"
-version = "0.2.4"
+version = "0.3.0"
 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.4 → devnomads-0.3.0}/src/devnomads/acme/__init__.py

@@ -17,9 +17,16 @@ _EXTRA_MODULES = {"acme", "josepy", "cryptography", "dns"}
 
 try:
     from .challenge_server import ChallengeServer
-    from .client import DEFAULT_DIRECTORY_URL, AcmeClient
+    from .client import (
+        CA_DIRECTORIES,
+        DEFAULT_DIRECTORY_URL,
+        LETSENCRYPT_DIRECTORY_URL,
+        LETSENCRYPT_STAGING_DIRECTORY_URL,
+        ZEROSSL_DIRECTORY_URL,
+        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,
@@ -40,7 +47,12 @@ except ImportError as exc:  # pragma: no cover - exercised via packaging
 __all__ = [
     "AcmeClient",
     "DEFAULT_DIRECTORY_URL",
+    "LETSENCRYPT_DIRECTORY_URL",
+    "LETSENCRYPT_STAGING_DIRECTORY_URL",
+    "ZEROSSL_DIRECTORY_URL",
+    "CA_DIRECTORIES",
     "AcmeError",
+    "TransientAcmeError",
     "DnsProvider",
     "DevNomadsDnsProvider",
     "Http01Solver",

{devnomads-0.2.4 → devnomads-0.3.0}/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,
@@ -25,7 +27,54 @@ from .verify import verify_txt_record
 
 log = logging.getLogger("devnomads.acme")
 
-DEFAULT_DIRECTORY_URL = "https://acme-v02.api.letsencrypt.org/directory"
+LETSENCRYPT_DIRECTORY_URL = "https://acme-v02.api.letsencrypt.org/directory"
+LETSENCRYPT_STAGING_DIRECTORY_URL = (
+    "https://acme-staging-v02.api.letsencrypt.org/directory"
+)
+ZEROSSL_DIRECTORY_URL = "https://acme.zerossl.com/v2/DV90"
+
+# Let's Encrypt remains the default CA everywhere it is not specified.
+DEFAULT_DIRECTORY_URL = LETSENCRYPT_DIRECTORY_URL
+
+# Named ACME providers, resolvable via :meth:`AcmeClient.for_provider`.
+CA_DIRECTORIES = {
+    "letsencrypt": LETSENCRYPT_DIRECTORY_URL,
+    "letsencrypt-staging": LETSENCRYPT_STAGING_DIRECTORY_URL,
+    "zerossl": ZEROSSL_DIRECTORY_URL,
+}
+
+# Providers that mandate External Account Binding (RFC 8555 §7.3.4) for new
+# 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:
@@ -61,7 +110,14 @@ class AcmeClient:
         preferred_chain: str | None = None,
         recursive_nameservers: list[str] | None = None,
         user_agent: str = "devnomads",
+        eab_kid: str | None = None,
+        eab_hmac_key: str | None = None,
+        eab_hmac_alg: str = "HS256",
     ) -> None:
+        if bool(eab_kid) != bool(eab_hmac_key):
+            raise AcmeError(
+                "external account binding requires both eab_kid and eab_hmac_key"
+            )
         self.account_key_path = account_key_path
         self.directory_url = directory_url
         self.account_key_algorithm = account_key_algorithm
@@ -69,6 +125,39 @@ class AcmeClient:
         self.preferred_chain = preferred_chain
         self.recursive_nameservers = recursive_nameservers
         self.user_agent = user_agent
+        self.eab_kid = eab_kid
+        self.eab_hmac_key = eab_hmac_key
+        self.eab_hmac_alg = eab_hmac_alg
+
+    @classmethod
+    def for_provider(
+        cls, provider: str, account_key_path: str, **kwargs
+    ) -> "AcmeClient":
+        """Build a client for a named CA from :data:`CA_DIRECTORIES`.
+
+        ``provider`` is one of ``"letsencrypt"`` (the default CA),
+        ``"letsencrypt-staging"`` or ``"zerossl"``. Providers that mandate
+        External Account Binding (e.g. ZeroSSL) require ``eab_kid`` and
+        ``eab_hmac_key`` keyword arguments. Any other keyword is forwarded to
+        :class:`AcmeClient`.
+        """
+
+        try:
+            directory_url = CA_DIRECTORIES[provider]
+        except KeyError:
+            raise AcmeError(
+                f"unknown ACME provider {provider!r}; "
+                f"known providers: {', '.join(sorted(CA_DIRECTORIES))}"
+            ) from None
+        if provider in _EAB_REQUIRED_PROVIDERS and not (
+            kwargs.get("eab_kid") and kwargs.get("eab_hmac_key")
+        ):
+            raise AcmeError(
+                f"provider {provider!r} requires external account binding; "
+                "pass eab_kid and eab_hmac_key"
+            )
+        kwargs.pop("directory_url", None)
+        return cls(account_key_path, directory_url=directory_url, **kwargs)
 
     # -- account / client setup -------------------------------------------
 
@@ -81,24 +170,38 @@ 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)
 
-        new_account = messages.NewRegistration(
+        registration_kwargs = dict(
             contact=(f"mailto:{self.contact_email}",) if self.contact_email else (),
             terms_of_service_agreed=True,
             only_return_existing=False,
         )
+        if self.eab_kid and self.eab_hmac_key:
+            log.debug("attaching external account binding (kid=%s)", self.eab_kid)
+            registration_kwargs["external_account_binding"] = (
+                messages.ExternalAccountBinding.from_data(
+                    account_key.public_key(),
+                    self.eab_kid,
+                    self.eab_hmac_key,
+                    directory,
+                    hmac_alg=self.eab_hmac_alg,
+                )
+            )
+        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)
@@ -113,13 +216,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 []
@@ -165,7 +269,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] = []
@@ -188,9 +293,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)
 
@@ -238,7 +344,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:
@@ -247,7 +358,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:
@@ -259,13 +371,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(

devnomads-0.3.0/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.3.0/tests/test_acme_client.py

@@ -0,0 +1,359 @@
+"""Tests for the pure helpers of the ACME client."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from devnomads.acme import AcmeError, TransientAcmeError
+from devnomads.acme.client import (
+    _challenge_for_authz,
+    _normalize_challenge_types,
+    _normalize_identifiers,
+    _reraise_transient,
+    _split_fullchain,
+)
+
+
+def test_normalize_identifiers_dedup_preserves_order():
+    assert _normalize_identifiers(["a.com", "b.com", "a.com", ""]) == ["a.com", "b.com"]
+
+
+def test_normalize_challenge_types_string_applies_to_all():
+    assert _normalize_challenge_types("dns-01", ["a.com", "b.com"]) == {
+        "a.com": "dns-01",
+        "b.com": "dns-01",
+    }
+
+
+def test_normalize_challenge_types_dict_per_identifier():
+    mapping = {"a.com": "dns-01", "b.com": "http-01"}
+    assert _normalize_challenge_types(mapping, ["a.com", "b.com"]) == mapping
+
+
+def test_normalize_challenge_types_missing_raises():
+    with pytest.raises(AcmeError):
+        _normalize_challenge_types({"a.com": "dns-01"}, ["a.com", "b.com"])
+
+
+def _authz(value, wildcard):
+    return SimpleNamespace(identifier=SimpleNamespace(value=value), wildcard=wildcard)
+
+
+def test_challenge_for_authz_plain():
+    body = _authz("example.com", False)
+    assert _challenge_for_authz({"example.com": "dns-01"}, body) == "dns-01"
+
+
+def test_challenge_for_authz_wildcard_reprefixes():
+    body = _authz("example.com", True)
+    assert _challenge_for_authz({"*.example.com": "dns-01"}, body) == "dns-01"
+
+
+def test_split_fullchain():
+    leaf = "-----BEGIN CERTIFICATE-----\nAAA\n-----END CERTIFICATE-----\n"
+    rest = "-----BEGIN CERTIFICATE-----\nBBB\n-----END CERTIFICATE-----\n"
+    leaf_pem, chain_pem = _split_fullchain(leaf + rest)
+    assert leaf_pem == leaf
+    assert chain_pem == rest
+
+
+def test_split_fullchain_no_marker():
+    leaf_pem, chain_pem = _split_fullchain("garbage")
+    assert leaf_pem == "garbage"
+    assert chain_pem == ""
+
+
+def test_init_client_registers_with_new_registration(monkeypatch, tmp_path):
+    """_init_client must build a real acme.messages.NewRegistration and hand
+    it to new_account; this exercises the message construction that a wrong
+    class name (e.g. the non-existent NewAccount) would break."""
+
+    import josepy
+    from acme import messages
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives.asymmetric import ec
+    from josepy import jwk
+
+    from devnomads.acme import client as client_mod
+
+    captured = {}
+    account_key = jwk.JWKEC(
+        key=ec.generate_private_key(ec.SECP256R1(), backend=default_backend())
+    )
+
+    class FakeResponse:
+        def json(self):
+            return {}
+
+    class FakeNetwork:
+        def __init__(self, *args, **kwargs):
+            captured["alg"] = kwargs.get("alg")
+            self.account = None
+
+        def get(self, url):
+            return FakeResponse()
+
+    class FakeClientV2:
+        def __init__(self, directory, net):
+            self.net = net
+
+        def new_account(self, registration):
+            captured["registration"] = registration
+            return SimpleNamespace(uri="https://acme.example/acct/1")
+
+    monkeypatch.setattr(
+        client_mod, "load_or_create_account_key", lambda *a, **k: account_key
+    )
+    monkeypatch.setattr(client_mod.acme_client, "ClientNetwork", FakeNetwork)
+    monkeypatch.setattr(client_mod.acme_client, "ClientV2", FakeClientV2)
+    monkeypatch.setattr(
+        client_mod.messages.Directory, "from_json", lambda data: object()
+    )
+
+    ac = client_mod.AcmeClient(
+        str(tmp_path / "account.pem"), contact_email="ops@example.com"
+    )
+    client, _account_key = ac._init_client()
+
+    # an EC account key must be signed with ES256, not the ClientNetwork
+    # default of RS256, or josepy rejects the JWS.
+    assert captured["alg"] == josepy.ES256
+    registration = captured["registration"]
+    assert isinstance(registration, messages.NewRegistration)
+    assert registration.contact == ("mailto:ops@example.com",)
+    # without EAB credentials, no external account binding is attached
+    assert not registration.external_account_binding
+    assert client.net.account is not None
+
+
+def _patch_fake_network(monkeypatch, client_mod, account_key, captured, directory):
+    from types import SimpleNamespace
+
+    class FakeResponse:
+        def json(self):
+            return {}
+
+    class FakeNetwork:
+        def __init__(self, *args, **kwargs):
+            self.account = None
+
+        def get(self, url):
+            return FakeResponse()
+
+    class FakeClientV2:
+        def __init__(self, directory, net):
+            self.net = net
+
+        def new_account(self, registration):
+            captured["registration"] = registration
+            return SimpleNamespace(uri="https://acme.example/acct/1")
+
+    monkeypatch.setattr(
+        client_mod, "load_or_create_account_key", lambda *a, **k: account_key
+    )
+    monkeypatch.setattr(client_mod.acme_client, "ClientNetwork", FakeNetwork)
+    monkeypatch.setattr(client_mod.acme_client, "ClientV2", FakeClientV2)
+    monkeypatch.setattr(
+        client_mod.messages.Directory, "from_json", lambda data: directory
+    )
+
+
+def test_init_client_attaches_external_account_binding(monkeypatch, tmp_path):
+    """When EAB credentials are supplied, _init_client must attach an
+    externalAccountBinding to the NewRegistration (required by ZeroSSL)."""
+
+    from acme import messages
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives.asymmetric import ec
+    from josepy import jwk
+
+    from devnomads.acme import client as client_mod
+
+    captured = {}
+    account_key = jwk.JWKEC(
+        key=ec.generate_private_key(ec.SECP256R1(), backend=default_backend())
+    )
+    directory = messages.Directory.from_json(
+        {"newAccount": "https://acme.example/new-acct"}
+    )
+    _patch_fake_network(monkeypatch, client_mod, account_key, captured, directory)
+
+    ac = client_mod.AcmeClient(
+        str(tmp_path / "account.pem"),
+        directory_url=client_mod.ZEROSSL_DIRECTORY_URL,
+        eab_kid="kid-123",
+        # HMAC key must be valid base64; this is "hmac-secret" encoded.
+        eab_hmac_key="aG1hYy1zZWNyZXQ",
+    )
+    ac._init_client()
+
+    registration = captured["registration"]
+    assert registration.external_account_binding  # signed JWS dict
+
+
+def test_for_provider_resolves_directory_urls(tmp_path):
+    from devnomads.acme import client as client_mod
+
+    le = client_mod.AcmeClient.for_provider("letsencrypt", str(tmp_path / "a.pem"))
+    assert le.directory_url == client_mod.LETSENCRYPT_DIRECTORY_URL
+
+    zs = client_mod.AcmeClient.for_provider(
+        "zerossl",
+        str(tmp_path / "b.pem"),
+        eab_kid="kid-123",
+        eab_hmac_key="aG1hYy1zZWNyZXQ",
+    )
+    assert zs.directory_url == client_mod.ZEROSSL_DIRECTORY_URL
+    assert zs.eab_kid == "kid-123"
+
+
+def test_for_provider_unknown_raises(tmp_path):
+    from devnomads.acme import client as client_mod
+
+    with pytest.raises(AcmeError):
+        client_mod.AcmeClient.for_provider("notaca", str(tmp_path / "a.pem"))
+
+
+def test_for_provider_zerossl_requires_eab(tmp_path):
+    from devnomads.acme import client as client_mod
+
+    with pytest.raises(AcmeError):
+        client_mod.AcmeClient.for_provider("zerossl", str(tmp_path / "a.pem"))
+
+
+def test_partial_eab_credentials_raise(tmp_path):
+    from devnomads.acme import client as client_mod
+
+    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.4 → devnomads-0.3.0}/uv.lock

@@ -468,7 +468,7 @@ wheels = [
 
 [[package]]
 name = "devnomads"
-version = "0.2.4"
+version = "0.2.5"
 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.4/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."""

devnomads-0.2.4/tests/test_acme_client.py

@@ -1,125 +0,0 @@
-"""Tests for the pure helpers of the ACME client."""
-
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-import pytest
-
-from devnomads.acme import AcmeError
-from devnomads.acme.client import (
-    _challenge_for_authz,
-    _normalize_challenge_types,
-    _normalize_identifiers,
-    _split_fullchain,
-)
-
-
-def test_normalize_identifiers_dedup_preserves_order():
-    assert _normalize_identifiers(["a.com", "b.com", "a.com", ""]) == ["a.com", "b.com"]
-
-
-def test_normalize_challenge_types_string_applies_to_all():
-    assert _normalize_challenge_types("dns-01", ["a.com", "b.com"]) == {
-        "a.com": "dns-01",
-        "b.com": "dns-01",
-    }
-
-
-def test_normalize_challenge_types_dict_per_identifier():
-    mapping = {"a.com": "dns-01", "b.com": "http-01"}
-    assert _normalize_challenge_types(mapping, ["a.com", "b.com"]) == mapping
-
-
-def test_normalize_challenge_types_missing_raises():
-    with pytest.raises(AcmeError):
-        _normalize_challenge_types({"a.com": "dns-01"}, ["a.com", "b.com"])
-
-
-def _authz(value, wildcard):
-    return SimpleNamespace(identifier=SimpleNamespace(value=value), wildcard=wildcard)
-
-
-def test_challenge_for_authz_plain():
-    body = _authz("example.com", False)
-    assert _challenge_for_authz({"example.com": "dns-01"}, body) == "dns-01"
-
-
-def test_challenge_for_authz_wildcard_reprefixes():
-    body = _authz("example.com", True)
-    assert _challenge_for_authz({"*.example.com": "dns-01"}, body) == "dns-01"
-
-
-def test_split_fullchain():
-    leaf = "-----BEGIN CERTIFICATE-----\nAAA\n-----END CERTIFICATE-----\n"
-    rest = "-----BEGIN CERTIFICATE-----\nBBB\n-----END CERTIFICATE-----\n"
-    leaf_pem, chain_pem = _split_fullchain(leaf + rest)
-    assert leaf_pem == leaf
-    assert chain_pem == rest
-
-
-def test_split_fullchain_no_marker():
-    leaf_pem, chain_pem = _split_fullchain("garbage")
-    assert leaf_pem == "garbage"
-    assert chain_pem == ""
-
-
-def test_init_client_registers_with_new_registration(monkeypatch, tmp_path):
-    """_init_client must build a real acme.messages.NewRegistration and hand
-    it to new_account; this exercises the message construction that a wrong
-    class name (e.g. the non-existent NewAccount) would break."""
-
-    import josepy
-    from acme import messages
-    from cryptography.hazmat.backends import default_backend
-    from cryptography.hazmat.primitives.asymmetric import ec
-    from josepy import jwk
-
-    from devnomads.acme import client as client_mod
-
-    captured = {}
-    account_key = jwk.JWKEC(
-        key=ec.generate_private_key(ec.SECP256R1(), backend=default_backend())
-    )
-
-    class FakeResponse:
-        def json(self):
-            return {}
-
-    class FakeNetwork:
-        def __init__(self, *args, **kwargs):
-            captured["alg"] = kwargs.get("alg")
-            self.account = None
-
-        def get(self, url):
-            return FakeResponse()
-
-    class FakeClientV2:
-        def __init__(self, directory, net):
-            self.net = net
-
-        def new_account(self, registration):
-            captured["registration"] = registration
-            return SimpleNamespace(uri="https://acme.example/acct/1")
-
-    monkeypatch.setattr(
-        client_mod, "load_or_create_account_key", lambda *a, **k: account_key
-    )
-    monkeypatch.setattr(client_mod.acme_client, "ClientNetwork", FakeNetwork)
-    monkeypatch.setattr(client_mod.acme_client, "ClientV2", FakeClientV2)
-    monkeypatch.setattr(
-        client_mod.messages.Directory, "from_json", lambda data: object()
-    )
-
-    ac = client_mod.AcmeClient(
-        str(tmp_path / "account.pem"), contact_email="ops@example.com"
-    )
-    client, _account_key = ac._init_client()
-
-    # an EC account key must be signed with ES256, not the ClientNetwork
-    # default of RS256, or josepy rejects the JWS.
-    assert captured["alg"] == josepy.ES256
-    registration = captured["registration"]
-    assert isinstance(registration, messages.NewRegistration)
-    assert registration.contact == ("mailto:ops@example.com",)
-    assert client.net.account is not None