feat(dstack-ingress): ACME DNS-01 challenge delegation (CNAME alias)

Adds an opt-in `ACME_CHALLENGE_ALIAS` mode so the DNS token can be scoped to a
delegated zone instead of the served domain's own (often shared, production)
zone. Closes the least-privilege gap described in the issue.

- certman.py: when ACME_CHALLENGE_ALIAS is set, run certbot via `--manual` with
  auth/cleanup hooks instead of the provider's DNS plugin; `renew` reuses the
  hooks saved in the renewal config.
- acme-dns-alias-hook.sh: writes/removes the `_acme-challenge` TXT in the
  delegated zone (reusing dnsman.py / the existing provider abstraction).
- dnsman.py + base.py: add `unset_txt` for challenge cleanup.
- entrypoint.sh: in delegation mode the served-zone records (alias, app-address
  TXT, CAA) can't be written by our token, so print the exact records the
  operator must set statically, and for CAA verify presence (via DoH) and warn
  loudly if missing — instead of silently dropping the accounturi lock.
- README: document the mode, required static records, and the CAA security note.

Non-breaking: unset ACME_CHALLENGE_ALIAS = current behavior.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xa1zFJs3FVP8UTsSWuS3Yj

Author: Ravenyjh

custom-domain/dstack-ingress/README.md

@@ -179,9 +179,39 @@ environment:
 | `EVIDENCE_SERVER` | `true` | Serve evidence files at `/evidences/` on the TLS port |
 | `EVIDENCE_PORT` | `80` | Internal port for evidence HTTP server |
 | `ALPN` | | TLS ALPN protocols (e.g. `h2,http/1.1`). Only set if backends support h2c |
+| `ACME_CHALLENGE_ALIAS` | | Delegate the ACME DNS-01 challenge to this zone (see below) so the DNS token needs no access to the served domain's own zone |
+| `ACME_CHALLENGE_PROPAGATION_SECONDS` | `30` | Wait after writing the delegated challenge TXT before validation (only used with `ACME_CHALLENGE_ALIAS`) |
 
 For DNS provider credentials, see [DNS_PROVIDERS.md](DNS_PROVIDERS.md).
 
+### ACME challenge delegation (least-privilege DNS token)
+
+By default the DNS token must be able to edit the **served domain's own zone**
+(to write `_acme-challenge`, and — with `SET_CAA` — the CAA record). If the
+served name lives under a shared production zone (e.g. `svc.example.com` under
+`example.com`), that token can edit every record in the zone, which may be more
+privilege than you want.
+
+Set `ACME_CHALLENGE_ALIAS=<delegation-zone>` to answer the DNS-01 challenge in a
+separate zone that your token controls, so the token never touches the served
+domain's zone. In this mode dstack-ingress **only** manages the challenge TXT in
+the delegation zone; you set the following records **once, statically**, in the
+served domain's production zone (the container prints the exact values on start):
+
+```
+svc.example.com                       CNAME  <GATEWAY_DOMAIN>
+_dstack-app-address.svc.example.com   TXT    "<app-id>:<port>"
+_acme-challenge.svc.example.com       CNAME  _acme-challenge.svc.example.com.<delegation-zone>
+svc.example.com                       CAA    0 issue "letsencrypt.org;validationmethods=dns-01;accounturi=<account-uri>"
+```
+
+> **Security note.** The `accounturi` CAA restricts issuance to this enclave's
+> ACME account. In delegation mode dstack-ingress cannot set it for you (no
+> token for the served zone), so it prints the record and verifies (via DoH)
+> that it is present, warning loudly if not. Without this CAA, anyone who can
+> satisfy the delegated challenge could obtain a certificate for the domain.
+> Provide the token scoped only to `<delegation-zone>`.
+
 ## Evidence & Attestation
 
 Evidence files are served at `https://your-domain.com/evidences/` by default (via payload inspection in HAProxy's TCP mode). They can also be accessed by the backend application through the shared `/evidences` volume.

custom-domain/dstack-ingress/scripts/acme-dns-alias-hook.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# certbot --manual auth/cleanup hook for ACME DNS-01 challenge delegation.
+#
+# Instead of writing the `_acme-challenge` TXT into the served domain's own
+# zone (which requires a DNS token for that zone), this writes it into a
+# delegated zone that our token controls (ACME_CHALLENGE_ALIAS). The served
+# domain's zone only needs one static, operator-managed CNAME:
+#
+#   _acme-challenge.<domain>  CNAME  _acme-challenge.<domain>.<ACME_CHALLENGE_ALIAS>
+#
+# Let's Encrypt follows that CNAME during validation and reads the TXT from the
+# delegated zone, so the enclave's token never needs access to the served
+# domain's (production) zone.
+#
+# certbot invokes this with $CERTBOT_DOMAIN and $CERTBOT_VALIDATION set, and
+# runs it as either:  acme-dns-alias-hook.sh auth  |  acme-dns-alias-hook.sh cleanup
+set -euo pipefail
+
+action="${1:-}"
+
+if [ -z "${ACME_CHALLENGE_ALIAS:-}" ]; then
+    echo "acme-dns-alias-hook: ACME_CHALLENGE_ALIAS is not set" >&2
+    exit 1
+fi
+if [ -z "${CERTBOT_DOMAIN:-}" ]; then
+    echo "acme-dns-alias-hook: CERTBOT_DOMAIN not set (must be invoked by certbot)" >&2
+    exit 1
+fi
+
+# certbot always passes the base domain (no leading "*.") in CERTBOT_DOMAIN.
+record="_acme-challenge.${CERTBOT_DOMAIN}.${ACME_CHALLENGE_ALIAS}"
+
+case "$action" in
+    auth)
+        : "${CERTBOT_VALIDATION:?CERTBOT_VALIDATION not set}"
+        echo "acme-dns-alias-hook: writing challenge TXT to delegated record $record"
+        dnsman.py set_txt --domain "$record" --content "$CERTBOT_VALIDATION"
+        # certbot asks Let's Encrypt to validate immediately after this hook
+        # returns, so wait for the record to propagate on the delegated zone's
+        # authoritative servers before returning.
+        sleep "${ACME_CHALLENGE_PROPAGATION_SECONDS:-30}"
+        ;;
+    cleanup)
+        echo "acme-dns-alias-hook: removing challenge TXT $record"
+        # Non-fatal: a failed cleanup leaves a stale TXT in the delegated zone,
+        # which the next auth overwrites; it must not fail the whole run.
+        dnsman.py unset_txt --domain "$record" || true
+        ;;
+    *)
+        echo "acme-dns-alias-hook: usage: $0 <auth|cleanup>" >&2
+        exit 1
+        ;;
+esac

