devnomads 0.1.0__py3-none-any.whl

devnomads/acme/keys.py

@@ -0,0 +1,104 @@
+"""Key generation, serialization, and CSR building.
+
+Account and certificate keys are RSA or EC; the ACME account key is
+persisted (0600) so the same account is reused across runs.
+"""
+
+from __future__ import annotations
+
+import os
+
+from cryptography import x509
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+from cryptography.x509.oid import NameOID
+from josepy import jwk
+
+from .errors import AcmeError
+
+PrivateKey = rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey
+
+
+def generate_key(algorithm: str) -> PrivateKey:
+    """Generate a private key for ``algorithm`` (rsa2048/rsa4096/ec256/ec384)."""
+
+    algo = algorithm.lower()
+    if algo.startswith("rsa"):
+        size = int(algo.replace("rsa", ""))
+        return rsa.generate_private_key(
+            public_exponent=65537, key_size=size, backend=default_backend()
+        )
+    if algo in ("ec256", "ecdsa256"):
+        return ec.generate_private_key(ec.SECP256R1(), backend=default_backend())
+    if algo in ("ec384", "ecdsa384"):
+        return ec.generate_private_key(ec.SECP384R1(), backend=default_backend())
+    raise AcmeError(f"unsupported key algorithm: {algorithm}")
+
+
+def serialize_key(key: PrivateKey) -> bytes:
+    """Serialize ``key`` to unencrypted PEM."""
+
+    return key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.TraditionalOpenSSL,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+def _secure_write(path: str, data: bytes) -> None:
+    """Write ``data`` to ``path`` with owner-only (0600) permissions."""
+
+    directory = os.path.dirname(path)
+    if directory:
+        os.makedirs(directory, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "wb") as fh:
+        fh.write(data)
+
+
+def load_or_create_account_key(path: str, algorithm: str):
+    """Load the ACME account key from ``path`` or create and persist one.
+
+    Returns a josepy JWK suitable for ACME account operations.
+    """
+
+    private_key: PrivateKey | None = None
+    if os.path.isfile(path):
+        try:
+            with open(path, "rb") as fh:
+                loaded = serialization.load_pem_private_key(
+                    fh.read(), password=None, backend=default_backend()
+                )
+            # Only keep the key if it is a type we support; anything else
+            # falls through and is regenerated.
+            if isinstance(loaded, (rsa.RSAPrivateKey, ec.EllipticCurvePrivateKey)):
+                private_key = loaded
+        except (OSError, ValueError):
+            private_key = None  # fall through and regenerate
+
+    if private_key is None:
+        private_key = generate_key(algorithm)
+        _secure_write(path, serialize_key(private_key))
+
+    if isinstance(private_key, rsa.RSAPrivateKey):
+        return jwk.JWKRSA(key=private_key)
+    if isinstance(private_key, ec.EllipticCurvePrivateKey):
+        return jwk.JWKEC(key=private_key)
+    raise AcmeError("unsupported account key type")
+
+
+def build_csr(private_key: PrivateKey, identifiers: list[str]) -> bytes:
+    """Build a PEM CSR: ``identifiers[0]`` is the CN, all are SANs."""
+
+    if not identifiers:
+        raise AcmeError("no identifiers for CSR")
+    subject = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, identifiers[0])])
+    san = x509.SubjectAlternativeName([x509.DNSName(i) for i in identifiers])
+    csr = (
+        x509.CertificateSigningRequestBuilder()
+        .subject_name(subject)
+        .add_extension(san, critical=False)
+        .sign(private_key, hashes.SHA256(), default_backend())
+    )
+    return csr.public_bytes(serialization.Encoding.PEM)

devnomads/acme/verify.py

