devnomads 0.2.4__tar.gz → 0.2.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devnomads
-Version: 0.2.4
+Version: 0.2.5
 Summary: Python client library for the DevNomads API (transport, DNS, ACME)
 Project-URL: Homepage, https://devnomads.nl
 Author-email: DevNomads <support@devnomads.nl>
@@ -320,9 +320,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 +426,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.2.5}/README.md

@@ -303,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.
 
@@ -402,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.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devnomads"
-version = "0.2.4"
+version = "0.2.5"
 description = "Python client library for the DevNomads API (transport, DNS, ACME)"
 readme = "README.md"
 requires-python = ">=3.10"

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

@@ -17,7 +17,14 @@ _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 .http01 import Http01Solver, StandaloneSolver, WebrootSolver
@@ -40,6 +47,10 @@ 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",
     "DnsProvider",
     "DevNomadsDnsProvider",

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

@@ -25,7 +25,25 @@ 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"})
 
 
 def _challenge_for_authz(challenge_types_map: dict[str, str], authz_body) -> str | None:
@@ -61,7 +79,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 +94,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 -------------------------------------------
 
@@ -84,11 +142,23 @@ class AcmeClient:
         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:

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

@@ -122,4 +122,108 @@ def test_init_client_registers_with_new_registration(monkeypatch, tmp_path):
     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")