certbot-dns-alias 0.1.0__py3-none-any.whl

certbot_dns_alias/__init__.py

@@ -0,0 +1 @@
+"""CNAME delegation for Certbot's DNS-01 authenticator."""

certbot_dns_alias/config.py

@@ -0,0 +1,95 @@
+"""Validate Certbot INI credentials and construct provider accounts."""
+
+from certbot import errors
+from certbot.plugins.dns_common import CredentialsConfiguration
+
+from certbot_dns_alias.dns import normalize_name
+from certbot_dns_alias.providers.aliyun import AliyunDNSProvider
+from certbot_dns_alias.providers.base import DNSProvider, ZoneRouter
+from certbot_dns_alias.providers.tencent import TencentDNSProvider
+
+
+def setting(credentials: CredentialsConfiguration, key: str, default: str = "") -> str:
+    value = credentials.conf(key)
+    if value is None:
+        return default
+    if not isinstance(value, str):
+        raise errors.PluginError(f"dns_alias_{key} must be a single value")
+    return value.strip()
+
+
+def provider_names(credentials: CredentialsConfiguration) -> list[str]:
+    mode = setting(credentials, "provider").lower()
+    if mode not in {"aliyun", "tencent", "auto"}:
+        raise errors.PluginError("dns_alias_provider must be aliyun, tencent, or auto")
+    required = {
+        "aliyun": {
+            "aliyun_access_key_id": "Alibaba Cloud AccessKey ID",
+            "aliyun_access_key_secret": "Alibaba Cloud AccessKey secret",
+        },
+        "tencent": {
+            "tencent_secret_id": "Tencent Cloud SecretId",
+            "tencent_secret_key": "Tencent Cloud SecretKey",
+        },
+    }
+    names = (
+        [mode]
+        if mode != "auto"
+        else [
+            name
+            for name, keys in required.items()
+            if any(credentials.conf(key) is not None for key in keys)
+        ]
+    )
+    if not names:
+        raise errors.PluginError("dns_alias_provider=auto requires at least one provider's keys")
+    for name in names:
+        credentials.require(required[name])
+        for key in required[name]:
+            if not setting(credentials, key):
+                raise errors.PluginError(f"dns_alias_{key} must not be empty")
+    return names
+
+
+def configured_zones(credentials: CredentialsConfiguration, provider: str) -> list[str] | None:
+    value = credentials.conf(f"{provider}_zones")
+    if value is None:
+        return None
+    # ConfigObj parses an unquoted comma-separated INI value as a list.
+    parts = value if isinstance(value, list) else value.split(",")
+    if not parts or any(not isinstance(part, str) or not part.strip() for part in parts):
+        raise errors.PluginError(f"dns_alias_{provider}_zones must contain DNS zone names")
+    return [normalize_name(part) for part in parts]
+
+
+def validate_credentials(credentials: CredentialsConfiguration) -> None:
+    for name in provider_names(credentials):
+        configured_zones(credentials, name)
+        optional = (
+            ["aliyun_region_id", "aliyun_security_token"] if name == "aliyun" else ["tencent_token"]
+        )
+        for key in optional:
+            setting(credentials, key)
+
+
+def build_router(credentials: CredentialsConfiguration) -> ZoneRouter:
+    providers: dict[str, DNSProvider] = {}
+    zones = {}
+    for name in provider_names(credentials):
+        explicit = configured_zones(credentials, name)
+        if explicit is not None:
+            zones[name] = explicit
+        if name == "aliyun":
+            providers[name] = AliyunDNSProvider(
+                setting(credentials, "aliyun_access_key_id"),
+                setting(credentials, "aliyun_access_key_secret"),
+                region_id=setting(credentials, "aliyun_region_id", "cn-hangzhou"),
+                security_token=setting(credentials, "aliyun_security_token") or None,
+            )
+        else:
+            providers[name] = TencentDNSProvider(
+                setting(credentials, "tencent_secret_id"),
+                setting(credentials, "tencent_secret_key"),
+                token=setting(credentials, "tencent_token") or None,
+            )
+    return ZoneRouter(providers, zones)

certbot_dns_alias/dns.py

