feat(panelica): the mail certificate's host name, and the DNS records a failed one needs

[ertugrulkeyvan]

What

Two follow-ups to #178, on the Panelica mail certificate.

1. The host name the panel gives the certificate.

This is your note on #178. The panel lets an operator give a domain a different mail host name, and GET /v1/ssl/domains/{id}/mail returns it as data.hostname.

• When the panel gives one: mail clients are told that name, on the email page and in the welcome email.
• Otherwise: mail.<domain>, as now.

2. Telling the customer what a failed certificate needs.

• Why it fails: the certificate covers mail., autoconfig. and autodiscover., and each of them is checked. For a domain whose DNS is somewhere else, issuing fails until all three point at the server. We measured this on Panelica 1.0.14: the status is failed, with an NXDOMAIN error for each name.
• What the customer sees today: nothing. Their mail app warns that the connection is not secure, and the next step is a support ticket.
• After this: when the certificate's status is failed, the email page shows a short notice with the three records to add, each with a copy button:
  • CNAMEs to the server's hostname, which follow the server if its address changes;
  • or A records to its address, for a server known only by a public IP. A private address gets no notice, since it would be the wrong record.
• Asking again: a Request the certificate again button asks the panel for it once the records are in. This goes through the same check as the first mailbox, so only a missing or failed certificate is requested, and it is limited to 3 requests in 10 minutes.
• No notice while the certificate is active, pending, renewing or missing.

How

• PanelicaModule::mailCertificate():
  • reads the status of the service's domain (panelica_domain_id): status, host name and last error;
  • once per service per request, since the email page and the welcome email both ask;
  • null when the panel cannot say.
• mailHostname(): prefers that host name, then mail.<domain>, then the server-hostname guess.
• mailDnsHelp(): builds the records for a failed certificate, or null.
• retryMailCertificate(): calls the existing ensureMailCertificate().
• ServiceController: emails() passes $mailDns to the view only when the account has mailboxes. retryMailCertificate() is the button, behind the client-ownership check and throttle:3,10, on the route client.services.emails.certificate.
• View: a notice card above the mail client settings on client/services/hosting/email.
• Text: in en, tr, de, pl and zh.
• Docs: the Panelica mail paragraph in docs/guides/connect-a-server.md.

The work is split into six commits: the certificate status and host name, the records and the retry, the page, the translations, the docs and the tests.

Tests

tests/Feature/PanelicaMailDnsHelpTest.php, 12 tests:

• Host name:
  • the name from the certificate status is the one mail clients are told;
  • without one, or with no status, it is mail.<domain>.
• Records:
  • a failed certificate gives CNAMEs to the server's hostname;
  • a server known only by a public address gives A records; a private one gives nothing;
  • nothing is given while the certificate is active, pending, renewing or missing.
• Page:
  • the notice and the records appear when the certificate failed, and do not when it is active;
  • the owner can request the certificate again, and the panel is asked; another client gets a 403.

Nine of them fail on main. The existing Panelica tests pass unchanged.

Full suite: 4098 passed. The one failure is the CurrencyAndBackupTest db backup test, which fails on main too in my local setup.

[Panelica]

Thank you, @ertugrulkeyvan, merged. Reading the panel's certificate status and showing the customer exactly which records to add will save a lot of "my mail app says the connection is not secure" tickets.

On top of your commits there is one more (9dbf6b5):

• webmail. is listed too. The mail certificate covers the mail host name plus webmail., autoconfig. and autodiscover. under the domain, and the panels in use today check every name on it, so with three records the certificate still could not be issued. Newer panels leave out a name that does not resolve, but still fail on one that points somewhere else, so all four are listed.
• The first record is the mail host name the panel gave the domain, the same name mailHostname() now tells mail clients. A host name outside the customer's domain is the operator's to point and is not listed.
• "Request the certificate again" no longer says it was requested when the panel did not take the request (it refuses a new one for a few minutes after a failed attempt) or could not be reached. That case has its own message, client.hosting.email.dns_not_requested, in all five languages.
• Docs and tests follow: the new tests fail on your branch and pass with the change.

Full suite green.