devnomads 0.1.0__py3-none-any.whl

devnomads/dns/names.py

@@ -0,0 +1,75 @@
+"""DNS name helpers.
+
+The DevNomads DNS API is a PowerDNS proxy, so zone ids and record names
+are absolute (trailing dot) and TXT content is stored quoted.
+"""
+
+from __future__ import annotations
+
+from .errors import DnsError
+
+CHALLENGE_PREFIX = "_acme-challenge"
+
+
+def zone_id(zone: str) -> str:
+    """PowerDNS zone ids carry a trailing dot; accept names without it."""
+
+    return zone if zone.endswith(".") else f"{zone}."
+
+
+def absolute(name: str) -> str:
+    """Return ``name`` with a trailing dot, PowerDNS style."""
+
+    return name if name.endswith(".") else f"{name}."
+
+
+def fqdn(name: str, zone: str) -> str:
+    """Absolute record name for ``name`` within ``zone``.
+
+    Accepts relative names, ``@``/empty for the apex, or a name that
+    already includes the zone, and always returns the trailing-dot form.
+    """
+
+    zone_root = zone.rstrip(".")
+    relative = name.rstrip(".")
+    if relative in ("@", ""):
+        return f"{zone_root}."
+    if relative == zone_root or relative.endswith(f".{zone_root}"):
+        return f"{relative}."
+    return f"{relative}.{zone_root}."
+
+
+def challenge_name(domain: str) -> str:
+    """The TXT record name to validate for ``domain``.
+
+    Accepts a plain domain (``example.com`` or ``*.example.com``) and
+    returns ``_acme-challenge.example.com``; a name already starting with
+    ``_acme-challenge`` is passed through unchanged, so callers can hand us
+    the full record name directly.
+    """
+
+    name = domain.strip().rstrip(".")
+    if name.startswith("*."):
+        name = name[2:]
+    if not name:
+        raise DnsError("empty domain")
+    if name == CHALLENGE_PREFIX or name.startswith(f"{CHALLENGE_PREFIX}."):
+        return name
+    return f"{CHALLENGE_PREFIX}.{name}"
+
+
+def quote_txt(value: str) -> str:
+    """PowerDNS stores TXT content quoted; quote ``value`` if it is not."""
+
+    if len(value) >= 2 and value.startswith('"') and value.endswith('"'):
+        return value
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def unquote_txt(value: str) -> str:
+    """Inverse of :func:`quote_txt`."""
+
+    if len(value) >= 2 and value.startswith('"') and value.endswith('"'):
+        return value[1:-1].replace('\\"', '"').replace("\\\\", "\\")
+    return value

devnomads/dns/zones.py