custom-domain/dstack-ingress/scripts/certman.py

@@ -265,13 +265,40 @@ def setup_credentials(self) -> bool:
 
     def _build_certbot_command(self, action: str, domain: str, email: str) -> List[str]:
         """Build certbot command using provider configuration."""
+        certbot_cmd = self._get_certbot_command()
+
+        # Challenge-delegation mode: when ACME_CHALLENGE_ALIAS is set, answer the
+        # DNS-01 challenge in a delegated zone via a manual hook instead of the
+        # provider's certbot plugin, so our DNS token never needs access to the
+        # served domain's own zone. See scripts/acme-dns-alias-hook.sh.
+        if os.environ.get("ACME_CHALLENGE_ALIAS", "").strip():
+            hook = "/scripts/acme-dns-alias-hook.sh"
+            base_cmd = certbot_cmd + [action, "--non-interactive", "-v"]
+            if action == "certonly":
+                base_cmd.extend([
+                    "--manual",
+                    "--preferred-challenges=dns",
+                    f"--manual-auth-hook={hook} auth",
+                    f"--manual-cleanup-hook={hook} cleanup",
+                    "--agree-tos", "--no-eff-email",
+                    "--email", email, "-d", domain,
+                ])
+            # For `renew`, certbot reuses the authenticator + hooks saved in the
+            # renewal config from the initial `certonly`, so we don't re-specify
+            # them here (and must not fall back to the DNS plugin).
+            if os.environ.get("CERTBOT_STAGING", "false") == "true":
+                base_cmd.append("--staging")
+            masked = [a if not (i > 0 and base_cmd[i - 1] == "--email") else "<email>"
+                      for i, a in enumerate(base_cmd)]
+            print(f"Executing (challenge-delegation): {' '.join(masked)}")
+            return base_cmd
+
         plugin = self.provider.CERTBOT_PLUGIN
         if not plugin:
             raise ValueError(
                 f"No certbot plugin configured for {self.provider_type}")
 
         # Use Python module execution to ensure same environment
-        certbot_cmd = self._get_certbot_command()
         base_cmd = certbot_cmd + [action, "-a",
                                   plugin, "--non-interactive", "-v"]
 

custom-domain/dstack-ingress/scripts/dns_providers/base.py

@@ -247,6 +247,24 @@ def set_txt_record(self, name: str, content: str, ttl: int = 60) -> bool:
         )
         return self.create_dns_record(new_record)
 