@@ -0,0 +1,115 @@
+"""DNS name handling and bounded CNAME resolution."""
+
+import logging
+import re
+import time
+
+import dns.exception
+import dns.name
+import dns.rdatatype
+import dns.resolver
+from certbot import errors
+
+logger = logging.getLogger(__name__)
+
+
+def normalize_name(value: str) -> str:
+    """Return an absolute, lower-case ASCII DNS name without its trailing dot."""
+    try:
+        name = dns.name.from_text(value.strip()).canonicalize()
+        if name == dns.name.root or any(
+            not re.fullmatch(rb"[a-z0-9_-]+", label) for label in name.labels[:-1]
+        ):
+            raise ValueError("invalid label")
+        return name.to_text(omit_final_dot=True)
+    except (dns.exception.DNSException, UnicodeError, ValueError) as exc:
+        raise errors.PluginError(f"Invalid DNS name: {value!r}") from exc
+
+
+def relative_name(fqdn: str, zone: str) -> str:
+    """Return a provider's host record, using @ for the zone apex."""
+    fqdn, zone = normalize_name(fqdn), normalize_name(zone)
+    if fqdn == zone:
+        return "@"
+    if fqdn.endswith("." + zone):
+        return fqdn[: -len(zone) - 1]
+    raise errors.PluginError(f"DNS name {fqdn} is outside zone {zone}")
+
+
+class CnameResolver:
+    """Follow individual CNAME links, including links in negative DNS answers."""
+
+    def __init__(
+        self,
+        resolver: dns.resolver.Resolver | None = None,
+        *,
+        max_depth: int = 8,
+        timeout: float = 10,
+        retries: int = 2,
+    ) -> None:
+        if max_depth < 1 or timeout <= 0 or retries < 0:
+            raise errors.PluginError("Invalid CNAME resolver limits")
+        self.resolver = resolver if resolver is not None else dns.resolver.Resolver()
+        self.max_depth = max_depth
+        self.timeout = timeout
+        self.retries = retries
+
+    def resolve(self, fqdn: str, *, require_cname: bool = False) -> str:
+        original = current = normalize_name(fqdn)
+        visited = {current}
+        # One terminal query beyond the allowed number of links is necessary:
+        # a chain of exactly max_depth links must still be accepted.
+        for depth in range(self.max_depth + 1):
+            target = self._target(current)
+            if target is None:
+                if require_cname and current == original:
+                    raise errors.PluginError(f"CNAME delegation required for {original}")
+                return current
+            if target in visited:
+                raise errors.PluginError(f"CNAME loop detected for {original} at {target}")
+            if depth == self.max_depth:
+                raise errors.PluginError(
+                    f"CNAME chain exceeds {self.max_depth} links for {original}"
+                )
+            logger.debug("CNAME delegation: %s -> %s", current, target)
+            visited.add(target)
+            current = target
+        raise AssertionError("unreachable")
+
+    def _target(self, current: str) -> str | None:
+        for attempt in range(self.retries + 1):
+            try:
+                answer = self.resolver.resolve(
+                    current + ".",
+                    "CNAME",
+                    lifetime=self.timeout,
+                    search=False,
+                    raise_on_no_answer=False,
+                )
+                responses = [answer.response]
+            except dns.resolver.NXDOMAIN as exc:
+                # NXDOMAIN can refer to the CNAME's destination rather than
+                # the queried name. Preserve the CNAME in the answer section.
+                responses = list(exc.responses().values())
+            except dns.resolver.NoAnswer as exc:
+                responses = [exc.response()]
+            except (dns.exception.Timeout, dns.resolver.NoNameservers) as exc:
+                if attempt == self.retries:
+                    raise errors.PluginError(
+                        f"Unable to resolve CNAME for {current} after {attempt + 1} attempts "
+                        f"({type(exc).__name__}); check DNS connectivity and resolvers"
+                    ) from exc
+                time.sleep(min(2**attempt, 4))
+                continue
+            except dns.exception.DNSException as exc:
+                raise errors.PluginError(f"CNAME lookup failed for {current}") from exc
+
+            owner = dns.name.from_text(current + ".")
+            for response in responses:
+                for rrset in response.answer:
+                    if rrset.name == owner and rrset.rdtype == dns.rdatatype.CNAME:
+                        if len(rrset) != 1:
+                            raise errors.PluginError(f"Invalid CNAME RRset for {current}")
+                        return normalize_name(rrset[0].target.to_text())
+            return None
+        raise AssertionError("unreachable")

certbot_dns_alias/dns_alias.py