@@ -0,0 +1,109 @@
+"""Authoritative-nameserver verification of DNS-01 TXT records.
+
+Before answering a dns-01 challenge we confirm the TXT record is visible at
+the domain's authoritative nameservers, so we don't hand the CA a name that
+has not propagated yet.
+"""
+
+from __future__ import annotations
+
+import logging
+from time import sleep, time
+
+import dns.exception
+import dns.resolver
+
+log = logging.getLogger("devnomads.acme")
+
+
+def _make_resolver(nameservers: list[str] | None) -> dns.resolver.Resolver:
+    resolver = dns.resolver.Resolver()
+    if nameservers:
+        resolver.nameservers = nameservers
+    return resolver
+
+
+def _resolve_ns_hostname(hostname: str, resolver: dns.resolver.Resolver) -> list[str]:
+    """Resolve a nameserver hostname to IPs, AAAA first then A."""
+
+    ips: list[str] = []
+    for rdtype in ("AAAA", "A"):
+        try:
+            ips.extend(str(ip) for ip in resolver.resolve(hostname, rdtype))
+        except dns.exception.DNSException:
+            continue
+    return ips
+
+
+def authoritative_nameservers(
+    domain: str, nameservers: list[str] | None = None
+) -> list[str]:
+    """Return the authoritative NS hostnames for ``domain`` (walking upward)."""
+
+    resolver = _make_resolver(nameservers)
+    parts = domain.split(".")
+    for i in range(len(parts)):
+        check = ".".join(parts[i:])
+        if not check:
+            continue
+        try:
+            answers = resolver.resolve(check, "NS")
+            return [str(rdata.target).rstrip(".") for rdata in answers]
+        except dns.exception.DNSException:
+            continue
+    return []
+
+
+def verify_txt_record(
+    fqdn: str,
+    expected_value: str,
+    *,
+    timeout: int = 120,
+    interval: int = 5,
+    nameservers: list[str] | None = None,
+) -> bool:
+    """Poll authoritative nameservers until ``_acme-challenge.<fqdn>`` carries
+    ``expected_value``. Returns False on timeout."""
+
+    challenge = f"_acme-challenge.{fqdn}"
+    base_resolver = _make_resolver(nameservers)
+    auth_ns: list[str | None] = list(authoritative_nameservers(fqdn, nameservers))
+    if not auth_ns:
+        log.warning("no authoritative NS for %s, using default resolver", fqdn)
+        auth_ns = [None]
+    else:
+        log.info("polling authoritative nameservers for %s: %s", challenge, auth_ns)
+
+    start = time()
+    while time() - start < timeout:
+        if _all_nameservers_have(challenge, expected_value, auth_ns, base_resolver):
+            log.info("all %d nameserver(s) verified %s", len(auth_ns), challenge)
+            return True
+        sleep(interval)
+
+    log.warning("timeout waiting for TXT record %s", challenge)
+    return False
+
+
+def _all_nameservers_have(
+    challenge: str,
+    expected_value: str,
+    auth_ns: list[str | None],
+    base_resolver: dns.resolver.Resolver,
+) -> bool:
+    for ns in auth_ns:
+        resolver = dns.resolver.Resolver()
+        if ns:
+            ns_ips = _resolve_ns_hostname(ns, base_resolver)
+            if not ns_ips:
+                log.debug("failed to resolve nameserver %s", ns)
+                return False
+            resolver.nameservers = ns_ips
+        try:
+            answers = resolver.resolve(challenge, "TXT")
+        except dns.exception.DNSException:
+            return False
+        values = [str(rdata).strip('"') for rdata in answers]
+        if expected_value not in values:
+            return False
+    return True

devnomads/api/__init__.py

@@ -0,0 +1,28 @@
+"""DevNomads API transport and credential resolution."""
+
+from __future__ import annotations
+
+from .client import Client
+from .credentials import (
+    DEFAULT_API_URL,
+    DEFAULT_PROFILE,
+    Credentials,
+    config_dir,
+    credentials_path,
+    resolve,
+)
+from .errors import ApiError, AuthError, ConfigError, DevNomadsError
+
+__all__ = [
+    "Client",
+    "Credentials",
+    "resolve",
+    "config_dir",
+    "credentials_path",
+    "DEFAULT_API_URL",
+    "DEFAULT_PROFILE",
+    "DevNomadsError",
+    "ConfigError",
+    "ApiError",
+    "AuthError",
+]

devnomads/api/client.py

