feat(dstack-ingress): ACME DNS-01 challenge delegation (CNAME alias) for least-privilege DNS tokens

[Ravenyjh]

Implements #103.

Problem

dstack-ingress issues certs via ACME DNS-01, which needs a DNS token that can edit the served domain's own zone (_acme-challenge TXT, plus the A/alias record and — with SET_CAA — the CAA). When the served name lives under a shared production zone, that token can edit the whole zone, which is more privilege than an enclave should hold. Cloudflare tokens can't scope below zone level, and subdomain zones are Enterprise-only.

What this adds

Opt-in ACME_CHALLENGE_ALIAS=<delegation-zone>: answer the DNS-01 challenge in a separate zone the token controls, so the token never touches the served domain's zone.

• 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 authenticator + hooks saved in the renewal config.
• scripts/acme-dns-alias-hook.sh (new) — writes/removes the _acme-challenge TXT in the delegation zone, reusing dnsman.py / the existing dns_providers abstraction.
• dnsman.py + dns_providers/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 it prints the exact records the operator must set statically. For CAA it does not silently skip: it prints the required accounturi CAA and verifies its presence (via DoH), warning loudly if absent — since that CAA is the forge-prevention.
• README.md — documents the mode, the required static records, and the security note.

Security note

The accounturi CAA (only this enclave's ACME account may issue) normally auto-set by entrypoint.sh cannot be set by us in delegation mode (no token for the served zone). Rather than silently dropping it (which would let anyone who satisfies the delegated challenge obtain a cert for the domain), the feature prints the exact record and verifies/warns. The delegation token should be scoped only to <delegation-zone>.

Compatibility

Non-breaking: with ACME_CHALLENGE_ALIAS unset, behavior is unchanged.

Testing

Python (py_compile) and bash (bash -n) syntax checks pass. This is the DNS/orchestration path; happy to add an e2e case (Let's Encrypt staging + a delegated test zone) if you'd like.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xa1zFJs3FVP8UTsSWuS3Yj

[kvinwang]

Post-merge note, @Ravenyjh — I merged this before reviewing it properly, which was my mistake, so here is the review after the fact. The mechanism holds up; I verified the parts that worried me most:

• _get_zone_info does longest-suffix matching, so _acme-challenge.svc.example.com.deleg.example.net resolves to the delegation zone and not to the served zone whose name it happens to contain — the case I most expected to be wrong;
• the hook computes the right record name, finds dnsman.py on PATH, and gets the venv interpreter;
• a failed auth exits non-zero, so certbot does see the challenge fail.

Three things came out of it, tracked in #106: the CAA verification is single-resolver and fails closed (a stale negative cache means the container refuses to start, and dnsguide.py from #105 already solves this properly), unset_txt_record reports success when the zone lookup failed, and the delegated issuance path itself has still never been executed end to end.

One small fix already landed in #105: the delegated TXT instruction printed "$APP_ID:$PORT", but APP_ID is an optional override rather than the app id itself, so with it unset — the normal case — the operator was told to create a record with the value ":443". It now prints $(txt_record_value), the same function that writes the record when delegation is off, so the instruction cannot drift from what the gateway expects.

#105 also moved this feature's shell half into scripts/dns01.sh: that branch splits entrypoint.sh into one script per challenge type, and delegation is a dns-01 capability. The hook, unset_txt_record, the dnsman.py action, the certman.py branch and the README section are unchanged. Two integration fixes were needed where the two PRs met — the delegation branch read CERTBOT_STAGING, which #105 renamed to ACME_STAGING (so ACME_STAGING=true plus delegation would have issued production certificates), and it passed --email unconditionally, which #105 made optional.

Thanks for this — the shared-production-zone problem is real, and delegation covers the wildcard and multi-instance cases that tls-alpn-01 structurally cannot.