Repository navigation
Validate DNS-PERSIST-01 end to end and document migration and operations #1288
Description
Parent: #1152
Problem
The operating guide describes preparation only. Complete support needs evidence that issuance and renewal work without DNS access, plus accurate deployment, migration, and removal instructions.
Implementation timing
Reviewed on 2026-10-21. Separate early compatibility investigation from full end-to-end validation:
- Initial compatibility review completed (2026-10-21): inspected public directories and current specification/CA documentation independently of Issue and renew certificates through DNS-PERSIST-01 without DNS writes #1286 and Expose DNS-PERSIST-01 provisioning and verification in the API, dashboard, and CLI #1287. Continue a new compatibility review when a CA announces a relevant revision or its metadata changes; the current evidence does not satisfy the draft
-02staging interoperability gate. - Current finding: neither the Let's Encrypt production nor staging directory advertised
issuerDomainNamesoraccountHashPrefixat review time. Record this as missing pre-provisioning metadata, not proof that an interactive challenge can never be offered. - Defer full end-to-end work: resume once target-CA staging interoperability is established and the dependencies below are ready. A compatible local test server can provide protocol regression coverage, but does not by itself demonstrate target-CA availability.
Use draft -02 as the current reference and recheck the latest published draft before implementation. Do not treat the February rollout targets as evidence of successful deployment.
Scope
- Add an integration scenario against a CA/test server that implements the selected protocol revision; verify actual target-CA capabilities rather than relying on rollout announcements.
- Validate pre-provisioning, first issuance, scheduled renewal, multiple SANs, wildcard scope, expired/missing records, malformed responses, and already-valid authorizations.
- Prove that DNS provider calls and TXT mutations remain zero on success, failure, and retry, and test with provider configuration/permissions removed.
- Verify mode persistence and existing DNS-01 regression coverage.
- Update the operating guide, API/CLI references, and dashboard/deployment instructions with the supported revision, capabilities, examples, expiry warnings, and migration/rollback procedures.
- Explain account-key storage/protection, key rotation and account replacement, removal versus certificate revocation, and CA validation reuse. Document local verification limits for records created under prior keys. Do not present key rotation as immediate invalidation of persistent authorization; upstream issue #69 remains open. Automated rollover or record migration is deferred separately.
Acceptance criteria
- A reproducible integration run demonstrates issuance and renewal using operator-managed persistent DNS records without DNS credentials.
- CA/revision compatibility and unresolved external rollout dependencies are recorded explicitly.
- Documentation distinguishes released behavior, unmerged work, and future scope. Remove unsupported-feature notices only when the complete corresponding workflow has been implemented and validated; discovery metadata alone is insufficient.
- Existing account information features and DNS-01 workflows remain covered.
Remaining-work audit — 2026-10-21
| Area | Evidence and disposition |
|---|---|
| Protocol discovery and account interfaces | Completed on master through #1282 and PR #1302. Missing/malformed metadata, CAA-only directories, older API responses, and raw account URL omission are covered. No additional discovery implementation gap was identified. |
| Specification | Latest published revision remains -02. It includes hash examples/test vectors in Section 10.2; test-vector absence is not the remaining blocker. |
| Let's Encrypt | Production and staging still lack issuerDomainNames and accountHashPrefix. This establishes missing pre-provisioning inputs, not absence of every historical or interactive implementation. |
| Google Trust Services | September announcement explicitly supports draft -01, with cleartext account URIs. The production directory lacks the -02 discovery inputs. Older-draft support is not evidence of interoperability with the selected hashed format; do not add an implicit legacy fallback. |
| Remaining implementation | #1283–#1286 and the remaining provisioning/issuance scope of #1287 stay deferred under #1152. Full end-to-end work here stays deferred with them. No additional implementation should be started solely to satisfy a future acceptance criterion before its prerequisites are met. |
This review used repository inspection, public directory GETs, and primary documentation. It did not register accounts, create orders, publish records, or demonstrate live issuance. It does not claim to survey every CA or establish that no CA supports draft -02. No additional independent implementation task was identified within the agreed scope.
Dependencies
#1286 and #1287 for the full end-to-end scenario. Initial compatibility investigation and updates to current limitations can proceed before those issues are complete.
Activity