@@ -0,0 +1,197 @@
+"""HTTP transport for the DevNomads API.
+
+A thin wrapper over ``httpx`` that owns authentication, retries, and error
+handling so higher layers never touch HTTP directly. It is presentation
+free: failures raise :class:`~devnomads.api.errors.ApiError`, progress is
+reported through the standard :mod:`logging` module.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from .credentials import Credentials, resolve
+from .errors import ApiError, AuthError
+
+log = logging.getLogger("devnomads.api")
+
+REQUEST_TIMEOUT = 30.0
+MAX_ATTEMPTS = 4
+MAX_RETRY_DELAY = 30.0
+
+
+class Client:
+    """Authenticated client for the DevNomads API.
+
+    Construct from explicit credentials, or use :meth:`from_environment`
+    to resolve them from the environment and credentials file.
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        api_key: str,
+        *,
+        user_agent: str | None = None,
+        timeout: float = REQUEST_TIMEOUT,
+    ) -> None:
+        from .. import __version__
+
+        self._http = httpx.Client(
+            base_url=api_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+                "User-Agent": user_agent or f"devnomads/{__version__}",
+            },
+            timeout=timeout,
+        )
+
+    @classmethod
+    def from_credentials(cls, creds: Credentials, **kwargs: Any) -> "Client":
+        return cls(creds.api_url, creds.api_key, **kwargs)
+
+    @classmethod
+    def from_environment(
+        cls,
+        *,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        profile: str | None = None,
+        **kwargs: Any,
+    ) -> "Client":
+        """Resolve credentials (env + credentials file) and build a client."""
+
+        creds = resolve(api_key=api_key, api_url=api_url, profile=profile)
+        return cls.from_credentials(creds, **kwargs)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any = None,
+    ) -> Any:
+        """Send a request and return parsed JSON.
+
+        Retries 429 and 5xx responses with backoff (honouring
+        ``Retry-After``). Returns ``None`` on 404 and on empty/204 bodies,
+        so callers can treat a missing resource as absence rather than an
+        error. Raises :class:`AuthError` on 401/403 and :class:`ApiError`
+        on any other 4xx.
+        """
+
+        response = self._send(method, path, params, json_body)
+        for attempt in range(1, MAX_ATTEMPTS):
+            if response.status_code != 429 and response.status_code < 500:
+                break
+            delay = _retry_delay(response, attempt)
+            log.warning(
+                "got %s from %s, retrying in %.0fs", response.status_code, path, delay
+            )
+            time.sleep(delay)
+            response = self._send(method, path, params, json_body)
+
+        status = response.status_code
+        if status == 404:
+            return None
+        if status in (401, 403):
+            raise AuthError(
+                _error_message(response),
+                status=status,
+                detail=_error_detail(response),
+            )
+        if status >= 400:
+            raise ApiError(
+                _error_message(response),
+                status=status,
+                detail=_error_detail(response),
+            )
+        if status == 204 or not response.content:
+            return None
+        try:
+            return _unwrap(response.json())
+        except ValueError as exc:
+            raise ApiError(f"API returned invalid JSON: {exc}", status=status) from exc
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None,
+        json_body: Any,
+    ) -> httpx.Response:
+        log.debug("> %s %s", method, path)
+        try:
+            response = self._http.request(method, path, params=params, json=json_body)
+        except httpx.HTTPError as exc:
+            raise ApiError(f"request to {path} failed: {exc}", status=0) from exc
+        log.debug("< %s %s", response.status_code, response.text[:500])
+        return response
+
+
+def _unwrap(body: Any) -> Any:
+    """Strip the Laravel resource envelope (``{"data": ...}`` with optional
+    ``links``/``meta``) so callers see the actual payload."""
+
+    if (
+        isinstance(body, dict)
+        and "data" in body
+        and set(body) <= {"data", "links", "meta"}
+    ):
+        return body["data"]
+    return body
+
+
+def _retry_delay(response: httpx.Response, attempt: int) -> float:
+    try:
+        delay = float(response.headers.get("Retry-After", ""))
+    except (TypeError, ValueError):
+        delay = float(2 ** (attempt - 1))
+    return min(delay, MAX_RETRY_DELAY)
+
+
+def _error_detail(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        return ""
+    if not isinstance(body, dict):
+        return ""
+    detail = str(body.get("message") or body.get("error") or "")
+    errors = body.get("errors")
+    if isinstance(errors, dict):
+        flat = "; ".join(
+            (
+                f"{field}: {' '.join(map(str, messages))}"
+                if isinstance(messages, list)
+                else f"{field}: {messages}"
+            )
+            for field, messages in errors.items()
+        )
+        detail = f"{detail} ({flat})" if detail else flat
+    return detail
+
+
+def _error_message(response: httpx.Response) -> str:
+    detail = _error_detail(response)
+    message = f"API error {response.status_code}"
+    if detail:
+        message += f": {detail}"
+    if response.status_code in (401, 403):
+        message += " - check your API key and that it may edit this resource"
+    return message

devnomads/api/credentials.py

@@ -0,0 +1,164 @@
+"""Credential resolution shared by every DevNomads tool.
+
+The scheme matches what ``dnctl configure`` writes, so a host already set
+up for dnctl works with no extra configuration. Resolution order for the
+API key:
+
+1. an explicit value passed by the caller,
+2. ``DN_API_KEY`` (``DEVNOMADS_API_KEY`` is accepted as an alias),
+3. the ``api_key`` of the selected profile in an INI credentials file.
+
+The credentials file is found at ``DN_CREDENTIALS_FILE`` if set, otherwise
+the first that exists of ``/etc/devnomads/credentials`` and
+``<config dir>/credentials`` (the dnctl config dir). The profile is the
+caller's argument, else ``DN_PROFILE``, else ``default``.
+"""
+
+from __future__ import annotations
+
+import configparser
+import logging
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import ConfigError
+
+log = logging.getLogger("devnomads.api")
+
+DEFAULT_API_URL = "https://api.devnomads.nl"
+DEFAULT_PROFILE = "default"
+
+ENV_API_KEYS = ("DN_API_KEY", "DEVNOMADS_API_KEY")
+ENV_PROFILES = ("DN_PROFILE", "DEVNOMADS_PROFILE")
+ENV_CREDENTIALS_FILES = ("DN_CREDENTIALS_FILE", "DEVNOMADS_CREDENTIALS_FILE")
+ENV_API_URLS = ("DN_API_URL", "DEVNOMADS_API_URL")
+ENV_CONFIG_DIR = "DN_CONFIG_DIR"
+
+SYSTEM_CREDENTIAL_PATHS = ("/etc/devnomads/credentials",)
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """A resolved API key and the base URL to use it against."""
+
+    api_key: str
+    api_url: str = DEFAULT_API_URL
+
+
+def _first_env(names: tuple[str, ...]) -> str | None:
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+def config_dir() -> Path:
+    """The dnctl config directory, matching dnctl's own resolution.
+
+    ``DN_CONFIG_DIR`` wins, then ``$XDG_CONFIG_HOME/dnctl``, then
+    ``~/.config/dnctl``.
+    """
+
+    override = os.environ.get(ENV_CONFIG_DIR)
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "dnctl"
+
+
+def credentials_path() -> Path:
+    """Default per-user credentials file (``<config dir>/credentials``)."""
+
+    return config_dir() / "credentials"
+
+
+def _candidate_files() -> list[Path]:
+    candidates = [Path(p) for p in SYSTEM_CREDENTIAL_PATHS]
+    candidates.append(credentials_path())
+    return candidates
+
+
+def resolve(
+    *,
+    api_key: str | None = None,
+    api_url: str | None = None,
+    profile: str | None = None,
+) -> Credentials:
+    """Resolve credentials from explicit args, environment, and files.
+
+    Raises :class:`ConfigError` if no API key can be found.
+    """
+
+    profile = profile or _first_env(ENV_PROFILES) or DEFAULT_PROFILE
+    url = api_url or _first_env(ENV_API_URLS)
+
+    # An explicit or environment API key short-circuits file lookup, but we
+    # still let the file supply an api_url if one was not given.
+    direct_key = api_key or _first_env(ENV_API_KEYS)
+
+    override = _first_env(ENV_CREDENTIALS_FILES)
+    if override:
+        path = Path(override).expanduser()
+        if not path.is_file():
+            raise ConfigError(f"credentials file {path} does not exist")
+        candidates = [path]
+    else:
+        candidates = _candidate_files()
+
+    section = _find_profile(candidates, profile, required=bool(override))
+
+    resolved_key = direct_key or (section.get("api_key") if section else None)
+    resolved_url = (
+        url or (section.get("api_url") if section else None) or DEFAULT_API_URL
+    )
+
+    if not resolved_key:
+        searched = ", ".join(str(p) for p in candidates)
+        raise ConfigError(
+            "no API key found - set DN_API_KEY or run 'dnctl configure' to "
+            f"create a credentials file (searched: {searched})"
+        )
+    return Credentials(api_key=resolved_key.strip(), api_url=resolved_url)
+
+
+def _find_profile(
+    candidates: list[Path],
+    profile: str,
+    *,
+    required: bool,
+) -> configparser.SectionProxy | None:
+    """Return the [profile] section from the first readable file that has it.
+
+    When ``required`` (an explicit credentials file was given) a missing
+    section is an error; otherwise we fall through so env/explicit keys can
+    still satisfy the caller.
+    """
+
+    last_path: Path | None = None
+    for path in candidates:
+        path = path.expanduser()
+        if not path.is_file():
+            continue
+        last_path = path
+        mode = stat.S_IMODE(path.stat().st_mode)
+        if mode & 0o077:
+            log.warning(
+                "%s is readable by others (mode %03o); run: chmod 600 %s",
+                path,
+                mode,
+                path,
+            )
+        parser = configparser.ConfigParser()
+        try:
+            parser.read(path)
+        except configparser.Error as exc:
+            raise ConfigError(f"cannot parse credentials file {path}: {exc}") from exc
+        if parser.has_section(profile):
+            return parser[profile]
+    if required and last_path is not None:
+        raise ConfigError(f"credentials file {last_path} has no [{profile}] section")
+    return None

devnomads/api/errors.py

@@ -0,0 +1,32 @@
+"""Exception hierarchy for the DevNomads client.
+
+The library never prints or exits; it raises these so callers (a CLI, a
+hook, a daemon) decide how to present failures.
+"""
+
+from __future__ import annotations
+
+
+class DevNomadsError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class ConfigError(DevNomadsError):
+    """Credentials or configuration could not be resolved."""
+
+
+class ApiError(DevNomadsError):
+    """The API returned an error response.
+
+    ``status`` is the HTTP status code; ``detail`` is the human-readable
+    message extracted from the response body, if any.
+    """
+
+    def __init__(self, message: str, *, status: int, detail: str = "") -> None:
+        super().__init__(message)
+        self.status = status
+        self.detail = detail
+
+
+class AuthError(ApiError):
+    """The API rejected the credentials (401/403)."""

devnomads/dns/__init__.py

@@ -0,0 +1,31 @@
+"""DNS zone and record helpers for the DevNomads API."""
+
+from __future__ import annotations
+
+from .errors import DnsError, ZoneNotFound
+from .names import (
+    CHALLENGE_PREFIX,
+    absolute,
+    challenge_name,
+    fqdn,
+    quote_txt,
+    unquote_txt,
+    zone_id,
+)
+from .zones import DEFAULT_TXT_TTL, Dns, TxtResult, current_txt_values
+
+__all__ = [
+    "Dns",
+    "TxtResult",
+    "DEFAULT_TXT_TTL",
+    "current_txt_values",
+    "DnsError",
+    "ZoneNotFound",
+    "CHALLENGE_PREFIX",
+    "zone_id",
+    "absolute",
+    "fqdn",
+    "challenge_name",
+    "quote_txt",
+    "unquote_txt",
+]

devnomads/dns/errors.py

@@ -0,0 +1,13 @@
+"""DNS-specific exceptions."""
+
+from __future__ import annotations
+
+from ..api.errors import DevNomadsError
+
+
+class DnsError(DevNomadsError):
+    """A DNS operation could not be completed."""
+
+
+class ZoneNotFound(DnsError):
+    """No accessible zone matches the requested record name."""