@@ -0,0 +1,169 @@
+"""Certbot DNS authenticator with CNAME delegation to Aliyun and DNSPod."""
+
+import ipaddress
+import logging
+import math
+from dataclasses import dataclass
+from typing import Any
+
+import dns.resolver
+from certbot import errors
+from certbot.plugins import dns_common
+
+from certbot_dns_alias.config import build_router, validate_credentials
+from certbot_dns_alias.dns import CnameResolver, normalize_name, relative_name
+from certbot_dns_alias.providers.base import DNSProvider, ZoneRouter
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class _RecordLease:
+    provider: DNSProvider
+    zone: str
+    target: str
+    record_id: str
+    created: bool
+    users: int = 1
+
+
+class Authenticator(dns_common.DNSAuthenticator):
+    """Place each ACME TXT value in its final CNAME target's managed zone."""
+
+    description = "DNS-01 with CNAME delegation to Alibaba Cloud DNS or Tencent Cloud DNSPod."
+    ttl = 600
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.credentials: dns_common.CredentialsConfiguration | None = None
+        self._router: ZoneRouter | None = None
+        self._resolver: CnameResolver | None = None
+        self._challenges: dict[tuple[str, str], list[tuple[str, str, str, str]]] = {}
+        self._leases: dict[tuple[str, str, str, str], _RecordLease] = {}
+
+    @classmethod
+    def add_parser_arguments(cls, add, default_propagation_seconds: int = 60) -> None:
+        super().add_parser_arguments(add, default_propagation_seconds)
+        add("credentials", help="Path to the dns-alias provider credentials INI file.")
+        add("ttl", type=int, default=600, help="TXT record TTL in seconds (default: 600).")
+        add("cname-max-depth", type=int, default=8, help="Maximum CNAME links (default: 8).")
+        add("dns-timeout", type=float, default=10, help="DNS query lifetime (default: 10 seconds).")
+        add("dns-retries", type=int, default=2, help="Retries per failed DNS query (default: 2).")
+        add("resolvers", help="Comma-separated DNS resolver IPv4/IPv6 addresses.")
+        add(
+            "require-cname",
+            action="store_true",
+            default=False,
+            help="Fail if the original challenge name has no CNAME delegation.",
+        )
+
+    def more_info(self) -> str:
+        return (
+            "Follows _acme-challenge CNAME chains and manages individual TXT records "
+            "in Alibaba Cloud DNS or Tencent Cloud DNSPod. Select aliyun, tencent, or auto "
+            "in the credentials file. Cleanup uses saved record IDs and delegation targets."
+        )
+
+    def _setup_credentials(self) -> None:
+        limits = {"ttl": 1, "cname-max-depth": 1, "dns-retries": 0}
+        for option, minimum in limits.items():
+            value = self.conf(option)
+            if value is None or value < minimum:
+                raise errors.PluginError(f"--dns-alias-{option} must be at least {minimum}")
+        timeout = self.conf("dns-timeout")
+        if timeout is None or not math.isfinite(timeout) or timeout <= 0:
+            raise errors.PluginError("--dns-alias-dns-timeout must be a finite positive number")
+        propagation = self.conf("propagation-seconds")
+        if propagation is None or propagation < 0:
+            raise errors.PluginError("--dns-alias-propagation-seconds must be non-negative")
+
+        resolver = dns.resolver.Resolver()
+        if self.conf("resolvers"):
+            try:
+                resolver.nameservers = [
+                    str(ipaddress.ip_address(address.strip()))
+                    for address in self.conf("resolvers").split(",")
+                ]
+            except ValueError as exc:
+                raise errors.PluginError(
+                    "--dns-alias-resolvers must be comma-separated IPv4/IPv6 addresses"
+                ) from exc
+        self._resolver = CnameResolver(
+            resolver,
+            max_depth=self.conf("cname-max-depth"),
+            timeout=timeout,
+            retries=self.conf("dns-retries"),
+        )
+        self.credentials = self._configure_credentials(
+            "credentials",
+            "DNS alias credentials INI file",
+            None,
+            validate_credentials,
+        )
+        self._router = build_router(self.credentials)
+        self.ttl = self.conf("ttl")
+
+    def _perform(self, domain: str, validation_name: str, validation: str) -> None:
+        if self._resolver is None or self._router is None:
+            raise errors.PluginError("DNS alias credentials have not been configured")
+        challenge = (normalize_name(validation_name), validation)
+        target = self._resolver.resolve(
+            validation_name,
+            require_cname=self.conf("require-cname"),
+        )
+        provider, zone = self._router.find(target)
+        record_key = (provider.name, zone, target, validation)
+        if record_key in self._leases:
+            self._leases[record_key].users += 1
+        else:
+            host = relative_name(target, zone)
+            records = provider.list_txt_records(zone, host)
+            existing = next((record for record in records if record.value == validation), None)
+            record_id = (
+                existing.id
+                if existing
+                else provider.create_txt_record(
+                    zone,
+                    host,
+                    validation,
+                    self.ttl,
+                )
+            )
+            self._leases[record_key] = _RecordLease(
+                provider,
+                zone,
+                target,
+                record_id,
+                created=existing is None,
+            )
+            logger.info(
+                "TXT challenge ready: %s -> %s (%s)", validation_name, target, provider.name
+            )
+        # Keep no cleanup state for a write that failed. Keys include the TXT
+        # value because apex and wildcard challenges share validation names.
+        self._challenges.setdefault(challenge, []).append(record_key)
+
+    def _cleanup(self, domain: str, validation_name: str, validation: str) -> None:
+        challenge = (normalize_name(validation_name), validation)
+        keys = self._challenges.get(challenge)
+        if not keys:
+            return
+        record_key = keys[-1]
+        lease = self._leases[record_key]
+        if lease.users == 1 and lease.created:
+            try:
+                lease.provider.delete_txt_record(lease.zone, lease.record_id)
+            except errors.PluginError as exc:
+                # Certbot continues cleaning other challenges. Keep our saved
+                # ID so a subsequent cleanup call can retry this deletion.
+                logger.warning(
+                    "Unable to clean TXT record %s (%s): %s", lease.target, lease.provider.name, exc
+                )
+                return
+            logger.info("Cleaned TXT challenge at %s (%s)", lease.target, lease.provider.name)
+        lease.users -= 1
+        keys.pop()
+        if not keys:
+            del self._challenges[challenge]
+        if lease.users == 0:
+            del self._leases[record_key]

certbot_dns_alias/providers/__init__.py

@@ -0,0 +1 @@
+"""Cloud DNS provider adapters."""

certbot_dns_alias/providers/aliyun.py

