devnomads 0.1.0__py3-none-any.whl

devnomads/__init__.py

@@ -0,0 +1,17 @@
+"""Python client for the DevNomads API.
+
+Three layers, smallest dependency footprint first:
+
+* :mod:`devnomads.api` - HTTP transport (auth, retries, error handling)
+  and, in time, the generated API SDK. Depends only on ``httpx``.
+* :mod:`devnomads.dns` - DNS zone/record helpers (zone discovery, rrset
+  merging, TXT/challenge handling) on top of the transport.
+* :mod:`devnomads.acme` - ACME client (DNS-01 and HTTP-01). Requires the
+  ``acme`` extra: ``pip install devnomads[acme]``.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

devnomads/acme/__init__.py

@@ -0,0 +1,49 @@
+"""ACME client for the DevNomads tooling (DNS-01 and HTTP-01 issuance).
+
+Requires the ``acme`` extra::
+
+    pip install devnomads[acme]
+
+Without it, importing this package raises a clear ImportError pointing at
+the extra rather than a bare "No module named 'acme'".
+"""
+
+from __future__ import annotations
+
+# The heavy third-party dependencies (acme, josepy, cryptography, dnspython)
+# only ship with the [acme] extra. Catch their absence and re-raise with an
+# actionable message; let any unrelated ImportError surface unchanged.
+_EXTRA_MODULES = {"acme", "josepy", "cryptography", "dns"}
+
+try:
+    from .challenge_server import ChallengeServer
+    from .client import DEFAULT_DIRECTORY_URL, AcmeClient
+    from .dns01 import DevNomadsDnsProvider, DnsProvider
+    from .errors import AcmeError
+    from .http01 import Http01Solver, StandaloneSolver, WebrootSolver
+    from .keys import build_csr, generate_key, load_or_create_account_key, serialize_key
+    from .verify import verify_txt_record
+except ImportError as exc:  # pragma: no cover - exercised via packaging
+    if (exc.name or "").split(".")[0] in _EXTRA_MODULES:
+        raise ImportError(
+            "devnomads.acme requires the 'acme' extra; install it with: "
+            "pip install devnomads[acme]"
+        ) from exc
+    raise
+
+__all__ = [
+    "AcmeClient",
+    "DEFAULT_DIRECTORY_URL",
+    "AcmeError",
+    "DnsProvider",
+    "DevNomadsDnsProvider",
+    "Http01Solver",
+    "WebrootSolver",
+    "StandaloneSolver",
+    "ChallengeServer",
+    "build_csr",
+    "generate_key",
+    "serialize_key",
+    "load_or_create_account_key",
+    "verify_txt_record",
+]

devnomads/acme/challenge_server.py

@@ -0,0 +1,103 @@
+"""In-memory HTTP-01 challenge server.
+
+Serves ACME HTTP-01 responses from memory, so no shared filesystem with a
+web server is required. Intended to listen on port 80 (directly or behind
+a reverse proxy). A permanent token at
+``/.well-known/acme-challenge/devnomads-test`` aids manual reachability
+checks.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+log = logging.getLogger("devnomads.acme")
+
+CHALLENGE_PREFIX = "/.well-known/acme-challenge/"
+TEST_TOKEN = "devnomads-test"  # nosec B105 - a public health-check token, not a secret
+TEST_RESPONSE = "devnomads-ok"
+
+
+class _ChallengeHandler(BaseHTTPRequestHandler):
+    """Serves challenge tokens from the server's in-memory map."""
+
+    def do_GET(self):  # noqa: N802
+        if not self.path.startswith(CHALLENGE_PREFIX):
+            self.send_error(404)
+            return
+
+        token = self.path[len(CHALLENGE_PREFIX) :]
+        # Tokens are URL-safe base64 without slashes; a slash means the
+        # path is being probed, not a real challenge.
+        if "/" in token:
+            self.send_error(404)
+            return
+
+        # dict.get() is atomic under the GIL, so a concurrent remove()
+        # cannot turn this into a KeyError.
+        validation = self.server.challenges.get(token)
+        if validation is None:
+            self.send_error(404)
+            return
+
+        body = validation.encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "text/plain")
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format, *args):  # noqa: A002
+        log.debug("challenge server: %s", args[0] if args else "")
+
+
+class ChallengeServer:
+    """In-memory HTTP-01 challenge server running in a daemon thread."""
+
+    # B104: bind all interfaces so the ACME CA can reach the HTTP-01 server.
+    def __init__(self, host: str = "0.0.0.0", port: int = 80) -> None:  # nosec B104
+        self.host = host
+        self.port = port
+        self._challenges: dict[str, str] = {TEST_TOKEN: TEST_RESPONSE}
+        self._server: ThreadingHTTPServer | None = None
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+
+    def start(self) -> None:
+        """Start serving. A bind failure is logged, not raised, so a server
+        already owning the port (a co-located instance) is tolerated."""
+
+        try:
+            self._server = ThreadingHTTPServer(
+                (self.host, self.port), _ChallengeHandler
+            )
+        except OSError as exc:
+            log.warning(
+                "challenge server not started (%s); assuming another instance "
+                "owns the port",
+                exc,
+            )
+            return
+        self._server.challenges = self._challenges  # type: ignore[attr-defined]
+        self._thread = threading.Thread(
+            target=self._server.serve_forever, name="challenge-server", daemon=True
+        )
+        self._thread.start()
+        log.info("challenge server listening on %s:%s", self.host, self.port)
+
+    def stop(self) -> None:
+        if self._server:
+            self._server.shutdown()
+            self._server = None
+            self._thread = None
+
+    def set(self, token: str, validation: str) -> None:
+        with self._lock:
+            self._challenges[token] = validation
+
+    def remove(self, token: str) -> None:
+        with self._lock:
+            self._challenges.pop(token, None)

