Support DNS-PERSIST-01 and separate DNS changes from certificate issuance #1152

Background

DNS-PERSIST-01 replaces per-issuance _acme-challenge TXT record updates with persistent authorization at _validation-persist.<FQDN>. This can remove DNS writes, propagation waits, and DNS API credentials from certificate issuance and renewal.

The authorization is bound to a CA and ACME account. In the latest published draft, the record uses a hashed account URI computed from the account URL, account key thumbprint, and the record's own domain name (or the draft's explicit domain-omitted opt-out). Do not generate records using the raw account URI examples from older drafts or the February 2026 announcement.

Upstream Status

Last reviewed: 2026-10-21.

• The latest published specification is draft-ietf-acme-dns-persist-02, which remains an Internet-Draft.
• Revision -02 introduces directory issuerDomainNames, accountHashPrefix, and hashed account URIs. The upstream privacy design discussion #61 and client-computed account binding issue #64 are closed.
• The key rollover discussion #69 remains open. Revision -02 permits records provisioned before rollover to remain usable, including records not previously validated. Do not assume that rotating an account key immediately invalidates persistent authorization.
• Neither the Let's Encrypt production directory nor the staging directory advertised issuerDomainNames or accountHashPrefix at review time. The February announcement describes rollout targets, not confirmation of current draft interoperability.
• Google Trust Services announced support on 2026-09-28, explicitly for draft -01, using cleartext account URIs. Its production directory did not advertise issuerDomainNames or accountHashPrefix at review time. This does not establish compatibility with Acmebot's selected draft -02 baseline. Do not automatically fall back to the older record format or re-expose raw account URLs.

Directory metadata availability, an offered DNS-PERSIST-01 challenge, and successful issuance are separate checks. CAA identities alone do not establish support. Missing directory metadata prevents pre-provisioning discovery but does not prove that the CA cannot offer an interactive challenge.

Direction

Acmebot must not automatically create, update, or delete _validation-persist records. Manage them through DNS change management, IaC, or explicit DNS administrator approval.

Keep DNS-PERSIST-01 separate from DNS-01. The eventual workflow should generate instructions, verify DNS in read-only mode, explain wildcard scope and expiration, and issue or renew without DNS write credentials. Until that workflow is supported, retain the existing DNS-01 provider configuration and permissions.

The ACME account key becomes the primary sensitive asset. Document its protection, backup, compromise response, and the limits of record removal and key rollover.

Implementation Plan

Completed on master: discovery and operating guidance

• Expose issuerDomainNames, accountHashPrefix, and validated pre-provisioning metadata availability through the account API, CLI, and dashboard.
• Distinguish metadata availability from issuance support; do not infer persistent-validation issuer names from caaIdentities.
• Handle absent or malformed metadata and older API responses without affecting DNS-01.
• Document the operating model, account key protection, removal procedures, current limitations, and conditions for resuming deferred work.

These discovery changes and documentation updates were merged into master in PR #1302 on 2026-10-21. This records source completion, not a release or deployment. Raw account URLs remain internal and are removed from API responses and user-facing output. This does not complete DNS-PERSIST-01 issuance support.

Defer until target-CA interoperability can be verified

Resume the following work after confirming that a target CA's staging environment supports the intended draft and provides usable examples or test vectors. Recheck the latest published draft and CA behavior before implementation. This is an Acmebot implementation gate, not a claim that these features lack draft definitions.

• Generate hashed TXT record values using the advertised issuer names and hash prefix, account URL, account key thumbprint, and the record's own domain name; make any domain-omitted opt-out explicit.
• Verify account control with the draft-required authenticated account-resource proof before delegating record publication; never share private key material.
• Verify existing _validation-persist TXT records in read-only mode.
• Determine and display the required policy=wildcard scope, including its subdomain implications.
• Display persistUntil and warn about expired or soon-to-expire records.
• Expose required DNS records and verification results in the UI, CLI, and API.
• Carry a separate validation mode through certificate policy, persisted metadata, issuance, and renewal.
• Make DNS provider write credentials unnecessary for DNS-PERSIST-01 issuance and renewal.

Defer automated account rollover or record migration until the applicable CA behavior and upstream guidance have been reviewed.

Acceptance Criteria

• The application can generate current-draft DNS-PERSIST-01 TXT instructions and verify published records in read-only mode.
• DNS-PERSIST-01 issuance and renewal never automatically modify DNS records and require no DNS provider write credentials.
• Wildcard authorization scope and the presence or absence of policy=wildcard are explicit.
• Expired or soon-to-expire persistUntil values are detected.
• Documentation explains account key protection, compromise response, and the limitations of removal and rollover.
• Existing DNS-01 behavior remains supported and clearly separated from DNS-PERSIST-01.