fix(dstack-ingress): keep delegation's CAA gate fail-closed

Routing the delegation checks through dnsguide silently changed what the
CAA check means. dnsguide asks "does anything forbid us from issuing",
and under RFC 8659 an absent CAA record set forbids nothing, so it
passes. Delegation asks the opposite question: that record is the only
thing stopping anyone else who can satisfy the delegated challenge from
getting a certificate for the name, and we hold no token to create it, so
its absence is exactly the state that has to block.

The end-to-end run caught it -- with no CAA at all the check reported
"ok (no CAA record set; issuance is unrestricted)" and let issuance
proceed, where #104 would have refused to start. The unit tests did not,
because they only ever asserted on records that exist.

`--caa-required` inverts the rule for this one caller. ALLOW_MISSING_CAA
still downgrades it to a warning, so the escape hatch behaves as
documented.

It is now better than the original in one respect: under DNS_SETUP_MODE
wait the container waits for the operator to create the record rather
than failing on the first look, and still fails after DNS_SETUP_TIMEOUT.

TESTING.md documents how to exercise delegation without a second
registrar account -- any name under a zone you already control works,
because the provider resolves zones by longest-suffix match -- along with
what that substitution does not cover.

Author: kvinwang

custom-domain/dstack-ingress/TESTING.md

@@ -199,13 +199,59 @@ first issuance.
   payload, and a TDX quote whose `report_data` is `sha256(payload)`. Verify both:
   the HMAC proves the shared secret, the quote proves the enclave.
 
+### Challenge delegation (dns-01)
+
+`ACME_CHALLENGE_ALIAS` answers the DNS-01 challenge in a zone the container's
+token controls, so the token needs no access to the served domain's own zone.
+Testing it looks like it needs a second registrar account. It does not.
+
+Any name under a zone you already control works as the delegation zone, because
+the provider resolves a zone by longest-suffix match on the record name. With
+`ACME_CHALLENGE_ALIAS=deleg.example.com` and a served domain of
+`svc.example.com`, the challenge record is
+`_acme-challenge.svc.example.com.deleg.example.com`, which lands in
+`example.com` — the same zone, but through the delegation code path.
+
+Play the operator and create the three static records the container prints:
+
+```
+svc.example.com                    CNAME  <GATEWAY_DOMAIN>
+_dstack-app-address.svc.example.com  TXT  "<app-id>:443"
+_acme-challenge.svc.example.com    CNAME  _acme-challenge.svc.example.com.deleg.example.com
+```
+
+Then start the container with a real provider token and `ACME_STAGING=true`, and
+watch for: the three records verifying, `Executing (challenge-delegation):` with
+`--manual` and both hooks, the certificate arriving, and the challenge TXT being
+cleaned up afterwards (query `_acme-challenge.<domain>.<alias>` at the
+authoritative nameserver — it should be gone).
+
+The CAA step comes last, once the ACME account exists and its URI is known. It
+blocks until you create the record it prints. Cloudflare's API wants CAA as
+structured fields rather than one string, so most quick DNS scripts cannot write
+it; the image's own `dnsman.py set_caa` can, and running it in a one-off
+container is the easiest way to play the operator here:
+
+```bash
+docker run --rm --env-file .env --entrypoint dnsman.py <image> \
+  set_caa --domain svc.example.com --caa-tag issue \
+  --caa-value 'letsencrypt.org;validationmethods=dns-01;accounturi=<uri>'
+```
+
+**What this does not test.** The whole point of delegation is that a token scoped
+to *only* the delegation zone is enough. Sharing one zone exercises every line of
+the mechanism but leaves that property unverified — the token still has access to
+the served zone, so a bug that quietly writes there would not show up. Confirming
+the scoping needs a genuinely separate zone with a separate token.
+
 ### Negative paths
 
 These fail fast and are cheap, so run them on every change:
 
 | Scenario | Expected |
 |---|---|
 | tls-alpn-01 + a wildcard domain | Refused before any ACME call, citing RFC 8737 |
+| Delegation with no CAA record at all | Blocked — unlike normal issuance, where "no CAA" means unrestricted and passes |
 | A CAA record with `validationmethods=dns-01`, mode tls-alpn-01 | Blocked with the restriction quoted back |
 | TXT holding the wrong value | Reported as `want <x>, saw <y>`, not "missing" |
 | An instance ID the gateway does not know | The CA reports a connection error — the gateway will not route to it |

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