devnomads/acme/client.py

@@ -0,0 +1,364 @@
+"""ACME v2 client supporting DNS-01 and HTTP-01 challenges."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta
+from time import sleep, time
+
+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 .http01 import Http01Solver
+from .keys import PrivateKey, build_csr, load_or_create_account_key, serialize_key
+from .verify import verify_txt_record
+
+log = logging.getLogger("devnomads.acme")
+
+DEFAULT_DIRECTORY_URL = "https://acme-v02.api.letsencrypt.org/directory"
+
+
+def _challenge_for_authz(challenge_types_map: dict[str, str], authz_body) -> str | None:
+    """Resolve the configured challenge type for one authorization.
+
+    RFC 8555 §7.5: a wildcard authz reports ``identifier.value`` as the base
+    domain with ``wildcard=true``, so the lookup key is re-prefixed with
+    ``*.`` to match what the caller keyed.
+    """
+
+    ident = getattr(getattr(authz_body, "identifier", None), "value", None)
+    if ident is None:
+        return None
+    lookup = f"*.{ident}" if getattr(authz_body, "wildcard", False) else ident
+    return challenge_types_map.get(lookup)
+
+
+class AcmeClient:
+    """Issue certificates from an ACME CA (Let's Encrypt by default).
+
+    Supports DNS-01 (via a :class:`~devnomads.acme.DnsProvider`) and HTTP-01
+    (via an :class:`~devnomads.acme.Http01Solver`), and mixing the two
+    across the identifiers of a single order.
+    """
+
+    def __init__(
+        self,
+        account_key_path: str,
+        *,
+        directory_url: str = DEFAULT_DIRECTORY_URL,
+        account_key_algorithm: str = "ec256",
+        contact_email: str | None = None,
+        preferred_chain: str | None = None,
+        recursive_nameservers: list[str] | None = None,
+        user_agent: str = "devnomads",
+    ) -> None:
+        self.account_key_path = account_key_path
+        self.directory_url = directory_url
+        self.account_key_algorithm = account_key_algorithm
+        self.contact_email = contact_email
+        self.preferred_chain = preferred_chain
+        self.recursive_nameservers = recursive_nameservers
+        self.user_agent = user_agent
+
+    # -- account / client setup -------------------------------------------
+
+    def _init_client(self):
+        """Build an ACME v2 client with an account KID attached."""
+
+        account_key = load_or_create_account_key(
+            self.account_key_path, self.account_key_algorithm
+        )
+        net = acme_client.ClientNetwork(account_key, user_agent=self.user_agent)
+        directory = messages.Directory.from_json(net.get(self.directory_url).json())
+        client = acme_client.ClientV2(directory, net)
+
+        new_account = messages.NewAccount(
+            contact=(f"mailto:{self.contact_email}",) if self.contact_email else (),
+            terms_of_service_agreed=True,
+            only_return_existing=False,
+        )
+
+        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)
+
+        if account is None:
+            account = getattr(client.net, "account", None)
+        if account is None:
+            raise AcmeError("unable to establish or load ACME account")
+
+        client.net.account = account
+        return client, account_key
+
+    # -- polling helpers ---------------------------------------------------
+
+    def _wait_for_authz(self, client, authz, timeout: int = 300):
+        deadline = time() + timeout
+        while time() < deadline:
+            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")
+
+    def _fetch_order_authorizations(self, client, order):
+        raw = getattr(order, "authorizations", None) or []
+        if raw and hasattr(raw[0], "body"):
+            return raw
+        authzs = []
+        for url in raw:
+            try:
+                body = messages.Authorization.from_json(client.net.get(url).json())
+                authzs.append(messages.AuthorizationResource(uri=url, body=body))
+            except Exception as exc:  # noqa: BLE001
+                log.warning("failed to fetch authorization %s: %s", url, exc)
+        return authzs or raw
+
+    # -- issuance ----------------------------------------------------------
+
+    def obtain_certificate(
+        self,
+        domain: str,
+        challenge_types: dict[str, str] | str,
+        domain_key: PrivateKey,
+        *,
+        sans: list[str] | None = None,
+        dns_provider: DnsProvider | None = None,
+        http01_solver: Http01Solver | None = None,
+        dns_propagation_delay: int = 2,
+    ) -> tuple[str, str, str, bytes]:
+        """Obtain a certificate for ``domain`` (plus ``sans``).
+
+        ``challenge_types`` is either a single ``"dns-01"``/``"http-01"``
+        applied to every identifier, or a ``{identifier: type}`` mapping for
+        per-identifier selection within one order. Returns
+        ``(cert_pem, fullchain_pem, chain_pem, domain_key_pem)``.
+        """
+
+        client, account_key = self._init_client()
+        identifiers = _normalize_identifiers([domain] + (sans or []))
+        if not identifiers:
+            raise AcmeError("no valid identifiers for CSR")
+        types_map = _normalize_challenge_types(challenge_types, identifiers)
+
+        domain_key_pem = serialize_key(domain_key)
+        csr_pem = build_csr(domain_key, identifiers)
+        log.info("requesting certificate for: %s", ", ".join(identifiers))
+
+        order = client.new_order(csr_pem)
+        authzs = self._fetch_order_authorizations(client, order)
+
+        http_tokens: list[str] = []
+        dns_challenges: list[tuple[str, object, object, object, str]] = []
+        try:
+            for authz in authzs:
+                self._setup_authz(
+                    client,
+                    account_key,
+                    authz,
+                    types_map,
+                    dns_provider,
+                    http01_solver,
+                    http_tokens,
+                    dns_challenges,
+                )
+
+            if dns_challenges:
+                self._answer_dns_challenges(
+                    client, dns_challenges, dns_propagation_delay
+                )
+
+            order = client.poll_and_finalize(
+                order, deadline=datetime.now() + timedelta(seconds=300)
+            )
+        finally:
+            self._cleanup(http01_solver, http_tokens, dns_provider, dns_challenges)
+
+        fullchain_pem = self._select_chain(client, order)
+        leaf_pem, chain_pem = _split_fullchain(fullchain_pem)
+        return leaf_pem, fullchain_pem, chain_pem, domain_key_pem
+
+    def _setup_authz(
+        self,
+        client,
+        account_key,
+        authz,
+        types_map,
+        dns_provider,
+        http01_solver,
+        http_tokens,
+        dns_challenges,
+    ) -> None:
+        ident = getattr(getattr(authz.body, "identifier", None), "value", None)
+        status = getattr(authz.body, "status", None)
+        if status and status.name == "valid":
+            log.debug("authorization for %s already valid, skipping", ident)
+            return
+
+        this = _challenge_for_authz(types_map, authz.body)
+        if this is None:
+            raise AcmeError(f"no challenge type configured for identifier {ident!r}")
+
+        want = challenges.DNS01 if this == "dns-01" else challenges.HTTP01
+        challb = next(
+            (c for c in authz.body.challenges if isinstance(c.chall, want)), None
+        )
+        if not challb:
+            offered = [c.chall.typ for c in authz.body.challenges if c.chall]
+            raise AcmeError(
+                f"{this} challenge not offered for {ident} (offered: {offered})"
+            )
+
+        response, validation = challb.response_and_validation(account_key)
+
+        if this == "dns-01":
+            if not dns_provider:
+                raise AcmeError("dns-01 selected but no DNS provider configured")
+            fqdn = authz.body.identifier.value
+            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)
+            dns_challenges.append((fqdn, challb, response, authz, validation))
+        else:
+            if not http01_solver:
+                raise AcmeError("http-01 selected but no HTTP-01 solver configured")
+            token = challb.chall.encode("token")
+            log.info("serving http-01 challenge for %s", ident)
+            http01_solver.set(token, validation)
+            http_tokens.append(token)
+            client.answer_challenge(challb, response)
+            self._wait_for_authz(client, authz)
+
+    def _answer_dns_challenges(self, client, dns_challenges, delay: int) -> None:
+        if delay > 0:
+            log.info("waiting %ds for DNS propagation", delay)
+            sleep(delay)
+        log.info("verifying %d DNS challenge(s)", len(dns_challenges))
+        for fqdn, _, _, _, validation in dns_challenges:
+            if not verify_txt_record(
+                fqdn, validation, nameservers=self.recursive_nameservers
+            ):
+                raise AcmeError(
+                    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)
+            self._wait_for_authz(client, authz)
+
+    def _cleanup(
+        self, http01_solver, http_tokens, dns_provider, dns_challenges
+    ) -> None:
+        if http01_solver:
+            for token in http_tokens:
+                http01_solver.remove(token)
+        if dns_provider:
+            for fqdn, _, _, _, validation in dns_challenges:
+                try:
+                    dns_provider.delete_challenge(fqdn, validation)
+                except Exception as exc:  # noqa: BLE001
+                    log.warning("failed to clean up DNS challenge %s: %s", fqdn, exc)
+
+    def _select_chain(self, client, order) -> str:
+        fullchain_pem = order.fullchain_pem
+        if not (self.preferred_chain and getattr(order, "fullchain_uri", None)):
+            return fullchain_pem
+        try:
+            resp = client._post_as_get(order.fullchain_uri)
+            candidates = [resp.text] if hasattr(resp, "text") else []
+            for rel, link in getattr(resp, "links", {}).items():
+                if rel == "alternate" and isinstance(link, dict) and link.get("url"):
+                    alt = client._post_as_get(link["url"])
+                    if hasattr(alt, "text"):
+                        candidates.append(alt.text)
+            for candidate in candidates:
+                if self.preferred_chain in candidate:
+                    return candidate
+        except Exception as exc:  # noqa: BLE001
+            log.warning("preferred chain selection failed (%s), using default", exc)
+        return fullchain_pem
+
+
+def _normalize_identifiers(names: list[str]) -> list[str]:
+    """IDNA-encode and de-duplicate identifiers, preserving order."""
+
+    identifiers: list[str] = []
+    seen: set[str] = set()
+    for name in names:
+        if not name:
+            continue
+        try:
+            ascii_name = name.encode("idna").decode("ascii")
+        except Exception:  # noqa: BLE001  # nosec B112
+            continue
+        if ascii_name not in seen:
+            seen.add(ascii_name)
+            identifiers.append(ascii_name)
+    return identifiers
+
+
+def _normalize_challenge_types(
+    challenge_types: dict[str, str] | str, identifiers: list[str]
+) -> dict[str, str]:
+    """Return a ``{identifier: challenge_type}`` map for every identifier."""
+
+    if isinstance(challenge_types, str):
+        return {ident: challenge_types for ident in identifiers}
+
+    result: dict[str, str] = {}
+    for ident in identifiers:
+        ct = challenge_types.get(ident)
+        if ct is None:
+            for key, value in challenge_types.items():
+                try:
+                    if key.encode("idna").decode("ascii") == ident:
+                        ct = value
+                        break
+                except Exception:  # noqa: BLE001  # nosec B112
+                    continue
+        if ct is None:
+            raise AcmeError(
+                f"no challenge type specified for identifier {ident!r} "
+                f"(provided: {sorted(challenge_types)})"
+            )
+        result[ident] = ct
+    return result
+
+
+def _authz_failure(authz_body) -> str:
+    err = getattr(authz_body, "error", None)
+    if err:
+        detail = getattr(err, "detail", None) or "unknown error"
+        return (
+            f"authorization failed: {detail} (type: {getattr(err, 'typ', 'unknown')})"
+        )
+    parts = []
+    for challb in getattr(authz_body, "challenges", []):
+        ch_err = getattr(challb, "error", None)
+        if ch_err:
+            detail = getattr(ch_err, "detail", None) or "unknown error"
+            parts.append(f"{getattr(challb.chall, 'typ', 'unknown')}: {detail}")
+    return "authorization failed: " + ("; ".join(parts) if parts else "unknown")
+
+
+def _split_fullchain(fullchain_pem: str) -> tuple[str, str]:
+    marker = "-----END CERTIFICATE-----"
+    end = fullchain_pem.find(marker)
+    if end == -1:
+        return fullchain_pem, ""
+    cut = end + len(marker) + 1
+    return fullchain_pem[:cut], fullchain_pem[cut:]

devnomads/acme/dns01.py

@@ -0,0 +1,42 @@
+"""DNS-01 challenge solvers.
+
+A solver plants and removes the ``_acme-challenge`` TXT record that proves
+control of a domain. :class:`DnsProvider` is the interface; the bundled
+:class:`DevNomadsDnsProvider` drives it through :mod:`devnomads.dns`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..dns import Dns, challenge_name
+
+
+class DnsProvider(ABC):
+    """Plants/removes DNS-01 challenge records for a domain."""
+
+    @abstractmethod
+    def create_challenge(self, fqdn: str, validation: str) -> None:
+        """Create the ``_acme-challenge.<fqdn>`` TXT record."""
+
+    @abstractmethod
+    def delete_challenge(self, fqdn: str, validation: str | None = None) -> None:
+        """Remove the challenge record.
+
+        ``validation`` lets the provider remove just that one value, leaving
+        any other values (e.g. a concurrent wildcard order) intact; with
+        ``None`` the whole record is removed.
+        """
+
+
+class DevNomadsDnsProvider(DnsProvider):
+    """DNS-01 provider backed by the DevNomads DNS API."""
+
+    def __init__(self, dns: Dns) -> None:
+        self.dns = dns
+
+    def create_challenge(self, fqdn: str, validation: str) -> None:
+        self.dns.set_txt(challenge_name(fqdn), validation)
+
+    def delete_challenge(self, fqdn: str, validation: str | None = None) -> None:
+        self.dns.unset_txt(challenge_name(fqdn), validation)

devnomads/acme/errors.py

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

devnomads/acme/http01.py

@@ -0,0 +1,91 @@
+"""HTTP-01 challenge solvers.
+
+Two ways to answer an HTTP-01 challenge, both behind one interface:
+
+* :class:`WebrootSolver` writes the validation file under an existing web
+  server's document root (``<webroot>/.well-known/acme-challenge/<token>``).
+* :class:`StandaloneSolver` runs the bundled :class:`ChallengeServer` and
+  answers requests itself, for hosts with no web server.
+
+Use a solver as a context manager so the server (if any) is started and
+stopped around issuance::
+
+    with StandaloneSolver(port=80) as solver:
+        client.obtain_certificate(..., http01_solver=solver)
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from .challenge_server import CHALLENGE_PREFIX, ChallengeServer
+from .errors import AcmeError
+
+log = logging.getLogger("devnomads.acme")
+
+# CHALLENGE_PREFIX is an absolute URL path ("/.well-known/..."); strip the
+# leading slash to use it as a relative filesystem path under a webroot.
+_RELATIVE_CHALLENGE_DIR = CHALLENGE_PREFIX.strip("/")
+
+
+class Http01Solver(ABC):
+    """Serves and removes HTTP-01 challenge validations."""
+
+    def __enter__(self) -> "Http01Solver":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+    @abstractmethod
+    def set(self, token: str, validation: str) -> None:
+        """Make ``validation`` reachable at ``/.well-known/acme-challenge/<token>``."""
+
+    @abstractmethod
+    def remove(self, token: str) -> None:
+        """Stop serving ``token``."""
+
+
+class WebrootSolver(Http01Solver):
+    """Writes challenge files under an existing web server's document root."""
+
+    def __init__(self, webroot: str | Path) -> None:
+        self.challenge_dir = Path(webroot) / _RELATIVE_CHALLENGE_DIR
+
+    def set(self, token: str, validation: str) -> None:
+        try:
+            self.challenge_dir.mkdir(parents=True, exist_ok=True)
+            (self.challenge_dir / token).write_text(validation)
+        except OSError as exc:
+            raise AcmeError(f"failed to write challenge file: {exc}") from exc
+
+    def remove(self, token: str) -> None:
+        try:
+            (self.challenge_dir / token).unlink()
+        except FileNotFoundError:
+            pass
+        except OSError as exc:
+            log.warning("failed to remove challenge file %s: %s", token, exc)
+
+
+class StandaloneSolver(Http01Solver):
+    """Answers HTTP-01 challenges from the bundled in-memory server."""
+
+    # B104: bind all interfaces so the ACME CA can reach the HTTP-01 server.
+    def __init__(self, host: str = "0.0.0.0", port: int = 80) -> None:  # nosec B104
+        self.server = ChallengeServer(host=host, port=port)
+
+    def __enter__(self) -> "StandaloneSolver":
+        self.server.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.server.stop()
+
+    def set(self, token: str, validation: str) -> None:
+        self.server.set(token, validation)
+
+    def remove(self, token: str) -> None:
+        self.server.remove(token)