@@ -0,0 +1,127 @@
+"""Alibaba Cloud DNS adapter using the official OpenAPI SDK."""
+
+from alibabacloud_alidns20150109 import models
+from alibabacloud_alidns20150109.client import Client
+from alibabacloud_tea_openapi.models import Config
+from alibabacloud_tea_util.models import RuntimeOptions
+from certbot import errors
+from Tea.exceptions import TeaException, UnretryableException
+
+from certbot_dns_alias.providers.base import DNSProvider, TxtRecord
+
+
+class AliyunDNSProvider(DNSProvider):
+    name = "aliyun"
+    page_size = 100
+
+    def __init__(
+        self,
+        access_key_id: str,
+        access_key_secret: str,
+        *,
+        region_id: str = "cn-hangzhou",
+        security_token: str | None = None,
+    ) -> None:
+        self.client = Client(
+            Config(
+                access_key_id=access_key_id,
+                access_key_secret=access_key_secret,
+                security_token=security_token,
+                region_id=region_id,
+                endpoint="alidns.aliyuncs.com",
+            )
+        )
+        # Never automatically replay a write whose result may have been lost.
+        self.runtime = RuntimeOptions(
+            connect_timeout=10000,
+            read_timeout=30000,
+            autoretry=False,
+        )
+
+    def _call(self, operation: str, request):
+        try:
+            return getattr(self.client, operation)(request, self.runtime).body
+        except (TeaException, UnretryableException) as exc:
+            # SDK messages can contain request details. Report only the code.
+            code = getattr(exc, "code", None) or type(exc).__name__
+            raise errors.PluginError(f"Aliyun DNS {operation} failed ({code})") from exc
+
+    def list_zones(self) -> list[str]:
+        zones = []
+        page = 1
+        while True:
+            body = self._call(
+                "describe_domains_with_options",
+                models.DescribeDomainsRequest(
+                    page_number=page,
+                    page_size=self.page_size,
+                ),
+            )
+            items = body.domains.domain if body.domains else []
+            items = items or []
+            zones.extend(item.domain_name for item in items)
+            if page * self.page_size >= body.total_count:
+                return zones
+            if not items:
+                raise errors.PluginError("Aliyun DNS returned an incomplete zone list")
+            page += 1
+
+    def list_txt_records(self, zone: str, name: str) -> list[TxtRecord]:
+        records = []
+        page = 1
+        while True:
+            body = self._call(
+                "describe_domain_records_with_options",
+                models.DescribeDomainRecordsRequest(
+                    domain_name=zone,
+                    rrkey_word=name,
+                    type="TXT",
+                    search_mode="EXACT",
+                    page_number=page,
+                    page_size=self.page_size,
+                ),
+            )
+            items = body.domain_records.record if body.domain_records else []
+            items = items or []
+            records.extend(
+                TxtRecord(str(item.record_id), item.rr, item.value)
+                for item in items
+                if item.type == "TXT"
+                and item.rr.lower() == name.lower()
+                and item.status == "ENABLE"
+                and item.line == "default"
+            )
+            if page * self.page_size >= body.total_count:
+                return records
+            if not items:
+                raise errors.PluginError("Aliyun DNS returned an incomplete TXT record list")
+            page += 1
+
+    def create_txt_record(self, zone: str, name: str, value: str, ttl: int) -> str:
+        body = self._call(
+            "add_domain_record_with_options",
+            models.AddDomainRecordRequest(
+                domain_name=zone,
+                rr=name,
+                type="TXT",
+                value=value,
+                ttl=ttl,
+                line="default",
+            ),
+        )
+        if not body.record_id:
+            raise errors.PluginError("Aliyun DNS did not return a new TXT record ID")
+        return str(body.record_id)
+
+    def delete_txt_record(self, zone: str, record_id: str) -> None:
+        try:
+            self._call(
+                "delete_domain_record_with_options",
+                models.DeleteDomainRecordRequest(
+                    record_id=record_id,
+                ),
+            )
+        except errors.PluginError as exc:
+            # DeleteDomainRecord takes only a record ID, not a zone name.
+            if getattr(exc.__cause__, "code", None) != "InvalidRecordId.NotFound":
+                raise

certbot_dns_alias/providers/base.py

