happyDomain/checker-email-autoconfig
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit

Browse source
This commit is contained in:
nemunaire 2026-04-23 17:45:37 +07:00
commit c4bf833274
19 changed files with 2451 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

417
checker/report.go Normal file
View file

@ -0,0 +1,417 @@
package checker
import (
"encoding/json"
"fmt"
"html/template"
"strings"
sdk "git.happydns.org/checker-sdk-go/checker"
)
type reportStatus string
const (
statusOK reportStatus = "ok"
statusWarn reportStatus = "warn"
statusFail reportStatus = "fail"
statusInfo reportStatus = "info"
statusSkip reportStatus = "skip"
)
type reportProbe struct {
ProbeResult
Source string
Verdict reportStatus
VerdictText string
}
type reportServer struct {
Type string
Hostname string
Port int
SocketType string
Authentication string
Encrypted bool
AuthSafe bool
}
type reportRemediation struct {
Title string
Body template.HTML
}
type reportData struct {
Domain string
Email string
HeadlineBadge string
HeadlineClass reportStatus
HeadlineText string
Summary []reportSummaryItem
Autoconfig []reportProbe
Autodiscover []reportProbe
SRVRecords []SRVRecord
MX []string
ConfigServers struct {
Incoming []reportServer
Outgoing []reportServer
CardDAV []DavServer
CalDAV []DavServer
}
Remediations []reportRemediation
ExampleXML template.HTML
}
type reportSummaryItem struct {
Label string
Status reportStatus
Message string
}
// GetHTMLReport implements sdk.CheckerHTMLReporter.
func (p *autoconfigProvider) GetHTMLReport(ctx sdk.ReportContext) (string, error) {
var d Data
if err := json.Unmarshal(ctx.Data(), &d); err != nil {
return "", fmt.Errorf("decode autoconfig data: %w", err)
}
data := buildReport(&d)
var buf strings.Builder
buf.Grow(32 * 1024)
if err := autoconfigHTMLTemplate.Execute(&buf, data); err != nil {
return "", fmt.Errorf("render: %w", err)
}
return buf.String(), nil
}
func buildReport(d *Data) reportData {
r := reportData{
Domain: d.Domain,
Email: d.Email,
}
for _, m := range d.MX {
r.MX = append(r.MX, fmt.Sprintf("%s (pref %d)", m.Host, m.Preference))
}
hasParsed := false
hasAutoconfigOK := false
hasWellKnownOK := false
plaintextOK := false
tlsFailures := 0
for _, p := range d.Autoconfig {
rp := reportProbe{ProbeResult: p.Result}
switch {
case p.Parsed != nil:
rp.Verdict = statusOK
rp.VerdictText = "Parsed OK"
hasParsed = true
if p.Source == "autoconfig" {
hasAutoconfigOK = true
}
if p.Source == "wellknown" {
hasWellKnownOK = true
}
if strings.HasPrefix(p.Result.URL, "http://") {
plaintextOK = true
}
case p.Result.TLSError != "":
rp.Verdict = statusFail
rp.VerdictText = "TLS error"
tlsFailures++
case p.Result.Error != "":
rp.Verdict = statusFail
rp.VerdictText = "Unreachable"
case p.Result.ParseError != "":
rp.Verdict = statusFail
rp.VerdictText = "XML parse error"
case p.Result.StatusCode >= 400:
rp.Verdict = statusFail
rp.VerdictText = fmt.Sprintf("HTTP %d", p.Result.StatusCode)
default:
rp.Verdict = statusWarn
rp.VerdictText = fmt.Sprintf("HTTP %d (no config)", p.Result.StatusCode)
}
rp.Source = probeSourceLabel(p.Source)
r.Autoconfig = append(r.Autoconfig, rp)
}
hasAutodiscover := false
for _, p := range d.Autodiscover {
rp := reportProbe{ProbeResult: p.Result}
switch {
case p.Parsed != nil:
rp.Verdict = statusOK
rp.VerdictText = "Parsed OK"
hasAutodiscover = true
case p.Result.Error != "":
rp.Verdict = statusSkip
rp.VerdictText = "Unreachable"
case p.Result.ParseError != "":
rp.Verdict = statusFail
rp.VerdictText = "XML parse error"
case p.Result.StatusCode >= 400:
rp.Verdict = statusSkip
rp.VerdictText = fmt.Sprintf("HTTP %d", p.Result.StatusCode)
default:
rp.Verdict = statusWarn
rp.VerdictText = fmt.Sprintf("HTTP %d", p.Result.StatusCode)
}
rp.Source = probeSourceLabel(p.Source)
r.Autodiscover = append(r.Autodiscover, rp)
}
hasIncomingSRV, hasSubmissionSRV := false, false
for _, s := range d.SRV {
if !s.Skip {
inc, sub := classifySRV(s.Service)
hasIncomingSRV = hasIncomingSRV || inc
hasSubmissionSRV = hasSubmissionSRV || sub
}
}
r.SRVRecords = d.SRV
if d.ClientConfig != nil {
for _, s := range d.ClientConfig.Incoming {
r.ConfigServers.Incoming = append(r.ConfigServers.Incoming, toReportServer(s))
}
for _, s := range d.ClientConfig.Outgoing {
r.ConfigServers.Outgoing = append(r.ConfigServers.Outgoing, toReportServer(s))
}
r.ConfigServers.CardDAV = d.ClientConfig.AddressBook
r.ConfigServers.CalDAV = d.ClientConfig.Calendar
}
switch {
case hasParsed && hasAutoconfigOK && tlsFailures == 0 && !plaintextOK:
r.HeadlineBadge, r.HeadlineClass, r.HeadlineText = "OK", statusOK, "Email autoconfiguration is published and healthy."
case hasParsed && tlsFailures == 0:
r.HeadlineBadge, r.HeadlineClass, r.HeadlineText = "PARTIAL", statusWarn, "Autoconfig works but has room for improvement (see remediation)."
case hasParsed && tlsFailures > 0:
r.HeadlineBadge, r.HeadlineClass, r.HeadlineText = "TLS ISSUE", statusFail, "Autoconfig answers but at least one endpoint has a TLS problem."
case hasAutodiscover:
r.HeadlineBadge, r.HeadlineClass, r.HeadlineText = "LEGACY ONLY", statusWarn, "Only Microsoft Autodiscover answers. Thunderbird/K9/Evolution users will see manual setup."
case hasIncomingSRV && hasSubmissionSRV:
r.HeadlineBadge, r.HeadlineClass, r.HeadlineText = "SRV ONLY", statusWarn, "Only RFC 6186 SRV records; most clients still need a clientConfig XML."
default:
r.HeadlineBadge, r.HeadlineClass, r.HeadlineText = "NOT FOUND", statusFail, "No email autoconfiguration was discovered for this domain."
}
r.Summary = []reportSummaryItem{
{"Primary autoconfig (autoconfig." + d.Domain + ")", boolStatus(hasAutoconfigOK), primaryMsg(hasAutoconfigOK)},
{".well-known/autoconfig", boolStatus(hasWellKnownOK), wellKnownMsg(hasWellKnownOK)},
{"Microsoft Autodiscover", boolStatus(hasAutodiscover), autodiscoverMsg(hasAutodiscover)},
{"RFC 6186 SRV records", srvStatus(hasIncomingSRV, hasSubmissionSRV), srvMsg(hasIncomingSRV, hasSubmissionSRV)},
}
r.Remediations = buildRemediations(d, hasParsed, hasAutoconfigOK, hasWellKnownOK, plaintextOK, tlsFailures, hasIncomingSRV, hasSubmissionSRV)
r.ExampleXML = template.HTML(exampleClientConfig(d.Domain))
return r
}
func boolStatus(ok bool) reportStatus {
if ok {
return statusOK
}
return statusFail
}
func primaryMsg(ok bool) string {
if ok {
return "Reachable and serves a valid clientConfig."
}
return "Not reachable. This is the first URL Thunderbird tries."
}
func wellKnownMsg(ok bool) string {
if ok {
return "Answers on the domain apex."
}
return "Not exposed. Optional, but useful when you cannot add a subdomain."
}
func autodiscoverMsg(ok bool) string {
if ok {
return "Responds. Microsoft Outlook / mobile clients will find your server."
}
return "Silent. Outlook-for-Windows and iOS Mail rely on this."
}
func srvStatus(inc, sub bool) reportStatus {
switch {
case inc && sub:
return statusOK
case inc || sub:
return statusWarn
}
return statusInfo
}
func srvMsg(inc, sub bool) string {
switch {
case inc && sub:
return "Incoming and submission SRV records published."
case inc:
return "Submission SRV missing (_submissions._tcp)."
case sub:
return "Incoming SRV missing (_imaps._tcp / _pop3s._tcp)."
}
return "No RFC 6186 SRV records. Not mandatory, but a cheap safety net."
}
var probeLabelMap = map[string]string{
"autoconfig": "autoconfig.<domain>",
"wellknown": ".well-known/autoconfig",
"http-autoconfig": "http://autoconfig.<domain>",
"ispdb": "Mozilla ISPDB",
"mx-autoconfig": "MX-parent autoconfig",
"mx-ispdb": "MX-parent ISPDB",
"subdomain": "autodiscover.<domain>",
"root": "apex /autodiscover",
}
func probeSourceLabel(src string) string {
if label, ok := probeLabelMap[src]; ok {
return label
}
return src
}
func toReportServer(s ServerConfig) reportServer {
return reportServer{
Type: s.Type,
Hostname: s.Hostname,
Port: s.Port,
SocketType: s.SocketType,
Authentication: s.Authentication,
Encrypted: isEncryptedSocket(s.SocketType),
AuthSafe: !strings.EqualFold(s.Authentication, "password-cleartext") || isEncryptedSocket(s.SocketType),
}
}
// ── Remediation snippets ────────────────────────────────────────────────────
func buildRemediations(d *Data, hasParsed, hasAutoconfig, hasWellKnown, plaintextOK bool, tlsFailures int, hasIncomingSRV, hasSubmissionSRV bool) []reportRemediation {
var out []reportRemediation
if !hasParsed {
out = append(out, reportRemediation{
Title: "Publish an autoconfig XML file",
Body: template.HTML(fmt.Sprintf(`
<p>Clients such as Thunderbird, K-9 Mail, Evolution and KMail will query
<code>https://autoconfig.%[1]s/mail/config-v1.1.xml</code> when the user
types <code>user@%[1]s</code>. Publishing the file removes the need for
manual IMAP/SMTP setup.</p>
<ol>
<li>Create a subdomain <code>autoconfig.%[1]s</code> pointing to a TLS-enabled web server (a 200-byte static file is enough).</li>
<li>Drop the XML below at <code>/mail/config-v1.1.xml</code> and make sure it is served with <code>Content-Type: text/xml</code>.</li>
<li>Do the same at <code>https://%[1]s/.well-known/autoconfig/mail/config-v1.1.xml</code> so users who cannot add a subdomain still get configured.</li>
</ol>`, d.Domain)),
})
}
if hasParsed && !hasAutoconfig && hasWellKnown {
out = append(out, reportRemediation{
Title: "Add the autoconfig.<domain> subdomain",
Body: template.HTML(fmt.Sprintf(`
<p>Only the <code>.well-known</code> fallback responded. Thunderbird tries
<code>autoconfig.%[1]s</code> <em>first</em>, so adding the subdomain is a
cheap win. Copy the XML from your apex, expose it on
<code>https://autoconfig.%[1]s/mail/config-v1.1.xml</code>.</p>`, d.Domain)),
})
}
if plaintextOK {
out = append(out, reportRemediation{
Title: "Stop serving autoconfig over HTTP",
Body: template.HTML(`
<p>The draft requires clients to ignore plaintext responses unless HTTPS
fails. Clients will still warn the user. Redirect HTTP to HTTPS and drop
the plaintext virtualhost entirely.</p>`),
})
}
if tlsFailures > 0 {
out = append(out, reportRemediation{
Title: "Fix the TLS certificate on the autoconfig endpoint",
Body: template.HTML(fmt.Sprintf(`
<p>At least one autoconfig endpoint failed certificate verification
(expired, self-signed, hostname mismatch or unknown CA). Clients will
refuse the document outright.</p>
<p>Issue a certificate that covers <code>autoconfig.%[1]s</code> (and
<code>%[1]s</code> if you serve <code>.well-known</code>). Let's Encrypt
works out of the box.</p>`, d.Domain)),
})
}
if d.ClientConfig != nil {
servers := make([]ServerConfig, 0, len(d.ClientConfig.Incoming)+len(d.ClientConfig.Outgoing))
servers = append(servers, d.ClientConfig.Incoming...)
servers = append(servers, d.ClientConfig.Outgoing...)
for _, s := range servers {
if !isEncryptedSocket(s.SocketType) {
out = append(out, reportRemediation{
Title: "Remove plaintext server definitions",
Body: template.HTML(fmt.Sprintf(`
<p>The server <code>%s %s:%d</code> is advertised with
<code>socketType=%s</code>. Clients that apply your config will send the
password in clear. Switch to:</p>
<ul>
<li><code>SSL</code> on IMAP 993 / POP3 995 / SMTP submission 465.</li>
<li><code>STARTTLS</code> on IMAP 143 or SMTP submission 587.</li>
</ul>`, s.Type, s.Hostname, s.Port, s.SocketType)),
})
break
}
}
}
if !hasIncomingSRV || !hasSubmissionSRV {
out = append(out, reportRemediation{
Title: "Publish RFC 6186 SRV records",
Body: template.HTML(fmt.Sprintf(`
<p>SRV records are a cheap safety net for clients that do not fetch an
autoconfig XML. Advertise IMAPS and submission:</p>
<pre>_imaps._tcp.%[1]s. IN SRV 0 1 993 imap.%[1]s.
_submissions._tcp.%[1]s. IN SRV 0 1 465 smtp.%[1]s.</pre>
<p>Use target <code>.</code> to explicitly declare a service as unsupported (e.g. <code>_pop3._tcp</code>).</p>`, d.Domain)),
})
}
return out
}
// exampleClientConfig returns a paste-ready XML snippet for the domain.
func exampleClientConfig(domain string) string {
if domain == "" {
domain = "example.com"
}
tpl := `&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;clientConfig version=&quot;1.1&quot;&gt;
&lt;emailProvider id=&quot;%[1]s&quot;&gt;
&lt;domain&gt;%[1]s&lt;/domain&gt;
&lt;displayName&gt;%[1]s Mail&lt;/displayName&gt;
&lt;displayShortName&gt;%[1]s&lt;/displayShortName&gt;
&lt;incomingServer type=&quot;imap&quot;&gt;
&lt;hostname&gt;imap.%[1]s&lt;/hostname&gt;
&lt;port&gt;993&lt;/port&gt;
&lt;socketType&gt;SSL&lt;/socketType&gt;
&lt;username&gt;%%EMAILADDRESS%%&lt;/username&gt;
&lt;authentication&gt;password-cleartext&lt;/authentication&gt;
&lt;/incomingServer&gt;
&lt;outgoingServer type=&quot;smtp&quot;&gt;
&lt;hostname&gt;smtp.%[1]s&lt;/hostname&gt;
&lt;port&gt;465&lt;/port&gt;
&lt;socketType&gt;SSL&lt;/socketType&gt;
&lt;username&gt;%%EMAILADDRESS%%&lt;/username&gt;
&lt;authentication&gt;password-cleartext&lt;/authentication&gt;
&lt;/outgoingServer&gt;
&lt;/emailProvider&gt;
&lt;/clientConfig&gt;`
return fmt.Sprintf(tpl, domain)
}