@@ -0,0 +1,211 @@
+"""Zone and record operations on top of the API transport.
+
+The DevNomads DNS API exposes three PowerDNS-style endpoints scoped to the
+zones a key may access::
+
+    GET   /services/dns/zones              list zones
+    GET   /services/dns/zones/{zone_id}    zone with its rrsets
+    PATCH /services/dns/zones/{zone_id}    apply an rrset change
+
+:class:`Dns` wraps a :class:`~devnomads.api.Client` with the higher-level
+operations the tools need: zone discovery, reading current values, and the
+merge-aware TXT updates ACME challenges require.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..api import Client
+from .errors import ZoneNotFound
+from .names import absolute, quote_txt, unquote_txt, zone_id
+
+DEFAULT_TXT_TTL = 60
+
+
+@dataclass
+class TxtResult:
+    """Outcome of a TXT set/unset operation.
+
+    ``values`` is the list of values present after the operation;
+    ``changed`` says whether the API was actually modified.
+    """
+
+    zone: str
+    values: list[str]
+    changed: bool
+
+
+def current_txt_values(zone_data: dict, record_name: str) -> list[str]:
+    """Unquoted TXT values already present at ``record_name`` in the zone."""
+
+    target = absolute(record_name).lower()
+    for rrset in zone_data.get("rrsets", []) or []:
+        if rrset.get("type") == "TXT" and (rrset.get("name") or "").lower() == target:
+            return [
+                unquote_txt(rec.get("content", "")) for rec in rrset.get("records", [])
+            ]
+    return []
+
+
+def _replace_rrset(
+    record_name: str,
+    rtype: str,
+    contents: list[str],
+    ttl: int,
+) -> dict:
+    return {
+        "name": absolute(record_name),
+        "type": rtype,
+        "changetype": "REPLACE",
+        "ttl": ttl,
+        "records": [{"content": c, "disabled": False} for c in contents],
+    }
+
+
+def _delete_rrset(record_name: str, rtype: str) -> dict:
+    return {"name": absolute(record_name), "type": rtype, "changetype": "DELETE"}
+
+
+class Dns:
+    """DNS operations bound to an API client."""
+
+    def __init__(self, client: Client) -> None:
+        self.client = client
+
+    # -- raw zone access ---------------------------------------------------
+
+    def list_zone_names(self) -> list[str]:
+        """Names of every zone this key may access (one request, no probing).
+
+        This API returns 403 (not 404) for names that are not owned zones,
+        so probing label suffixes would misread permissions and risk
+        throttling. Listing once and matching locally avoids that.
+        """
+
+        data = self.client.request("GET", "/services/dns/zones") or []
+        return [z.get("name", "") for z in data if isinstance(z, dict)]
+
+    def get_zone(self, zone: str) -> dict | None:
+        return self.client.request("GET", f"/services/dns/zones/{zone_id(zone)}")
+
+    def patch_rrset(self, zone: str, rrset: dict) -> None:
+        self.client.request(
+            "PATCH",
+            f"/services/dns/zones/{zone_id(zone)}",
+            json_body={"rrsets": [rrset]},
+        )
+
+    def find_zone(self, record_name: str) -> str:
+        """Return the owned zone that is the longest suffix of ``record_name``.
+
+        A deep host like ``_acme-challenge.a.b.example.com`` lives in the
+        flat ``example.com`` zone. Longest-suffix wins, so a delegated
+        sub-zone (``a.example.com``) is preferred over its parent when both
+        are present.
+        """
+
+        target = record_name.rstrip(".").lower()
+        best = ""
+        for name in self.list_zone_names():
+            zone = name.rstrip(".").lower()
+            if zone and (target == zone or target.endswith(f".{zone}")):
+                if len(zone) > len(best):
+                    best = zone
+        if not best:
+            raise ZoneNotFound(
+                f"no DevNomads zone found for {record_name!r} - is the domain "
+                "hosted at DevNomads and reachable with this API key?"
+            )
+        return best
+
+    # -- generic records ---------------------------------------------------
+
+    def replace_records(
+        self,
+        record_name: str,
+        rtype: str,
+        contents: list[str],
+        *,
+        ttl: int,
+        zone: str | None = None,
+    ) -> None:
+        """Replace ``record_name``'s ``rtype`` rrset with ``contents``.
+
+        Content is sent verbatim (use for A/AAAA/CNAME etc.); for TXT use
+        :meth:`set_txt`, which handles quoting and value merging.
+        """
+
+        zone = zone or self.find_zone(record_name)
+        self.patch_rrset(zone, _replace_rrset(record_name, rtype, contents, ttl))
+
+    def delete_records(
+        self,
+        record_name: str,
+        rtype: str,
+        *,
+        zone: str | None = None,
+    ) -> None:
+        zone = zone or self.find_zone(record_name)
+        self.patch_rrset(zone, _delete_rrset(record_name, rtype))
+
+    # -- TXT / ACME challenges ---------------------------------------------
+
+    def set_txt(
+        self,
+        record_name: str,
+        value: str,
+        *,
+        ttl: int = DEFAULT_TXT_TTL,
+    ) -> TxtResult:
+        """Add ``value`` to the TXT rrset at ``record_name``.
+
+        Merges with any values already present (so a wildcard + base-domain
+        order can validate the same name twice) and is idempotent: a value
+        already present makes no API call.
+        """
+
+        if not value:
+            raise ValueError("a challenge value is required to set a TXT record")
+        zone = self.find_zone(record_name)
+        values = current_txt_values(self.get_zone(zone) or {}, record_name)
+        if value in values:
+            return TxtResult(zone=zone, values=values, changed=False)
+        values = values + [value]
+        self.patch_rrset(
+            zone,
+            _replace_rrset(record_name, "TXT", [quote_txt(v) for v in values], ttl),
+        )
+        return TxtResult(zone=zone, values=values, changed=True)
+
+    def unset_txt(
+        self,
+        record_name: str,
+        value: str | None = None,
+        *,
+        ttl: int = DEFAULT_TXT_TTL,
+    ) -> TxtResult:
+        """Remove ``value`` from the TXT rrset at ``record_name``.
+
+        Deletes the whole rrset once the last value is gone. With
+        ``value=None`` the entire rrset is removed. Idempotent: absence of
+        the value makes no API call.
+        """
+
+        zone = self.find_zone(record_name)
+        values = current_txt_values(self.get_zone(zone) or {}, record_name)
+        if not values:
+            return TxtResult(zone=zone, values=[], changed=False)
+        remaining = [] if value is None else [v for v in values if v != value]
+        if remaining == values:
+            return TxtResult(zone=zone, values=values, changed=False)
+        if remaining:
+            self.patch_rrset(
+                zone,
+                _replace_rrset(
+                    record_name, "TXT", [quote_txt(v) for v in remaining], ttl
+                ),
+            )
+        else:
+            self.patch_rrset(zone, _delete_rrset(record_name, "TXT"))
+        return TxtResult(zone=zone, values=remaining, changed=True)

devnomads-0.1.0.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: devnomads
+Version: 0.1.0
+Summary: Python client for the DevNomads API (transport, DNS, ACME)
+Project-URL: Homepage, https://devnomads.nl
+Project-URL: Source, https://gitlab.infrapod.nl/infrapod/devnomads-libs
+Author-email: Loek Geleijn <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:
+HTTP transport, DNS zone/record management, and ACME certificate
+issuance.
+
+It is the shared foundation of the DevNomads command-line tools - `dnctl`
+and `dnsync` - exposed so you can build against the same primitives
+directly instead of reimplementing them.
+
+## Layers
+
+The package is split by dependency weight, lightest first. `httpx` is the
+only hard dependency; import what you need.
+
+- **`devnomads.api`** - HTTP transport: authentication, retries with
+  `Retry-After`, Laravel envelope unwrapping, and a typed error hierarchy.
+- **`devnomads.dns`** - DNS helpers on top of the transport: zone
+  discovery, rrset merging, A/AAAA records, and TXT/ACME-challenge
+  handling.
+- **`devnomads.acme`** - ACME client for certificate issuance over DNS-01
+  and HTTP-01. Requires the `acme` extra (`acme`, `josepy`,
+  `cryptography`, `dnspython`).
+
+## Installation
+
+```bash
+pip install devnomads          # api + dns (httpx only)
+pip install devnomads[acme]    # + the ACME client and its dependencies
+```
+
+`devnomads.acme` only imports cleanly with the `acme` extra installed;
+without it, importing the module raises an `ImportError` that names the
+extra. Requires Python 3.10 or newer.
+
+## Authentication
+
+Build a client from the environment, or pass credentials explicitly:
+
+```python
+from devnomads.api import Client
+
+# Resolved from the environment and credentials file.
+client = Client.from_environment()
+
+# Or explicit:
+client = Client("https://api.devnomads.nl", "dn_xxx")
+```
+
+`Client` is a context manager and reuses one underlying connection pool:
+
+```python
+with Client.from_environment() as client:
+    ...
+```
+
+The API key is resolved in this order:
+
+1. an explicit value passed to `Client`/`resolve`;
+2. `DN_API_KEY` (or the `DEVNOMADS_API_KEY` alias);
+3. the `api_key` of the selected profile in an INI credentials file.
+
+The credentials file is taken from `DN_CREDENTIALS_FILE` if set, otherwise
+the first of `/etc/devnomads/credentials` and `~/.config/dnctl/credentials`
+(the file `dnctl configure` writes). The profile is `DN_PROFILE`, else
+`default`. This matches the resolution used by `dnctl` and `dnsync`, so a
+host already configured for those works unchanged.
+
+## DNS
+
+`Dns` wraps a `Client` with zone-scoped operations. Zone discovery is
+done by listing accessible zones and picking the longest matching suffix,
+so a deep host resolves to its flat parent zone automatically.
+
+```python
+from devnomads.api import Client
+from devnomads.dns import Dns
+
+with Client.from_environment() as client:
+    dns = Dns(client)
+
+    # Merge-aware, idempotent TXT updates (used for ACME challenges).
+    dns.set_txt("_acme-challenge.example.com", "token-value")
+    dns.unset_txt("_acme-challenge.example.com", "token-value")
+
+    # Generic records (content sent verbatim).
+    dns.replace_records("host.example.com", "A", ["192.0.2.1"], ttl=300)
+    dns.delete_records("host.example.com", "A")
+
+    zone = dns.find_zone("_acme-challenge.deep.host.example.com")
+```
+
+`set_txt`/`unset_txt` return a `TxtResult(zone, values, changed)`;
+`set_txt` merges with any values already present (so a wildcard and its
+base domain can validate the same name concurrently) and makes no request
+when the value is already there. `unset_txt` deletes the rrset once its
+last value is gone.
+
+The `devnomads.dns` module also exports name helpers - `challenge_name`,
+`fqdn`, `zone_id`, `quote_txt`, `unquote_txt` - and the `ZoneNotFound`
+error.
+
+## ACME
+
+`AcmeClient` issues certificates from an ACME CA (Let's Encrypt by
+default) over DNS-01, HTTP-01, or a mix of both within one order. It
+manages the account key, builds the CSR, verifies DNS propagation against
+the authoritative nameservers, and selects the preferred chain.
+
+```python
+from devnomads.api import Client
+from devnomads.dns import Dns
+from devnomads.acme import AcmeClient, DevNomadsDnsProvider, generate_key
+
+acme = AcmeClient(
+    "/etc/devnomads/account.key",
+    contact_email="ops@example.com",
+)
+domain_key = generate_key("ec256")
+
+# DNS-01, including wildcards:
+with Client.from_environment() as client:
+    provider = DevNomadsDnsProvider(Dns(client))
+    leaf, fullchain, chain, key_pem = acme.obtain_certificate(
+        "example.com",
+        "dns-01",
+        domain_key,
+        sans=["*.example.com"],
+        dns_provider=provider,
+    )
+```
+
+`obtain_certificate` returns
+`(cert_pem, fullchain_pem, chain_pem, domain_key_pem)` as strings (the key
+as bytes).
+
+### HTTP-01
+
+Answer HTTP-01 challenges either from the bundled in-memory server or by
+writing files under an existing web root:
+
+```python
+from devnomads.acme import StandaloneSolver, WebrootSolver
+
+# Standalone: bind :80 and serve challenges directly.
+with StandaloneSolver(port=80) as solver:
+    acme.obtain_certificate(
+        "example.com", "http-01", domain_key, http01_solver=solver
+    )
+
+# Webroot: write files for an existing server to serve.
+acme.obtain_certificate(
+    "example.com",
+    "http-01",
+    domain_key,
+    http01_solver=WebrootSolver("/var/www/html"),
+)
+```
+
+### Mixed challenges
+
+Pass a `{identifier: challenge_type}` mapping to use different challenge
+types per name in a single order - e.g. HTTP-01 for the base domain and
+DNS-01 for its wildcard:
+
+```python
+acme.obtain_certificate(
+    "example.com",
+    {"example.com": "http-01", "*.example.com": "dns-01"},
+    domain_key,
+    sans=["*.example.com"],
+    dns_provider=provider,
+    http01_solver=solver,
+)
+```
+
+To target staging, pass
+`directory_url="https://acme-staging-v02.api.letsencrypt.org/directory"`.
+Implement `devnomads.acme.DnsProvider` to drive a DNS backend other than
+DevNomads.
+
+## Errors
+
+The library never prints or exits; operations return values and failures
+raise `devnomads.api.DevNomadsError` subclasses, so the caller decides how
+to present them.
+
+```python
+from devnomads.api import DevNomadsError, AuthError
+
+try:
+    dns.set_txt(name, value)
+except AuthError:
+    ...  # 401/403: missing, invalid, or unauthorized key
+except DevNomadsError as exc:
+    ...  # ApiError, ConfigError, DnsError, AcmeError, ...
+```
+
+`ApiError` carries `status` and `detail`. Note that `Client.request`
+returns `None` (rather than raising) for a 404, so a missing resource
+reads as absence.
+
+## Logging
+
+Progress and warnings go through the standard `logging` module under the
+`devnomads` logger (`devnomads.api`, `devnomads.acme`). It is silent
+unless you configure logging:
+
+```python
+import logging
+
+logging.getLogger("devnomads").setLevel(logging.INFO)
+```
+
+## Development
+
+```bash
+uv sync --dev --extra acme
+uv run pytest
+uv run black . && uv run flake8 src tests
+```
+
+## License
+
+MIT

devnomads-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+devnomads/__init__.py,sha256=Dl4cUcfwLuA7wk_fPMud2JJoTFUjjEQDnKdcwYrgKyU,577
+devnomads/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devnomads/acme/__init__.py,sha256=NH5OKG41WeO--4CBnO5woTbsdz0R0Fma4CqLggeUN98,1629
+devnomads/acme/challenge_server.py,sha256=Enfu3ROfMJ5lnUOqbEVIJnvzOWl1rA89ZOs0JQigbxw,3637
+devnomads/acme/client.py,sha256=BhymHVHcdCS-euT2cgQ2180v8vHwlEiXIYTFTQT565M,14064
+devnomads/acme/dns01.py,sha256=q_KBd_baAejjuAJ4a_sKd4gA3e5OvUspWwTzTgTu70I,1398
+devnomads/acme/errors.py,sha256=FLqf3Ad2FuhgF1F8uAGSuSZlbz2jbXqsfCPsQcP7sMc,184
+devnomads/acme/http01.py,sha256=3XjgPTxNbV-0tInpJVJkvKIlX-W4eV5KnkITC6E2w0I,3028
+devnomads/acme/keys.py,sha256=E6dABXpDo5NP_x1R6pdy1kNiS11J1DN6Ffgl7gU7YFg,3776
+devnomads/acme/verify.py,sha256=McjEQ0iK-KCs7t0TbMswkbtUrZlnTuf1BGRh4nUS7Bg,3374
+devnomads/api/__init__.py,sha256=431itPZsjEzz7sYhVKsAoa8KRiLHF8CU_9ARvv7Du9c,554
+devnomads/api/client.py,sha256=Vk6vo-BnTLgpjHvWsal8KaKu63fY77O5YKyrc42uNmQ,5986
+devnomads/api/credentials.py,sha256=yxPhiAZgvk5ddh7mojQRimYRFFR8XR6FjqfCbZiOsa0,5102
+devnomads/api/errors.py,sha256=2Atwqmv9ZJzKS0ht0WczrKC4Gha93YDISrtruWcEQ1Y,874
+devnomads/dns/__init__.py,sha256=xNtQg1sgrtXfPwyAbDsxAYUaIxmKUQNzcvVb7ry8Zt8,595
+devnomads/dns/errors.py,sha256=8vgaBpbqEwQbJH_GT49rYLPJsfOQ6MjfHlcTDMPiZEU,288
+devnomads/dns/names.py,sha256=4G7DvDmyZcw_v4KfTea7aoq4eD4ViXNbGM2PeeONO0A,2273
+devnomads/dns/zones.py,sha256=ReSQaAMnWyzOwCry6k5QsllgpEz45dEswATOvNyZAg8,7061
+devnomads-0.1.0.dist-info/METADATA,sha256=tWEFjSBM7JtELN57wYnBnkDKrQlxQ9I8-aP9nJND7Qs,7329
+devnomads-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+devnomads-0.1.0.dist-info/RECORD,,

devnomads-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any