+    def unset_txt_record(self, name: str) -> bool:
+        """Delete all TXT records for a name.
+
+        Used to clean up ACME DNS-01 challenge records (e.g. from a certbot
+        --manual cleanup hook). Missing records are treated as success.
+
+        Args:
+            name: The record name
+
+        Returns:
+            True if all matching records were removed (or none existed).
+        """
+        ok = True
+        for record in self.get_dns_records(name, RecordType.TXT):
+            if record.id and not self.delete_dns_record(record.id, name):
+                ok = False
+        return ok
+
     def set_caa_record(
         self,
         name: str,

custom-domain/dstack-ingress/scripts/dnsman.py

@@ -14,7 +14,7 @@ def main():
     )
     parser.add_argument(
         "action",
-        choices=["set_cname", "set_alias", "set_txt", "set_caa"],
+        choices=["set_cname", "set_alias", "set_txt", "unset_txt", "set_caa"],
         help="Action to perform",
     )
     parser.add_argument("--domain", required=True, help="Domain name")
@@ -67,6 +67,13 @@ def main():
                 sys.exit(1)
             print(f"Successfully set TXT record for {args.domain}")
 
+        elif args.action == "unset_txt":
+            success = provider.unset_txt_record(args.domain)
+            if not success:
+                print(f"Failed to unset TXT record for {args.domain}", file=sys.stderr)
+                sys.exit(1)
+            print(f"Successfully unset TXT record for {args.domain}")
+
         elif args.action == "set_caa":
             if not args.caa_tag or not args.caa_value:
                 print(

custom-domain/dstack-ingress/scripts/entrypoint.sh

@@ -268,6 +268,13 @@ backend ${be_name}
 
 set_alias_record() {
     local domain="$1"
+    if [ -n "${ACME_CHALLENGE_ALIAS:-}" ]; then
+        echo "[challenge-delegation] Not touching ${domain}'s own zone (token is scoped to the delegated zone)."
+        echo "[challenge-delegation] Set these in your production zone yourself (static, one-time):"
+        echo "    ${domain}  CNAME  ${GATEWAY_DOMAIN}"
+        echo "    _acme-challenge.${domain}  CNAME  _acme-challenge.${domain}.${ACME_CHALLENGE_ALIAS}"
+        return
+    fi
     echo "Setting alias record for $domain"
     dnsman.py set_alias \
         --domain "$domain" \
@@ -301,6 +308,12 @@ set_txt_record() {
         txt_domain="${TXT_PREFIX}.${domain}"
     fi
 
+    if [ -n "${ACME_CHALLENGE_ALIAS:-}" ]; then
+        echo "[challenge-delegation] Set this in your production zone yourself (static, one-time):"
+        echo "    ${txt_domain}  TXT  \"$APP_ID:$PORT\""
+        return
+    fi
+
     dnsman.py set_txt \
         --domain "$txt_domain" \
         --content "$APP_ID:$PORT"
@@ -337,6 +350,30 @@ set_caa_record() {
     fi
 
     ACCOUNT_URI=$(jq -j '.uri' "$account_file")
+
+    if [ -n "${ACME_CHALLENGE_ALIAS:-}" ]; then
+        # Delegation mode: our token has no access to the served domain's zone,
+        # so we cannot set the accounturi CAA ourselves. This CAA is the
+        # forge-prevention (only the enclave's ACME account may issue), so we do
+        # NOT silently skip it — we print the exact record the operator must set,
+        # then best-effort verify it and warn loudly if it is missing.
+        local caa_value="letsencrypt.org;validationmethods=dns-01;accounturi=$ACCOUNT_URI"
+        echo "[challenge-delegation] Set this CAA in your production zone yourself (static):"
+        echo "    ${caa_domain}  CAA  0 ${caa_tag} \"${caa_value}\""
+        # Verify via DNS-over-HTTPS (dig is not installed; curl is).
+        local caa_answer
+        caa_answer=$(curl -s --max-time 10 "https://dns.google/resolve?name=${caa_domain}&type=257" 2>/dev/null || true)
+        if echo "$caa_answer" | grep -q "accounturi=$ACCOUNT_URI"; then
+            echo "[challenge-delegation] Verified: accounturi CAA is present for $caa_domain"
+        else
+            echo "WARNING: accounturi CAA is NOT present for $caa_domain."
+            echo "WARNING: Without it, anyone who can satisfy the DNS-01 challenge could obtain a"
+            echo "WARNING: publicly-trusted certificate for this domain (forged TLS termination)."
+            echo "WARNING: Set the CAA record shown above before relying on this endpoint."
+        fi
+        return
+    fi
+
     echo "Adding CAA record ($caa_tag) for $caa_domain, accounturi=$ACCOUNT_URI"
     dnsman.py set_caa \
         --domain "$caa_domain" \