Document the account endpoint and the DNS-PERSIST-01 operating model

[shibayan]

Background

Part of #1152.

Acmebot's position on DNS-PERSIST-01 is that _validation-persist records are persistent issuance authorization managed by the operator, never written by the application. That model needs to be documented, along with its security consequences, before operators start publishing records.

Scope

docs/reference/api.md

• Document GET /api/account, its response shape, and its authorization requirement
• State that the first call registers an ACME account when none exists yet

docs/guide/

• Acmebot never creates, updates, or deletes _validation-persist records
• Where each part of the record comes from, using the values shown in the dashboard
• The ACME account key becomes the primary sensitive asset: where Acmebot stores it, and what its compromise implies
• Removal and rollback: deleting the record stops future issuance but does not revoke certificates that were already issued
• Current limitation: certificate issuance through DNS-PERSIST-01 is not available yet, so DNS-01 with a configured DNS provider remains the only issuance path

Notes

The record format is not stable. draft-ietf-acme-dns-persist is in active revision and the accounturi parameter is being replaced with a client-computed hashed URI (ietf-wg-acme/draft-ietf-acme-dns-persist#64, PR ietf-wg-acme/draft-ietf-acme-dns-persist#67). Let's Encrypt has stated it will not deploy DNS-PERSIST-01 until that issue is resolved.

The documentation should therefore link to the draft for the record syntax rather than pinning the exact format, and should be explicit that Acmebot does not generate the value.

Acceptance Criteria

• GET /api/account is documented in the API reference, including the account registration side effect
• The operating model, ACME account key security considerations, and the removal procedure are documented
• The docs state that Acmebot does not write _validation-persist records
• The docs state that issuance via DNS-PERSIST-01 is not yet supported

[tomatotomata]

I was thinking of taking this documentation slice on. I will update docs/reference/api.md for GET /api/account and add the DNS-PERSIST-01 operating model to the existing guide without changing implementation or claiming issuance support that is not available yet. Let me know what you think.

[tomatotomata]

While mapping the docs to master, I found no /api/account function or client call in the checkout, and parent issue #1152 is still open. I do not want to invent a response shape or imply DNS-PERSIST-01 issuance exists before that endpoint/behavior lands. If the endpoint is expected to arrive through #1152, I can prepare the guide updates once that contract is available.

[shibayan]

Thanks for checking. Please do not work on this issue yet. DNS-PERSIST-01 is still under active specification development and is not implemented in Acmebot. This issue and its sub-issues are only being used to identify and organize possible future work; they are not open for implementation or external contributions at this time. We will update their status when the specification and implementation plan are ready.