@@ -0,0 +1,81 @@
+"""Shared provider contract and managed-zone selection."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from certbot import errors
+
+from certbot_dns_alias.dns import normalize_name
+
+
+@dataclass(frozen=True)
+class TxtRecord:
+    id: str
+    name: str
+    value: str
+
+
+class DNSProvider(ABC):
+    """Manage individual TXT records without replacing a TXT RRset."""
+
+    name: str
+
+    @abstractmethod
+    def list_zones(self) -> list[str]:
+        """List all managed DNS zones, including all result pages."""
+
+    @abstractmethod
+    def list_txt_records(self, zone: str, name: str) -> list[TxtRecord]:
+        """List TXT records at an exact relative name, including all pages."""
+
+    @abstractmethod
+    def create_txt_record(self, zone: str, name: str, value: str, ttl: int) -> str:
+        """Create one TXT value and return its record ID."""
+
+    @abstractmethod
+    def delete_txt_record(self, zone: str, record_id: str) -> None:
+        """Delete the saved record ID. An already absent record is success."""
+
+
+class ZoneRouter:
+    """Select the longest matching zone across configured provider accounts."""
+
+    def __init__(
+        self,
+        providers: dict[str, DNSProvider],
+        zones: dict[str, list[str]] | None = None,
+    ) -> None:
+        self.providers = providers
+        self.zones = zones or {}
+        self._loaded_zones: dict[str, list[str]] | None = None
+
+    def find(self, fqdn: str) -> tuple[DNSProvider, str]:
+        fqdn = normalize_name(fqdn)
+        if self._loaded_zones is None:
+            # Cache only a complete discovery; API/permission errors must not
+            # silently route to a less specific zone on another provider.
+            discovered = {}
+            for name, provider in self.providers.items():
+                candidates = self.zones[name] if name in self.zones else provider.list_zones()
+                discovered[name] = sorted({normalize_name(zone) for zone in candidates})
+            self._loaded_zones = discovered
+
+        matches = [
+            (zone.count("."), name, zone)
+            for name, zones in self._loaded_zones.items()
+            for zone in zones
+            if fqdn == zone or fqdn.endswith("." + zone)
+        ]
+        if not matches:
+            raise errors.PluginError(
+                f"No managed zone found for {fqdn}; check credentials and configured zones"
+            )
+        best_depth = max(item[0] for item in matches)
+        best = [item for item in matches if item[0] == best_depth]
+        if len(best) != 1:
+            raise errors.PluginError(
+                f"Ambiguous managed zone for {fqdn} on multiple providers; "
+                "set provider-specific zones or select a single provider"
+            )
+        _, provider_name, zone = best[0]
+        return self.providers[provider_name], zone

certbot_dns_alias/providers/tencent.py

@@ -0,0 +1,106 @@
+"""Tencent Cloud DNSPod adapter using the official API v20210323 SDK."""
+
+from certbot import errors
+from tencentcloud.common.credential import Credential
+from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
+from tencentcloud.common.profile.client_profile import ClientProfile
+from tencentcloud.common.profile.http_profile import HttpProfile
+from tencentcloud.dnspod.v20210323 import dnspod_client, models
+
+from certbot_dns_alias.providers.base import DNSProvider, TxtRecord
+
+
+class TencentDNSProvider(DNSProvider):
+    name = "tencent"
+    page_size = 100
+
+    def __init__(self, secret_id: str, secret_key: str, *, token: str | None = None) -> None:
+        http = HttpProfile(endpoint="dnspod.tencentcloudapi.com", reqTimeout=30)
+        self.client = dnspod_client.DnspodClient(
+            Credential(secret_id, secret_key, token),
+            "",
+            ClientProfile(httpProfile=http),
+        )
+
+    def _call(self, operation: str, request):
+        try:
+            return getattr(self.client, operation)(request)
+        except TencentCloudSDKException as exc:
+            raise errors.PluginError(
+                f"Tencent DNSPod {operation} failed ({exc.get_code()})"
+            ) from exc
+
+    def list_zones(self) -> list[str]:
+        zones = []
+        offset = 0
+        while True:
+            request = models.DescribeDomainListRequest()
+            request.Type = "ALL"
+            request.Offset = offset
+            request.Limit = self.page_size
+            body = self._call("DescribeDomainList", request)
+            items = body.DomainList or []
+            zones.extend(item.Name for item in items)
+            offset += len(items)
+            if offset >= body.DomainCountInfo.DomainTotal:
+                return zones
+            if not items:
+                raise errors.PluginError("Tencent DNSPod returned an incomplete zone list")
+
+    def list_txt_records(self, zone: str, name: str) -> list[TxtRecord]:
+        records = []
+        offset = 0
+        while True:
+            request = models.DescribeRecordListRequest()
+            request.Domain = zone
+            request.SubDomain = name
+            request.RecordType = "TXT"
+            request.Offset = offset
+            request.Limit = self.page_size
+            request.ErrorOnEmpty = "no"
+            # Older API/SDK versions raise this code for an empty result.
+            # Do not confuse it with a missing zone or a permission failure.
+            try:
+                body = self._call("DescribeRecordList", request)
+            except errors.PluginError as exc:
+                if getattr(exc.__cause__, "code", None) == "ResourceNotFound.NoDataOfRecord":
+                    return records
+                raise
+            items = body.RecordList or []
+            records.extend(
+                TxtRecord(str(item.RecordId), item.Name, item.Value)
+                for item in items
+                if item.Type == "TXT"
+                and item.Name.lower() == name.lower()
+                and item.Status == "ENABLE"
+                and item.LineId == "0"
+            )
+            offset += len(items)
+            if offset >= body.RecordCountInfo.TotalCount:
+                return records
+            if not items:
+                raise errors.PluginError("Tencent DNSPod returned an incomplete TXT record list")
+
+    def create_txt_record(self, zone: str, name: str, value: str, ttl: int) -> str:
+        request = models.CreateRecordRequest()
+        request.Domain = zone
+        request.SubDomain = name
+        request.RecordType = "TXT"
+        request.RecordLine = "默认"
+        request.RecordLineId = "0"
+        request.Value = value
+        request.TTL = ttl
+        body = self._call("CreateRecord", request)
+        if not body.RecordId:
+            raise errors.PluginError("Tencent DNSPod did not return a new TXT record ID")
+        return str(body.RecordId)
+
+    def delete_txt_record(self, zone: str, record_id: str) -> None:
+        request = models.DeleteRecordRequest()
+        request.Domain = zone
+        request.RecordId = int(record_id)
+        try:
+            self._call("DeleteRecord", request)
+        except errors.PluginError as exc:
+            if getattr(exc.__cause__, "code", None) != "ResourceNotFound.NoDataOfRecord":
+                raise

certbot_dns_alias-0.1.0.dist-info/METADATA

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: certbot-dns-alias
+Version: 0.1.0
+Summary: Certbot DNS-01 plugin with CNAME delegation for Alibaba Cloud DNS and Tencent Cloud DNSPod
+Project-URL: Homepage, https://github.com/tiyee/certbot-dns-alias
+Project-URL: Repository, https://github.com/tiyee/certbot-dns-alias
+Project-URL: Issues, https://github.com/tiyee/certbot-dns-alias/issues
+Author-email: tiyee <tiyee@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acme,aliyun,certbot,cname,dns-01,dnspod,tencent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: alibabacloud-alidns20150109<5,>=3.0
+Requires-Dist: alibabacloud-tea-openapi<1,>=0.3
+Requires-Dist: alibabacloud-tea-util<1,>=0.3
+Requires-Dist: certbot<6,>=3.0
+Requires-Dist: dnspython<3,>=2.6
+Requires-Dist: tencentcloud-sdk-python-dnspod<4,>=3.1.130
+Description-Content-Type: text/markdown
+
+# certbot-dns-alias
+
+Certbot DNS-01 插件，通过 CNAME 委托在阿里云 DNS 或腾讯云 DNSPod 管理 TXT 验证记录。
+
+Certbot DNS-01 authentication with CNAME delegation, supporting Alibaba Cloud DNS and Tencent Cloud DNSPod.
+
+## 工作方式
+
+在业务域名的 DNS 中预先创建 CNAME：
+
+```dns
+_acme-challenge.example.com.  300 IN CNAME example-com.delegate.example.net.
+```
+
+`delegate.example.net` 托管在阿里云或腾讯云。插件自动跟随 CNAME 链，在最终目标
+`example-com.delegate.example.net` 添加本次挑战的 TXT 值，等待 DNS 传播，完成后按记录 ID 清理。
+业务域名可以由任意 DNS 服务商托管；插件只需要目标托管区域的 API 凭据。
+
+- 支持多级 CNAME、泛域名、一个证书包含多个域名。
+- 支持阿里云、腾讯云单独使用，或 `auto` 模式在一次申请中同时使用两者。
+- 根据托管区域列表做最长 DNS 后缀匹配，支持 `example.co.uk` 和独立托管的子域，匹配包含标签边界。
+- 区域列表及 TXT 查询支持 API 分页；可以显式配置区域以跳过自动枚举。
+- 每个 TXT 值单独创建，保留同名记录的其他值；复用已有的相同有效 TXT 时不删除原记录。
+- 清理使用创建时保存的目标区域和记录 ID；CNAME 发生变化也不会改删其他区域。
+- CNAME 环路、超深链、DNS 超时、权限错误和区域归属冲突会产生明确错误。
+
+Python **3.10+**，Certbot **3.x–5.x**。两个云服务商 SDK 均随插件安装。
+
+## 安装
+
+### 本地开发（uv）
+
+```bash
+uv sync --locked
+uv run certbot plugins --text
+uv run certbot --help dns-alias
+```
+
+`uv.lock` 已纳入版本管理，`uv sync` 会创建 `.venv` 并以 editable 模式安装插件。
+
+### 从 PyPI 安装（本项目发布后）
+
+使用 uv 安装 Certbot 和插件到同一个工具环境：
+
+```bash
+uv tool install --with certbot-dns-alias certbot
+certbot plugins --text
+```
+
+或者在安装 Certbot 的 Python 虚拟环境中执行：
+
+```bash
+python -m pip install certbot-dns-alias
+```
+
+插件与 Certbot 必须处于同一 Python 环境。如果已有 snap/docker 版 Certbot，需在该运行环境中
+安装插件，或者改用上述 uv 工具环境。
+
+## 凭据配置
+
+使用不带 INI section 的 `key = value` 格式。完整示例见 [examples](examples)。
+复制示例后填入密钥，并设置权限：
+
+```bash
+cp examples/tencent.ini credentials.ini
+chmod 600 credentials.ini
+```
+
+### 阿里云
+
+```ini
+dns_alias_provider = aliyun
+dns_alias_aliyun_access_key_id = YOUR_ACCESS_KEY_ID
+dns_alias_aliyun_access_key_secret = YOUR_ACCESS_KEY_SECRET
+dns_alias_aliyun_zones = delegate.example.net
+```
+
+可选项：`dns_alias_aliyun_region_id`（默认 `cn-hangzhou`）、
+`dns_alias_aliyun_security_token`（临时 STS 凭据）。固定使用公共端点 `alidns.aliyuncs.com`。
+
+### 腾讯云 DNSPod
+
+```ini
+dns_alias_provider = tencent
+dns_alias_tencent_secret_id = YOUR_SECRET_ID
+dns_alias_tencent_secret_key = YOUR_SECRET_KEY
+dns_alias_tencent_zones = delegate.example.net
+```
+
+可选项：`dns_alias_tencent_token`（临时会话凭据）。使用腾讯云 API v20210323 和
+`dnspod.tencentcloudapi.com`，不使用旧版 DNSPod Token API 或国际版端点。
+
+### 同时使用两家云服务商
+
+```ini
+dns_alias_provider = auto
+dns_alias_aliyun_access_key_id = YOUR_ACCESS_KEY_ID
+dns_alias_aliyun_access_key_secret = YOUR_ACCESS_KEY_SECRET
+dns_alias_aliyun_zones = ali-delegate.example.net
+dns_alias_tencent_secret_id = YOUR_SECRET_ID
+dns_alias_tencent_secret_key = YOUR_SECRET_KEY
+dns_alias_tencent_zones = tencent-delegate.example.org
+```
+
+例如：
+
+```dns
+_acme-challenge.example.com.      300 IN CNAME example-com.ali-delegate.example.net.
+_acme-challenge.api.example.org.  300 IN CNAME api-example-org.tencent-delegate.example.org.
+```
+
+随后在同一命令中传入 `-d example.com -d api.example.org` 即可。`auto` 至少需要一组完整密钥，
+也可以只配置一家。如果同一最长匹配区域同时属于两个服务商，插件会报错；通过调整显式区域列表
+或选择单一 `provider` 消除歧义。
+
+所有 `*_zones` 均为可选项，多个区域以逗号分隔，例如 `example.net, example.co.uk`。
+配置后只允许这些区域，不再调用对应的域名枚举 API；填写云平台实际托管区域名称，
+不要填写完整 TXT 主机名。未配置时自动枚举当前凭据可见的区域。
+每家服务商目前支持一个凭据账号。
+
+## 申请和续期
+
+先创建 CNAME，并确保公共 DNS 可以解析；第一次申请可以使用测试环境：
+
+```bash
+uv run certbot certonly \
+  --authenticator dns-alias \
+  --dns-alias-credentials "$(pwd)/credentials.ini" \
+  --dns-alias-require-cname \
+  --dns-alias-propagation-seconds 120 \
+  --staging \
+  --non-interactive --agree-tos --email admin@example.com \
+  -d example.com -d '*.example.com'
+```
+
+测试通过后去掉 `--staging` 申请正式证书。域名和邮箱应替换为自己的值。
+如果使用 uv 工具安装，命令前缀用 `certbot`。
+Certbot 默认写入 `/etc/letsencrypt`、`/var/lib/letsencrypt` 和 `/var/log/letsencrypt`，
+运行账号需要相应权限；也可使用 `--config-dir`、`--work-dir` 和 `--logs-dir` 指定目录。
+
+Certbot 保存认证器和凭据文件的绝对路径，后续可使用同一环境续期：
+
+```bash
+uv run certbot renew --dry-run
+uv run certbot renew
+```
+
+凭据文件需长期保留，临时凭据过期前需更新。按部署方式配置定时续期及证书部署 hook。
+
+### 可配置参数
+
+| 参数 | 默认值 | 作用 |
+| --- | --- | --- |
+| `--dns-alias-credentials` | 必填 | 凭据 INI 路径 |
+| `--dns-alias-propagation-seconds` | `60` | 全部 TXT 添加后，统一等待的传播时间 |
+| `--dns-alias-ttl` | `600` | 创建 TXT 时的 TTL，需满足云套餐限制 |
+| `--dns-alias-cname-max-depth` | `8` | 允许的最大 CNAME 链接数 |
+| `--dns-alias-dns-timeout` | `10` | 每次 CNAME 查询的总超时，秒 |
+| `--dns-alias-dns-retries` | `2` | 超时或无可用 nameserver 时额外重试次数 |
+| `--dns-alias-resolvers` | 系统 DNS | 逗号分隔的 DNS 服务器 IPv4/IPv6 地址 |
+| `--dns-alias-require-cname` | 关闭 | 原始挑战名称没有 CNAME 时拒绝写入 |
+
+没有 CNAME 时，默认允许直接在原始挑战名称所属托管区域创建 TXT。只允许委托验证时启用
+`--dns-alias-require-cname`。解析器使用绝对 DNS 名称，禁止系统 search suffix 扩展。
+NXDOMAIN / 无 CNAME 表示链终点；超时、SERVFAIL 等解析失败不会当作链终点。
+
+TTL 与传播等待时间不同。第一次创建目标主机可能受 DNS 负缓存影响，必要时提高传播等待时间。
+不同业务域名应使用不同委托主机名；普通域名与其泛域名会共用 `_acme-challenge` 名称，
+插件会保留本次申请需要的多个 TXT 值。插件不会更新整个 TXT RRset。
+
+## API 权限
+
+阿里云需要：
+
+- `alidns:DescribeDomainRecords`
+- `alidns:AddDomainRecord`
+- `alidns:DeleteDomainRecord`
+- 未配置 `dns_alias_aliyun_zones` 时，还需要 `alidns:DescribeDomains`
+
+腾讯云需要：
+
+- `dnspod:DescribeRecordList`
+- `dnspod:CreateRecord`
+- `dnspod:DeleteRecord`
+- 未配置 `dns_alias_tencent_zones` 时，还需要 `dnspod:DescribeDomainList`
+
+可根据云平台支持的资源范围将权限限制在委托区域。API 字段与权限参考
+[阿里云 AddDomainRecord](https://www.alibabacloud.com/help/en/dns/api-alidns-2015-01-09-adddomainrecord)、
+[阿里云 DescribeDomains](https://www.alibabacloud.com/help/en/dns/api-alidns-2015-01-09-describedomains) 和
+[腾讯云 DescribeRecordList](https://cloud.tencent.com/document/api/1427/56166)。
+
+## 测试和构建
+
+```bash
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest --cov=certbot_dns_alias --cov-report=term-missing
+uv build
+uv run twine check --strict dist/*
+```
+
+测试通过 mock 官方 SDK 和 DNS 响应运行，不需要真实 API 密钥，不会写入云端 DNS。
+包含 Certbot 公共挑战生命周期测试、CNAME 链 / 环路 / 超时 / NXDOMAIN、区域匹配、
+两个 SDK 的真实请求模型和分页、已有 TXT 保留、多挑战共享与清理失败处理。
+CI 配置 Python 3.10–3.14，以及 Certbot 3.0 兼容性验证。
+Certbot 3.0 的旧 ACME/josepy 依赖需要 `pyOpenSSL<25`；兼容性测试使用这一旧版本依赖组合。
+新安装默认由 uv 选择最新可用的 Certbot 版本。
+
+目录结构：
+
+```text
+certbot_dns_alias/
+  dns_alias.py        # Certbot Authenticator、TXT 所有权和清理状态
+  dns.py              # CNAME 解析、DNS 名称和相对主机记录
+  config.py           # INI 校验和服务商构建
+  providers/
+    base.py           # 服务商接口及区域路由
+    aliyun.py         # 阿里云 OpenAPI SDK
+    tencent.py        # 腾讯云 DNSPod SDK
+examples/             # 三种模式的凭据示例
+tests/                # 无网络单元和生命周期测试
+```
+
+创建和删除 API 不自动重试写请求，避免响应丢失后的重复创建。清理失败会记录警告并继续清理其他挑战。
+创建状态保存在当前 Certbot 进程内；进程被强制终止、创建成功但响应丢失或删除失败时，可能留有 TXT，
+需要在委托区域手动清理。插件不持久化密钥或挑战值，也不会通过重新解析 CNAME 来猜测待删除记录。
+
+## 发布到 PyPI
+
+包名为 `certbot-dns-alias`，Certbot 入口点为 `dns-alias`。
+
+手动发布前，在 `pyproject.toml` 更新版本，再运行 `uv lock`、测试和构建。可先上传 TestPyPI：
+
+```bash
+uv build
+uv publish --publish-url https://test.pypi.org/legacy/ dist/*
+# 正式发布
+uv publish dist/*
+```
+
+上传时配置对应的 `UV_PUBLISH_TOKEN`。发布新版本前清空旧 `dist` 产物，以免上传旧版本。
+
+仓库包含 `.github/workflows/publish.yml`，GitHub Release 发布时会验证标签与项目版本一致
+（例如版本 `0.1.0` 对应 `v0.1.0`），运行测试、构建 wheel/sdist 并通过 PyPI Trusted Publishing 上传。
+需先在 PyPI 为仓库 `tiyee/certbot-dns-alias` 配置 Trusted Publisher，工作流文件名 `publish.yml`，
+environment 为 `pypi`；尚未创建 PyPI 项目时可以使用 pending publisher。
+GitHub 仓库中创建同名 environment，可按需要设置发布审核。预发布 Release 只构建，不上传正式 PyPI。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。

certbot_dns_alias-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+certbot_dns_alias/__init__.py,sha256=VylHtRr5N_3VpRDJhznxp_mqZtPiYMj_UiL1Vzmi0W4,59
+certbot_dns_alias/config.py,sha256=E256Y5jpe5PHDURpLY2MjC8gGOKUxfFDGGmQ12mOxCw,3830
+certbot_dns_alias/dns.py,sha256=Mge5FLR6EZH_Ijt1OCx7wfLf7kRHLbHyWFw0JX4uWzg,4739
+certbot_dns_alias/dns_alias.py,sha256=w9Kk8dnBWu6LegyOu5hS8pL4hmiCECklH8gDlWBaLy4,7106
+certbot_dns_alias/providers/__init__.py,sha256=0KXnLkdf8_u17QWBgnBEp1Fss6XbeluFOydvCgjU7aI,35
+certbot_dns_alias/providers/aliyun.py,sha256=D4CmsA9vPO10XOaZXNEs8dO4xtsPr92qq7j9qVnzyog,4648
+certbot_dns_alias/providers/base.py,sha256=kq4vKDSkZwCcETddI4ZGadVNfWiWdd6imtDC6DXQQX4,2843
+certbot_dns_alias/providers/tencent.py,sha256=SsLnd7-Uqapv5UXbLeuwZ5LoQ2Ejw8oJtVhSJ323d9g,4339
+certbot_dns_alias-0.1.0.dist-info/METADATA,sha256=fVGA0DgJcUsTeDz8-U80hwL5zZKXpL0tT88-yDXTCYk,11858
+certbot_dns_alias-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+certbot_dns_alias-0.1.0.dist-info/entry_points.txt,sha256=h9Le-acht10yK8Cyf2svaZuyV9EQWbY1MY4YbP8picA,72
+certbot_dns_alias-0.1.0.dist-info/licenses/LICENSE,sha256=ZrKzYat2vy2EQzTVpYheUM-WOPSyYJ20P6RFOGgaltI,1067
+certbot_dns_alias-0.1.0.dist-info/RECORD,,

certbot_dns_alias-0.1.0.dist-info/WHEEL

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

certbot_dns_alias-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[certbot.plugins]
+dns-alias = certbot_dns_alias.dns_alias:Authenticator

certbot_dns_alias-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TiyeeJiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.