@@ -138,18 +138,23 @@ delegation_guide() {
 # a confirmed-absent record is fatal. ALLOW_MISSING_CAA downgrades it to a
 # warning for operators who accept that risk.
 delegation_verify_caa() {
-    local domain="$1" account_file account_uri advisory=()
+    local domain="$1" account_file account_uri
     if ! account_file=$(get_letsencrypt_account_file); then
         echo "ERROR: cannot read the ACME account file to determine the required CAA" >&2
         return 1
     fi
     account_uri=$(jq -j '.uri' "$account_file")
-    [ "${ALLOW_MISSING_CAA:-false}" = "true" ] && advisory=(--caa-advisory)
+    # Absent is the state to block on here, not "absent means unrestricted":
+    # we cannot create this record, so nothing else protects the name.
+    local gate=(--caa-required)
+    if [ "${ALLOW_MISSING_CAA:-false}" = "true" ]; then
+        gate=(--caa-required --caa-advisory)
+    fi
 
     delegation_guide "$domain" caa \
         --caa-value "letsencrypt.org;validationmethods=dns-01;accounturi=$account_uri" \
         --account-uri "$account_uri" \
-        "${advisory[@]}"
+        "${gate[@]}"
 }
 
 set_caa_record() {

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

@@ -269,12 +269,24 @@ def _caa_permits(value: str, tag: str, want_method: str, account_uri: str) -> Tu
 
 
 def check_caa(
-    domain: str, want_tag: str, want_method: str, account_uri: str, resolvers: str
+    domain: str,
+    want_tag: str,
+    want_method: str,
+    account_uri: str,
+    resolvers: str,
+    require_present: bool = False,
 ) -> Tuple[bool, str]:
     """Check CAA for domain, walking up to the closest ancestor that has one.
 
     An absent CAA record set means every CA may issue (RFC 8659), so "no CAA
-    anywhere" is a pass, not a failure.
+    anywhere" is normally a pass: we are asking whether *we* may issue, and
+    nothing forbids it.
+
+    `require_present` inverts that for challenge delegation, where the question
+    is different. There the record is not a formality but the only thing stopping
+    someone else who can satisfy the delegated challenge from getting a
+    certificate for this name, and we hold no token to create it ourselves. An
+    unrestricted name is exactly the state that must block.
     """
     labels = _fqdn(domain).split(".")
     for i in range(len(labels) - 1):
@@ -308,6 +320,11 @@ def check_caa(
             reasons.append(reason)
         return False, f"CAA at {candidate} does not permit issuance: {'; '.join(reasons)}"
 
+    if require_present:
+        return False, (
+            "no CAA record set, so any account that can satisfy the delegated "
+            "challenge could obtain a certificate for this name"
+        )
     return True, "ok (no CAA record set; issuance is unrestricted)"
 
 
@@ -341,6 +358,7 @@ def verify_once(
     account_uri: str,
     resolvers: str,
     caa_advisory: bool = False,
+    caa_required: bool = False,
 ) -> List[Tuple[str, bool, str]]:
     results = []
     for rec in records:
@@ -353,7 +371,9 @@ def verify_once(
             else:
                 ok, why = check_alias(rec, resolvers)
             results.append((f"CNAME {rec.name}", ok, why))
-    ok, why = check_caa(domain, caa_tag, caa_method, account_uri, resolvers)
+    ok, why = check_caa(
+        domain, caa_tag, caa_method, account_uri, resolvers, caa_required
+    )
     if not ok and caa_advisory:
         results.append((f"CAA {domain}", True, f"WARNING: {why} (continuing: CAA is advisory)"))
     else:
@@ -428,6 +448,12 @@ def main() -> int:
         default=os.environ.get("ACME_CHALLENGE_ALIAS", ""),
         help="delegation zone for the _acme-challenge CNAME (dns-01 delegation)",
     )
+    parser.add_argument(
+        "--caa-required",
+        action="store_true",
+        help="treat an absent CAA record set as a failure (challenge delegation: "
+             "the record is the only protection and we cannot create it)",
+    )
     parser.add_argument(
         "--caa-advisory",
         action="store_true",
@@ -484,6 +510,7 @@ def main() -> int:
             results = verify_once(
                 records, args.domain.lstrip("*."), args.caa_tag, args.challenge,
                 args.account_uri, args.resolver, args.caa_advisory,
+                args.caa_required,
             )
         except ResolveError as exc:
             print(f"[dns-check #{attempt}] resolver problem: {exc}", flush=True)

custom-domain/dstack-ingress/scripts/tests/test_dnsguide.py

@@ -176,6 +176,48 @@ def test_reports_absence_without_claiming_it_does_not_resolve(self):
         self.assertIn("no CNAME record found", why)
 
 
+class TestCaaRequiredForDelegation(unittest.TestCase):
+    """Delegation inverts the usual CAA question.
+
+    Normally we ask "does anything forbid us from issuing", and no CAA at all
+    means no. Under challenge delegation the record is the only thing stopping
+    someone else who can satisfy the delegated challenge, and we cannot create
+    it, so its absence has to block.
+    """
+
+    def _no_caa(self):
+        saved = dnsguide.query_union
+        dnsguide.query_union = lambda name, rr, r: []
+        self.addCleanup(lambda: setattr(dnsguide, "query_union", saved))
+
+    def test_absent_caa_passes_by_default(self):
+        self._no_caa()
+        ok, why = dnsguide.check_caa("app.example.com", "issue", "dns-01", "", "r")
+        self.assertTrue(ok)
+        self.assertIn("unrestricted", why)
+
+    def test_absent_caa_blocks_when_required(self):
+        self._no_caa()
+        ok, why = dnsguide.check_caa(
+            "app.example.com", "issue", "dns-01", "", "r", require_present=True
+        )
+        self.assertFalse(ok)
+        self.assertIn("no CAA record set", why)
+
+    def test_present_and_matching_passes_when_required(self):
+        saved = dnsguide.query_union
+        dnsguide.query_union = lambda name, rr, r: (
+            ['0 issue "letsencrypt.org;validationmethods=dns-01;accounturi=https://acme/1"']
+            if name == "app.example.com" else []
+        )
+        self.addCleanup(lambda: setattr(dnsguide, "query_union", saved))
+        ok, _ = dnsguide.check_caa(
+            "app.example.com", "issue", "dns-01", "https://acme/1", "r",
+            require_present=True,
+        )
+        self.assertTrue(ok)
+
+
 class TestTxtNormalisation(unittest.TestCase):
     def test_strips_quotes(self):
         self.assertEqual(dnsguide._unquote_txt('"abc:443"'), "abc:443")